On Thu, Apr 29, 2021 at 07:49:08PM +0100, Matthew Wilcox wrote:

On Thu, Apr 29, 2021 at 11:34:12AM -0700, Paul E. McKenney wrote:

quoted

+++ b/include/linux/rcupdate.h

@@ -532,7 +532,10 @@ do {									      \
  * @p: The pointer to read, prior to dereferencing
  * @c: The conditions under which the dereference will take place
  *
- * This is the RCU-bh counterpart to rcu_dereference_check().
+ * This is the RCU-bh counterpart to rcu_dereference_check().  However,
+ * please note that in recent kernels, synchronize_rcu() waits for
+ * local_bh_disable() regions of code in addition to regions of code
+ * demarked by rcu_read_lock() and rcu_read_unlock().
  */

I've been trying to get rid of "please note that" in my own documentation
recently.  It doesn't add any value.  Also, "recent kernels" is going to
go stale quickly, "Since v5.8" (or whatever) is good because it lets us
know in ten years that we can just delete the reference.

So I'd make this:

 * This is the RCU-bh equivalent of rcu_dereference_check().  Since v5.8,
 * synchronize_rcu() waits for code with bottom halves disabled as well
 * as code between rcu_read_lock() and rcu_read_unlock().

Normally, I would be right there with you on the "less is more"
approach to writing.  But in this particular case:

1.	I added comments to rcu_read_lock_bh(), rcu_read_lock_sched(),
	call_rcu(), and synchronize_rcu().

2.	I included a section entitled "RCU flavor consolidation" in the
	2019 edition of the RCU API: https://lwn.net/Articles/777036/

3.	I presented on this topic at LCA:
	https://www.youtube.com/watch?v=hZX1aokdNiY

4.	I published a paper on this topic:
	https://dl.acm.org/doi/10.1145/3319647.3325836
	http://www.rdrop.com/~paulmck/RCU/rcu-exploit.2019.05.01a.pdf

All of these, even taken together, have proven to be insufficient.
This therefore does not appear to be the place to economize on words.  :-/

Your point on the version (v5.0, as it turns out) is right on, and I
will make that change.

							Thanx, Paul