On Mon, Oct 08, 2018 at 06:33:41PM -0700, Joel Fernandes (Google) wrote: > whatisRCU says rcu_dereference cannot be used outside of rcu read lock > protected sections. Its better to mention rcu_dereference_protected when > it says that, so that the new reader is aware of this API and is not led > to believing that all RCU dereferences in all situations have to be > protected by a rcu_read_lock() and rcu_read_unlock(). > > Cc: tytso@xxxxxxx > Suggested-by: tytso@xxxxxxx > Signed-off-by: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx> Good stuff! I queued and pushed this with some wordsmithing. Could you please check for my having messed something up? Thanx, Paul > --- > Documentation/RCU/whatisRCU.txt | 20 +++++++++++++++++++- > 1 file changed, 19 insertions(+), 1 deletion(-) > > diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt > index 7c33445fd0e5..da820fc9b307 100644 > --- 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,24 @@ 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 update-side locks. These update-side locks are > + obviously acquired by the update-side code, but may also be used > + to protect other code sequences outside of the reader and the > + updater. If such sequences need to make an rcu_dereference() call, > + they can instead simply call rcu_dereference_protected() without > + needing extra calls to rcu_read_lock() and rcu_read_unlock(). > + Another advantage of using rcu_dereference_protected() is it does > + not prevent compiler optimizations unlike rcu_dereference() which > + could result in optimized and the result is assured to be > + functionaly correct due to the update-side locks. > + rcu_dereference_protected() takes a lockdep expression to > + indicate what is providing the protection. 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. > > -- > 2.19.0.605.g01d371f741-goog >
