doc: Present the role of READ_ONCE()

This commit adds an explanation of the special cases where READ_ONCE()
may be used in place of a member of the rcu_dereference() family.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index 2efed9926c3f9039d151ceb1bcca96bf381ab543..bb7128eb322ef8f42c0d76ea653da146355ebbb6 100644 (file)
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -314,6 +314,13 @@ over a rather long period of time, but improvements are always welcome!
        shared between readers and updaters.  Additional primitives
        are provided for this case, as discussed in lockdep.txt.
 
+       One exception to this rule is when data is only ever added to
+       the linked data structure, and is never removed during any
+       time that readers might be accessing that structure.  In such
+       cases, READ_ONCE() may be used in place of rcu_dereference()
+       and the read-side markers (rcu_read_lock() and rcu_read_unlock(),
+       for example) may be omitted.
+
 10.    Conversely, if you are in an RCU read-side critical section,
        and you don't hold the appropriate update-side lock, you -must-
        use the "_rcu()" variants of the list macros.  Failing to do so

diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index c9667eb0d44469308c401f8270bbf7ea261dab6d..f3e587acb4deb732ee77a1c14a1c58a8f9cbeff5 100644 (file)
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -28,6 +28,12 @@ Follow these rules to keep your RCU code working properly:
        for an example where the compiler can in fact deduce the exact
        value of the pointer, and thus cause misordering.
 
+-      In the special case where data is added but is never removed
+       while readers are accessing the structure, READ_ONCE() may be used
+       instead of rcu_dereference().  In this case, use of READ_ONCE()
+       takes on the role of the lockless_dereference() primitive that
+       was removed in v4.15.
+
 -      You are only permitted to use rcu_dereference on pointer values.
        The compiler simply knows too much about integral values to
        trust it to carry dependencies through integer operations.