man2/membarrier.2

   1 .\" Copyright 2015 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH MEMBARRIER 2 2015-12-28 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 membarrier \- issue memory barriers on a set of threads
  28 .SH SYNOPSIS
  29 .B #include <linux/membarrier.h>
  30 .sp
  31 .BI "int membarrier(int " cmd ", int " flags ");
  32 .SH DESCRIPTION
  33 The
  34 .BR membarrier ()
  35 system call helps reducing the overhead of the memory barrier
  36 instructions required to order memory accesses on multi-core systems.
  37 However, this system call is heavier than a memory barrier, so using it
  38 effectively is
  39 .I not
  40 as simple as replacing memory barriers with this
  41 system call, but requires understanding of the details below.
  42
  43 Use of memory barriers needs to be done taking into account that a
  44 memory barrier always needs to be either matched with its memory barrier
  45 counterparts, or that the architecture's memory model doesn't require the
  46 matching barriers.
  47
  48 There are cases where one side of the matching barriers (which we will
  49 refer to as "fast side") is executed much more often than the other
  50 (which we will refer to as "slow side").
  51 This is a prime target for the use of
  52 .BR membarrier ().
  53 The key idea is to replace, for these matching
  54 barriers, the fast-side memory barriers by simple compiler barriers,
  55 for example:
  56
  57     asm volatile ("" : : : "memory")
  58
  59 and replace the slow-side memory barriers by calls to
  60 .BR membarrier ().
  61
  62 This will add overhead to the slow side, and remove overhead from the
  63 fast side, thus resulting in an overall performance increase as long as
  64 the slow side is infrequent enough that the overhead of the
  65 .BR membarrier ()
  66 calls does not outweigh the performance gain on the fast side.
  67
  68 The
  69 .I cmd
  70 argument is one of the following:
  71 .TP
  72 .B MEMBARRIER_CMD_QUERY
  73 Query the set of supported commands.
  74 The return value of the call is a bit mask of supported
  75 commands.
  76 .BR MEMBARRIER_CMD_QUERY ,
  77 which has the value 0,
  78 is not itself included in this bit mask.
  79 This command is always supported (on kernels where
  80 .BR membarrier ()
  81 is provided).
  82 .TP
  83 .B MEMBARRIER_CMD_SHARED
  84 Ensure that all threads from all processes on the system pass through a
  85 state where all memory accesses to user-space addresses match program
  86 order between entry to and return from the
  87 .BR membarrier ()
  88 system call.
  89 All threads on the system are targeted by this command.
  90 .PP
  91 The
  92 .I flags
  93 argument is currently unused and must be specified as 0.
  94 .PP
  95 All memory accesses performed in program order from each targeted thread
  96 are guaranteed to be ordered with respect to
  97 .BR membarrier ().
  98
  99 If we use the semantic
 100 .I barrier()
 101 to represent a compiler barrier forcing memory
 102 accesses to be performed in program order across the barrier, and
 103 .I smp_mb()
 104 to represent explicit memory barriers forcing full memory
 105 ordering across the barrier, we have the following ordering table for
 106 each pairing of
 107 .IR barrier() ,
 108 .BR membarrier ()
 109 and
 110 .IR smp_mb() .
 111 The pair ordering is detailed as (O: ordered, X: not ordered):
 112
 113                        barrier()  smp_mb()  membarrier()
 114        barrier()          X          X          O
 115        smp_mb()           X          O          O
 116        membarrier()       O          O          O
 117 .SH RETURN VALUE
 118 On success, the
 119 .B MEMBARRIER_CMD_QUERY
 120 operation returns a bit mask of supported commands and the
 121 .B MEMBARRIER_CMD_SHARED
 122 operation returns zero.
 123 On error, \-1 is returned,
 124 and
 125 .I errno
 126 is set appropriately.
 127
 128 For a given command, with
 129 .I flags
 130 set to 0, this system call is
 131 guaranteed to always return the same value until reboot.
 132 Further calls with the same arguments will lead to the same result.
 133 Therefore, with
 134 .I flags
 135 set to 0, error handling is required only for the first call to
 136 .BR membarrier ().
 137 .SH ERRORS
 138 .TP
 139 .B EINVAL
 140 .I cmd
 141 is invalid or
 142 .I flags
 143 is non-zero.
 144 .TP
 145 .B ENOSYS
 146 The
 147 .BR membarrier ()
 148 system call is not implemented by this kernel.
 149 .TP
 150 .BR ENOSYS " (since Linux 4.11)"
 151 .\" 907565337ebf998a68cb5c5b2174ce5e5da065eb
 152 The
 153 .BR membarrier ()
 154 system call is disabled because the
 155 .I nohz_full
 156 CPU parameter has been set.
 157 .SH VERSIONS
 158 The
 159 .BR membarrier ()
 160 system call was added in Linux 4.3.
 161 .\"
 162 .SH CONFORMING TO
 163 .BR membarrier ()
 164 is Linux-specific.
 165 .SH NOTES
 166 A memory barrier instruction is part of the instruction set of
 167 architectures with weakly-ordered memory models.
 168 It orders memory
 169 accesses prior to the barrier and after the barrier with respect to
 170 matching barriers on other cores.
 171 For instance, a load fence can order
 172 loads prior to and following that fence with respect to stores ordered
 173 by store fences.
 174
 175 Program order is the order in which instructions are ordered in the
 176 program assembly code.
 177
 178 Examples where
 179 .BR membarrier ()
 180 can be useful include implementations
 181 of Read-Copy-Update libraries and garbage collectors.
 182 .SH EXAMPLE
 183 Assuming a multithreaded application where "fast_path()" is executed
 184 very frequently, and where "slow_path()" is executed infrequently, the
 185 following code (x86) can be transformed using
 186 .BR membarrier ():
 187
 188 .in +4n
 189 .nf
 190 #include <stdlib.h>
 191
 192 static volatile int a, b;
 193
 194 static void
 195 fast_path(void)
 196 {
 197     int read_a, read_b;
 198
 199     read_b = b;
 200     asm volatile ("mfence" : : : "memory");
 201     read_a = a;
 202
 203     /* read_b == 1 implies read_a == 1. */
 204
 205     if (read_b == 1 && read_a == 0)
 206         abort();
 207 }
 208
 209 static void
 210 slow_path(void)
 211 {
 212     a = 1;
 213     asm volatile ("mfence" : : : "memory");
 214     b = 1;
 215 }
 216
 217 int
 218 main(int argc, char **argv)
 219 {
 220     /*
 221      * Real applications would call fast_path() and slow_path()
 222      * from different threads. Call those from main() to keep
 223      * this example short.
 224      */
 225
 226     slow_path();
 227     fast_path();
 228
 229     exit(EXIT_SUCCESS);
 230 }
 231 .fi
 232 .in
 233
 234 The code above transformed to use
 235 .BR membarrier ()
 236 becomes:
 237
 238 .in +4n
 239 .nf
 240 #define _GNU_SOURCE
 241 #include <stdlib.h>
 242 #include <stdio.h>
 243 #include <unistd.h>
 244 #include <sys/syscall.h>
 245 #include <linux/membarrier.h>
 246
 247 static volatile int a, b;
 248
 249 static int
 250 membarrier(int cmd, int flags)
 251 {
 252     return syscall(__NR_membarrier, cmd, flags);
 253 }
 254
 255 static int
 256 init_membarrier(void)
 257 {
 258     int ret;
 259
 260     /* Check that membarrier() is supported. */
 261
 262     ret = membarrier(MEMBARRIER_CMD_QUERY, 0);
 263     if (ret < 0) {
 264         perror("membarrier");
 265         return \-1;
 266     }
 267
 268     if (!(ret & MEMBARRIER_CMD_SHARED)) {
 269         fprintf(stderr,
 270             "membarrier does not support MEMBARRIER_CMD_SHARED\\n");
 271         return \-1;
 272     }
 273
 274     return 0;
 275 }
 276
 277 static void
 278 fast_path(void)
 279 {
 280     int read_a, read_b;
 281
 282     read_b = b;
 283     asm volatile ("" : : : "memory");
 284     read_a = a;
 285
 286     /* read_b == 1 implies read_a == 1. */
 287
 288     if (read_b == 1 && read_a == 0)
 289         abort();
 290 }
 291
 292 static void
 293 slow_path(void)
 294 {
 295     a = 1;
 296     membarrier(MEMBARRIER_CMD_SHARED, 0);
 297     b = 1;
 298 }
 299
 300 int
 301 main(int argc, char **argv)
 302 {
 303     if (init_membarrier())
 304         exit(EXIT_FAILURE);
 305
 306     /*
 307      * Real applications would call fast_path() and slow_path()
 308      * from different threads. Call those from main() to keep
 309      * this example short.
 310      */
 311
 312     slow_path();
 313     fast_path();
 314
 315     exit(EXIT_SUCCESS);
 316 }
 317 .fi
 318 .in