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: ty...@mit.edu
> Suggested-by: ty...@mit.edu
> Signed-off-by: Joel Fernandes (Google) <j...@joelfernandes.org>
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
>
