mirror of https://github.com/mkerrisk/man-pages
membarrier.2: Minor fixups to Mathieu's text
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
d06aa1bf7a
commit
7e6241dc67
|
|
@ -31,37 +31,40 @@ membarrier \- issue memory barriers on a set of threads
|
|||
.BI "int membarrier(int " cmd ", int " flags ");
|
||||
.sp
|
||||
.SH DESCRIPTION
|
||||
The membarrier system call helps reducing overhead of memory barrier
|
||||
The
|
||||
.BR membarrier ()
|
||||
system call helps reducing the overhead of the memory barrier
|
||||
instructions required to order memory accesses on multi-core systems.
|
||||
However, this system call is heavier than a memory barrier, so using it
|
||||
effectively is
|
||||
.B not
|
||||
.I not
|
||||
as simple as replacing memory barriers with this
|
||||
system call, but requires understanding the following:
|
||||
system call, but requires understanding of the details below.
|
||||
|
||||
Use of memory barriers needs to be done taking into account that a
|
||||
memory barrier always needs to be either matched with its memory barrier
|
||||
counterparts, or that the architecture's memory model don't require the
|
||||
counterparts, or that the architecture's memory model doesn't require the
|
||||
matching barriers.
|
||||
|
||||
There are cases where one side of the matching barriers (which we will
|
||||
refer to as "fast side") is executed much more often than the other
|
||||
(which we will refer to as "slow side"). This is a prime target for the
|
||||
membarrier system call. The key idea is to replace, for these matching
|
||||
barriers, the fast side memory barriers by simple compiler barriers,
|
||||
e.g.:
|
||||
(which we will refer to as "slow side").
|
||||
This is a prime target for the use of
|
||||
.BR membarrier ().
|
||||
The key idea is to replace, for these matching
|
||||
barriers, the fast-side memory barriers by simple compiler barriers,
|
||||
for example:
|
||||
|
||||
asm volatile ("" : : : "memory")
|
||||
asm volatile ("" : : : "memory")
|
||||
|
||||
and replace the slow side memory barriers by the membarrier system call.
|
||||
and replace the slow-side memory barriers by calls to
|
||||
.BR membarrier ().
|
||||
|
||||
This will add overhead to the slow side, and remove overhead from the
|
||||
fast side, thus resulting in an overall performance increase as long as
|
||||
the slow side is infrequent enough that the membarrier system call
|
||||
overhead does not counterweight the performance gain on the fast side.
|
||||
|
||||
Examples where this system call can be useful includes implementations
|
||||
of Ready-Copy Update librarires, and garbage collectors.
|
||||
the slow side is infrequent enough that the overhead of the
|
||||
.BR membarrier ()
|
||||
calls does not outweigh the performance gain on the fast side.
|
||||
|
||||
The
|
||||
.I cmd
|
||||
|
|
@ -69,72 +72,95 @@ argument is one of the following:
|
|||
|
||||
.TP
|
||||
.B MEMBARRIER_CMD_QUERY
|
||||
Query the set of supported commands. It returns a bitmask of supported
|
||||
Query the set of supported commands.
|
||||
The return value of the call is a bit mask of supported
|
||||
commands.
|
||||
.RB ( MEMBARRIER_CMD_QUERY
|
||||
is not itself included included in this bit mask.)
|
||||
.TP
|
||||
.B MEMBARRIER_CMD_SHARED
|
||||
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 membarrier system call.
|
||||
All threads on the system are targeted by this command. This command
|
||||
returns 0.
|
||||
order between entry to and return from the
|
||||
.BR membarrier ()
|
||||
system call.
|
||||
All threads on the system are targeted by this command.
|
||||
This command returns 0.
|
||||
|
||||
.PP
|
||||
The
|
||||
.I cmd
|
||||
argument expects a one-hot bit of a bitmask, except for the
|
||||
argument expects a one-hot bit of a bit mask, except for the
|
||||
.B MEMBARRIER_CMD_QUERY
|
||||
command which has the value 0. This query command is always supported,
|
||||
even though it is not part of the bitmask.
|
||||
command which has the value 0.
|
||||
This query command is always supported,
|
||||
even though it is not part of the bit mask.
|
||||
|
||||
.PP
|
||||
The
|
||||
.I flags
|
||||
argument is currently unused.
|
||||
argument is currently unused and must be specified as 0.
|
||||
|
||||
.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():
|
||||
are guaranteed to be ordered with respect to
|
||||
.BR membarrier ().
|
||||
|
||||
If we use the semantic
|
||||
.I barrier()
|
||||
to represent a compiler barrier forcing memory
|
||||
accesses to be performed in program order across the barrier, and
|
||||
.I smp_mb()
|
||||
to represent explicit memory barriers forcing full memory
|
||||
ordering across the barrier, we have the following ordering table for
|
||||
each pairing of
|
||||
.IR barrier() ,
|
||||
.BR membarrier ()
|
||||
and
|
||||
.IR 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
|
||||
barrier() smp_mb() membarrier()
|
||||
barrier() X X O
|
||||
smp_mb() X O O
|
||||
sys_membarrier() O O O
|
||||
|
||||
.SH RETURN VALUE
|
||||
On success, this system call returns zero. On error, \-1 is returned,
|
||||
On success, this system call returns 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. Therefore, it
|
||||
guaranteed to always return the same value until reboot.
|
||||
Therefore, it
|
||||
is sufficient to handle errors in a program or library initialization
|
||||
function. Further calls with the same parameters will lead to the same
|
||||
result. Therefore, for flag argument set to 0, error handling is only
|
||||
function.
|
||||
Further calls with the same parameters will lead to the same
|
||||
result.
|
||||
Therefore, for flag argument set to 0, error handling is only
|
||||
required for the first calls to the
|
||||
.BR membarrier ()
|
||||
system call in an application.
|
||||
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B ENOSYS
|
||||
System call is not implemented.
|
||||
.TP
|
||||
.B EINVAL
|
||||
.I cmd
|
||||
is invalid or
|
||||
.I flags
|
||||
is non-zero.
|
||||
.TP
|
||||
.B ENOSYS
|
||||
The
|
||||
.BR membarrier ()
|
||||
system call is not implemented by this kernel.
|
||||
|
||||
.SH VERSIONS
|
||||
The membarrier system call was added in Linux 4.3.
|
||||
The
|
||||
.BR membarrier ()
|
||||
system call was added in Linux 4.3.
|
||||
|
||||
.SH CONFORMING TO
|
||||
.BR membarrier ()
|
||||
|
|
@ -143,64 +169,80 @@ is Linux-specific.
|
|||
.SH NOTES
|
||||
|
||||
A memory barrier instruction is part of the instruction set of
|
||||
architectures with weakly-ordered memory models. It orders memory
|
||||
architectures with weakly-ordered memory models.
|
||||
It orders memory
|
||||
accesses prior to the barrier and after the barrier with respect to
|
||||
matching barriers on other cores. For instance, a load fence can order
|
||||
matching barriers on other cores.
|
||||
For instance, a load fence can order
|
||||
loads prior to and following that fence with respect to stores ordered
|
||||
by store fences.
|
||||
|
||||
Program order is the order in which instructions are ordered in the
|
||||
program assembly code.
|
||||
|
||||
Examples where
|
||||
.BR membarrier ()
|
||||
can be useful include implementations
|
||||
of Ready-Copy-Update libraries and garbage collectors.
|
||||
|
||||
.SH EXAMPLE
|
||||
|
||||
Assuming a multithreaded application where "fast_path()" is executed
|
||||
very frequently, and where "slow_path()" is executed infrequently, the
|
||||
following code (x86) can be transformed using
|
||||
.BR membarrier()
|
||||
:
|
||||
.BR membarrier ():
|
||||
|
||||
.in +4n
|
||||
.nf
|
||||
#include <stdlib.h>
|
||||
|
||||
static volatile int a, b;
|
||||
|
||||
static void fast_path(void)
|
||||
static void
|
||||
fast_path(void)
|
||||
{
|
||||
int read_a, read_b;
|
||||
int read_a, read_b;
|
||||
|
||||
read_b = b;
|
||||
asm volatile ("mfence" : : : "memory");
|
||||
read_a = a;
|
||||
/* read_b == 1 implies read_a == 1. */
|
||||
if (read_b == 1 && read_a == 0)
|
||||
abort();
|
||||
read_b = b;
|
||||
asm volatile ("mfence" : : : "memory");
|
||||
read_a = a;
|
||||
|
||||
/* read_b == 1 implies read_a == 1. */
|
||||
|
||||
if (read_b == 1 && read_a == 0)
|
||||
abort();
|
||||
}
|
||||
|
||||
static void slow_path(void)
|
||||
static void
|
||||
slow_path(void)
|
||||
{
|
||||
a = 1;
|
||||
asm volatile ("mfence" : : : "memory");
|
||||
b = 1;
|
||||
a = 1;
|
||||
asm volatile ("mfence" : : : "memory");
|
||||
b = 1;
|
||||
}
|
||||
|
||||
int main(int argc, char **argv)
|
||||
int
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
/*
|
||||
* Real applications would call fast_path() and slow_path() from
|
||||
* different threads. Call those from main() to keep this
|
||||
* example short.
|
||||
*/
|
||||
slow_path();
|
||||
fast_path();
|
||||
exit(EXIT_SUCCESS);
|
||||
/*
|
||||
* Real applications would call fast_path() and slow_path()
|
||||
* from different threads. Call those from main() to keep
|
||||
* this example short.
|
||||
*/
|
||||
|
||||
slow_path();
|
||||
fast_path();
|
||||
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.in
|
||||
|
||||
The code above transformed to use the
|
||||
.BR membarrier()
|
||||
system call becomes:
|
||||
The code above transformed to use
|
||||
.BR membarrier ()
|
||||
becomes:
|
||||
|
||||
.in +4n
|
||||
.nf
|
||||
#define _GNU_SOURCE
|
||||
#include <stdlib.h>
|
||||
|
|
@ -211,59 +253,73 @@ system call becomes:
|
|||
|
||||
static volatile int a, b;
|
||||
|
||||
static int membarrier(int cmd, int flags)
|
||||
static int
|
||||
membarrier(int cmd, int flags)
|
||||
{
|
||||
return syscall(__NR_membarrier, cmd, flags);
|
||||
return syscall(__NR_membarrier, cmd, flags);
|
||||
}
|
||||
|
||||
static int init_membarrier(void)
|
||||
static int
|
||||
init_membarrier(void)
|
||||
{
|
||||
int ret;
|
||||
int ret;
|
||||
|
||||
/* Ensure that membarrier is supported. */
|
||||
ret = membarrier(MEMBARRIER_CMD_QUERY, 0);
|
||||
if (ret < 0) {
|
||||
perror("membarrier");
|
||||
return -1;
|
||||
}
|
||||
if (!(ret & MEMBARRIER_CMD_SHARED)) {
|
||||
fprintf(stderr,
|
||||
"membarrier does not support MEMBARRIER_CMD_SHARED.\\n");
|
||||
return -1;
|
||||
}
|
||||
return 0;
|
||||
/* Check that membarrier() is supported. */
|
||||
|
||||
ret = membarrier(MEMBARRIER_CMD_QUERY, 0);
|
||||
if (ret < 0) {
|
||||
perror("membarrier");
|
||||
return \-1;
|
||||
}
|
||||
|
||||
if (!(ret & MEMBARRIER_CMD_SHARED)) {
|
||||
fprintf(stderr,
|
||||
"membarrier does not support MEMBARRIER_CMD_SHARED\\n");
|
||||
return \-1;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
static void fast_path(void)
|
||||
static void
|
||||
fast_path(void)
|
||||
{
|
||||
int read_a, read_b;
|
||||
int read_a, read_b;
|
||||
|
||||
read_b = b;
|
||||
asm volatile ("" : : : "memory");
|
||||
read_a = a;
|
||||
/* read_b == 1 implies read_a == 1. */
|
||||
if (read_b == 1 && read_a == 0)
|
||||
abort();
|
||||
read_b = b;
|
||||
asm volatile ("" : : : "memory");
|
||||
read_a = a;
|
||||
|
||||
/* read_b == 1 implies read_a == 1. */
|
||||
|
||||
if (read_b == 1 && read_a == 0)
|
||||
abort();
|
||||
}
|
||||
|
||||
static void slow_path(void)
|
||||
static void
|
||||
slow_path(void)
|
||||
{
|
||||
a = 1;
|
||||
membarrier(MEMBARRIER_CMD_SHARED, 0);
|
||||
b = 1;
|
||||
a = 1;
|
||||
membarrier(MEMBARRIER_CMD_SHARED, 0);
|
||||
b = 1;
|
||||
}
|
||||
|
||||
int main(int argc, char **argv)
|
||||
int
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
if (init_membarrier())
|
||||
exit(EXIT_FAILURE);
|
||||
/*
|
||||
* Real applications would call fast_path() and slow_path() from
|
||||
* different threads. Call those from main() to keep this
|
||||
* example short.
|
||||
*/
|
||||
slow_path();
|
||||
fast_path();
|
||||
exit(EXIT_SUCCESS);
|
||||
if (init_membarrier())
|
||||
exit(EXIT_FAILURE);
|
||||
|
||||
/*
|
||||
* Real applications would call fast_path() and slow_path()
|
||||
* from different threads. Call those from main() to keep
|
||||
* this example short.
|
||||
*/
|
||||
|
||||
slow_path();
|
||||
fast_path();
|
||||
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.in
|
||||
|
|
|
|||
Loading…
Reference in New Issue