[PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[Joel Fernandes (Google)]

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

Re: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[Paul E. McKenney]

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@mit.edu
> Suggested-by: tytso@mit.edu
> Signed-off-by: Joel Fernandes (Google) <joel@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
> 

Re: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[Joel Fernandes]

On Tue, Oct 09, 2018 at 08:09:06PM -0700, Paul E. McKenney wrote:
> 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@mit.edu
> > Suggested-by: tytso@mit.edu
> > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> 
> Good stuff!  I queued and pushed this with some wordsmithing.  Could
> you please check for my having messed something up?

One small nit which the below diff should fix, but otherwise looks good to
me, thanks!

 - Joel

----8<----

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 38044c978e54..093b85ad49eb 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -297,7 +297,7 @@ rcu_dereference()
 	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 have the advantage
+	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

Re: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[Paul E. McKenney]

On Tue, Oct 09, 2018 at 09:01:59PM -0700, Joel Fernandes wrote:
> On Tue, Oct 09, 2018 at 08:09:06PM -0700, Paul E. McKenney wrote:
> > 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@mit.edu
> > > Suggested-by: tytso@mit.edu
> > > Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > 
> > Good stuff!  I queued and pushed this with some wordsmithing.  Could
> > you please check for my having messed something up?
> 
> One small nit which the below diff should fix, but otherwise looks good to
> me, thanks!

Good catch!  I rolled the into the commit, thank you!

							Thanx, Paul

>  - Joel
> 
> ----8<----
> 
> diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
> index 38044c978e54..093b85ad49eb 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.txt
> @@ -297,7 +297,7 @@ rcu_dereference()
>  	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 have the advantage
> +	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
> 

Re: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected

[Theodore Y. Ts'o]

Thanks, the update to the documentation looks great!!

I think lockdep_is_held() should be better documented, but that should
be done in the lockdep docs, not the RCU documentation.

	    	      	  		- Ted