git: 45b0537f0ecf - stable/14 - membarrier: Add manual page

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Ed Maste <emaste_at_FreeBSD.org>
Date: Mon, 21 Oct 2024 03:32:58 UTC
The branch stable/14 has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=45b0537f0ecf6ea3663f7180ad50fcd8170426ab

commit 45b0537f0ecf6ea3663f7180ad50fcd8170426ab
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-10-06 17:47:34 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2024-10-21 03:32:46 +0000

    membarrier: Add manual page
    
    Add a minimal membarrier man page that documents the available cmd
    values and errors that can be returned.  We can add more information and
    iterate on it in the tree.
    
    Reviewed by:    kib
    Sponsored by:   The FreeBSD Foundation
    Differential Revision: https://reviews.freebsd.org/D46967
    
    (cherry picked from commit 1fc766e3b41d0cdbd166ef95258434069a90ca52)
    (cherry picked from commit 92cd5abb64dd70c305535c9504c6a2b73552147f)
    (cherry picked from commit 8b41e693fc3956385d5771d60ee93e18001a5a0d)
---
 lib/libc/sys/Makefile.inc |   1 +
 lib/libc/sys/membarrier.2 | 151 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+)

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 33c0b9711d46..e964e3dcff26 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -244,6 +244,7 @@ MAN+=	abort2.2 \
 	listen.2 \
 	lseek.2 \
 	madvise.2 \
+	membarrier.2 \
 	mincore.2 \
 	minherit.2 \
 	mkdir.2 \
diff --git a/lib/libc/sys/membarrier.2 b/lib/libc/sys/membarrier.2
new file mode 100644
index 000000000000..87db620975ef
--- /dev/null
+++ b/lib/libc/sys/membarrier.2
@@ -0,0 +1,151 @@
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2024 The FreeBSD Foundation
+.\"
+.\" This documentation was written by Ed Maste <emaste@FreeBSD.org>
+.\" under sponsorship from the FreeBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd October 6, 2024
+.Dt MEMBARRIER 2
+.Os
+.Sh NAME
+.Nm membarrier
+.Nd memory barrier
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/membarrier.h
+.Ft int
+.Fn membarrier "int cmd" "unsigned flags" "int cpu_id"
+.Sh DESCRIPTION
+The
+.Nm
+system call provides a memory barrier, ensuring ordering between memory
+accesses performed by different threads or processes within the same address
+space.
+.Pp
+The following values for
+.Fa cmd
+may be specified:
+.Bl -tag -width Dv
+.It Dv MEMBARRIER_CMD_QUERY
+Query supported commands.
+A bitmask of commands supported by the kernel is returned.
+.It Dv MEMBARRIER_CMD_GLOBAL
+Issue a memory barrier for all threads from all processes.
+.It Dv MEMBARRIER_CMD_SHARED
+This is an alias for
+.Dv MEMBARRIER_CMD_GLOBAL .
+.It Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED
+Execute a memory barrier on all running threads of all processes registered
+with
+.Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED .
+.It Dv MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED
+Register the process to receive
+.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED
+memory barriers.
+.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED
+Execute a memory barrier on each running thread belonging to the same process
+as the thread calling
+.Nm .
+.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED
+Register the process to receive
+.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED
+memory barriers.
+.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+In addition to the guarantees provided by
+.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED
+it also executes machine-specific serialization instructions, which
+ensures that all possible speculative and out-of-order activities on the target
+CPU are fenced.
+.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE
+Register the process to receive
+.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+memory barriers.
+.El
+.Pp
+The following
+.Fa cmd
+values are defined for source compatibility but are not yet supported:
+.Pp
+.Bl -tag -width Dv -compact
+.It Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ
+.It Dv MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ
+.El
+.Pp
+The
+.Fa flags
+argument must be 0.
+The
+.Fa cpu_id
+argument is ignored.
+.Sh RETURN VALUES
+If the
+.Fa cmd
+is
+.Dv MEMBARRIER_CMD_QUERY
+a bitmask of supported commands is returned.
+Otherwise, on success,
+.Nm
+returns 0.
+On error, -1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+.Nm
+may fail with the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+.Fa cmd
+does not specify a valid command.
+.It Bq Er EINVAL
+.Fa flags
+is not 0.
+.It Bq Er EPERM
+An attempt was made to use
+.Dv MEMBARRIER_CMD_GLOBAL_EXPEDITED ,
+.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED ,
+or
+.Dv MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE
+by a process that did not previously register use with the corresponding
+.Dv MEMBARRIER_CMD_REGISTER_*
+.Fa cmd .
+.El
+.\" .Sh SEE ALSO
+.Sh STANDARDS
+The
+.Nm
+system call originated in Linux.
+This implementation aims to be source-compatible with the Linux implementation.
+Certain
+.Fa cmd
+and
+.Fa flags
+values are currently not supported by
+.Fx .
+.Sh HISTORY
+The
+.Nm
+function was introduced in
+.Fx 14.1 .