Re: [PATCH tip/core/rcu 2/4] docs: Update RCU's hotplug requirements with a bit about design

[Paul E. McKenney]

On Tue, Nov 10, 2020 at 03:33:28PM -0500, Joel Fernandes wrote:
> On Mon, Nov 09, 2020 at 06:14:33PM +0100, Peter Zijlstra wrote:
> > On Mon, Nov 09, 2020 at 08:24:52AM -0800, Paul E. McKenney wrote:
> > > On Mon, Nov 09, 2020 at 01:23:17PM +0100, Peter Zijlstra wrote:
> > > > On Thu, Nov 05, 2020 at 03:05:08PM -0800, paulmck@xxxxxxxxxx wrote:
> > > > > From: "Joel Fernandes (Google)" <joel@xxxxxxxxxxxxxxxxx>
> > > > > 
> > > > > The rcu_barrier() section of the "Hotplug CPU" section discusses
> > > > > deadlocks, however the description of deadlocks other than those involving
> > > > > rcu_barrier() is rather incomplete.
> > > > > 
> > > > > This commit therefore continues the section by describing how RCU's
> > > > > design handles CPU hotplug in a deadlock-free way.
> > > > > 
> > > > > Signed-off-by: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx>
> > > > > Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx>
> > > > > ---
> > > > >  .../RCU/Design/Requirements/Requirements.rst       | 49 +++++++++++++++++-----
> > > > >  1 file changed, 39 insertions(+), 10 deletions(-)
> > > > > 
> > > > > diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
> > > > > index 1ae79a1..98557fe 100644
> > > > > --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> > > > > +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> > > > > @@ -1929,16 +1929,45 @@ The Linux-kernel CPU-hotplug implementation has notifiers that are used
> > > > >  to allow the various kernel subsystems (including RCU) to respond
> > > > >  appropriately to a given CPU-hotplug operation. Most RCU operations may
> > > > >  be invoked from CPU-hotplug notifiers, including even synchronous
> > > > > -grace-period operations such as ``synchronize_rcu()`` and
> > > > > -``synchronize_rcu_expedited()``.
> > > > 
> > > > I was under the impression that this rst crap now recognises func() and
> > > > you no longer need to make the text unreadable with "``".
> > > 
> > > It was there to start with, but good point.  How about the commit
> > > below?
> > 
> > Much appreciated, thanks!
> 
> Thanks for making the change, I built it and it looks good in my web browser
> ;-).
> 
> BTW, these APIs are obsolete due to consolidation. Paul could you remove them
> from the document?:
>  synchronize_rcu_bh(), synchronize_rcu_bh_expedited(), call_rcu_bh(),
>  rcu_barrier_bh().

Like this?

							Thanx, Paul

------------------------------------------------------------------------

commit ade4480b079c508923060d5f31e4f58475e8ea55
Author: Paul E. McKenney <paulmck@xxxxxxxxxx>
Date:   Tue Nov 10 16:17:42 2020 -0800

    doc: Remove obsolete RCU-bh and RCU-sched update-side API members
    
    synchronize_rcu_bh(), synchronize_rcu_bh_expedited(), call_rcu_bh(),
    rcu_barrier_bh(), synchronize_sched(), synchronize_rcu_sched_expedited(),
    call_rcu_sched(), and rcu_barrier_sched() no longer exist, so this
    commit removes mention of them.
    
    Reported-by: Joel Fernandes <joel@xxxxxxxxxxxxxxxxx>
    Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx>

diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index 9b23be6..1e3df77 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -2438,13 +2438,13 @@ glance as if rcu_read_unlock_bh() was executing very slowly.
 
 The `RCU-bh
 API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
-includes rcu_read_lock_bh(), rcu_read_unlock_bh(),
-rcu_dereference_bh(), rcu_dereference_bh_check(),
-synchronize_rcu_bh(), synchronize_rcu_bh_expedited(),
-call_rcu_bh(), rcu_barrier_bh(), and
-rcu_read_lock_bh_held(). However, the update-side APIs are now
-simple wrappers for other RCU flavors, namely RCU-sched in
-CONFIG_PREEMPT=n kernels and RCU-preempt otherwise.
+includes rcu_read_lock_bh(), rcu_read_unlock_bh(), rcu_dereference_bh(),
+rcu_dereference_bh_check(), and rcu_read_lock_bh_held(). However, the
+old RCU-bh update-side APIs are now gone, replaced by synchronize_rcu(),
+synchronize_rcu_expedited(), call_rcu(), and rcu_barrier().  In addition,
+anything that disables bottom halves also marks an RCU-bh read-side
+critical section, including local_bh_disable() and local_bh_enable(),
+local_irq_save() and local_irq_restore(), and so on.
 
 Sched Flavor (Historical)
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2481,13 +2481,13 @@ The `RCU-sched
 API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
 includes rcu_read_lock_sched(), rcu_read_unlock_sched(),
 rcu_read_lock_sched_notrace(), rcu_read_unlock_sched_notrace(),
-rcu_dereference_sched(), rcu_dereference_sched_check(),
-synchronize_sched(), synchronize_rcu_sched_expedited(),
-call_rcu_sched(), rcu_barrier_sched(), and
-rcu_read_lock_sched_held(). However, anything that disables
-preemption also marks an RCU-sched read-side critical section, including
-preempt_disable() and preempt_enable(), local_irq_save() and
-local_irq_restore(), and so on.
+rcu_dereference_sched(), rcu_dereference_sched_check(), and
+rcu_read_lock_sched_held().  However, the old RCU-sched update-side APIs
+are now gone, replaced by synchronize_rcu(), synchronize_rcu_expedited(),
+call_rcu(), and rcu_barrier().  In addition, anything that disables
+preemption also marks an RCU-sched read-side critical section,
+including preempt_disable() and preempt_enable(), local_irq_save()
+and local_irq_restore(), and so on.
 
 Sleepable RCU
 ~~~~~~~~~~~~~