diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/membarrier.2 | 46 |
1 files changed, 23 insertions, 23 deletions
diff --git a/man2/membarrier.2 b/man2/membarrier.2 index f118fd0..ce5a9de 100644 --- a/man2/membarrier.2 +++ b/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 2023-10-31 "Linux man-pages 6.7" .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 |