[src/trunk]: src/share/man/man9 Specify memory ordering implied by mutex_(spi...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/2d872ef54bc1
branches:  trunk
changeset: 828330:2d872ef54bc1
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri Dec 08 15:52:01 2017 +0000

description:
Specify memory ordering implied by mutex_(spin_)enter/exit.

I'm hesitant to just say `implies membar_enter/exit' -- that may be a
little stronger than we intend, since we don't really mean to
guarantee anything about loads and stores before the mutex_enter or
after the mutex_exit.  But we probably end up implementing the
semantics that we imply membar_enter/exit on all CPUs.

diffstat:

 share/man/man9/mutex.9 |  30 ++++++++++++++++++++++++++++--
 1 files changed, 28 insertions(+), 2 deletions(-)

diffs (72 lines):

diff -r 5849ae384b2b -r 2d872ef54bc1 share/man/man9/mutex.9
--- a/share/man/man9/mutex.9    Fri Dec 08 15:31:13 2017 +0000
+++ b/share/man/man9/mutex.9    Fri Dec 08 15:52:01 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mutex.9,v 1.29 2017/07/03 21:28:48 wiz Exp $
+.\"    $NetBSD: mutex.9,v 1.30 2017/12/08 15:52:01 riastradh Exp $
 .\"
 .\" Copyright (c) 2007, 2009 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 1, 2017
+.Dd December 8, 2017
 .Dt MUTEX 9
 .Os
 .Sh NAME
@@ -159,6 +159,17 @@
 If the mutex is already held, the caller will block and not return until the
 mutex is acquired.
 .Pp
+All loads and stores after
+.Fn mutex_enter
+will not be reordered before it or served from a prior cache, and hence
+will
+.Em happen after
+any prior
+.Fn mutex_exit
+to release the mutex even on another CPU or in an interrupt.
+Thus, there is a global total ordering on all loads and stores under
+the same mutex.
+.Pp
 Mutexes and other types of locks must always be acquired in a
 consistent order with respect to each other.
 Otherwise, the potential for system deadlock exists.
@@ -175,6 +186,17 @@
 Release a mutex.
 The mutex must have been previously acquired by the caller.
 Mutexes may be released out of order as needed.
+.Pp
+All loads and stores before
+.Fn mutex_exit
+will not be reordered after it or delayed in a write buffer, and hence
+will
+.Fn happen before
+any subsequent
+.Fn mutex_enter
+to acquire the mutex even on another CPU or in an interrupt.
+Thus, there is a global total ordering on all loads and stores under
+the same mutex.
 .It Fn mutex_ownable "mtx"
 .Pp
 When compiled with
@@ -218,6 +240,8 @@
 but may only be used when it is known that
 .Ar mtx
 is a spin mutex.
+Implies the same memory ordering as
+.Fn mutex_enter .
 On some architectures, this can substantially reduce the cost of acquiring
 a spin mutex.
 .It Fn mutex_spin_exit "mtx"
@@ -227,6 +251,8 @@
 but may only be used when it is known that
 .Ar mtx
 is a spin mutex.
+Implies the same memory ordering as
+.Fn mutex_exit .
 On some architectures, this can substantially reduce the cost of releasing
 a spin mutex.
 .It Fn mutex_tryenter "mtx"