Merge branch 'linus' into cpus4096

[pandora-kernel.git] / Documentation / RCU / whatisRCU.txt

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 4f41a60..e04d643 100644 (file)
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -1,3 +1,11 @@
+Please note that the "What is RCU?" LWN series is an excellent place
+to start learning about RCU:
+
+1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
+2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
+3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
+
+
 What is RCU?
 
 RCU is a synchronization mechanism that was added to the Linux kernel
@@ -582,7 +590,7 @@ The rcu_read_lock() and rcu_read_unlock() primitive read-acquire
 and release a global reader-writer lock.  The synchronize_rcu()
 primitive write-acquires this same lock, then immediately releases
 it.  This means that once synchronize_rcu() exits, all RCU read-side
-critical sections that were in progress before synchonize_rcu() was
+critical sections that were in progress before synchronize_rcu() was
 called are guaranteed to have completed -- there is no way that
 synchronize_rcu() would have been able to write-acquire the lock
 otherwise.
@@ -687,8 +695,9 @@ diff shows how closely related RCU and reader-writer locking can be.
        +       spin_lock(&listmutex);
                list_for_each_entry(p, head, lp) {
                        if (p->key == key) {
-                               list_del(&p->list);
+       -                       list_del(&p->list);
        -                       write_unlock(&listmutex);
+       +                       list_del_rcu(&p->list);
        +                       spin_unlock(&listmutex);
        +                       synchronize_rcu();
                                kfree(p);
@@ -736,7 +745,7 @@ Or, for those who prefer a side-by-side listing:
  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
  7     if (p->key == key) {             7     if (p->key == key) {
- 8       list_del(&p->list);            8       list_del(&p->list);
+ 8       list_del(&p->list);            8       list_del_rcu(&p->list);
  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
                                        10       synchronize_rcu();
 10       kfree(p);                     11       kfree(p);
@@ -749,7 +758,7 @@ Or, for those who prefer a side-by-side listing:
 
 Either way, the differences are quite small.  Read-side locking moves
 to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
-from a reader-writer lock to a simple spinlock, and a synchronize_rcu()
+a reader-writer lock to a simple spinlock, and a synchronize_rcu()
 precedes the kfree().
 
 However, there is one potential catch: the read-side and update-side
@@ -771,24 +780,18 @@ Linux-kernel source code, but it helps to have a full list of the
 APIs, since there does not appear to be a way to categorize them
 in docbook.  Here is the list, by category.
 
-Markers for RCU read-side critical sections:
-
-       rcu_read_lock
-       rcu_read_unlock
-       rcu_read_lock_bh
-       rcu_read_unlock_bh
-
 RCU pointer/list traversal:
 
        rcu_dereference
+       list_for_each_entry_rcu
+       hlist_for_each_entry_rcu
+
        list_for_each_rcu               (to be deprecated in favor of
                                         list_for_each_entry_rcu)
-       list_for_each_entry_rcu
        list_for_each_continue_rcu      (to be deprecated in favor of new
                                         list_for_each_entry_continue_rcu)
-       hlist_for_each_entry_rcu
 
-RCU pointer update:
+RCU pointer/list update:
 
        rcu_assign_pointer
        list_add_rcu
@@ -796,15 +799,36 @@ RCU pointer update:
        list_del_rcu
        list_replace_rcu
        hlist_del_rcu
+       hlist_add_after_rcu
+       hlist_add_before_rcu
        hlist_add_head_rcu
+       hlist_replace_rcu
+       list_splice_init_rcu()
+
+RCU:   Critical sections       Grace period            Barrier
+
+       rcu_read_lock           synchronize_net         rcu_barrier
+       rcu_read_unlock         synchronize_rcu
+                               call_rcu
+
+
+bh:    Critical sections       Grace period            Barrier
+
+       rcu_read_lock_bh        call_rcu_bh             rcu_barrier_bh
+       rcu_read_unlock_bh
+
+
+sched: Critical sections       Grace period            Barrier
+
+       [preempt_disable]       synchronize_sched       rcu_barrier_sched
+       [and friends]           call_rcu_sched
+
+
+SRCU:  Critical sections       Grace period            Barrier
 
-RCU grace period:
+       srcu_read_lock          synchronize_srcu        N/A
+       srcu_read_unlock
 
-       synchronize_net
-       synchronize_sched
-       synchronize_rcu
-       call_rcu
-       call_rcu_bh
 
 See the comment headers in the source code (or the docbook generated
 from them) for more information.