LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

membarrier.2: Document new membarrier commands introduced in Linux 4.16 

Document the following membarrier commands introduced in
Linux 4.16:

    MEMBARRIER_CMD_GLOBAL_EXPEDITED
        (the old enum label MEMBARRIER_CMD_SHARED is now an
        alias to preserve header backward compatibility)
    MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED
    MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
    MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
CC: Michael Kerrisk <mtk.manpages@gmail.com>
CC: Ingo Molnar <mingo@redhat.com>
CC: Peter Zijlstra <peterz@infradead.org>
CC: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Mathieu Desnoyers 2018-02-12 14:55:49 -05:00 committed by Michael Kerrisk
parent 2f72816f86
commit f5a563c0c4
1 changed files with 62 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
man2/membarrier.2
View File

@ -80,7 +80,7 @@ This command is always supported (on kernels where
.BR membarrier ()
is provided).
.TP
.B MEMBARRIER_CMD_SHARED
.B MEMBARRIER_CMD_GLOBAL " (since Linux 4.16)"
Ensure that all threads from all processes on the system pass through a
state where all memory accesses to user-space addresses match program
order between entry to and return from the
@ -88,7 +88,30 @@ order between entry to and return from the
system call.
All threads on the system are targeted by this command.
.TP
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)"
.B MEMBARRIER_CMD_GLOBAL_EXPEDITED " (since Linux 4.16)"
Execute a memory barrier on all running threads of all processes which
previously registered with
.BR MEMBARRIER_CMD_REGISTER_GLOBAL_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_GLOBAL_EXPEDITED .
Given that registration is about the intent to receive the barriers, it
is valid to invoke
.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
from a non-registered process.
.IP
The "expedited" commands complete faster than the non-expedited ones;
they never block, but have the downside of causing extra overhead.
.TP
.B MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED " (since Linux 4.16)"
Register the process intent to receive
.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
memory barriers.
.TP
.B 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
@ -103,9 +126,29 @@ 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)"
.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)"
Register the process's intent to use
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED .
.B MEMBARRIER_CMD_PRIVATE_EXPEDITED .
.TP
.B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)"
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.
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 " (since Linux 4.16)"
Register the process intent to use
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE .
.TP
.B MEMBARRIER_CMD_SHARED
Alias to
.BR MEMBARRIER_CMD_GLOBAL .
Provided for header backward compatibility.
.PP
The
.I flags
@ -137,10 +180,14 @@ The pair ordering is detailed as (O: ordered, X: not ordered):
On success, the
.B MEMBARRIER_CMD_QUERY
operation returns a bit mask of supported commands, and the
.B MEMBARRIER_CMD_SHARED ,
.B MEMBARRIER_CMD_GLOBAL ,
.B MEMBARRIER_CMD_GLOBAL_EXPEDITED ,
.B MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED ,
.B MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
and
.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
@ -163,10 +210,14 @@ set to 0, error handling is required only for the first call to
is invalid, or
.I flags
is nonzero, or the
.BR MEMBARRIER_CMD_SHARED
.BR MEMBARRIER_CMD_GLOBAL
command is disabled because the
.I nohz_full
CPU parameter has been set.
CPU parameter has been set, or the
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
and
.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
commands are not implemented by the architecture.
.TP
.B ENOSYS
The
@ -294,9 +345,9 @@ init_membarrier(void)
return \-1;
}
if (!(ret & MEMBARRIER_CMD_SHARED)) {
if (!(ret & MEMBARRIER_CMD_GLOBAL)) {
fprintf(stderr,
"membarrier does not support MEMBARRIER_CMD_SHARED\\n");
"membarrier does not support MEMBARRIER_CMD_GLOBAL\\n");
return \-1;
}
@ -315,7 +366,7 @@ static void
slow_path(int *read_a)
{
b = 1;
membarrier(MEMBARRIER_CMD_SHARED, 0);
membarrier(MEMBARRIER_CMD_GLOBAL, 0);
*read_a = a;
}