[PATCH rcu 0/2] Documentation updates for v5.19

[PATCH rcu 0/2] Documentation updates for v5.19

[Paul E. McKenney]

Hello!

This series contains a couple of documentation updates:

1.	Add documentation for rude and trace RCU flavors.

2.	Update RCU cross-references as suggested in doc-guide, courtesy
	of Akira Yokosawa.

						Thanx, Paul

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

 Documentation/RCU/Design/Requirements/Requirements.rst                         |    4 -
 b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst                 |    2 
 b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst |    2 
 b/Documentation/RCU/Design/Requirements/Requirements.rst                       |   32 ++++++++++
 b/Documentation/RCU/arrayRCU.rst                                               |    4 -
 b/Documentation/RCU/checklist.rst                                              |    9 +-
 b/Documentation/RCU/rcu.rst                                                    |   13 +---
 b/Documentation/RCU/rculist_nulls.rst                                          |    2 
 b/Documentation/RCU/whatisRCU.rst                                              |   18 ++---
 9 files changed, 57 insertions(+), 29 deletions(-)

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

[Paul E. McKenney]

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().
+
+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.
+
+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
 -----------------------
 
-- 
2.31.1.189.g2e36527f23

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

[Steven Rostedt]

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?

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

-- Steve

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

[Paul E. McKenney]

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

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

[Steven Rostedt]

On Wed, 20 Apr 2022 09:13:19 -0700
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > 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.

I'll add to my todo list to audit the existing code to see if we can
finally drop it.

-- Steve

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

[Steven Rostedt]

On Wed, 20 Apr 2022 09:13:19 -0700
"Paul E. McKenney" <paulmck@kernel.org> wrote:

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

Hmm, if we no longer need the rude version due to noinstr, if then we need
to use something that adds full memory barriers at *every function call*
then I rather keep the rude version.

-- Steve

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

[Paul E. McKenney]

On Wed, Apr 20, 2022 at 12:19:06PM -0400, Steven Rostedt wrote:
> On Wed, 20 Apr 2022 09:13:19 -0700
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > > +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?

Ah, I did miss this question, apologies.  The tradeoff is IPIs during
each Tasks Trace RCU grace period on the one hand or the read-side
memory barrier on the other.

CONFIG_TASKS_TRACE_RCU_READ_MB=y gets you the read-side memory barriers.

CONFIG_TASKS_TRACE_RCU_READ_MB=n gets you the IPIs.

Choose wisely!  ;-)

More seriously, I could easily imagine an RT system being set up so that
Tasks Trace RCU grace periods never happen while the real-time application
is running.  This requires the system administrator being careful what
tracing facilities are used that those application is running, but
it seems doable to me.

Such an RT system could build with CONFIG_TASKS_TRACE_RCU_READ_MB=n to
avoid the read-side memory barriers, but also avoiding the IPIs while
the application was running.

Even more seriously, if the real-time application runs in nohz_full mode,
Tasks Trace RCU will avoid IPIing it.  In that case, the kernel can be
built with CONFIG_TASKS_TRACE_RCU_READ_MB=n and avoid both the read-side
memory barriers and the IPIs.

And the final bit of seriousness for this email, if your real-time
application didn't have a time-critical CPU-bound component, it might
be possible to avoid both read-side memory barriers and IPIs by
adjusting the rcu_tasks_trace_qs() code in the context-switch hook.

> Hmm, if we no longer need the rude version due to noinstr, if then we need
> to use something that adds full memory barriers at *every function call*
> then I rather keep the rude version.

A full memory barrier at every function call does sound more heavy weight
than would be good.  ;-)

							Thanx, Paul

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

[Steven Rostedt]

