rcu: Documentation update

This commit applies a few updates based on a quick review of the RCU
documentations.

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

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 31ef8fe07f828026ad31f29e63bdd95143bf3e2a..79e789b8b8ea22d680463a531a3e3d9990adb8ba 100644 (file)
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -217,9 +217,14 @@ over a rather long period of time, but improvements are always welcome!
        whether the increased speed is worth it.
 
 8.     Although synchronize_rcu() is slower than is call_rcu(), it
-       usually results in simpler code.  So, unless update performance
-       is critically important or the updaters cannot block,
-       synchronize_rcu() should be used in preference to call_rcu().
+       usually results in simpler code.  So, unless update performance is
+       critically important, the updaters cannot block, or the latency of
+       synchronize_rcu() is visible from userspace, synchronize_rcu()
+       should be used in preference to call_rcu().  Furthermore,
+       kfree_rcu() usually results in even simpler code than does
+       synchronize_rcu() without synchronize_rcu()'s multi-millisecond
+       latency.  So please take advantage of kfree_rcu()'s "fire and
+       forget" memory-freeing capabilities where it applies.
 
        An especially important property of the synchronize_rcu()
        primitive is that it automatically self-limits: if grace periods
@@ -268,7 +273,8 @@ over a rather long period of time, but improvements are always welcome!
        e.      Periodically invoke synchronize_rcu(), permitting a limited
                number of updates per grace period.
 
-       The same cautions apply to call_rcu_bh() and call_rcu_sched().
+       The same cautions apply to call_rcu_bh(), call_rcu_sched(),
+       call_srcu(), and kfree_rcu().
 
 9.     All RCU list-traversal primitives, which include
        rcu_dereference(), list_for_each_entry_rcu(), and
@@ -296,9 +302,9 @@ over a rather long period of time, but improvements are always welcome!
        all currently executing rcu_read_lock()-protected RCU read-side
        critical sections complete.  It does -not- necessarily guarantee
        that all currently running interrupts, NMIs, preempt_disable()
-       code, or idle loops will complete.  Therefore, if you do not have
-       rcu_read_lock()-protected read-side critical sections, do -not-
-       use synchronize_rcu().
+       code, or idle loops will complete.  Therefore, if your
+       read-side critical sections are protected by something other
+       than rcu_read_lock(), do -not- use synchronize_rcu().
 
        Similarly, disabling preemption is not an acceptable substitute
        for rcu_read_lock().  Code that attempts to use preemption
@@ -401,9 +407,9 @@ over a rather long period of time, but improvements are always welcome!
        read-side critical sections.  It is the responsibility of the
        RCU update-side primitives to deal with this.
 
-17.    Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and
-       the __rcu sparse checks to validate your RCU code.  These
-       can help find problems as follows:
+17.    Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
+       __rcu sparse checks (enabled by CONFIG_SPARSE_RCU_POINTER) to
+       validate your RCU code.  These can help find problems as follows:
 
        CONFIG_PROVE_RCU: check that accesses to RCU-protected data
                structures are carried out under the proper RCU

diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.txt
index a102d4b3724bad454250d5d9e4ae883818725d91..cd83d2348fef8c4a3ff3bee57fc9904976b46390 100644 (file)
--- a/Documentation/RCU/lockdep.txt
+++ b/Documentation/RCU/lockdep.txt
@@ -64,6 +64,11 @@ checking of rcu_dereference() primitives:
                but retain the compiler constraints that prevent duplicating
                or coalescsing.  This is useful when when testing the
                value of the pointer itself, for example, against NULL.
+       rcu_access_index(idx):
+               Return the value of the index and omit all barriers, but
+               retain the compiler constraints that prevent duplicating
+               or coalescsing.  This is useful when when testing the
+               value of the index itself, for example, against -1.
 
 The rcu_dereference_check() check expression can be any boolean
 expression, but would normally include a lockdep expression.  However,

diff --git a/Documentation/RCU/rcubarrier.txt b/Documentation/RCU/rcubarrier.txt
index 38428c125135504de8737943088a4e0f3df6f213..2e319d1b9ef28c0d9c19505306063cfc6bc9f595 100644 (file)
--- a/Documentation/RCU/rcubarrier.txt
+++ b/Documentation/RCU/rcubarrier.txt
@@ -79,7 +79,20 @@ complete. Pseudo-code using rcu_barrier() is as follows:
    2. Execute rcu_barrier().
    3. Allow the module to be unloaded.
 
-The rcutorture module makes use of rcu_barrier in its exit function
+There are also rcu_barrier_bh(), rcu_barrier_sched(), and srcu_barrier()
+functions for the other flavors of RCU, and you of course must match
+the flavor of rcu_barrier() with that of call_rcu().  If your module
+uses multiple flavors of call_rcu(), then it must also use multiple
+flavors of rcu_barrier() when unloading that module.  For example, if
+it uses call_rcu_bh(), call_srcu() on srcu_struct_1, and call_srcu() on
+srcu_struct_2(), then the following three lines of code will be required
+when unloading:
+
+ 1 rcu_barrier_bh();
+ 2 srcu_barrier(&srcu_struct_1);
+ 3 srcu_barrier(&srcu_struct_2);
+
+The rcutorture module makes use of rcu_barrier() in its exit function
 as follows:
 
  1 static void