Message-Id: <20171115191316.828-4-mathieu.desnoyers@efficios.com>
Date:   Wed, 15 Nov 2017 14:13:16 -0500
From:   Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
To:     Michael Kerrisk <mtk.manpages@...il.com>
Cc:     linux-kernel@...r.kernel.org, linux-api@...r.kernel.org,
        Peter Zijlstra <peterz@...radead.org>,
        "Paul E . McKenney" <paulmck@...ux.vnet.ibm.com>,
        Boqun Feng <boqun.feng@...il.com>,
        Andy Lutomirski <luto@...capital.net>,
        Dave Watson <davejwatson@...com>, Paul Turner <pjt@...gle.com>,
        Andrew Morton <akpm@...ux-foundation.org>,
        Russell King <linux@....linux.org.uk>,
        Thomas Gleixner <tglx@...utronix.de>,
        Ingo Molnar <mingo@...hat.com>,
        "H . Peter Anvin" <hpa@...or.com>, Andrew Hunter <ahh@...gle.com>,
        Andi Kleen <andi@...stfloor.org>, Chris Lameter <cl@...ux.com>,
        Ben Maurer <bmaurer@...com>,
        Steven Rostedt <rostedt@...dmis.org>,
        Josh Triplett <josh@...htriplett.org>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        Catalin Marinas <catalin.marinas@....com>,
        Will Deacon <will.deacon@....com>,
        Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
Subject: [RFC PATCH manpages 3/3] Update membarrier manpage for 4.14, 4.15

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

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
CC: "Paul E. McKenney" <paulmck@...ux.vnet.ibm.com>
CC: Peter Zijlstra <peterz@...radead.org>
CC: Paul Turner <pjt@...gle.com>
CC: Thomas Gleixner <tglx@...utronix.de>
CC: Andrew Hunter <ahh@...gle.com>
CC: Andy Lutomirski <luto@...capital.net>
CC: Andi Kleen <andi@...stfloor.org>
CC: Dave Watson <davejwatson@...com>
CC: Chris Lameter <cl@...ux.com>
CC: Ingo Molnar <mingo@...hat.com>
CC: "H. Peter Anvin" <hpa@...or.com>
CC: Ben Maurer <bmaurer@...com>
CC: Steven Rostedt <rostedt@...dmis.org>
CC: Josh Triplett <josh@...htriplett.org>
CC: Linus Torvalds <torvalds@...ux-foundation.org>
CC: Andrew Morton <akpm@...ux-foundation.org>
CC: Russell King <linux@....linux.org.uk>
CC: Catalin Marinas <catalin.marinas@....com>
CC: Will Deacon <will.deacon@....com>
CC: Michael Kerrisk <mtk.manpages@...il.com>
CC: Boqun Feng <boqun.feng@...il.com>
CC: linux-api@...r.kernel.org
---
 man2/membarrier.2 | 98 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 84 insertions(+), 14 deletions(-)

diff --git a/man2/membarrier.2 b/man2/membarrier.2
index bbf611e10..6720d20f3 100644
--- a/man2/membarrier.2
+++ b/man2/membarrier.2
@@ -1,4 +1,4 @@
-.\" Copyright 2015 Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
+.\" Copyright 2015-2017 Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
 .\"
 .\" %%%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,60 @@ order between entry to and return from the
 .BR membarrier ()
 system call.
 All threads on the system are targeted by this command.
+.TP
+.B MEMBARRIER_CMD_SHARED_EXPEDITED
+Execute a memory barrier on all running threads part of a process which
+previously registered with
+.BR MEMBARRIER_CMD_REGISTER_SHARED_EXPEDITED .
+Upon return from system call, the caller thread is ensured that all
+running threads 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 only covers threads from processes which registered with
+.BR MEMBARRIER_CMD_REGISTER_SHARED_EXPEDITED .
+Given that registration is about the intent to receive the barriers, it
+is valid to invoke
+.BR MEMBARRIER_CMD_SHARED_EXPEDITED
+from a non-registered process.
+.TP
+.B MEMBARRIER_CMD_REGISTER_SHARED_EXPEDITED
+Register the process intent to receive
+.BR MEMBARRIER_CMD_SHARED_EXPEDITED
+memory barriers.
+.TP
+.B MEMBARRIER_CMD_PRIVATE_EXPEDITED
+Execute a memory barrier on each running thread belonging to the same
+process as the current thread. Upon return from system call, the caller
+thread is ensured 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 only covers
+threads from the same process as the caller thread. 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
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED
+Register the process intent to use
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED .
+.TP
+.B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+In addition to provide memory ordering guarantees described in
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+ensure the caller thread, upon return from system call, that all its
+running threads siblings have executed a core serializing instruction.
+(architectures are required to guarantee that non-running threads issue
+core serializing instructions before they resume user-space execution).
+This only covers threads from the same process as the caller thread.
+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 sync
+core command prior to using it.
+.TP
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
+Register the process intent to use
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE .
 .PP
 The
 .I flags
@@ -117,9 +171,16 @@ 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_SHARED_EXPEDITED ,
+.B MEMBARRIER_CMD_REGISTER_SHARED_EXPEDITED ,
+.B MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED ,
+.B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE ,
+and
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE 
+operations return zero.
 On error, \-1 is returned,
 and
 .I errno
@@ -138,22 +199,27 @@ 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 architecture does not implement the
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+and
+.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
+commands, 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 +228,10 @@ system call was added in Linux 4.3.
 .SH CONFORMING TO
 .BR membarrier ()
 is Linux-specific.
+.in
+.SH SEE ALSO
+.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.
-- 
2.11.0

Powered by blists - more mailing lists