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

[Sebastian Andrzej Siewior <bigeasy@linutronix.de>]

On 2025-08-29 13:46:19 [-0400], Carlos O'Donell wrote:
> On 8/29/25 12:02 PM, Sebastian Andrzej Siewior wrote:
> > 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@linutronix.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.
> 
> This seems out of place with the flow of the rest of the text.
> 
> I suggest adding this as a foot note.
> 
> >   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.
> 
> I think it is acceptable to link to Documentation/memory-barriers.rst, but
> the truth is that this document doesn't yet provide all the notes required
> to answer the questions wrt a futex. Fundamentally we use spinlocks for futexes
> (and some arches use more like parisc), and spinlocks are covered in
> "Implicit Kernel Memory Barrires", there isn't any direct connection between
> them in the text (and doing so would create a design requirement).

There might be two things to it. The spinlocks are used in kernel and
synchronize the kernel internal state. The memory barriers might be
important in regard to how the futex word should be updated atomically.

> >   .P
> >   One use of futexes is for implementing locks.
> >   The state of the lock (i.e., acquired or not acquired)

Sebastian