Re: [RFC PATCH 3/3] Update membarrier manpage for 4.14, 4.15

[Mathieu Desnoyers]

----- On Nov 19, 2017, at 6:12 AM, Michael Kerrisk mtk.manpages@xxxxxxxxx wrote:

> Hi Mathieu,
> 
> On 11/16/2017 04:17 PM, Mathieu Desnoyers wrote:
>> Add documentation for those new membarrier commands:
>> 
>> New in 4.14:
>>         MEMBARRIER_CMD_PRIVATE_EXPEDITED
>>         MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED
>> 
>> Adapt the MEMBARRIER_CMD_SHARED return value documentation to reflect
>> that it now returns -EINVAL when issued on a system configured for
>> nohz_full.
>> 
>> New in 4.15:
>>         MEMBARRIER_CMD_SHARED_EXPEDITED
>>         MEMBARRIER_CMD_REGISTER_SHARED_EXPEDITED
> 
> Combining details into one patch in this way makes things more difficult
> for me. I would prefer these details to be split into separate pieces
> for the 4.14 and 4.15 changes, in part because of the way the man-pages
> release cycle currently works (roughly synchronized with kernel releases)
> and also because the 4.15 details might change.

Sorry about that. I did not expect that you'd pick up the change
right away given the RFC tag.

> 
> I've applied the 4.14 details from this patch to the man page; if you had a
> chance to check whether I did that job correctly, that would be great.
> See the patch below.

Yes, looks good. There is one specific paragraph that I think may need
rewording now that I read it again:

       For  a  given command, with flags set to 0, this system call is guaranâ
       teed to always return the same value until reboot.  Further calls  with
       the same arguments will lead to the same result.  Therefore, with flags
       set to 0, error handling is required only for the first call to membarâ
       rier().

This is now untrue for the MEMBARRIER_CMD_PRIVATE_EXPEDITED command, which
may return EPERM before the registration is performed, and then return
0 once the registration is done for the process. I'm not entirely sure
how to word this.


> 
> Once the pieces get merged for 4.15, could you ping me/resend a patch for
> the 4.15 changes please.

Of course,

Thanks!

Mathieu

> 
> Cheers,
> 
> Michael
> 
> 
> diff --git a/man2/membarrier.2 b/man2/membarrier.2
> index bbf611e10..6390f9693 100644
> --- a/man2/membarrier.2
> +++ b/man2/membarrier.2
> @@ -1,4 +1,4 @@
> -.\" Copyright 2015 Mathieu Desnoyers <mathieu.desnoyers@xxxxxxxxxxxx>
> +.\" Copyright 2015-2017 Mathieu Desnoyers <mathieu.desnoyers@xxxxxxxxxxxx>
> .\"
> .\" %%%LICENSE_START(VERBATIM)
> .\" Permission is granted to make and distribute verbatim copies of this
> @@ -22,7 +22,7 @@
> .\" the source, must acknowledge the copyright and authors of this work.
> .\" %%%LICENSE_END
> .\"
> -.TH MEMBARRIER 2 2017-09-15 "Linux" "Linux Programmer's Manual"
> +.TH MEMBARRIER 2 2017-11-15 "Linux" "Linux Programmer's Manual"
> .SH NAME
> membarrier \- issue memory barriers on a set of threads
> .SH SYNOPSIS
> @@ -87,6 +87,25 @@ order between entry to and return from the
> .BR membarrier ()
> system call.
> All threads on the system are targeted by this command.
> +.TP
> +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)"
> +Execute a memory barrier on each running thread belonging to the same
> +process as the current thread.
> +Upon return from system call, the calling
> +thread is assured that all its running threads siblings have passed
> +through a state where all memory accesses to user-space addresses match
> +program order between entry to and return from the system call
> +(non-running threads are de facto in such a state).
> +This covers only threads from the same process as the calling thread.
> +.IP
> +The "expedited" commands complete faster than the non-expedited ones;
> +they never block, but have the downside of causing extra overhead.
> +A process needs to register its intent to use the private
> +expedited command prior to using it.
> +.TP
> +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)"
> +Register the process's intent to use
> +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED .
> .PP
> The
> .I flags
> @@ -117,9 +136,12 @@ The pair ordering is detailed as (O: ordered, X: not
> ordered):
> .SH RETURN VALUE
> On success, the
> .B MEMBARRIER_CMD_QUERY
> -operation returns a bit mask of supported commands and the
> -.B MEMBARRIER_CMD_SHARED
> -operation returns zero.
> +operation returns a bit mask of supported commands, and the
> +.B MEMBARRIER_CMD_SHARED ,
> +.B MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
> +and
> +.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED ,
> +operations return zero.
> On error, \-1 is returned,
> and
> .I errno
> @@ -138,22 +160,22 @@ set to 0, error handling is required only for the first
> call to
> .TP
> .B EINVAL
> .I cmd
> -is invalid or
> +is invalid, or
> .I flags
> -is non-zero.
> +is non-zero, or the
> +.BR MEMBARRIER_CMD_SHARED
> +command is disabled because the
> +.I nohz_full
> +CPU parameter has been set.
> .TP
> .B ENOSYS
> The
> .BR membarrier ()
> system call is not implemented by this kernel.
> .TP
> -.BR ENOSYS " (since Linux 4.11)"
> -.\" 907565337ebf998a68cb5c5b2174ce5e5da065eb
> -The
> -.BR membarrier ()
> -system call is disabled because the
> -.I nohz_full
> -CPU parameter has been set.
> +.B EPERM
> +The current process was not registered prior to using private expedited
> +commands.
> .SH VERSIONS
> The
> .BR membarrier ()
> @@ -162,6 +184,10 @@ system call was added in Linux 4.3.
> .SH CONFORMING TO
> .BR membarrier ()
> is Linux-specific.
> +.\" .SH SEE ALSO
> +.\" FIXME See if the following syscalls make it into Linux 4.15 or later
> +.\" .BR cpu_opv (2),
> +.\" .BR rseq (2)
> .SH NOTES
> A memory barrier instruction is part of the instruction set of
> architectures with weakly-ordered memory models.
> 
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com