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>

4 files changed, 29 insertions, 16 deletions

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 0c134f8afc6f..bff2d8be1e18 100644
--- 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 31852705b586..bf778332a28f 100644
--- 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 f3e0625f4290..083d88cbc089 100644
--- 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 6ef692667e2f..8e8cdc2430b9 100644
--- 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.