linux-kernel - [PATCH 1/1] docs/memory-barriers.txt: Add wait_event_cmd() and wait_event_exclusive

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250626143707.1533808-1-haakon.bugge@oracle.com>
Date: Thu, 26 Jun 2025 16:37:05 +0200
From: Håkon Bugge <haakon.bugge@...cle.com>
To: Alan Stern <stern@...land.harvard.edu>,
        Andrea Parri <parri.andrea@...il.com>, Will Deacon <will@...nel.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Boqun Feng <boqun.feng@...il.com>, Nicholas Piggin <npiggin@...il.com>,
        David Howells <dhowells@...hat.com>,
        Jade Alglave <j.alglave@....ac.uk>,
        Luc Maranget <luc.maranget@...ia.fr>,
        "Paul E. McKenney" <paulmck@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>, Daniel Lustig <dlustig@...dia.com>,
        Joel Fernandes <joelagnelf@...dia.com>,
        Jonathan Corbet <corbet@....net>
Cc: Håkon Bugge <haakon.bugge@...cle.com>,
        linux-kernel@...r.kernel.org, linux-arch@...r.kernel.org,
        lkmm@...ts.linux.dev, linux-doc@...r.kernel.org
Subject: [PATCH 1/1] docs/memory-barriers.txt: Add wait_event_cmd() and wait_event_exclusive_cmd()

Add said functions to the documentation and relate them to userspace's
pthread_cond_wait(). The latter because when searching for
functionality comparable to pthread_cond_wait(), it is very hard to
find wait_event_cmd().

Signed-off-by: Håkon Bugge <haakon.bugge@...cle.com>
---
 Documentation/memory-barriers.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 93d58d9a428b8..d721e9be5a4f5 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -2192,6 +2192,8 @@ interpolate the memory barrier in the right place:
 	wait_event_timeout();
 	wait_on_bit();
 	wait_on_bit_lock();
+	wait_event_cmd();
+	wait_event_exclusive_cmd();
 
 
 Secondly, code that performs a wake up normally follows something like this:
@@ -2296,6 +2298,15 @@ and the waker should do:
 	event_indicated = 1;
 	wake_up(&event_wait_queue);
 
+Note that the wait_event_cmd() and wait_event_exclusive_cmd() are the
+kernel's polymorphic implementation of userspace's
+pthread_cond_wait().
+
+Using wait_event_cmd() or wait_event_exclusive_cmd(), cmd1 is
+typically a lock-release call and cmd2 a lock-acquire call. The
+locking primitive can be chosen, contrary to pthread_cond_wait(),
+where the locking type is cast in stone and is a pthread_mutex_t.
+
 
 MISCELLANEOUS FUNCTIONS
 -----------------------
-- 
2.43.5