Re: [PATCH] membarrier.2: Update membarrier manpage for 5.10

[Peter Oskolkov <posk@google.com>]

On Wed, Nov 4, 2020 at 1:39 AM Alejandro Colomar
<colomar.6.4.3@gmail.com> wrote:
>
> Maybe I'd also add a paragraph in VERSIONS, saying there was an old
> version with a different prototype (and maybe show it there).
>
> What do you think about it?

Hi Alex,

I don't mind your re-doing my patch with the typo fix, updated
examples, and the addition to versions. Please
let me know if you would like to do that. If not, I'll send a new
patch with these changes.

Thanks,
Peter

>
> Thanks,
>
> Alex
>
> On 2020-11-03 22:01, Alejandro Colomar wrote:
> > Hi Peter,
> >
> > It looks very good! Just one typo:
> >
> > [[
> > .BI "int membarrier(int " cmd ", unsigned int " flags ", int " cpu_id );"
> > ]]
> > should be:
> > [[
> > .BI "int membarrier(int " cmd ", unsigned int " flags ", int " cpu_id );
> > ]]
> >
> > Note the removal of the last '"', which was unpaired.
> >
> >
> > Thanks,
> >
> > Alex
> >
> > On 2020-11-03 20:04, Peter Oskolkov wrote:
> >> Linux kernel commit 2a36ab717e8fe678d98f81c14a0b124712719840
> >> (part of 5.10 release) changed sys_membarrier prototype/parameters
> >> and added two new commands. This manpages patch reflects these
> >> changes, by mostly copying comments from the kernel patch
> >> into the manpage (I was also the author of the kernel change).
> >> ---
> >>   man2/membarrier.2 | 41 +++++++++++++++++++++++++++++++++++++++--
> >>   1 file changed, 39 insertions(+), 2 deletions(-)
> >>
> >> diff --git a/man2/membarrier.2 b/man2/membarrier.2
> >> index 3064b2d2e..c95e97cb6 100644
> >> --- a/man2/membarrier.2
> >> +++ b/man2/membarrier.2
> >> @@ -30,7 +30,7 @@ membarrier \- issue memory barriers on a set of threads
> >>   .PP
> >>   .B #include <linux/membarrier.h>
> >>   .PP
> >> -.BI "int membarrier(int " cmd ", int " flags ");"
> >> +.BI "int membarrier(int " cmd ", unsigned int " flags ", int " cpu_id
> >> );"
> >>   .fi
> >>   .PP
> >>   .IR Note :
> >> @@ -165,6 +165,29 @@ core command prior to using it.
> >>   Register the process's intent to use
> >>   .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE .
> >>   .TP
> >> +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)"
> >> +Ensure the caller thread, upon return from system call, that all its
> >> +running thread siblings have any currently running rseq critical
> >> sections
> >> +restarted if
> >> +.I flags
> >> +parameter is 0; if
> >> +.I flags
> >> +parameter is
> >> +.BR MEMBARRIER_CMD_FLAG_CPU ,
> >> +then this operation is performed only on CPU indicated by
> >> +.I cpu_id .
> >> +This guarantee is provided only for threads in
> >> +the same process as the calling thread.
> >> +.IP
> >> +RSEQ membarrier is only available in the "private expedited" form.
> >> +.IP
> >> +A process must register its intent to use the private expedited rseq
> >> +command prior to using it.
> >> +.TP
> >> +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)"
> >> +Register the process's intent to use
> >> +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ .
> >> +.TP
> >>   .BR MEMBARRIER_CMD_SHARED " (since Linux 4.3)"
> >>   This is an alias for
> >>   .BR MEMBARRIER_CMD_GLOBAL
> >> @@ -172,7 +195,21 @@ that exists for header backward compatibility.
> >>   .PP
> >>   The
> >>   .I flags
> >> -argument is currently unused and must be specified as 0.
> >> +argument must be specified as 0 unless the command is
> >> +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ ,
> >> +in which case
> >> +.I flags
> >> +can be either 0 or
> >> +.BR MEMBARRIER_CMD_FLAG_CPU .
> >> +.PP
> >> +The
> >> +.I cpu_id
> >> +argument is ignored unless
> >> +.I flags
> >> +is
> >> +.BR MEMBARRIER_CMD_FLAG_CPU ,
> >> +in which case it must specify the CPU targeted by this membarrier
> >> +command.
> >>   .PP
> >>   All memory accesses performed in program order from each targeted
> >> thread
> >>   are guaranteed to be ordered with respect to
> >>