linux-kernel - Re: [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-prev] [day] [month] [year] [list]

Message-ID: <DB1B2B27-F7D4-4C5F-B9E2-4B06F5258A83@oracle.com>
Date: Thu, 26 Jun 2025 16:18:59 +0000
From: Haakon Bugge <haakon.bugge@...cle.com>
To: Matthew Wilcox <willy@...radead.org>
CC: 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>,
        "linux-kernel@...r.kernel.org"
	<linux-kernel@...r.kernel.org>,
        "linux-arch@...r.kernel.org"
	<linux-arch@...r.kernel.org>,
        "lkmm@...ts.linux.dev" <lkmm@...ts.linux.dev>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>
Subject: Re: [PATCH 1/1] docs/memory-barriers.txt: Add wait_event_cmd() and
 wait_event_exclusive_cmd()



> On 26 Jun 2025, at 17:17, Matthew Wilcox <willy@...radead.org> wrote:
> 
> On Thu, Jun 26, 2025 at 04:37:05PM +0200, Håkon Bugge wrote:
>> 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().
> 
> Would it not go better in the kernel-doc for wait_event_cmd() in
> include/linux/wait.h?

What about both? The list with wait_foo_bars() in Documentation/memory-barriers.txt misses wait_event_cmd() and wait_event_exclusive_cmd().

But my prosaic explanation could very well go into include/linux/wait.h

>> +Note that the wait_event_cmd() and wait_event_exclusive_cmd() are the
>> +kernel's polymorphic implementation of userspace's
>> +pthread_cond_wait().
> 
> Pet peeve: "Note that" adds nothing to this sentence.  You can just
> write:
> 
> The wait_event_cmd() and wait_event_exclusive_cmd() functions are the
> kernel's polymorphic implementation of userspace's pthread_cond_wait().

Me blushing! +1

Thxs, Håkon

> 
>> +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
>> 
>>