linux-stable.git/Documentation/RCU, branch v5.18

Merge branches 'doc.2021.11.30c', 'exp.2021.12.07a', 'fastnohz.2021.11.30c', 'fixes.2021.11.30c', 'nocb.2021.12.09a', 'nolibc.2021.11.30c', 'tasks.2021.12.09a', 'torture.2021.12.07a' and 'torturescript.2021.11.30c' into HEAD

2021-12-09T19:38:09+00:00

doc.2021.11.30c: Documentation updates.
exp.2021.12.07a: Expedited-grace-period fixes.
fastnohz.2021.11.30c: Remove CONFIG_RCU_FAST_NO_HZ.
fixes.2021.11.30c: Miscellaneous fixes.
nocb.2021.12.09a: No-CB CPU updates.
nolibc.2021.11.30c: Tiny in-kernel library updates.
tasks.2021.12.09a: RCU-tasks updates, including update-side scalability.
torture.2021.12.07a: Torture-test in-kernel module updates.
torturescript.2021.11.30c: Torture-test scripting updates.

rcu: Remove the RCU_FAST_NO_HZ Kconfig option

2021-12-01T01:24:47+00:00

All of the uses of CONFIG_RCU_FAST_NO_HZ=y that I have seen involve
systems with RCU callbacks offloaded.  In this situation, all that this
Kconfig option does is slow down idle entry/exit with an additional
allways-taken early exit.  If this is the only use case, then this
Kconfig option nothing but an attractive nuisance that needs to go away.

This commit therefore removes the RCU_FAST_NO_HZ Kconfig option.

Signed-off-by: Paul E. McKenney

doc: RCU: Avoid 'Symbol' font-family in SVG figures

2021-12-01T01:23:14+00:00

On Ubuntu Focal, strings in some of SVG files under
Documentation/RCU/Design can not be rendered properly when
converted to PDF.

Ubuntu releases since Focal and Debian bullseye have trouble
with "Symbol" font-family in SVG files.

As those strings are mostly API names such as "READ_ONCE()",
"WRITE_ONCE(), "rcu_read_lock()", and so on, using a generic
monospace font-family should be a good alternative.

Substitute the font-family name by a simple sed pattern:

    's/Symbol/monospace/g'

Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney

doc: Add refcount analogy to What is RCU

2021-12-01T01:23:06+00:00

The reader-writer-lock analogy is a useful way to think about RCU, but
it is not always applicable.  It is useful to have other analogies to
work with, and particularly to emphasise that no single analogy is
perfect.

This patch add a "RCU as reference count" to the "what is RCU" document.

See https://lwn.net/Articles/872559/

[ paulmck: Apply Akira Yokosawa feedback. ]
Reviewed-by: Akira Yokosawa 
Signed-off-by: NeilBrown 
Signed-off-by: Paul E. McKenney

rcu: Fix undefined Kconfig macros

2021-09-13T23:32:46+00:00

Invoking scripts/checkkconfigsymbols.py in the Linux-kernel source tree
located the following issues:

1. TREE_PREEMPT_RCU
Referencing files: arch/sh/configs/sdk7786_defconfig

It should now be CONFIG_PREEMPT_RCU. Except that the CONFIG_PREEMPT=y in
that same file implies CONFIG_PREEMPT_RCU=y.  Therefore, delete the
CONFIG_TREE_PREEMPT_RCU=y line.

The reason is as follows:

In kernel/rcu/Kconfig, we have
config PREEMPT_RCU
        bool
        default y if PREEMPTION

https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt says,
"The default value is only assigned to the config symbol if no other value
 was set by the user (via the input prompt above)."
there is no prompt in config PREEMPT_RCU entry, so we are guaranteed to
get CONFIG_PREEMPT_RCU=y when CONFIG_PREEMPT is present.

2. RCU_CPU_STALL_INFO
Referencing files: arch/xtensa/configs/nommu_kc705_defconfig

The old Kconfig option RCU_CPU_STALL_INFO was removed by commit
75c27f119b64 ("rcu: Remove CONFIG_RCU_CPU_STALL_INFO"), and the kernel
now acts as if this Kconfig option was unconditionally enabled.

3. RCU_NOCB_CPU_ALL
Referencing files:
Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst

This is an old snapshot of the code. I update this from the real
rcu_prepare_for_idle() function in kernel/rcu/tree_plugin.h.
This change was tested by invoking "make htmldocs".

4. RCU_TORTURE_TESTS
Referencing files: kernel/rcu/rcutorture.c

Forward-progress checking conflicts with CPU-stall testing, so we should
complain at "modprobe rcutorture" when both are enabled.

Signed-off-by: Zhouyi Zhou 
Signed-off-by: Paul E. McKenney

doc: Add another stall-warning root cause in stallwarn.rst

2021-09-13T23:32:46+00:00

This commit adds a bullet item noting that both deficiencies and surpluses
of calls to rcu_*_enter() and rcu_*_exit() can result in RCU CPU stall
warnings.

Signed-off-by: Paul E. McKenney

doc: Update stallwarn.rst with recent changes

2021-07-20T20:36:33+00:00

This commit calls out the possibility of self-detected stalls, adds new
messages, and calls out the use for stack traces.

Reported-by: Jeff Layton 
Signed-off-by: Paul E. McKenney

rcu/doc: Add a quick quiz to explain further why we need smp_mb__after_unlock_lock()

2021-07-20T20:36:33+00:00

Add some missing critical pieces of explanation to understand the need
for full memory barriers throughout the whole grace period state machine,
thanks to Paul's explanations.

Signed-off-by: Frederic Weisbecker 
Cc: Neeraj Upadhyay 
Cc: Joel Fernandes 
Cc: Uladzislau Rezki 
Cc: Boqun Feng 
[ paulmck: Adjust code block per Akira Yokosawa. ]
Signed-off-by: Paul E. McKenney

docs: Fix a typo in Documentation/RCU/stallwarn.rst

2021-07-20T20:36:33+00:00

Add the missing ')' in the documentation.

Signed-off-by: Haocheng Xie 
Signed-off-by: Paul E. McKenney

Documentation/RCU: Fix nested inline markup

2021-07-20T20:36:33+00:00

To avoid the ``foo`` markup inside the `bar`__ hyperlink marker,
use the "replace" directive [1].

This should restore the intended appearance of the link.

Tested with sphinx versions 1.7.9 and 2.4.4.

[1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#replace

Signed-off-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney