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.El 87.Pp 88The following 89.Fa cmd 90values are defined for source compatibility but are not yet supported: 91.Pp 92.Bl -tag -width Dv -compact 93.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ 94.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ 95.El 96.Pp 97The 98.Fa flags 99argument must be 0. 100The 101.Fa cpu_id 102argument is ignored. 103.Sh RETURN VALUES 104If the 105.Dv cmd 106is MEMBARRIER_CMD_QUERY 107a bitmask of supported commands is returned. 108Otherwise, on success, 109.Nm 110returns 0. 111On error, -1 is returned and 112.Va errno 113is set to indicate the error. 114.Sh ERRORS 115.Nm 116may fail with the following errors: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119.Fa cmd 120does not specify a valid command. 121.It Bq Er EINVAL 122.Fa flags 123is not 0. 124.It Bq Er EPERM 125An attempt was made to use 126.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED , 127.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED , 128or 129.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE 130by a process that did not previously register use with the corresponding 131.Dv MEMBARRIER_CMD_REGISTER_* 132.Fa cmd . 133.El 134.\" .Sh SEE ALSO 135.Sh STANDARDS 136The 137.Nm 138system call originated in Linux. 139This implementation aims to be source-compatible with the Linux implementation. 140Certain 141.Fa cmd 142and 143.Fa flags 144values are currently not supported by 145.Fx . 146.Sh HISTORY 147The 148.Nm 149function was introduced in 150.Fx 14.1 . 151