diff --git a/man2/membarrier.2 b/man2/membarrier.2 index 552d81742..586293513 100644 --- a/man2/membarrier.2 +++ b/man2/membarrier.2 @@ -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 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 @@ -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