summaryrefslogtreecommitdiffstats
path: root/upstream/debian-unstable/man2/membarrier.2
diff options
context:
space:
mode:
Diffstat (limited to 'upstream/debian-unstable/man2/membarrier.2')
-rw-r--r--upstream/debian-unstable/man2/membarrier.246
1 files changed, 23 insertions, 23 deletions
diff --git a/upstream/debian-unstable/man2/membarrier.2 b/upstream/debian-unstable/man2/membarrier.2
index f118fd01..94337ed3 100644
--- a/upstream/debian-unstable/man2/membarrier.2
+++ b/upstream/debian-unstable/man2/membarrier.2
@@ -3,7 +3,7 @@
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH membarrier 2 2023-05-03 "Linux man-pages 6.05.01"
+.TH membarrier 2 2024-05-02 "Linux man-pages 6.8"
.SH NAME
membarrier \- issue memory barriers on a set of threads
.SH LIBRARY
@@ -11,16 +11,16 @@ Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.BR "#include <linux/membarrier.h>" \
" /* Definition of " MEMBARRIER_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \
", int " cpu_id );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR membarrier (),
@@ -36,12 +36,12 @@ effectively is
.I not
as simple as replacing memory barriers with this
system call, but requires understanding of the details below.
-.PP
+.P
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 doesn't require the
matching barriers.
-.PP
+.P
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").
@@ -50,22 +50,22 @@ This is a prime target for the use of
The key idea is to replace, for these matching
barriers, the fast-side memory barriers by simple compiler barriers,
for example:
-.PP
+.P
.in +4n
.EX
asm volatile ("" : : : "memory")
.EE
.in
-.PP
+.P
and replace the slow-side memory barriers by calls to
.BR membarrier ().
-.PP
+.P
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 overhead of the
.BR membarrier ()
calls does not outweigh the performance gain on the fast side.
-.PP
+.P
The
.I cmd
argument is one of the following:
@@ -183,7 +183,7 @@ Register the process's intent to use
This is an alias for
.B MEMBARRIER_CMD_GLOBAL
that exists for header backward compatibility.
-.PP
+.P
The
.I flags
argument must be specified as 0 unless the command is
@@ -192,7 +192,7 @@ in which case
.I flags
can be either 0 or
.BR MEMBARRIER_CMD_FLAG_CPU .
-.PP
+.P
The
.I cpu_id
argument is ignored unless
@@ -201,11 +201,11 @@ is
.BR MEMBARRIER_CMD_FLAG_CPU ,
in which case it must specify the CPU targeted by this membarrier
command.
-.PP
+.P
All memory accesses performed in program order from each targeted thread
are guaranteed to be ordered with respect to
.BR membarrier ().
-.PP
+.P
If we use the semantic
.I barrier()
to represent a compiler barrier forcing memory
@@ -219,7 +219,7 @@ each pairing of
and
.IR smp_mb() .
The pair ordering is detailed as (O: ordered, X: not ordered):
-.PP
+.P
.RS
.TS
l c c c.
@@ -246,7 +246,7 @@ On error, \-1 is returned,
and
.I errno
is set to indicate the error.
-.PP
+.P
For a given command, with
.I flags
set to 0, this system call is
@@ -284,9 +284,9 @@ commands.
Linux.
.SH HISTORY
Linux 4.3.
-.PP
+.P
Before Linux 5.10, the prototype was:
-.PP
+.P
.in +4n
.EX
.BI "int membarrier(int " cmd ", int " flags );
@@ -301,10 +301,10 @@ 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.
-.PP
+.P
Program order is the order in which instructions are ordered in the
program assembly code.
-.PP
+.P
Examples where
.BR membarrier ()
can be useful include implementations
@@ -314,7 +314,7 @@ 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 ():
-.PP
+.P
.in +4n
.\" SRC BEGIN (membarrier.c)
.EX
@@ -365,11 +365,11 @@ main(void)
.EE
.\" SRC END
.in
-.PP
+.P
The code above transformed to use
.BR membarrier ()
becomes:
-.PP
+.P
.in +4n
.EX
#define _GNU_SOURCE