x86: unify and correct the GDT_ENTRY() macro

[linux-2.6-omap-h63xx.git] / Documentation / RCU / whatisRCU.txt

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 07cb93b82ba9e4e6539e1b0ecb43e4b8a0af416a..e04d643a9f57a802e59057165f719f36b5ebf5ab 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
 What is RCU?
 
 RCU is a synchronization mechanism that was added to the Linux kernel


@@ -184,7 +192,17 @@ synchronize_rcu()
        blocking, it registers a function and argument which are invoked
        after all ongoing RCU read-side critical sections have completed.
        This callback variant is particularly useful in situations where
        blocking, it registers a function and argument which are invoked
        after all ongoing RCU read-side critical sections have completed.
        This callback variant is particularly useful in situations where

-       it is illegal to block.
+       it is illegal to block or where update-side performance is
+       critically important.
+
+       However, the call_rcu() API should not be used lightly, as use
+       of the synchronize_rcu() API generally results in simpler code.
+       In addition, the synchronize_rcu() API has the nice property
+       of automatically limiting update rate should grace periods
+       be delayed.  This property results in system resilience in face
+       of denial-of-service attacks.  Code using call_rcu() should limit
+       update rate in order to gain this same sort of resilience.  See
+       checklist.txt for some approaches to limiting the update rate.

 
 rcu_assign_pointer()
 
 
 rcu_assign_pointer()
 


@@ -572,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
 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.
 called are guaranteed to have completed -- there is no way that
 synchronize_rcu() would have been able to write-acquire the lock
 otherwise.


@@ -677,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) {
        +       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);
        -                       write_unlock(&listmutex);

+       +                       list_del_rcu(&p->list);

        +                       spin_unlock(&listmutex);
        +                       synchronize_rcu();
                                kfree(p);
        +                       spin_unlock(&listmutex);
        +                       synchronize_rcu();
                                kfree(p);


@@ -726,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) {
  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);
  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
                                        10       synchronize_rcu();
 10       kfree(p);                     11       kfree(p);


@@ -739,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
 
 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
 precedes the kfree().
 
 However, there is one potential catch: the read-side and update-side


@@ -761,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.
 
 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
 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_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)
        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
 
        rcu_assign_pointer
        list_add_rcu


@@ -786,16 +799,36 @@ RCU pointer update:
        list_del_rcu
        list_replace_rcu
        hlist_del_rcu
        list_del_rcu
        list_replace_rcu
        hlist_del_rcu

+       hlist_add_after_rcu
+       hlist_add_before_rcu

        hlist_add_head_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_kernel (deprecated)
-       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.
 
 See the comment headers in the source code (or the docbook generated
 from them) for more information.