doc: Make reader aware of rcu_dereference_protected

The whatisRCU.txt document says rcu_dereference() cannot be used
outside of rcu_read_lock() protected sections.  The commit adds a
mention of rcu_dereference_protected(), so that the new reader knows
that this API can be used to avoid update-side use of rcu_read_lock()
and rcu_read_unlock().

Cc: tytso@mit.edu
Suggested-by: tytso@mit.edu
Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
[ paulmck: Update wording, including further feedback from Joel. ]
Signed-off-by: Paul E. McKenney <paulmck@linux.ibm.com>

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 7c33445fd0e54e6f5d11e63134714ae962633fc9..4a6854318b17f0d7c8cdf95dc1a3e612a7ea910b 100644 (file)
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -266,7 +266,7 @@ rcu_dereference()
        unnecessary overhead on Alpha CPUs.
 
        Note that the value returned by rcu_dereference() is valid
-       only within the enclosing RCU read-side critical section.
+       only within the enclosing RCU read-side critical section [1].
        For example, the following is -not- legal:
 
                rcu_read_lock();
@@ -292,6 +292,19 @@ rcu_dereference()
        typically used indirectly, via the _rcu list-manipulation
        primitives, such as list_for_each_entry_rcu().
 
+       [1] The variant rcu_dereference_protected() can be used outside
+       of an RCU read-side critical section as long as the usage is
+       protected by locks acquired by the update-side code.  This variant
+       avoids the lockdep warning that would happen when using (for
+       example) rcu_dereference() without rcu_read_lock() protection.
+       Using rcu_dereference_protected() also has the advantage
+       of permitting compiler optimizations that rcu_dereference()
+       must prohibit.  The rcu_dereference_protected() variant takes
+       a lockdep expression to indicate which locks must be acquired
+       by the caller. If the indicated protection is not provided,
+       a lockdep splat is emitted.  See RCU/Design/Requirements.html
+       and the API's code comments for more details and example usage.
+
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.