Re: [RFC PATCH 13/37] mm: implement speculative handling in __handle_mm_fault().

[Paul E. McKenney]

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:
> > +++ 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