On Wed, 20 Apr 2022 09:48:47 -0700
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > > > If NOHZ_FULL is enabled, is there a way to also be able to have this full
> > > > mb on RT removed as well?  
> 
> Ah, I did miss this question, apologies.  The tradeoff is IPIs during
> each Tasks Trace RCU grace period on the one hand or the read-side
> memory barrier on the other.
> 
> CONFIG_TASKS_TRACE_RCU_READ_MB=y gets you the read-side memory barriers.
> 
> CONFIG_TASKS_TRACE_RCU_READ_MB=n gets you the IPIs.
> 
> Choose wisely!  ;-)

Yes, I figured this part.

> 
> More seriously, I could easily imagine an RT system being set up so that
> Tasks Trace RCU grace periods never happen while the real-time application
> is running.  This requires the system administrator being careful what
> tracing facilities are used that those application is running, but
> it seems doable to me.

Not something I would want to put onto the system administrator.

> 
> Such an RT system could build with CONFIG_TASKS_TRACE_RCU_READ_MB=n to
> avoid the read-side memory barriers, but also avoiding the IPIs while
> the application was running.
> 
> Even more seriously, if the real-time application runs in nohz_full mode,
> Tasks Trace RCU will avoid IPIing it.  In that case, the kernel can be
> built with CONFIG_TASKS_TRACE_RCU_READ_MB=n and avoid both the read-side
> memory barriers and the IPIs.

Is this currently the case?

> 
> And the final bit of seriousness for this email, if your real-time
> application didn't have a time-critical CPU-bound component, it might
> be possible to avoid both read-side memory barriers and IPIs by
> adjusting the rcu_tasks_trace_qs() code in the context-switch hook.
> 
> > Hmm, if we no longer need the rude version due to noinstr, if then we need
> > to use something that adds full memory barriers at *every function call*
> > then I rather keep the rude version.  
> 
> A full memory barrier at every function call does sound more heavy weight
> than would be good.  ;-)

Hmm, I just realized that the function tracer can not use any "reader side"
tracing. Thus, I wonder if we can modify the rude side to be a bit less
rude? That is, what can be changed if the reader always happens inside an
"RCU is watching" location but still has the requirement that it can not
tell RCU it started "reading" and allows preemption?

The issue with function tracing is that the "read side" starts at the
location that calls the trampoline (aka fentry or mcount call). Where it's
either a nop or a call to the trampoline. To free the trampoline, we would
still need to wait for all locations watched by RCU to schedule. Would it
still be rude to do so? That is, we do not need to worry about idle tasks
nor NOHZ_FULL tasks.

-- Steve

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

[Paul E. McKenney]

On Wed, Apr 20, 2022 at 02:02:26PM -0400, Steven Rostedt wrote:
> On Wed, 20 Apr 2022 09:48:47 -0700
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > > > If NOHZ_FULL is enabled, is there a way to also be able to have this full
> > > > > mb on RT removed as well?  
> > 
> > Ah, I did miss this question, apologies.  The tradeoff is IPIs during
> > each Tasks Trace RCU grace period on the one hand or the read-side
> > memory barrier on the other.
> > 
> > CONFIG_TASKS_TRACE_RCU_READ_MB=y gets you the read-side memory barriers.
> > 
> > CONFIG_TASKS_TRACE_RCU_READ_MB=n gets you the IPIs.
> > 
> > Choose wisely!  ;-)
> 
> Yes, I figured this part.

Very good!  ;-)

> > More seriously, I could easily imagine an RT system being set up so that
> > Tasks Trace RCU grace periods never happen while the real-time application
> > is running.  This requires the system administrator being careful what
> > tracing facilities are used that those application is running, but
> > it seems doable to me.
> 
> Not something I would want to put onto the system administrator.

Indeed, I could imagine cases where this restriction would not be welcome.

> > Such an RT system could build with CONFIG_TASKS_TRACE_RCU_READ_MB=n to
> > avoid the read-side memory barriers, but also avoiding the IPIs while
> > the application was running.
> > 
> > Even more seriously, if the real-time application runs in nohz_full mode,
> > Tasks Trace RCU will avoid IPIing it.  In that case, the kernel can be
> > built with CONFIG_TASKS_TRACE_RCU_READ_MB=n and avoid both the read-side
> > memory barriers and the IPIs.
> 
> Is this currently the case?

