Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 460 insertions, 0 deletions

diff --git a/man/man2/membarrier.2 b/man/man2/membarrier.2
new file mode 100644
index 0000000..38f774f
--- /dev/null
+++ b/man/man2/membarrier.2
@@ -0,0 +1,460 @@
+'\" t
+.\" Copyright 2015-2017 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH membarrier 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+membarrier \- issue memory barriers on a set of threads
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.P
+.BR "#include <linux/membarrier.h>" \
+" /* Definition of " MEMBARRIER_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \
+", int " cpu_id );
+.fi
+.P
+.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.
+.P
+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.
+.P
+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:
+.P
+.in +4n
+.EX
+asm volatile ("" : : : "memory")
+.EE
+.in
+.P
+and replace the slow-side memory barriers by calls to
+.BR membarrier ().
+.P
+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.
+.P
+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.
+.P
+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 .
+.P
+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.
+.P
+All memory accesses performed in program order from each targeted thread
+are guaranteed to be ordered with respect to
+.BR membarrier ().
+.P
+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):
+.P
+.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.
+.P
+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.
+.P
+Before Linux 5.10, the prototype was:
+.P
+.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.
+.P
+Program order is the order in which instructions are ordered in the
+program assembly code.
+.P
+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 ():
+.P
+.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
+.P
+The code above transformed to use
+.BR membarrier ()
+becomes:
+.P
+.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)