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

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

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
>