Yes.

There are of course races where the IPI might be sent due to some task
other than the application running, but where the IPI arrives after
that task is done and the application is once again running in nohz_full
userspace mode, but once the application is going, no IPIs will be sent.

> > And the final bit of seriousness for this email, if your real-time
> > application didn't have a time-critical CPU-bound component, it might
> > be possible to avoid both read-side memory barriers and IPIs by
> > adjusting the rcu_tasks_trace_qs() code in the context-switch hook.
> > 
> > > Hmm, if we no longer need the rude version due to noinstr, if then we need
> > > to use something that adds full memory barriers at *every function call*
> > > then I rather keep the rude version.  
> > 
> > A full memory barrier at every function call does sound more heavy weight
> > than would be good.  ;-)
> 
> Hmm, I just realized that the function tracer can not use any "reader side"
> tracing. Thus, I wonder if we can modify the rude side to be a bit less
> rude? That is, what can be changed if the reader always happens inside an
> "RCU is watching" location but still has the requirement that it can not
> tell RCU it started "reading" and allows preemption?

This was the original motivation for Tasks RCU, in which voluntary context
switches (but not preemptions) are quiescent states.  But this does not
send IPIs because it instead relies on the memory ordering provided by
the scheduler.

This flavor of RCU does not care about whether or not RCU is watching,
but it does ignore idle tasks, which no not necessarily ever do voluntary
context switches, for example, when a given CPU remains idle for a long
time.

But the comments on schedule_idle() look like they were set up to
try to do something about this.  I don't see how they do without
that CPU coming out of idle, though.  So what am I missing?

> The issue with function tracing is that the "read side" starts at the
> location that calls the trampoline (aka fentry or mcount call). Where it's
> either a nop or a call to the trampoline. To free the trampoline, we would
> still need to wait for all locations watched by RCU to schedule. Would it
> still be rude to do so? That is, we do not need to worry about idle tasks
> nor NOHZ_FULL tasks.

The original purpose of RCU Tasks Rude was to deal with the idle tasks,
given that RCU Tasks dealt only with the non-idle tasks.

Or is there a trick that I missed?

							Thanx, Paul

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

[Steven Rostedt]

On Wed, 20 Apr 2022 11:37:26 -0700
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> The original purpose of RCU Tasks Rude was to deal with the idle tasks,
> given that RCU Tasks dealt only with the non-idle tasks.
> 
> Or is there a trick that I missed?

It use to be that ftrace trampolines could be called from all sorts of
locations until Peter introduced the "noinstr" annotation that causes
objtool to fail to build when tracing happens there. If that prevents
ftrace from happening in that idle case where RCU tasks can not handle it,
then it may be that we can simply switch ftrace to the RCU tasks and get
rid of rude. ?

-- Steve

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

[Paul E. McKenney]

On Wed, Apr 20, 2022 at 02:43:09PM -0400, Steven Rostedt wrote:
> On Wed, 20 Apr 2022 11:37:26 -0700
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > The original purpose of RCU Tasks Rude was to deal with the idle tasks,
> > given that RCU Tasks dealt only with the non-idle tasks.
> > 
> > Or is there a trick that I missed?
> 
> It use to be that ftrace trampolines could be called from all sorts of
> locations until Peter introduced the "noinstr" annotation that causes
> objtool to fail to build when tracing happens there. If that prevents
> ftrace from happening in that idle case where RCU tasks can not handle it,
> then it may be that we can simply switch ftrace to the RCU tasks and get
> rid of rude. ?

The last time that I asked Peter about this, he sounded less confident
than I would like, but...

Once sufficient confidence is present, RCU Tasks could pay attention to
idle tasks, and declare a quiescent state for that idle task if RCU is
not currently watching its corresponding CPU.

