membarrier: Create Documentation/scheduler/membarrier.rst

To gather the architecture requirements of the "private/global
expedited" membarrier commands.  The file will be expanded to
integrate further information about the membarrier syscall (as
needed/desired in the future).  While at it, amend some related
inline comments in the membarrier codebase.

Suggested-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Signed-off-by: Andrea Parri <parri.andrea@gmail.com>
Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Link: https://lore.kernel.org/r/20240131144936.29190-3-parri.andrea@gmail.com
Signed-off-by: Palmer Dabbelt <palmer@rivosinc.com>

diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 3170747226f6da7f828223f6504704391fe47314..43bd8a145b7a9b380e4706b751e40ab7fe05138a 100644 (file)
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -7,6 +7,7 @@ Scheduler
 
 
     completion
+    membarrier
     sched-arch
     sched-bwc
     sched-deadline

diff --git a/Documentation/scheduler/membarrier.rst b/Documentation/scheduler/membarrier.rst
new file mode 100644 (file)
index 0000000..2387804
--- /dev/null
+++ b/Documentation/scheduler/membarrier.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+membarrier() System Call
+========================
+
+MEMBARRIER_CMD_{PRIVATE,GLOBAL}_EXPEDITED - Architecture requirements
+=====================================================================
+
+Memory barriers before updating rq->curr
+----------------------------------------
+
+The commands MEMBARRIER_CMD_PRIVATE_EXPEDITED and MEMBARRIER_CMD_GLOBAL_EXPEDITED
+require each architecture to have a full memory barrier after coming from
+user-space, before updating rq->curr.  This barrier is implied by the sequence
+rq_lock(); smp_mb__after_spinlock() in __schedule().  The barrier matches a full
+barrier in the proximity of the membarrier system call exit, cf.
+membarrier_{private,global}_expedited().
+
+Memory barriers after updating rq->curr
+---------------------------------------
+
+The commands MEMBARRIER_CMD_PRIVATE_EXPEDITED and MEMBARRIER_CMD_GLOBAL_EXPEDITED
+require each architecture to have a full memory barrier after updating rq->curr,
+before returning to user-space.  The schemes providing this barrier on the various
+architectures are as follows.
+
+ - alpha, arc, arm, hexagon, mips rely on the full barrier implied by
+   spin_unlock() in finish_lock_switch().
+
+ - arm64 relies on the full barrier implied by switch_to().
+
+ - powerpc, riscv, s390, sparc, x86 rely on the full barrier implied by
+   switch_mm(), if mm is not NULL; they rely on the full barrier implied
+   by mmdrop(), otherwise.  On powerpc and riscv, switch_mm() relies on
+   membarrier_arch_switch_mm().
+
+The barrier matches a full barrier in the proximity of the membarrier system call
+entry, cf. membarrier_{private,global}_expedited().

diff --git a/MAINTAINERS b/MAINTAINERS
index 2450e88d3e2c2c38483b795e7a586f07eee4d010..78c835cc69c9aece1d1e028011c3cd2320194252 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14039,6 +14039,7 @@ M:      Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 M:     "Paul E. McKenney" <paulmck@kernel.org>
 L:     linux-kernel@vger.kernel.org
 S:     Supported
+F:     Documentation/scheduler/membarrier.rst
 F:     arch/*/include/asm/membarrier.h
 F:     include/uapi/linux/membarrier.h
 F:     kernel/sched/membarrier.c

diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index c4ca8085885a3a345d63cd04c7351e00a2248dd3..a972628e77567107bc2f5e138602aa9712d74448 100644 (file)
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -6638,7 +6638,9 @@ static void __sched notrace __schedule(unsigned int sched_mode)
         *     if (signal_pending_state())          if (p->state & @state)
         *
         * Also, the membarrier system call requires a full memory barrier
-        * after coming from user-space, before storing to rq->curr.
+        * after coming from user-space, before storing to rq->curr; this
+        * barrier matches a full barrier in the proximity of the membarrier
+        * system call exit.
         */
        rq_lock(rq, &rf);
        smp_mb__after_spinlock();
@@ -6716,6 +6718,9 @@ static void __sched notrace __schedule(unsigned int sched_mode)
                 *   architectures where spin_unlock is a full barrier,
                 * - switch_to() for arm64 (weakly-ordered, spin_unlock
                 *   is a RELEASE barrier),
+                *
+                * The barrier matches a full barrier in the proximity of
+                * the membarrier system call entry.
                 */
                ++*switch_count;
 

diff --git a/kernel/sched/membarrier.c b/kernel/sched/membarrier.c
index 2ad881d07752c15f60a4c14bee21051117d5aeb2..f3d91628d6b8ab5f98ace3b211ac2d2cd74e30f2 100644 (file)
--- a/kernel/sched/membarrier.c
+++ b/kernel/sched/membarrier.c
@@ -251,7 +251,7 @@ static int membarrier_global_expedited(void)
                return 0;
 
        /*
-        * Matches memory barriers around rq->curr modification in
+        * Matches memory barriers after rq->curr modification in
         * scheduler.
         */
        smp_mb();       /* system call entry is not a mb. */
@@ -300,7 +300,7 @@ static int membarrier_global_expedited(void)
 
        /*
         * Memory barrier on the caller thread _after_ we finished
-        * waiting for the last IPI. Matches memory barriers around
+        * waiting for the last IPI. Matches memory barriers before
         * rq->curr modification in scheduler.
         */
        smp_mb();       /* exit from system call is not a mb */
@@ -339,7 +339,7 @@ static int membarrier_private_expedited(int flags, int cpu_id)
                return 0;
 
        /*
-        * Matches memory barriers around rq->curr modification in
+        * Matches memory barriers after rq->curr modification in
         * scheduler.
         */
        smp_mb();       /* system call entry is not a mb. */
@@ -415,7 +415,7 @@ out:
 
        /*
         * Memory barrier on the caller thread _after_ we finished
-        * waiting for the last IPI. Matches memory barriers around
+        * waiting for the last IPI. Matches memory barriers before
         * rq->curr modification in scheduler.
         */
        smp_mb();       /* exit from system call is not a mb */