Document {mtx,rw,rrw}_init_flags() and MUTEX_INITIALIZER_FLAGS().

Input and OK jmc@, OK mpi@

2 files changed, 84 insertions, 7 deletions

diff --git a/share/man/man9/mutex.9 b/share/man/man9/mutex.9
index abbaac9e91b..fac88f29ff0 100644
--- a/share/man/man9/mutex.9
+++ b/share/man/man9/mutex.9
@@ -1,4 +1,4 @@
-.\" $OpenBSD: mutex.9,v 1.23 2016/06/19 11:54:33 natano Exp $
+.\" $OpenBSD: mutex.9,v 1.24 2017/10/30 13:33:36 visa Exp $
 .\"
 .\" Copyright (c) 2005 Pedro Martelletto <pedro@ambientworks.net>
 .\" All rights reserved.
@@ -15,24 +15,29 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 19 2016 $
+.Dd $Mdocdate: October 30 2017 $
 .Dt MUTEX 9
 .Os
 .Sh NAME
 .Nm mutex ,
 .Nm mtx_init ,
+.Nm mtx_init_flags ,
 .Nm mtx_enter ,
 .Nm mtx_enter_try ,
 .Nm mtx_leave ,
 .Nm MUTEX_ASSERT_LOCKED ,
 .Nm MUTEX_ASSERT_UNLOCKED ,
-.Nm MUTEX_INITIALIZER
+.Nm MUTEX_INITIALIZER ,
+.Nm MUTEX_INITIALIZER_FLAGS
 .Nd interface to CPU mutexes
 .Sh SYNOPSIS
 .In sys/mutex.h
 .Ft void
 .Fn mtx_init "struct mutex *mtxp" "int wantipl"
 .Ft void
+.Fn mtx_init_flags "struct mutex *mtxp" "int wantipl" "const char *name" \
+"int flags"
+.Ft void
 .Fn mtx_enter "struct mutex *mtxp"
 .Ft int
 .Fn mtx_enter_try "struct mutex *mtxp"
@@ -41,6 +46,7 @@
 .Fn MUTEX_ASSERT_LOCKED "struct mutex *mtxp"
 .Fn MUTEX_ASSERT_UNLOCKED "struct mutex *mtxp"
 .Fn MUTEX_INITIALIZER "int wantipl"
+.Fn MUTEX_INITIALIZER_FLAGS "int wantipl" "const char *name" "int flags"
 .Sh DESCRIPTION
 The
 .Nm
@@ -57,6 +63,34 @@ to
 if necessary.
 .Pp
 The
+.Fn mtx_init_flags
+macro is similar to
+.Fn mtx_init ,
+but it additionally accepts parameters for
+.Xr witness 4 .
+The pointer
+.Fa name
+differentiates a lock type.
+Two mutexes have the same lock type only if they have been created by the same
+occurrence of
+.Fn mtx_init_flags
+with the same pointer
+.Fa name .
+The
+.Fa flags
+parameter is a bitwise OR of the following options:
+.Bl -tag -width MTX_NOWITNESS -offset indent
+.It Dv MTX_DUPOK
+Prevents
+.Xr witness 4
+from logging when a CPU acquires more than one lock of this lock type.
+.It Dv MTX_NOWITNESS
+Instructs
+.Xr witness 4
+to ignore this lock.
+.El
+.Pp
+The
 .Fn mtx_enter
 function acquires a mutex, spinning if necessary.
 .Pp
@@ -84,8 +118,20 @@ When acquired, the mutex will cause the processor interrupt level to be raised
 to
 .Fa wantipl
 if necessary.
+.Pp
+The
+.Fn MUTEX_INITIALIZER_FLAGS
+macro is similar to
+.Fn MUTEX_INITIALIZER ,
+but it additionally accepts parameters for
+.Xr witness 4 .
+See the
+.Fn mtx_init_flags
+macro for details.
 .Sh CONTEXT
 .Fn mtx_init
+and
+.Fn mtx_init_flags
 can be called during autoconf, from process context, or from interrupt
 context.
 .Pp
diff --git a/share/man/man9/rwlock.9 b/share/man/man9/rwlock.9
index aa80466ff61..8270a938c97 100644
--- a/share/man/man9/rwlock.9
+++ b/share/man/man9/rwlock.9
@@ -1,4 +1,4 @@
-.\" $OpenBSD: rwlock.9,v 1.19 2017/08/12 23:27:44 guenther Exp $
+.\" $OpenBSD: rwlock.9,v 1.20 2017/10/30 13:33:36 visa Exp $
 .\"
 .\" Copyright (c) 2006 Pedro Martelletto <pedro@ambientworks.net>
 .\" All rights reserved.
@@ -15,12 +15,13 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 12 2017 $
+.Dd $Mdocdate: October 30 2017 $
 .Dt RWLOCK 9
 .Os
 .Sh NAME
 .Nm rwlock ,
 .Nm rw_init ,
+.Nm rw_init_flags ,
 .Nm rw_enter ,
 .Nm rw_exit ,
 .Nm rw_enter_read ,
@@ -34,6 +35,7 @@
 .Nm rw_status ,
 .Nm RWLOCK_INITIALIZER ,
 .Nm rrw_init ,
+.Nm rrw_init_flags ,
 .Nm rrw_enter ,
 .Nm rrw_exit ,
 .Nm rrw_status
@@ -42,6 +44,8 @@
 .In sys/rwlock.h
 .Ft void
 .Fn rw_init "struct rwlock *rwl" "const char *name"
+.Ft void
+.Fn rw_init_flags "struct rwlock *rwl" "const char *name" "int flags"
 .Ft int
 .Fn rw_enter "struct rwlock *rwl" "int flags"
 .Ft void
@@ -67,6 +71,8 @@
 .Fn RWLOCK_INITIALIZER "const char *name"
 .Ft void
 .Fn rrw_init "struct rrwlock *rrwl" "const char *name"
+.Ft void
+.Fn rrw_init_flags "struct rrwlock *rrwl" "const char *name" "int flags"
 .Ft int
 .Fn rrw_enter "struct rrwlock *rrwl" "int flags"
 .Ft void
@@ -94,6 +100,29 @@ argument specifies the name of the lock, which is used as the wait message
 if the thread needs to sleep.
 .Pp
 The
+.Fn rw_init_flags
+macro is similar to
+.Fn rw_init ,
+but it additionally accepts a bitwise OR of the following flags:
+.Bl -tag -width RWL_NOWITNESS -offset indent
+.It Dv RWL_DUPOK
+Prevents
+.Xr witness 4
+from logging when a thread acquires more than one lock of this lock type.
+.It Dv RWL_IS_VNODE
+Make
+.Xr witness 4
+ignore lock order issues between this lock type and any other lock type
+tagged with the
+.Dv RWL_IS_VNODE
+flag.
+.It Dv RWL_NOWITNESS
+Instructs
+.Xr witness 4
+to ignore this lock.
+.El
+.Pp
+The
 .Fn rw_enter
 function acquires a lock.
 The
@@ -180,9 +209,11 @@ The
 functions support recursive write locking by the same process.
 They otherwise behave the same as their rwlock counterparts.
 .Sh CONTEXT
-.Fn rw_init
-and
+.Fn rw_init ,
+.Fn rw_init_flags ,
 .Fn rrw_init
+and
+.Fn rrw_init_flags
 can be called during autoconf, from process context, or from interrupt context.
 .Pp
 All other functions can be called during autoconf or from process context.