2015-12-13 13:17:43 +00:00
|
|
|
.\" 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
|
|
|
|
.\"
|
accept.2, acct.2, bind.2, clock_getres.2, connect.2, dup.2, epoll_create.2, eventfd.2, execve.2, fanotify_init.2, fcntl.2, fork.2, futex.2, get_robust_list.2, getcpu.2, getpeername.2, getrlimit.2, getsockname.2, getsockopt.2, gettimeofday.2, inotify_init.2, listen.2, membarrier.2, memfd_create.2, mlock.2, mmap.2, personality.2, pipe.2, poll.2, recv.2, send.2, sendfile.2, shmget.2, shutdown.2, sigreturn.2, socket.2, socketcall.2, socketpair.2, spu_create.2, swapon.2, time.2, timerfd_create.2, uselib.2, dlerror.3, dlopen.3, drand48.3, errno.3, fnmatch.3, getgrent.3, getgrnam.3, getlogin.3, getpwent.3, getpwnam.3, iconv.3, mq_open.3, opendir.3, random_r.3, sem_open.3, shm_open.3, tmpfile.3, tzset.3, random.4, fanotify.7, futex.7, vdso.7, ld.so.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-12-29 12:48:42 +00:00
|
|
|
.TH MEMBARRIER 2 2015-12-28 "Linux" "Linux Programmer's Manual"
|
2015-12-13 13:17:43 +00:00
|
|
|
.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 ");
|
|
|
|
.SH DESCRIPTION
|
2015-12-15 14:53:49 +00:00
|
|
|
The
|
|
|
|
.BR membarrier ()
|
|
|
|
system call helps reducing the overhead of the memory barrier
|
2015-12-13 13:17:43 +00:00
|
|
|
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
|
2015-12-15 14:53:49 +00:00
|
|
|
.I not
|
2015-12-13 13:17:43 +00:00
|
|
|
as simple as replacing memory barriers with this
|
2015-12-15 14:53:49 +00:00
|
|
|
system call, but requires understanding of the details below.
|
2015-12-13 13:17:43 +00:00
|
|
|
|
|
|
|
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
|
2015-12-15 14:53:49 +00:00
|
|
|
counterparts, or that the architecture's memory model doesn't require the
|
2015-12-13 13:17:43 +00:00
|
|
|
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
|
2015-12-15 14:53:49 +00:00
|
|
|
(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:
|
2015-12-13 13:17:43 +00:00
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
asm volatile ("" : : : "memory")
|
2015-12-13 13:17:43 +00:00
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
and replace the slow-side memory barriers by calls to
|
|
|
|
.BR membarrier ().
|
2015-12-13 13:17:43 +00:00
|
|
|
|
|
|
|
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
|
2015-12-15 14:53:49 +00:00
|
|
|
the slow side is infrequent enough that the overhead of the
|
|
|
|
.BR membarrier ()
|
|
|
|
calls does not outweigh the performance gain on the fast side.
|
2015-12-13 13:17:43 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.I cmd
|
|
|
|
argument is one of the following:
|
|
|
|
.TP
|
|
|
|
.B MEMBARRIER_CMD_QUERY
|
2015-12-15 14:53:49 +00:00
|
|
|
Query the set of supported commands.
|
|
|
|
The return value of the call is a bit mask of supported
|
2015-12-13 13:17:43 +00:00
|
|
|
commands.
|
2015-12-15 15:23:11 +00:00
|
|
|
.BR MEMBARRIER_CMD_QUERY ,
|
|
|
|
which has the value 0,
|
|
|
|
is not itself included in this bit mask.
|
|
|
|
This command is always supported (on kernels where
|
|
|
|
.BR membarrier ()
|
|
|
|
is provided).
|
2015-12-13 13:17:43 +00:00
|
|
|
.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
|
2015-12-15 14:53:49 +00:00
|
|
|
order between entry to and return from the
|
|
|
|
.BR membarrier ()
|
|
|
|
system call.
|
|
|
|
All threads on the system are targeted by this command.
|
2015-12-13 13:17:43 +00:00
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I flags
|
2015-12-15 14:53:49 +00:00
|
|
|
argument is currently unused and must be specified as 0.
|
2015-12-13 13:17:43 +00:00
|
|
|
.PP
|
|
|
|
All memory accesses performed in program order from each targeted thread
|
2015-12-15 14:53:49 +00:00
|
|
|
are guaranteed to be ordered with respect to
|
|
|
|
.BR membarrier ().
|
|
|
|
|
|
|
|
If we use the semantic
|
|
|
|
.I barrier()
|
|
|
|
to represent a compiler barrier forcing memory
|
2015-12-13 13:17:43 +00:00
|
|
|
accesses to be performed in program order across the barrier, and
|
2015-12-15 14:53:49 +00:00
|
|
|
.I smp_mb()
|
|
|
|
to represent explicit memory barriers forcing full memory
|
2015-12-13 13:17:43 +00:00
|
|
|
ordering across the barrier, we have the following ordering table for
|
2015-12-15 14:53:49 +00:00
|
|
|
each pairing of
|
|
|
|
.IR barrier() ,
|
|
|
|
.BR membarrier ()
|
|
|
|
and
|
|
|
|
.IR smp_mb() .
|
2015-12-13 13:17:43 +00:00
|
|
|
The pair ordering is detailed as (O: ordered, X: not ordered):
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
barrier() smp_mb() membarrier()
|
|
|
|
barrier() X X O
|
|
|
|
smp_mb() X O O
|
2015-12-15 18:54:10 +00:00
|
|
|
membarrier() O O O
|
2015-12-13 13:17:43 +00:00
|
|
|
.SH RETURN VALUE
|
2015-12-15 15:11:06 +00:00
|
|
|
On success, the
|
|
|
|
.B MEMBARRIER_CMD_QUERY
|
|
|
|
operation returns a bit mask of supported commands and the
|
|
|
|
.B MEMBARRIER_CMD_SHARED
|
|
|
|
operation returns zero.
|
2015-12-15 14:53:49 +00:00
|
|
|
On error, \-1 is returned,
|
2015-12-13 13:17:43 +00:00
|
|
|
and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2015-12-15 14:53:49 +00:00
|
|
|
|
2015-12-15 15:15:39 +00:00
|
|
|
For a given command, with
|
|
|
|
.I flags
|
|
|
|
set to 0, this system call is
|
2015-12-15 14:53:49 +00:00
|
|
|
guaranteed to always return the same value until reboot.
|
2015-12-15 15:15:39 +00:00
|
|
|
Further calls with the same arguments will lead to the same result.
|
|
|
|
Therefore, with
|
|
|
|
.I flags
|
|
|
|
set to 0, error handling is required only for the first call to
|
|
|
|
.BR membarrier ().
|
2015-12-13 13:17:43 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I cmd
|
|
|
|
is invalid or
|
|
|
|
.I flags
|
|
|
|
is non-zero.
|
2015-12-15 14:53:49 +00:00
|
|
|
.TP
|
|
|
|
.B ENOSYS
|
|
|
|
The
|
|
|
|
.BR membarrier ()
|
|
|
|
system call is not implemented by this kernel.
|
2017-05-22 12:46:23 +00:00
|
|
|
.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.
|
2015-12-13 13:17:43 +00:00
|
|
|
.SH VERSIONS
|
2015-12-15 14:53:49 +00:00
|
|
|
The
|
|
|
|
.BR membarrier ()
|
|
|
|
system call was added in Linux 4.3.
|
membarrier.2, crypt.3, dladdr.3, duplocale.3, fmemopen.3, gethostbyname.3, mallopt.3, newlocale.3, resolver.3, sigsetops.3, strfmon.3, tzset.3, console_ioctl.4, lirc.4, loop.4, vcs.4, dir_colors.5, locale.5, proc.5, tzfile.5, attributes.7, bootparam.7, capabilities.7, feature_test_macros.7, icmp.7, man-pages.7, netlink.7, path_resolution.7, pipe.7, socket.7, unix.7, vdso.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-02-03 08:14:22 +00:00
|
|
|
.\"
|
2015-12-13 13:17:43 +00:00
|
|
|
.SH CONFORMING TO
|
|
|
|
.BR membarrier ()
|
|
|
|
is Linux-specific.
|
|
|
|
.SH NOTES
|
|
|
|
A memory barrier instruction is part of the instruction set of
|
2015-12-15 14:53:49 +00:00
|
|
|
architectures with weakly-ordered memory models.
|
|
|
|
It orders memory
|
2015-12-13 13:17:43 +00:00
|
|
|
accesses prior to the barrier and after the barrier with respect to
|
2015-12-15 14:53:49 +00:00
|
|
|
matching barriers on other cores.
|
|
|
|
For instance, a load fence can order
|
2015-12-13 13:17:43 +00:00
|
|
|
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.
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
Examples where
|
|
|
|
.BR membarrier ()
|
|
|
|
can be useful include implementations
|
2015-12-18 19:41:00 +00:00
|
|
|
of Read-Copy-Update libraries and garbage collectors.
|
2015-12-13 13:17:43 +00:00
|
|
|
.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
|
2015-12-15 14:53:49 +00:00
|
|
|
.BR membarrier ():
|
2015-12-13 13:17:43 +00:00
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
.in +4n
|
2015-12-13 13:17:43 +00:00
|
|
|
.nf
|
|
|
|
#include <stdlib.h>
|
|
|
|
|
|
|
|
static volatile int a, b;
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static void
|
|
|
|
fast_path(void)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
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();
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static void
|
|
|
|
slow_path(void)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
a = 1;
|
|
|
|
asm volatile ("mfence" : : : "memory");
|
|
|
|
b = 1;
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
int
|
|
|
|
main(int argc, char **argv)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
/*
|
|
|
|
* 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);
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
.fi
|
2015-12-15 14:53:49 +00:00
|
|
|
.in
|
2015-12-13 13:17:43 +00:00
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
The code above transformed to use
|
|
|
|
.BR membarrier ()
|
|
|
|
becomes:
|
2015-12-13 13:17:43 +00:00
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
.in +4n
|
2015-12-13 13:17:43 +00:00
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <sys/syscall.h>
|
|
|
|
#include <linux/membarrier.h>
|
|
|
|
|
|
|
|
static volatile int a, b;
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static int
|
|
|
|
membarrier(int cmd, int flags)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
return syscall(__NR_membarrier, cmd, flags);
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static int
|
|
|
|
init_membarrier(void)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
int ret;
|
|
|
|
|
|
|
|
/* 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;
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static void
|
|
|
|
fast_path(void)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
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();
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
static void
|
|
|
|
slow_path(void)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
a = 1;
|
|
|
|
membarrier(MEMBARRIER_CMD_SHARED, 0);
|
|
|
|
b = 1;
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
|
2015-12-15 14:53:49 +00:00
|
|
|
int
|
|
|
|
main(int argc, char **argv)
|
2015-12-13 13:17:43 +00:00
|
|
|
{
|
2015-12-15 14:53:49 +00:00
|
|
|
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);
|
2015-12-13 13:17:43 +00:00
|
|
|
}
|
|
|
|
.fi
|
2015-12-15 14:53:49 +00:00
|
|
|
.in
|