linux-stable.git/Documentation/RCU/Design, branch v5.13

Merge branch 'for-mingo-rcu' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu into core/rcu

2021-02-12T11:56:55+00:00

Pull RCU updates from Paul E. McKenney:

- Documentation updates.

- Miscellaneous fixes.

- kfree_rcu() updates: Addition of mem_dump_obj() to provide allocator return
  addresses to more easily locate bugs.  This has a couple of RCU-related commits,
  but is mostly MM.  Was pulled in with akpm's agreement.

- Per-callback-batch tracking of numbers of callbacks,
  which enables better debugging information and smarter
  reactions to large numbers of callbacks.

- The first round of changes to allow CPUs to be runtime switched from and to
  callback-offloaded state.

- CONFIG_PREEMPT_RT-related changes.

- RCU CPU stall warning updates.
- Addition of polling grace-period APIs for SRCU.

- Torture-test and torture-test scripting updates, including a "torture everything"
  script that runs rcutorture, locktorture, scftorture, rcuscale, and refscale.
  Plus does an allmodconfig build.

Signed-off-by: Ingo Molnar

Merge branches 'doc.2021.01.06a', 'fixes.2021.01.04b', 'kfree_rcu.2021.01.04a', 'mmdumpobj.2021.01.22a', 'nocb.2021.01.06a', 'rt.2021.01.04a', 'stall.2021.01.06a', 'torture.2021.01.12a' and 'tortureall.2021.01.06a' into HEAD

2021-01-22T23:26:44+00:00

doc.2021.01.06a: Documentation updates.
fixes.2021.01.04b: Miscellaneous fixes.
kfree_rcu.2021.01.04a: kfree_rcu() updates.
mmdumpobj.2021.01.22a: Dump allocation point for memory blocks.
nocb.2021.01.06a: RCU callback offload updates and cblist segment lengths.
rt.2021.01.04a: Real-time updates.
stall.2021.01.06a: RCU CPU stall warning updates.
torture.2021.01.12a: Torture-test updates and polling SRCU grace-period API.
tortureall.2021.01.06a: Torture-test script updates.

doc: Use CONFIG_PREEMPTION

2021-01-07T00:10:44+00:00

CONFIG_PREEMPTION is selected by CONFIG_PREEMPT and by CONFIG_PREEMPT_RT.
Both PREEMPT and PREEMPT_RT require the same functionality which today
depends on CONFIG_PREEMPT.

Update the documents and mention CONFIG_PREEMPTION. Spell out
CONFIG_PREEMPT_RT (instead PREEMPT_RT) since it is an option now.

Signed-off-by: Sebastian Andrzej Siewior 
Signed-off-by: Paul E. McKenney

doc: Update RCU's requirements page about the PREEMPT_RT wiki

2021-01-07T00:10:41+00:00

The PREEMPT_RT wiki moved from kernel.org to the Linux Foundation wiki.
The kernel.org wiki is read only.

This commit therefore updates the URL of the active PREEMPT_RT wiki.

Signed-off-by: Sebastian Andrzej Siewior 
Signed-off-by: Paul E. McKenney

srcu: Document polling interfaces for Tree SRCU grace periods

2021-01-04T21:53:39+00:00

This commit adds requirements documentation for the
get_state_synchronize_srcu(), start_poll_synchronize_srcu(), and
poll_state_synchronize_srcu() functions.

Link: https://lore.kernel.org/rcu/20201112201547.GF3365678@moria.home.lan/
Reported-by: Kent Overstreet 
Reviewed-by: Neeraj Upadhyay 
Signed-off-by: Paul E. McKenney

doc: Update RCU requirements RCU_INIT_POINTER() description

2021-01-04T21:35:15+00:00

Back in the day, RCU_INIT_POINTER() was the only way to avoid
memory-barrier instructions while storing NULL to an RCU-protected
pointer.  Fortunately, in 2016, rcu_assign_pointer() started checking for
compile-time NULL pointers and omitting the memory-barrier instructions in
that case.  Unfortunately, RCU's Requirements.rst document was not updated
accordingly.  This commit therefore at long last carries out that update.

Fixes: 3a37f7275cda ("rcu: No ordering for rcu_assign_pointer() of NULL")
Link: https://lore.kernel.org/lkml/20201209230755.GV7338@casper.infradead.org/
Reported-by: Matthew Wilcox 
Acked-by: Linus Torvalds 
Signed-off-by: Paul E. McKenney

docs: Fix typos and drop/fix dead links in RCU documentation

2021-01-04T21:35:14+00:00

It appears the Compaq link moved to a machine at HP for a while
after the merger of the two, but that doesn't work either.  A search
of HP for "wiz_2637" (w and w/o html suffix) comes up empty.

Since the references aren't critical to the documents we remove them.

Also, the lkml.kernel.org/g links have been broken for ages, so replace
them with lore.kernel.org/r links - standardize on lore for all links too.

Note that we put off fixing these 4y ago - presumably thinking that a
treewide fixup was pending.  Probably safe to go fix the RCU ones now.

https://lore.kernel.org/r/20160915144926.GD10850@linux.vnet.ibm.com/

Cc: Michael Opdenacker 
Cc: Steven Rostedt 
Cc: "Paul E. McKenney" 
Signed-off-by: Paul Gortmaker 
Signed-off-by: Paul E. McKenney

doc: Remove obsolete RCU-bh and RCU-sched update-side API members

2021-01-04T21:35:13+00:00

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 
Signed-off-by: Paul E. McKenney

docs: Remove redundant "``" from Requirements.rst

2021-01-04T21:35:13+00:00

The docbook system has learned that "()" designates a function, so
this commit removes the no-longer-needed "``" to improve readability
of the raw .rst file.

Reported-by: Peter Zijlstra 
Cc: Mauro Carvalho Chehab 
Cc: Jonathan Corbet 
[ paulmck: Apply Stephen Rothwell feedback. ]
Signed-off-by: Paul E. McKenney

docs: Fix reST markup when linking to sections

2020-12-31T22:44:47+00:00

During the process of converting the documentation to reST, some links
were converted using the following wrong syntax (and sometimes using %20
instead of spaces):

   `Display text <#section-name-in-html>`__

This syntax isn't valid according to the docutils' spec [1], but more
importantly, it is specific to HTML, since it uses '#' to link to an
HTML anchor.

The right syntax would instead use a docutils hyperlink reference as the
embedded URI to point to the section [2], that is:

   `Display text `__

This syntax works in both HTML and PDF.

The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
the pdf documentation (make pdfdocs), that is, the build succeeds but
the links don't work, but that syntax causes errors when trying to build
using the not-yet-merged rst2pdf:

   ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Forcing%20Quiescent%20States'

So, use the correct syntax in order to have it work in all different
output formats.

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
[2]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado 
Reviewed-by: Takashi Iwai 
Reviewed-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet