Fedora kernel-2.6.17-1.2142_FC4 patched with stable patch-2.6.17.4-vs2.0.2-rc26.diff

[linux-2.6.git] / Documentation / RCU / checklist.txt

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 8f3fb77..49e27cc 100644 (file)
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -43,6 +43,10 @@ over a rather long period of time, but improvements are always welcome!
        rcu_read_lock_bh()) in the read-side critical sections,
        and are also an excellent aid to readability.
 
        rcu_read_lock_bh()) in the read-side critical sections,
        and are also an excellent aid to readability.
 

+       As a rough rule of thumb, any dereference of an RCU-protected
+       pointer must be covered by rcu_read_lock() or rcu_read_lock_bh()
+       or by the appropriate update-side lock.
+

 3.     Does the update code tolerate concurrent accesses?
 
        The whole point of RCU is to permit readers to run without
 3.     Does the update code tolerate concurrent accesses?
 
        The whole point of RCU is to permit readers to run without


@@ -90,7 +94,11 @@ over a rather long period of time, but improvements are always welcome!
 
                The rcu_dereference() primitive is used by the various
                "_rcu()" list-traversal primitives, such as the
 
                The rcu_dereference() primitive is used by the various
                "_rcu()" list-traversal primitives, such as the

-               list_for_each_entry_rcu().
+               list_for_each_entry_rcu().  Note that it is perfectly
+               legal (if redundant) for update-side code to use
+               rcu_dereference() and the "_rcu()" list-traversal
+               primitives.  This is particularly useful in code
+               that is common to readers and updaters.

 
        b.      If the list macros are being used, the list_add_tail_rcu()
                and list_add_rcu() primitives must be used in order
 
        b.      If the list macros are being used, the list_add_tail_rcu()
                and list_add_rcu() primitives must be used in order


@@ -150,16 +158,9 @@ over a rather long period of time, but improvements are always welcome!
 
        Use of the _rcu() list-traversal primitives outside of an
        RCU read-side critical section causes no harm other than
 
        Use of the _rcu() list-traversal primitives outside of an
        RCU read-side critical section causes no harm other than

-       a slight performance degradation on Alpha CPUs and some
-       confusion on the part of people trying to read the code.
-
-       Another way of thinking of this is "If you are holding the
-       lock that prevents the data structure from changing, why do
-       you also need RCU-based protection?"  That said, there may
-       well be situations where use of the _rcu() list-traversal
-       primitives while the update-side lock is held results in
-       simpler and more maintainable code.  The jury is still out
-       on this question.
+       a slight performance degradation on Alpha CPUs.  It can
+       also be quite helpful in reducing code bloat when common
+       code is shared between readers and updaters.

 
 10.    Conversely, if you are in an RCU read-side critical section,
        you -must- use the "_rcu()" variants of the list macros.
 
 10.    Conversely, if you are in an RCU read-side critical section,
        you -must- use the "_rcu()" variants of the list macros.


@@ -176,3 +177,9 @@ over a rather long period of time, but improvements are always welcome!
 
        If you want to wait for some of these other things, you might
        instead need to use synchronize_irq() or synchronize_sched().
 
        If you want to wait for some of these other things, you might
        instead need to use synchronize_irq() or synchronize_sched().

+
+12.    Any lock acquired by an RCU callback must be acquired elsewhere
+       with irq disabled, e.g., via spin_lock_irqsave().  Failing to
+       disable irq on a given acquisition of that lock will result in
+       deadlock as soon as the RCU callback happens to interrupt that
+       acquisition's critical section.