1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2024 The FreeBSD Foundation 4.\" 5.\" This documentation was written by Ed Maste <emaste@FreeBSD.org> 6.\" under sponsorship from the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd October 6, 2024 30.Dt MEMBARRIER 2 31.Os 32.Sh NAME 33.Nm membarrier 34.Nd memory barrier 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/membarrier.h 39.Ft int 40.Fn membarrier "int cmd" "unsigned flags" "int cpu_id" 41.Sh DESCRIPTION 42The 43.Nm 44system call provides a memory barrier, ensuring ordering between memory 45accesses performed by different threads or processes within the same address 46space. 47.Pp 48The following values for 49.Fa cmd 50may be specified: 51.Bl -tag -width Dv 52.It Dv MEMBARRIER_CMD_QUERY 53Query supported commands. 54A bitmask of commands supported by the kernel is returned. 55.It Dv MEMBARRIER_CMD_GLOBAL 56Issue a memory barrier for all threads from all processes. 57.It Dv MEMBARRIER_CMD_SHARED 58This is an alias for 59.Dv MEMBARRIER_CMD_GLOBAL . 60.It Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED 61Execute a memory barrier on all running threads of all processes registered 62with 63.Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED . 64.It Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED 65Register the process to receive 66.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED 67memory barriers. 68.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED 69Execute a memory barrier on each running thread belonging to the same process 70as the thread calling 71.Nm . 72.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED 73Register the process to receive 74.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED 75memory barriers. 76.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE 77In addition to the guarantees provided by 78.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED 79it also executes machine-specific serialization instructions, which 80ensures that all possible speculative and out-of-order activities on the target 81CPU are fenced. 82.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE 83Register the process to receive 84.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE 85memory barriers. 86.It Dv MEMBARRIER_CMD_GET_REGISTRATIONS 87Return the bitmask of the currently registered receive barriers. 88.El 89.Pp 90The following 91.Fa cmd 92values are defined for source compatibility but are not yet supported: 93.Pp 94.Bl -tag -width Dv -compact 95.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ 96.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ 97.El 98.Pp 99The 100.Fa flags 101argument must be 0. 102The 103.Fa cpu_id 104argument is ignored. 105.Sh RETURN VALUES 106If the 107.Fa cmd 108is 109.Dv MEMBARRIER_CMD_QUERY 110a bitmask of supported commands is returned. 111For the 112.Dv MEMBARRIER_CMD_GET_REGISTRATIONS 113command, a bitmask of the registrations for the current process 114is returned. 115Otherwise, on success, 116.Nm 117returns 0. 118On error, -1 is returned and 119.Va errno 120is set to indicate the error. 121.Sh ERRORS 122.Nm 123may fail with the following errors: 124.Bl -tag -width Er 125.It Bq Er EINVAL 126.Fa cmd 127does not specify a valid command. 128.It Bq Er EINVAL 129.Fa flags 130is not 0. 131.It Bq Er EPERM 132An attempt was made to use 133.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED , 134.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED , 135or 136.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE 137by a process that did not previously register use with the corresponding 138.Dv MEMBARRIER_CMD_REGISTER_* 139.Fa cmd . 140.El 141.\" .Sh SEE ALSO 142.Sh STANDARDS 143The 144.Nm 145system call originated in Linux. 146This implementation aims to be source-compatible with the Linux implementation. 147Certain 148.Fa cmd 149and 150.Fa flags 151values are currently not supported by 152.Fx . 153.Sh HISTORY 154The 155.Nm 156function was introduced in 157.Fx 14.1 . 158