This would get rid of all of the RCU Tasks Rude use cases that I know of.

The ones that I don't know of?  Who knows?  ;-)

							Thanx, Paul

[PATCH rcu 2/2] docs: Update RCU cross-references as suggested in doc-guide

[Paul E. McKenney]

From: Akira Yokosawa <akiyks@gmail.com>

The RCU documentation contains old-style cross references which
do not follow the best practices outlined in doc-guide/sphinx.rst.
In addition, some of the cross references use URLs that should be replaced
by pathnames.

Update all of these cross references and adjust the surrounding words.

Summary of changes:

  - out-of-date plaintext file names (*.txt) -> *.rst
  - references by :ref: tags -> path names of *.rst
    * use relative paths to .rst files under the RCU/ subdirectory
    * use abs paths of Documentation/xxx for other .rst files
  - references by URL under https://www.kernel.org/ -> paths of *.rst
  - adjust surrounding words of some of updated references.

Note:
  The automarkup.py script interprets references via "*.txt" as if they
were via "*.rst", so the *.txt -> *.rst changes should be regarded as
cleanups rather than bug fixes.

Cc: rcu@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
---
 .../Design/Data-Structures/Data-Structures.rst |  2 +-
 .../Expedited-Grace-Periods.rst                |  2 +-
 .../RCU/Design/Requirements/Requirements.rst   |  4 ++--
 Documentation/RCU/arrayRCU.rst                 |  4 ++--
 Documentation/RCU/checklist.rst                |  9 ++++-----
 Documentation/RCU/rcu.rst                      | 13 ++++++-------
 Documentation/RCU/rculist_nulls.rst            |  2 +-
 Documentation/RCU/whatisRCU.rst                | 18 ++++++++----------
 8 files changed, 25 insertions(+), 29 deletions(-)

diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
index f4efd6897b09..b34990c7c377 100644
--- a/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
+++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.rst
@@ -973,7 +973,7 @@ The ``->dynticks`` field counts the corresponding CPU's transitions to
 and from either dyntick-idle or user mode, so that this counter has an
 even value when the CPU is in dyntick-idle mode or user mode and an odd
 value otherwise. The transitions to/from user mode need to be counted
-for user mode adaptive-ticks support (see timers/NO_HZ.txt).
+for user mode adaptive-ticks support (see Documentation/timers/no_hz.rst).
 
 The ``->rcu_need_heavy_qs`` field is used to record the fact that the
 RCU core code would really like to see a quiescent state from the
diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
index 6f89cf1e567d..c9c957c85bac 100644
--- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
+++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
@@ -406,7 +406,7 @@ In earlier implementations, the task requesting the expedited grace
 period also drove it to completion. This straightforward approach had
 the disadvantage of needing to account for POSIX signals sent to user
 tasks, so more recent implemementations use the Linux kernel's
-`workqueues <https://www.kernel.org/doc/Documentation/core-api/workqueue.rst>`__.
+workqueues (see Documentation/core-api/workqueue.rst).
 
 The requesting task still does counter snapshotting and funnel-lock
 processing, but the task reaching the top of the funnel lock does a
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index ff2be1ac54c4..04ed8bf27a0e 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -370,8 +370,8 @@ pointer fetched by rcu_dereference() may not be used outside of the
 outermost RCU read-side critical section containing that
 rcu_dereference(), unless protection of the corresponding data
 element has been passed from RCU to some other synchronization
