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