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
