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

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

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?

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