.\" Copyright 2015 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.TH MEMBARRIER 2 2015-04-15 "Linux" "Linux Programmer's Manual"
.SH NAME
membarrier \- issue memory barriers on a set of threads
.SH SYNOPSIS
.B #include <linux/membarrier.h>
.sp
.BI "int membarrier(int " cmd ", int " flags ");
.sp
.SH DESCRIPTION
The
.I cmd
argument is one of the following:

.TP
.B MEMBARRIER_CMD_QUERY
Query the set of supported commands. It returns a bitmask of supported
commands.
.TP
.B MEMBARRIER_CMD_SHARED
Execute a memory barrier on all threads running on the system. 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 covers threads from all processes running on the system.
This command returns 0.

.PP
The
.I flags
argument is currently unused.

.PP
All memory accesses performed in program order from each targeted thread
is guaranteed to be ordered with respect to sys_membarrier(). If we use
the semantic "barrier()" to represent a compiler barrier forcing memory
accesses to be performed in program order across the barrier, and
smp_mb() to represent explicit memory barriers forcing full memory
ordering across the barrier, we have the following ordering table for
each pair of barrier(), sys_membarrier() and smp_mb():

The pair ordering is detailed as (O: ordered, X: not ordered):

                       barrier()   smp_mb() sys_membarrier()
       barrier()          X           X            O
       smp_mb()           X           O            O
       sys_membarrier()   O           O            O

.SH RETURN VALUE
On success, these system calls return zero.  On error, \-1 is returned,
and
.I errno
is set appropriately.
For a given command, with flags argument set to 0, this system call is
guaranteed to always return the same value until reboot.
.SH ERRORS
.TP
.B ENOSYS
System call is not implemented.
.TP
.B EINVAL
Invalid arguments.