Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 9 Oct 2018 20:09:06 -0700
From:   "Paul E. McKenney" <paulmck@linux.ibm.com>
To:     "Joel Fernandes (Google)" <joel@joelfernandes.org>
Cc:     linux-kernel@vger.kernel.org, tytso@mit.edu,
        Jonathan Corbet <corbet@lwn.net>,
        Josh Triplett <josh@joshtriplett.org>,
        Lai Jiangshan <jiangshanlai@gmail.com>,
        linux-doc@vger.kernel.org,
        Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
        Steven Rostedt <rostedt@goodmis.org>
Subject: Re: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected
Reply-To: paulmck@linux.ibm.com
References: <20181009013341.60111-1-joel@joelfernandes.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20181009013341.60111-1-joel@joelfernandes.org>
User-Agent: Mutt/1.5.21 (2010-09-15)
Message-Id: <20181010030906.GB2674@linux.ibm.com>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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
>