.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH MEMBARRIER 2 2017-11-15 "Linux" "Linux Programmer's Manual"
+.TH MEMBARRIER 2 2018-04-30 "Linux" "Linux Programmer's Manual"
.SH NAME
membarrier \- issue memory barriers on a set of threads
.SH SYNOPSIS
barriers, the fast-side memory barriers by simple compiler barriers,
for example:
.PP
- asm volatile ("" : : : "memory")
+.in +4n
+.EX
+asm volatile ("" : : : "memory")
+.EE
+.in
.PP
and replace the slow-side memory barriers by calls to
.BR membarrier ().
.I cmd
argument is one of the following:
.TP
-.B MEMBARRIER_CMD_QUERY
+.BR MEMBARRIER_CMD_QUERY " (since Linux 4.3)"
Query the set of supported commands.
The return value of the call is a bit mask of supported
commands.
.BR membarrier ()
is provided).
.TP
-.B MEMBARRIER_CMD_SHARED
+.BR 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
system call.
All threads on the system are targeted by this command.
.TP
-.B MEMBARRIER_CMD_PRIVATE_EXPEDITED
+.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED " (since Linux 4.16)"
+Execute a memory barrier on all running threads of all processes that
+previously registered with
+.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
+.IP
+Upon return from the system call, the calling thread has a guarantee 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 guarantee is provided only for the threads of processes that
+previously registered with
+.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
+.IP
+Given that registration is about the intent to receive the barriers, it
+is valid to invoke
+.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
+from a process that has not employed
+.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
+.IP
+The "expedited" commands complete faster than the non-expedited ones;
+they never block, but have the downside of causing extra overhead.
+.TP
+.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED " (since Linux 4.16)"
+Register the process's intent to receive
+.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED
+memory barriers.
+.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 caller
-thread is ensured that all its running threads siblings have passed
+process as the calling thread.
+.IP
+Upon return from the system call, the calling
+thread has a guarantee that all its running thread 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.
+(non-running threads are de facto in such a state).
+This guarantee is provided only for threads in
+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.
+.IP
+A process must 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_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)"
+Register the process's intent to use
.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED .
.TP
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)"
+In addition to providing the memory ordering guarantees described in
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+upon return from system call the calling thread has a guarantee that all its
+running thread siblings have executed a core serializing instruction.
+This guarantee is provided only for threads in
+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.
+.IP
+A process must register its intent to use the private expedited sync
+core command prior to using it.
+.TP
+.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)"
+Register the process's intent to use
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE .
+.TP
+.BR MEMBARRIER_CMD_SHARED " (since Linux 4.3)"
+This is an alias for
+.BR MEMBARRIER_CMD_GLOBAL
+that exists for header backward compatibility.
.PP
The
.I flags
On success, the
.B MEMBARRIER_CMD_QUERY
operation returns a bit mask of supported commands, and the
-.B MEMBARRIER_CMD_SHARED ,
-.B MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+.BR MEMBARRIER_CMD_GLOBAL ,
+.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED ,
+.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED ,
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED ,
+.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE ,
and
-.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED ,
+.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
operations return zero.
On error, \-1 is returned,
and
.I cmd
is invalid, or
.I flags
-is non-zero, or the
-.BR MEMBARRIER_CMD_SHARED
+is nonzero, or the
+.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
.SH CONFORMING TO
.BR membarrier ()
is Linux-specific.
-.in
-.SH SEE ALSO
-.BR cpu_opv (2) ,
-.BR rseq (2)
+.\" .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.
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;
}
slow_path(int *read_a)
{
b = 1;
- membarrier(MEMBARRIER_CMD_SHARED, 0);
+ membarrier(MEMBARRIER_CMD_GLOBAL, 0);
*read_a = a;
}
projects / thirdparty / man-pages.git / blobdiff