-mechanism, most commonly locking or `reference
-counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
+mechanism, most commonly locking or reference counting
+(see ../../rcuref.rst).
 
 .. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]
 .. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf
diff --git a/Documentation/RCU/arrayRCU.rst b/Documentation/RCU/arrayRCU.rst
index 4051ea3871ef..a5f2ff8fc54c 100644
--- a/Documentation/RCU/arrayRCU.rst
+++ b/Documentation/RCU/arrayRCU.rst
@@ -33,8 +33,8 @@ Situation 1: Hash Tables
 
 Hash tables are often implemented as an array, where each array entry
 has a linked-list hash chain.  Each hash chain can be protected by RCU
-as described in the listRCU.txt document.  This approach also applies
-to other array-of-list situations, such as radix trees.
+as described in listRCU.rst.  This approach also applies to other
+array-of-list situations, such as radix trees.
 
 .. _static_arrays:
 
diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index f4545b7c9a63..42cc5d891bd2 100644
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -140,8 +140,7 @@ over a rather long period of time, but improvements are always welcome!
 		prevents destructive compiler optimizations.  However,
 		with a bit of devious creativity, it is possible to
 		mishandle the return value from rcu_dereference().
-		Please see rcu_dereference.txt in this directory for
-		more information.
+		Please see rcu_dereference.rst for more information.
 
 		The rcu_dereference() primitive is used by the
 		various "_rcu()" list-traversal primitives, such
@@ -151,7 +150,7 @@ over a rather long period of time, but improvements are always welcome!
 		primitives.  This is particularly useful in code that
 		is common to readers and updaters.  However, lockdep
 		will complain if you access rcu_dereference() outside
-		of an RCU read-side critical section.  See lockdep.txt
+		of an RCU read-side critical section.  See lockdep.rst
 		to learn what to do about this.
 
 		Of course, neither rcu_dereference() nor the "_rcu()"
@@ -323,7 +322,7 @@ over a rather long period of time, but improvements are always welcome!
 	primitives when the update-side lock is held is that doing so
 	can be quite helpful in reducing code bloat when common code is
 	shared between readers and updaters.  Additional primitives
-	are provided for this case, as discussed in lockdep.txt.
+	are provided for this case, as discussed in lockdep.rst.
 
 	One exception to this rule is when data is only ever added to
 	the linked data structure, and is never removed during any
@@ -480,4 +479,4 @@ over a rather long period of time, but improvements are always welcome!
 	both rcu_barrier() and synchronize_rcu(), if necessary, using
 	something like workqueues to to execute them concurrently.
 
-	See rcubarrier.txt for more information.
+	See rcubarrier.rst for more information.
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 0e03c6ef3147..3cfe01ba9a49 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -10,9 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the
-:ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` for more information on
-using RCU with linked lists.
+a grace period to elapse, then free the element.  See listRCU.rst for more
+information on using RCU with linked lists.
 
 Frequently Asked Questions
 --------------------------
@@ -50,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See :ref:`Documentation/RCU/UP.rst <up_doc>` for more information.
+  See UP.rst for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -64,13 +63,13 @@ Frequently Asked Questions
 
 - What guidelines should I follow when writing code that uses RCU?
 
-  See the checklist.txt file in this directory.
+  See checklist.rst.
 
 - Why the name "RCU"?
 
   "RCU" stands for "read-copy update".
