Module Name: src
Committed By: riastradh
Date: Fri Dec 8 15:52:01 UTC 2017
Modified Files:
src/share/man/man9: mutex.9
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.29 -r1.30 src/share/man/man9/mutex.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/mutex.9
diff -u src/share/man/man9/mutex.9:1.29 src/share/man/man9/mutex.9:1.30
--- src/share/man/man9/mutex.9:1.29 Mon Jul 3 21:28:48 2017
+++ src/share/man/man9/mutex.9 Fri Dec 8 15:52:01 2017
@@ -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 @@ Acquire a mutex.
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 @@ if it is not already equal or higher.
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 @@ Equivalent to
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 @@ Equivalent to
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"
