From fda32d586035f0bead930ecdb4547869e1c80fb5 Mon Sep 17 00:00:00 2001
From: Ryan Libby <rlibby@FreeBSD.org>
Date: Sun, 23 Jun 2024 14:46:31 -0700
Subject: [PATCH] lock.9: describe
 lockmgr_{disowned,lock_flags,slock,unlock,xlock}

Describe and link the following functions in the lockgmr API:
 - lockmgr_disowned
 - lockmgr_lock_flags
 - lockmgr_slock
 - lockmgr_unlock
 - lockmgr_xlock

This is not a complete update of lock.9 but at least covers all the main
lock operations.

Reviewed by:	gbe, kib
Sponsored by:	Dell EMC Isilon
Differential Revision:	https://reviews.freebsd.org/D45689
---
 share/man/man9/Makefile |  5 ++++
 share/man/man9/lock.9   | 63 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index dfc9bd996504..38d836b1647a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1431,9 +1431,14 @@ MLINKS+=lock.9 lockdestroy.9 \
 	lock.9 lockmgr_args_rw.9 \
 	lock.9 lockmgr_assert.9 \
 	lock.9 lockmgr_disown.9 \
+	lock.9 lockmgr_disowned.9 \
+	lock.9 lockmgr_lock_flags.9 \
 	lock.9 lockmgr_printinfo.9 \
 	lock.9 lockmgr_recursed.9 \
 	lock.9 lockmgr_rw.9 \
+	lock.9 lockmgr_slock.9 \
+	lock.9 lockmgr_unlock.9 \
+	lock.9 lockmgr_xlock.9 \
 	lock.9 lockstatus.9
 MLINKS+=LOCK_PROFILING.9 MUTEX_PROFILING.9
 MLINKS+=make_dev.9 destroy_dev.9 \
diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9
index 96f617a72123..9cff6e3bd8aa 100644
--- a/share/man/man9/lock.9
+++ b/share/man/man9/lock.9
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 .\" DAMAGE.
 .\"
-.Dd May 18, 2024
+.Dd June 21, 2024
 .Dt LOCK 9
 .Os
 .Sh NAME
@@ -34,9 +34,14 @@
 .Nm lockmgr_args ,
 .Nm lockmgr_args_rw ,
 .Nm lockmgr_disown ,
+.Nm lockmgr_disowned ,
+.Nm lockmgr_lock_flags ,
 .Nm lockmgr_printinfo ,
 .Nm lockmgr_recursed ,
 .Nm lockmgr_rw ,
+.Nm lockmgr_slock ,
+.Nm lockmgr_unlock ,
+.Nm lockmgr_xlock ,
 .Nm lockstatus ,
 .Nm lockmgr_assert
 .Nd "lockmgr family of functions"
@@ -56,6 +61,10 @@
 .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo"
 .Ft void
 .Fn lockmgr_disown "struct lock *lkp"
+.Ft int
+.Fn lockmgr_disowned "const struct lock *lkp"
+.Ft int
+.Fn lockmgr_lock_flags "struct lock *lkp" "u_int flags" "struct lock_object *ilk" "const char *file" "int line"
 .Ft void
 .Fn lockmgr_printinfo "const struct lock *lkp"
 .Ft int
@@ -63,6 +72,12 @@
 .Ft int
 .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk"
 .Ft int
+.Fn lockmgr_slock "struct lock *lkp" "u_int flags" "const char *file" "int line"
+.Ft int
+.Fn lockmgr_unlock "struct lock *lkp"
+.Ft int
+.Fn lockmgr_xlock "struct lock *lkp" "u_int flags" "const char *file" "int line"
+.Ft int
 .Fn lockstatus "const struct lock *lkp"
 .Pp
 .Cd "options INVARIANTS"
@@ -253,12 +268,55 @@ and
 .Dv LK_TIMO_DEFAULT .
 .Pp
 The
+.Fn lockmgr_lock_flags
+function works like
+.Fn lockmgr
+but accepts explicit
+.Fa file
+and
+.Fa line
+arguments for lock tracing.
+.Pp
+The
+.Fn lockmgr_slock ,
+.Fn lockmgr_xlock ,
+and
+.Fn lockmgr_unlock
+functions are lightweight entry points that function like
+.Fn lockmgr
+for the
+.Dv LK_SHARED ,
+.Dv LK_EXCLUSIVE ,
+and
+.Dv LK_RELEASE
+operations respectively.
+They provide functionality similar to
+.Xr sx 9
+locks in that none of the additional
+.Xr lockmgr 9
+features are supported.
+Specifically, these functions do not support unlocking interlocks, the
+.Dv LK_SLEEPFAIL
+flag, or locks with shared locking disabled via
+.Dv LK_NOSHARE .
+They also accept explicit
+.Fa file
+and
+.Fa line
+arguments for lock tracing.
+.Pp
+The
 .Fn lockmgr_disown
 function switches the owner from the current thread to be
 .Dv LK_KERNPROC ,
 if the lock is already held.
 .Pp
 The
+.Fn lockmgr_disowned
+function returns true or false according to whether the lock is held by
+.Dv LK_KERNPROC .
+.Pp
+The
 .Fn lockmgr_printinfo
 function prints debugging information about the lock.
 It is used primarily by
@@ -354,6 +412,8 @@ was requested and another thread had already requested a lock upgrade.
 was set, and a sleep would have been required, or
 .Dv LK_TRYUPGRADE
 operation was not able to upgrade the lock.
+.It Bq Er EDEADLK
+A shared lock was attempted while the thread already held the exclusive lock.
 .It Bq Er ENOLCK
 .Dv LK_SLEEPFAIL
 was set and
@@ -398,6 +458,7 @@ exclusive lock, and a
 .Xr panic 9
 will be the result of trying.
 .Sh SEE ALSO
+.Xr witness 4 ,
 .Xr condvar 9 ,
 .Xr locking 9 ,
 .Xr mtx_assert 9 ,