Debian Codegraph @

upstream/debian-unstable/man2/membarrier.2

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH membarrier 2 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 membarrier \- issue memory barriers on a set of threads
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .P
15 .BR "#include <linux/membarrier.h>" \
16 " /* Definition of " MEMBARRIER_* " constants */"
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \
21 ", int " cpu_id );
22 .fi
23 .P
24 .IR Note :
25 glibc provides no wrapper for
26 .BR membarrier (),
27 necessitating the use of
28 .BR syscall (2).
29 .SH DESCRIPTION
30 The
31 .BR membarrier ()
32 system call helps reducing the overhead of the memory barrier
33 instructions required to order memory accesses on multi-core systems.
34 However, this system call is heavier than a memory barrier, so using it
35 effectively is
36 .I not
37 as simple as replacing memory barriers with this
38 system call, but requires understanding of the details below.
39 .P
40 Use of memory barriers needs to be done taking into account that a
41 memory barrier always needs to be either matched with its memory barrier
42 counterparts, or that the architecture's memory model doesn't require the
43 matching barriers.
44 .P
45 There are cases where one side of the matching barriers (which we will
46 refer to as "fast side") is executed much more often than the other
47 (which we will refer to as "slow side").
48 This is a prime target for the use of
49 .BR membarrier ().
50 The key idea is to replace, for these matching
51 barriers, the fast-side memory barriers by simple compiler barriers,
52 for example:
53 .P
54 .in +4n
55 .EX
56 asm volatile ("" : : : "memory")
57 .EE
58 .in
59 .P
60 and replace the slow-side memory barriers by calls to
61 .BR membarrier ().
62 .P
63 This will add overhead to the slow side, and remove overhead from the
64 fast side, thus resulting in an overall performance increase as long as
65 the slow side is infrequent enough that the overhead of the
66 .BR membarrier ()
67 calls does not outweigh the performance gain on the fast side.
68 .P
69 The
70 .I cmd
71 argument is one of the following:
72 .TP
73 .BR MEMBARRIER_CMD_QUERY " (since Linux 4.3)"
74 Query the set of supported commands.
75 The return value of the call is a bit mask of supported
76 commands.
77 .BR MEMBARRIER_CMD_QUERY ,
78 which has the value 0,
79 is not itself included in this bit mask.
80 This command is always supported (on kernels where
81 .BR membarrier ()
82 is provided).
83 .TP
84 .BR MEMBARRIER_CMD_GLOBAL " (since Linux 4.16)"
85 Ensure that all threads from all processes on the system pass through a
86 state where all memory accesses to user-space addresses match program
87 order between entry to and return from the
88 .BR membarrier ()
89 system call.
90 All threads on the system are targeted by this command.
91 .TP
92 .BR MEMBARRIER_CMD_GLOBAL_EXPEDITED " (since Linux 4.16)"
93 Execute a memory barrier on all running threads of all processes that
94 previously registered with
95 .BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
96 .IP
97 Upon return from the system call, the calling thread has a guarantee that all
98 running threads have passed through a state where all memory accesses to
99 user-space addresses match program order between entry to and return
100 from the system call (non-running threads are de facto in such a state).
101 This guarantee is provided only for the threads of processes that
102 previously registered with
103 .BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
104 .IP
105 Given that registration is about the intent to receive the barriers, it
106 is valid to invoke
107 .B MEMBARRIER_CMD_GLOBAL_EXPEDITED
108 from a process that has not employed
109 .BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
110 .IP
111 The "expedited" commands complete faster than the non-expedited ones;
112 they never block, but have the downside of causing extra overhead.
113 .TP
114 .BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED " (since Linux 4.16)"
115 Register the process's intent to receive
116 .B MEMBARRIER_CMD_GLOBAL_EXPEDITED
117 memory barriers.
118 .TP
119 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)"
120 Execute a memory barrier on each running thread belonging to the same
121 process as the calling thread.
122 .IP
123 Upon return from the system call, the calling
124 thread has a guarantee that all its running thread siblings have passed
125 through a state where all memory accesses to user-space addresses match
126 program order between entry to and return from the system call
127 (non-running threads are de facto in such a state).
128 This guarantee is provided only for threads in
129 the same process as the calling thread.
130 .IP
131 The "expedited" commands complete faster than the non-expedited ones;
132 they never block, but have the downside of causing extra overhead.
133 .IP
134 A process must register its intent to use the private
135 expedited command prior to using it.
136 .TP
137 .BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)"
138 Register the process's intent to use
139 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED .
140 .TP
141 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)"
142 In addition to providing the memory ordering guarantees described in
143 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
144 upon return from system call the calling thread has a guarantee that all its
145 running thread siblings have executed a core serializing instruction.
146 This guarantee is provided only for threads in
147 the same process as the calling thread.
148 .IP
149 The "expedited" commands complete faster than the non-expedited ones,
150 they never block, but have the downside of causing extra overhead.
151 .IP
152 A process must register its intent to use the private expedited sync
153 core command prior to using it.
154 .TP
155 .BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)"
156 Register the process's intent to use
157 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE .
158 .TP
159 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)"
160 Ensure the caller thread, upon return from system call, that all its
161 running thread siblings have any currently running rseq critical sections
162 restarted if
163 .I flags
164 parameter is 0;
165 if
166 .I flags
167 parameter is
168 .BR MEMBARRIER_CMD_FLAG_CPU ,
169 then this operation is performed only on CPU indicated by
170 .IR cpu_id .
171 This guarantee is provided only for threads in
172 the same process as the calling thread.
173 .IP
174 RSEQ membarrier is only available in the "private expedited" form.
175 .IP
176 A process must register its intent to use the private expedited rseq
177 command prior to using it.
178 .TP
179 .BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)"
180 Register the process's intent to use
181 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ .
182 .TP
183 .BR MEMBARRIER_CMD_SHARED " (since Linux 4.3)"
184 This is an alias for
185 .B MEMBARRIER_CMD_GLOBAL
186 that exists for header backward compatibility.
187 .P
188 The
189 .I flags
190 argument must be specified as 0 unless the command is
191 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ ,
192 in which case
193 .I flags
194 can be either 0 or
195 .BR MEMBARRIER_CMD_FLAG_CPU .
196 .P
197 The
198 .I cpu_id
199 argument is ignored unless
200 .I flags
201 is
202 .BR MEMBARRIER_CMD_FLAG_CPU ,
203 in which case it must specify the CPU targeted by this membarrier
204 command.
205 .P
206 All memory accesses performed in program order from each targeted thread
207 are guaranteed to be ordered with respect to
208 .BR membarrier ().
209 .P
210 If we use the semantic
211 .I barrier()
212 to represent a compiler barrier forcing memory
213 accesses to be performed in program order across the barrier, and
214 .I smp_mb()
215 to represent explicit memory barriers forcing full memory
216 ordering across the barrier, we have the following ordering table for
217 each pairing of
218 .IR barrier() ,
219 .BR membarrier (),
220 and
221 .IR smp_mb() .
222 The pair ordering is detailed as (O: ordered, X: not ordered):
223 .P
224 .RS
225 .TS
226 l c c c.
227 \& barrier() smp_mb() membarrier()
228 barrier() X X O
229 smp_mb() X O O
230 membarrier() O O O
231 .TE
232 .RE
233 .SH RETURN VALUE
234 On success, the
235 .B MEMBARRIER_CMD_QUERY
236 operation returns a bit mask of supported commands, and the
237 .BR MEMBARRIER_CMD_GLOBAL ,
238 .BR MEMBARRIER_CMD_GLOBAL_EXPEDITED ,
239 .BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED ,
240 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
241 .BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED ,
242 .BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE ,
243 and
244 .B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
245 operations return zero.
246 On error, \-1 is returned,
247 and
248 .I errno
249 is set to indicate the error.
250 .P
251 For a given command, with
252 .I flags
253 set to 0, this system call is
254 guaranteed to always return the same value until reboot.
255 Further calls with the same arguments will lead to the same result.
256 Therefore, with
257 .I flags
258 set to 0, error handling is required only for the first call to
259 .BR membarrier ().
260 .SH ERRORS
261 .TP
262 .B EINVAL
263 .I cmd
264 is invalid, or
265 .I flags
266 is nonzero, or the
267 .B MEMBARRIER_CMD_GLOBAL
268 command is disabled because the
269 .I nohz_full
270 CPU parameter has been set, or the
271 .B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
272 and
273 .B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
274 commands are not implemented by the architecture.
275 .TP
276 .B ENOSYS
277 The
278 .BR membarrier ()
279 system call is not implemented by this kernel.
280 .TP
281 .B EPERM
282 The current process was not registered prior to using private expedited
283 commands.
284 .SH STANDARDS
285 Linux.
286 .SH HISTORY
287 Linux 4.3.
288 .P
289 Before Linux 5.10, the prototype was:
290 .P
291 .in +4n
292 .EX
293 .BI "int membarrier(int " cmd ", int " flags );
294 .EE
295 .in
296 .SH NOTES
297 A memory barrier instruction is part of the instruction set of
298 architectures with weakly ordered memory models.
299 It orders memory
300 accesses prior to the barrier and after the barrier with respect to
301 matching barriers on other cores.
302 For instance, a load fence can order
303 loads prior to and following that fence with respect to stores ordered
304 by store fences.
305 .P
306 Program order is the order in which instructions are ordered in the
307 program assembly code.
308 .P
309 Examples where
310 .BR membarrier ()
311 can be useful include implementations
312 of Read-Copy-Update libraries and garbage collectors.
313 .SH EXAMPLES
314 Assuming a multithreaded application where "fast_path()" is executed
315 very frequently, and where "slow_path()" is executed infrequently, the
316 following code (x86) can be transformed using
317 .BR membarrier ():
318 .P
319 .in +4n
320 .\" SRC BEGIN (membarrier.c)
321 .EX
322 #include <stdlib.h>
323 \&
324 static volatile int a, b;
325 \&
326 static void
327 fast_path(int *read_b)
328 {
329 a = 1;
330 asm volatile ("mfence" : : : "memory");
331 *read_b = b;
332 }
333 \&
334 static void
335 slow_path(int *read_a)
336 {
337 b = 1;
338 asm volatile ("mfence" : : : "memory");
339 *read_a = a;
340 }
341 \&
342 int
343 main(void)
344 {
345 int read_a, read_b;
346 \&
347 /*
348 * Real applications would call fast_path() and slow_path()
349 * from different threads. Call those from main() to keep
350 * this example short.
351 */
352 \&
353 slow_path(&read_a);
354 fast_path(&read_b);
355 \&
356 /*
357 * read_b == 0 implies read_a == 1 and
358 * read_a == 0 implies read_b == 1.
359 */
360 \&
361 if (read_b == 0 && read_a == 0)
362 abort();
363 \&
364 exit(EXIT_SUCCESS);
365 }
366 .EE
367 .\" SRC END
368 .in
369 .P
370 The code above transformed to use
371 .BR membarrier ()
372 becomes:
373 .P
374 .in +4n
375 .EX
376 #define _GNU_SOURCE
377 #include <stdlib.h>
378 #include <stdio.h>
379 #include <unistd.h>
380 #include <sys/syscall.h>
381 #include <linux/membarrier.h>
382 \&
383 static volatile int a, b;
384 \&
385 static int
386 membarrier(int cmd, unsigned int flags, int cpu_id)
387 {
388 return syscall(__NR_membarrier, cmd, flags, cpu_id);
389 }
390 \&
391 static int
392 init_membarrier(void)
393 {
394 int ret;
395 \&
396 /* Check that membarrier() is supported. */
397 \&
398 ret = membarrier(MEMBARRIER_CMD_QUERY, 0, 0);
399 if (ret < 0) {
400 perror("membarrier");
401 return \-1;
402 }
403 \&
404 if (!(ret & MEMBARRIER_CMD_GLOBAL)) {
405 fprintf(stderr,
406 "membarrier does not support MEMBARRIER_CMD_GLOBAL\[rs]n");
407 return \-1;
408 }
409 \&
410 return 0;
411 }
412 \&
413 static void
414 fast_path(int *read_b)
415 {
416 a = 1;
417 asm volatile ("" : : : "memory");
418 *read_b = b;
419 }
420 \&
421 static void
422 slow_path(int *read_a)
423 {
424 b = 1;
425 membarrier(MEMBARRIER_CMD_GLOBAL, 0, 0);
426 *read_a = a;
427 }
428 \&
429 int
430 main(int argc, char *argv[])
431 {
432 int read_a, read_b;
433 \&
434 if (init_membarrier())
435 exit(EXIT_FAILURE);
436 \&
437 /*
438 * Real applications would call fast_path() and slow_path()
439 * from different threads. Call those from main() to keep
440 * this example short.
441 */
442 \&
443 slow_path(&read_a);
444 fast_path(&read_b);
445 \&
446 /*
447 * read_b == 0 implies read_a == 1 and
448 * read_a == 0 implies read_b == 1.
449 */
450 \&
451 if (read_b == 0 && read_a == 0)
452 abort();
453 \&
454 exit(EXIT_SUCCESS);
455 }
456 .EE
457 .in
458 .\" .SH SEE ALSO
459 .\" FIXME See if the following syscalls make it into Linux 4.15 or later
460 .\" .BR cpu_opv (2),
461 .\" .BR rseq (2)