linux-kernel - Re: futex(3) man page, final draft for pre-release review

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <5674FF20.9030609@gmail.com>
Date:	Sat, 19 Dec 2015 07:54:24 +0100
From:	"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:	Torvald Riegel <triegel@...hat.com>
Cc:	mtk.manpages@...il.com, Darren Hart <dvhart@...radead.org>,
	Thomas Gleixner <tglx@...utronix.de>,
	lkml <linux-kernel@...r.kernel.org>,
	libc-alpha <libc-alpha@...rceware.org>,
	linux-man <linux-man@...r.kernel.org>,
	Carlos O'Donell <carlos@...hat.com>,
	Roland McGrath <roland@...k.frob.com>,
	Davidlohr Bueso <dave@...olabs.net>,
	Jakub Jelinek <jakub@...hat.com>, Ingo Molnar <mingo@...e.hu>,
	bill o gallmeister <bgallmeister@...il.com>,
	bert hubert <bert.hubert@...herlabs.nl>,
	Jan Kiszka <jan.kiszka@...mens.com>,
	Eric Dumazet <edumazet@...gle.com>,
	Arnd Bergmann <arnd@...db.de>,
	Rusty Russell <rusty@...tcorp.com.au>,
	Heinrich Schuchardt <xypron.glpk@....de>,
	Andy Lutomirski <luto@...capital.net>,
	Daniel Wagner <wagi@...om.org>,
	Anton Blanchard <anton@...ba.org>,
	Steven Rostedt <rostedt@...dmis.org>,
	Rich Felker <dalias@...c.org>,
	Jonathan Wakely <jwakely@...hat.com>,
	Mike Frysinger <vapier@...too.org>
Subject: Re: futex(3) man page, final draft for pre-release review

On 12/18/2015 12:11 PM, Torvald Riegel wrote:
> On Wed, 2015-12-16 at 16:54 +0100, Michael Kerrisk (man-pages) wrote:
>> Hello Darren,
>>
>> On 12/15/2015 10:18 PM, Darren Hart wrote:
>>> On Tue, Dec 15, 2015 at 02:43:50PM +0100, Michael Kerrisk (man-pages) wrote:
>>
>> [...]
>>
>>>>        When executing a futex operation that requests to block a thread,
>>>>        the kernel will block only if the futex word has the  value  that
>>>>        the  calling  thread  supplied  (as  one  of the arguments of the
>>>>        futex() call) as the expected value of the futex word.  The load‐
>>>>        ing  of the futex word's value, the comparison of that value with
>>>>        the expected value, and the actual blocking  will  happen  atomi‐
>>>>
>>>> FIXME: for next line, it would be good to have an explanation of
>>>> "totally ordered" somewhere around here.
>>>>
>>>>        cally  and totally ordered with respect to concurrently executing
>>>
>>> Totally ordered with respect futex operations refers to semantics of the
>>> ACQUIRE/RELEASE operations and how they impact ordering of memory reads and
>>> writes. The kernel futex operations are protected by spinlocks, which ensure
>>> that that all operations are serialized with respect to one another.
>>>
>>> This is a lot to attempt to define in this document. Perhaps a reference to
>>> linux/Documentation/memory-barriers.txt as a footnote would be sufficient? Or
>>> perhaps for this manual, "serialized" would be sufficient, with a footnote
>>> regarding "totally ordered" and a pointer to the memory-barrier documentation?
>>
>> I think I'll just settle for writing serialized in the man page, and be 
>> done with it :-).
> 
> I'd prefer if you'd not just use "serialized" :)  

Sigh :-). Okay--removed.

> Eventually, I'd prefer
> if we can explain the semantics for the user in terms of the terminology
> and semantics of the memory model of the programming language that users
> will likely use to call futex ops (ie, C11 / C++11).

And I'd be really happy to see such an explanation land in the page.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/