linux-kernel - [PATCH 4/4] man/man2/futex.2: Add a pointer to Linux' memory-barrier

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: <20250829160200.756194-5-bigeasy@linutronix.de>
Date: Fri, 29 Aug 2025 18:02:00 +0200
From: Sebastian Andrzej Siewior <bigeasy@...utronix.de>
To: linux-kernel@...r.kernel.org,
	linux-man@...r.kernel.org
Cc: Alejandro Colomar <alx@...nel.org>,
	André Almeida <andrealmeid@...lia.com>,
	Darren Hart <dvhart@...radead.org>,
	Davidlohr Bueso <dave@...olabs.net>,
	Ingo Molnar <mingo@...hat.com>,
	Juri Lelli <juri.lelli@...hat.com>,
	Peter Zijlstra <peterz@...radead.org>,
	Thomas Gleixner <tglx@...utronix.de>,
	Valentin Schneider <vschneid@...hat.com>,
	Waiman Long <longman@...hat.com>,
	Sebastian Andrzej Siewior <bigeasy@...utronix.de>
Subject: [PATCH 4/4] man/man2/futex.2: Add a pointer to Linux' memory-barrier

The "totally ordered with respect to concurrent operations" part refers
to memory ordering/ atomic update and has nothing to do with the inner
workings of the FUTEX code. It simply tries to express that the futex
operation will compare the supplied argument with that is written in
memory.

This might be a tad too verbose but then there is a fixme asking for
details on the sychronisation. Maybe a pointer to the memory barriers is
enough in terms of the required synchronisaton. Assuming this is related
to the memory value and not the futex internal synchronisation.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@...utronix.de>
---
 man/man2/futex.2 | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 027e91b826bf1..fe4a239c3812c 100644
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -84,16 +84,14 @@ on the same futex word.
 .\"     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?
+Please see
+.IR https://docs.kernel.org/\:next/\:core-api/\:wrappers/\:memory-barriers.html
+for the definition of atomic operations and memory ordering.
 Thus, the futex word is used to connect the synchronization in user space
 with the implementation of blocking by the kernel.
 Analogously to an atomic
 compare-and-exchange operation that potentially changes shared memory,
 blocking via a futex is an atomic compare-and-block operation.
-.\" FIXME(Torvald Riegel):
-.\" Eventually we want to have some text in NOTES to satisfy
-.\" the reference in the following sentence
-.\"     See NOTES for a detailed specification of
-.\"     the synchronization semantics.
 .P
 One use of futexes is for implementing locks.
 The state of the lock (i.e., acquired or not acquired)
-- 
2.51.0