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

From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
To: linux-kernel@vger.kernel.org
Cc: "Joel Fernandes (Google)" <joel@joelfernandes.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>,
	"Paul E. McKenney" <paulmck@linux.ibm.com>,
	Steven Rostedt <rostedt@goodmis.org>
Subject: [PATCH] docs: rcu: Make reader aware of rcu_dereference_protected
Date: Mon,  8 Oct 2018 18:33:41 -0700	[thread overview]
Message-ID: <20181009013341.60111-1-joel@joelfernandes.org> (raw)

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