-  :ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` has more information on where
-  this name came from, search for "read-copy update" to find it.
+  listRCU.rst has more information on where this name came from, search
+  for "read-copy update" to find it.
 
 - I hear that RCU is patented?  What is with that?
 
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
index a9fc774bc400..ca4692775ad4 100644
--- a/Documentation/RCU/rculist_nulls.rst
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -8,7 +8,7 @@ This section describes how to use hlist_nulls to
 protect read-mostly linked lists and
 objects using SLAB_TYPESAFE_BY_RCU allocations.
 
-Please read the basics in Documentation/RCU/listRCU.rst
+Please read the basics in listRCU.rst.
 
 Using 'nulls'
 =============
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index c34d2212eaca..77ea260efd12 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -224,7 +224,7 @@ synchronize_rcu()
 	be delayed.  This property results in system resilience in face
 	of denial-of-service attacks.  Code using call_rcu() should limit
 	update rate in order to gain this same sort of resilience.  See
-	checklist.txt for some approaches to limiting the update rate.
+	checklist.rst for some approaches to limiting the update rate.
 
 rcu_assign_pointer()
 ^^^^^^^^^^^^^^^^^^^^
@@ -318,7 +318,7 @@ rcu_dereference()
 	must prohibit.	The rcu_dereference_protected() variant takes
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
-	a lockdep splat is emitted.  See Documentation/RCU/Design/Requirements/Requirements.rst
+	a lockdep splat is emitted.  See Design/Requirements/Requirements.rst
 	and the API's code comments for more details and example usage.
 
 .. 	[2] If the list_for_each_entry_rcu() instance might be used by
@@ -399,8 +399,7 @@ for specialized uses, but are relatively uncommon.
 
 This section shows a simple use of the core RCU API to protect a
 global pointer to a dynamically allocated structure.  More-typical
-uses of RCU may be found in :ref:`listRCU.rst <list_rcu_doc>`,
-:ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst <NMI_rcu_doc>`.
+uses of RCU may be found in listRCU.rst, arrayRCU.rst, and NMI-RCU.rst.
 ::
 
 	struct foo {
@@ -482,10 +481,9 @@ So, to sum up:
 	RCU read-side critical sections that might be referencing that
 	data item.
 
-See checklist.txt for additional rules to follow when using RCU.
-And again, more-typical uses of RCU may be found in :ref:`listRCU.rst
-<list_rcu_doc>`, :ref:`arrayRCU.rst <array_rcu_doc>`, and :ref:`NMI-RCU.rst
-<NMI_rcu_doc>`.
+See checklist.rst for additional rules to follow when using RCU.
+And again, more-typical uses of RCU may be found in listRCU.rst,
+arrayRCU.rst, and NMI-RCU.rst.
 
 .. _4_whatisRCU:
 
@@ -579,7 +577,7 @@ to avoid having to write your own callback::
 
 	kfree_rcu(old_fp, rcu);
 
-Again, see checklist.txt for additional rules governing the use of RCU.
+Again, see checklist.rst for additional rules governing the use of RCU.
 
 .. _5_whatisRCU:
 
@@ -663,7 +661,7 @@ been able to write-acquire the lock otherwise.  The smp_mb__after_spinlock()
 promotes synchronize_rcu() to a full memory barrier in compliance with
 the "Memory-Barrier Guarantees" listed in:
 
-	Documentation/RCU/Design/Requirements/Requirements.rst
+	Design/Requirements/Requirements.rst
 
 It is possible to nest rcu_read_lock(), since reader-writer locks may
 be recursively acquired.  Note also that rcu_read_lock() is immune
-- 
2.31.1.189.g2e36527f23

Re: [PATCH rcu 0/2] Documentation updates for v5.19

[Bagas Sanjaya]

On 4/19/22 05:50, Paul E. McKenney wrote:
> Hello!
> 
> This series contains a couple of documentation updates:
> 
> 1.	Add documentation for rude and trace RCU flavors.
> 
> 2.	Update RCU cross-references as suggested in doc-guide, courtesy
> 	of Akira Yokosawa.
> 

Bulding htmldocs with this series, no new warnings found.

Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH rcu 0/2] Documentation updates for v5.19

[Paul E. McKenney]

On Tue, Apr 19, 2022 at 02:08:48PM +0700, Bagas Sanjaya wrote:
> On 4/19/22 05:50, Paul E. McKenney wrote:
> > Hello!
> > 
> > This series contains a couple of documentation updates:
> > 
> > 1.	Add documentation for rude and trace RCU flavors.
> > 
> > 2.	Update RCU cross-references as suggested in doc-guide, courtesy
> > 	of Akira Yokosawa.
> > 
> 
> Bulding htmldocs with this series, no new warnings found.
> 
> Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thank you for testing!  I will apply your Tested-by on the next
rebase.

> -- 
> An old man doll... just what I always wanted! - Clara

Nutcracker?

							Thanx, Paul