rcu: Add documentation for raw SRCU read-side primitives

Update various files in Documentation/RCU to reflect srcu_read_lock_raw()
and srcu_read_unlock_raw().  Credit to Peter Zijlstra for suggesting
use of the existing _raw suffix instead of the earlier bulkref names.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 0c134f8..bff2d8b 100644 (file)
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -328,6 +328,12 @@ over a rather long period of time, but improvements are always welcome!
        RCU rather than SRCU, because RCU is almost always faster and
        easier to use than is SRCU.
 
+       If you need to enter your read-side critical section in a
+       hardirq or exception handler, and then exit that same read-side
+       critical section in the task that was interrupted, then you need
+       to srcu_read_lock_raw() and srcu_read_unlock_raw(), which avoid
+       the lockdep checking that would otherwise this practice illegal.
+
        Also unlike other forms of RCU, explicit initialization
        and cleanup is required via init_srcu_struct() and
        cleanup_srcu_struct().  These are passed a "struct srcu_struct"

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index 3185270..bf77833 100644 (file)
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -38,11 +38,11 @@ o   How can the updater tell when a grace period has completed
 
        Preemptible variants of RCU (CONFIG_TREE_PREEMPT_RCU) get the
        same effect, but require that the readers manipulate CPU-local
-       counters.  These counters allow limited types of blocking
-       within RCU read-side critical sections.  SRCU also uses
-       CPU-local counters, and permits general blocking within
-       RCU read-side critical sections.  These two variants of
-       RCU detect grace periods by sampling these counters.
+       counters.  These counters allow limited types of blocking within
+       RCU read-side critical sections.  SRCU also uses CPU-local
+       counters, and permits general blocking within RCU read-side
+       critical sections.  These variants of RCU detect grace periods
+       by sampling these counters.
 
 o      If I am running on a uniprocessor kernel, which can only do one
        thing at a time, why should I wait for a grace period?

diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
index f3e0625..083d88c 100644 (file)
--- a/Documentation/RCU/stallwarn.txt
+++ b/Documentation/RCU/stallwarn.txt
@@ -114,12 +114,11 @@ o A hardware failure.  This is quite unlikely, but has occurred
        This resulted in a series of RCU CPU stall warnings, eventually
        leading the realization that the CPU had failed.
 
-The RCU, RCU-sched, and RCU-bh implementations have CPU stall
-warning.  SRCU does not have its own CPU stall warnings, but its
-calls to synchronize_sched() will result in RCU-sched detecting
-RCU-sched-related CPU stalls.  Please note that RCU only detects
-CPU stalls when there is a grace period in progress.  No grace period,
-no CPU stall warnings.
+The RCU, RCU-sched, and RCU-bh implementations have CPU stall warning.
+SRCU does not have its own CPU stall warnings, but its calls to
+synchronize_sched() will result in RCU-sched detecting RCU-sched-related
+CPU stalls.  Please note that RCU only detects CPU stalls when there is
+a grace period in progress.  No grace period, no CPU stall warnings.
 
 To diagnose the cause of the stall, inspect the stack traces.
 The offending function will usually be near the top of the stack.

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 6ef6926..8e8cdc2 100644 (file)
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -834,6 +834,8 @@ SRCU:       Critical sections       Grace period            Barrier
 
        srcu_read_lock          synchronize_srcu        N/A
        srcu_read_unlock        synchronize_srcu_expedited
+       srcu_read_lock_raw
+       srcu_read_unlock_raw
        srcu_dereference
 
 SRCU:  Initialization/cleanup
@@ -855,27 +857,33 @@ list can be helpful:
 
 a.     Will readers need to block?  If so, you need SRCU.
 
-b.     What about the -rt patchset?  If readers would need to block
+b.     Is it necessary to start a read-side critical section in a
+       hardirq handler or exception handler, and then to complete
+       this read-side critical section in the task that was
+       interrupted?  If so, you need SRCU's srcu_read_lock_raw() and
+       srcu_read_unlock_raw() primitives.
+
+c.     What about the -rt patchset?  If readers would need to block
        in an non-rt kernel, you need SRCU.  If readers would block
        in a -rt kernel, but not in a non-rt kernel, SRCU is not
        necessary.
 
-c.     Do you need to treat NMI handlers, hardirq handlers,
+d.     Do you need to treat NMI handlers, hardirq handlers,
        and code segments with preemption disabled (whether
        via preempt_disable(), local_irq_save(), local_bh_disable(),
        or some other mechanism) as if they were explicit RCU readers?
        If so, you need RCU-sched.
 
-d.     Do you need RCU grace periods to complete even in the face
+e.     Do you need RCU grace periods to complete even in the face
        of softirq monopolization of one or more of the CPUs?  For
        example, is your code subject to network-based denial-of-service
        attacks?  If so, you need RCU-bh.
 
-e.     Is your workload too update-intensive for normal use of
+f.     Is your workload too update-intensive for normal use of
        RCU, but inappropriate for other synchronization mechanisms?
        If so, consider SLAB_DESTROY_BY_RCU.  But please be careful!
 
-f.     Otherwise, use RCU.
+g.     Otherwise, use RCU.
 
 Of course, this all assumes that you have determined that RCU is in fact
 the right tool for your job.