Re: [PATCH rcu 1/2] docs: Add documentation for rude and trace RCU flavors

["Paul E. McKenney" <paulmck@kernel.org>]

On Wed, Apr 20, 2022 at 11:32:31AM -0400, Steven Rostedt wrote:
> On Mon, 18 Apr 2022 15:50:32 -0700
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > This commit belatedly adds documentation of Tasks Rude RCU and Tasks
> > Trace RCU to RCU's requirements document.
> > 
> > Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> > ---
> >  .../RCU/Design/Requirements/Requirements.rst  | 32 +++++++++++++++++++
> >  1 file changed, 32 insertions(+)
> > 
> > diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
> > index 45278e2974c0..ff2be1ac54c4 100644
> > --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> > +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> > @@ -2654,6 +2654,38 @@ synchronize_rcu(), and rcu_barrier(), respectively. In
> >  three APIs are therefore implemented by separate functions that check
> >  for voluntary context switches.
> >  
> > +Tasks Rude RCU
> > +~~~~~~~~~~~~~~
> > +
> > +Some forms of tracing need to wait for all preemption-disabled regions
> > +of code running on any online CPU, including those executed when RCU is
> > +not watching.  This means that synchronize_rcu() is insufficient, and
> > +Tasks Rude RCU must be used instead.  This flavor of RCU does its work by
> > +forcing a workqueue to be scheduled on each online CPU, hence the "Rude"
> > +moniker.  And this operation is considered to be quite rude by real-time
> > +workloads that don't want their ``nohz_full`` CPUs receiving IPIs and
> > +by battery-powered systems that don't want their idle CPUs to be awakened.
> > +
> > +The tasks-rude-RCU API is also reader-marking-free and thus quite compact,
> > +consisting of call_rcu_tasks_rude(), synchronize_rcu_tasks_rude(),
> > +and rcu_barrier_tasks_rude().
> 
> Are we going to be able to get rid of the "rude" version once we have all
> tracing in a RCU visible section?

You tell me!  ;-)

If there are no longer any users, I would be happy to get rid of it.
As of v5.18-rc1, the only user is ftrace.

> > +
> > +Tasks Trace RCU
> > +~~~~~~~~~~~~~~~
> > +
> > +Some forms of tracing need to sleep in readers, but cannot tolerate
> > +SRCU's read-side overhead, which includes a full memory barrier in both
> > +srcu_read_lock() and srcu_read_unlock().  This need is handled by a
> > +Tasks Trace RCU that uses scheduler locking and IPIs to synchronize with
> > +readers.  Real-time systems that cannot tolerate IPIs may build their
> > +kernels with ``CONFIG_TASKS_TRACE_RCU_READ_MB=y``, which avoids the IPIs at
> > +the expense of adding full memory barriers to the read-side primitives.
> 
> If NOHZ_FULL is enabled, is there a way to also be able to have this full
> mb on RT removed as well?
> 
> > +
> > +The tasks-trace-RCU API is also reasonably compact,
> > +consisting of rcu_read_lock_trace(), rcu_read_unlock_trace(),
> > +rcu_read_lock_trace_held(), call_rcu_tasks_trace(),
> > +synchronize_rcu_tasks_trace(), and rcu_barrier_tasks_trace().
> > +
> >  Possible Future Changes
> >  -----------------------
> >  
> 
> For the documentation:
> 
> Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>

I will apply this on the next rebase, thank you!

							Thanx, Paul