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. 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. Once the pieces get merged for 4.15, could you ping me/resend a patch for the 4.15 changes please. 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/ -- To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
