From nobody Sun Jun 23 21:48:06 2024 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4W6l863jxQz5P4R0; Sun, 23 Jun 2024 21:48:06 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4W6l861WnQz4Ydx; Sun, 23 Jun 2024 21:48:06 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1719179286; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bsRCOAflU9F8JEj3yRvg3FC0JN01BH3bi19pMBNIuR8=; b=p3TKa4A7wszK2pdSNTjOPpRYhuEbEim+7d3QaVlWEjS/wof7fEu/FP3ekG7MyGgHYMrYwW RsSQX3hxEv5UtRtabmt8ATYqMwRiONGjSIRaeKWQx8aZUbXNZDm83i/3HQRkyGIcfE9xdc X4qUqOLq5MFrOQHYQIWzoTy4M2Bxz4VO5vseKwREiuZgeXf1mCjCwdZCcL/ZzcIKeA5pm3 OZOPaoCBZsMcEgp/dtX6WF0C34Xkd+YgHiT5/JKIEufFyI77AFWTxaBVYkhN1p+myHwkyB S1FiERYsBYbBi8qOROC2VOe/NqMX2mlnSbZ9v+417yRwA4B1UU3cLzurK8RwYA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1719179286; a=rsa-sha256; cv=none; b=TcKm84oJR78Gcq1e2OXYUe/e7FWiW5i2jzbWR8/UYS6Q5pOWSisC7j8VYnL0w0aMphtCdb rK1m6HazyXK/WIMNd3sWC0ejqB5jWyVyjvy0rFBpiLBEmUq7lnyMNg+HXzHIASOGnfhMzu V76dX+AWC2Mf/Y9A5mNYqDjscq3USHP/0ZQ7mWBGHSusqsb6KxzPRicnJf8Q11J+S343VM vEd1vdzs9K803plixN1ejuTmk8YBEvkisKDKEj4cty+1bk+TrEaTfq0aJnm6opeC8BUwiD ADwWlD1ke4mEHyXGVIG6oj8nUdP0NyeI49XASoaPvH5QlGQdpBe9A+1SCvF6Hg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1719179286; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bsRCOAflU9F8JEj3yRvg3FC0JN01BH3bi19pMBNIuR8=; b=DeLAYxlxXjYcm12AidOudJ6+/kOHRHkOn7L13BwEV1fh0DjoYq5UFORGGSLt8LCj3ecGJf oMwU8EKRRJ7osq05IW5Xvnd46aSEoTbqYNSmQO0CA+baHIhMFrHsw/ZIC4Rp5Xubi4x97R 0j7J0XONSDpMVjv0LvUNhDNskXzmymxkD7NBPc0zY+tLe2k7c+fGzUeKyW9Jsl0KM47c0P WIyU6XfkVjLWq3TnnGm0MJzFVoDA4sMKDykRLMuGOgHBZJ5tg+MRm5Sb2chXJBUkFZrIwM nLvI6SuS+xW6/V06xfPSeAVtir/JpS3Nzs2TEyGmBdUSwY5yuyjjEwuUE2xhnQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4W6l8614ntzryD; Sun, 23 Jun 2024 21:48:06 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 45NLm6J7063937; Sun, 23 Jun 2024 21:48:06 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 45NLm64v063934; Sun, 23 Jun 2024 21:48:06 GMT (envelope-from git) Date: Sun, 23 Jun 2024 21:48:06 GMT Message-Id: <202406232148.45NLm64v063934@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Ryan Libby Subject: git: fda32d586035 - main - lock.9: describe lockmgr_{disowned,lock_flags,slock,unlock,xlock} List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: rlibby X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: fda32d586035f0bead930ecdb4547869e1c80fb5 Auto-Submitted: auto-generated The branch main has been updated by rlibby: URL: https://cgit.FreeBSD.org/src/commit/?id=fda32d586035f0bead930ecdb4547869e1c80fb5 commit fda32d586035f0bead930ecdb4547869e1c80fb5 Author: Ryan Libby AuthorDate: 2024-06-23 21:46:31 +0000 Commit: Ryan Libby CommitDate: 2024-06-23 21:46:31 +0000 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 ,