Pull documentation updates from Jonathan Corbet:
"There's not a huge amount of activity in the docs tree this time
around, but a few significant changes even so:
- A complete rewriting of the top-level index.rst file, which mostly
reflects itself in a redone top page in the HTML-rendered docs. The
hope is that the new organization will be a friendlier starting
point for both users and developers.
- Some math-rendering improvements.
- A coding-style.rst update on the use of BUG() and WARN()
- A big maintainer-PHP guide update.
- Some code-of-conduct updates
- More Chinese translation work
Plus the usual pile of typo fixes, corrections, and updates"
* tag 'docs-6.1' of git://git.lwn.net/linux: (66 commits)
checkpatch: warn on usage of VM_BUG_ON() and other BUG variants
coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel")
Documentation: devres: add missing IO helper
Documentation: devres: update IRQ helper
Documentation/mm: modify page_referenced to folio_referenced
Documentation/CoC: Reflect current CoC interpretation and practices
docs/doc-guide: Add documentation on SPHINX_IMGMATH
docs: process/5.Posting.rst: clarify use of Reported-by: tag
docs, kprobes: Fix the wrong location of Kprobes
docs: add a man-pages link to the front page
docs: put atomic*.txt and memory-barriers.txt into the core-api book
docs: move asm-annotations.rst into core-api
docs: remove some index.rst cruft
docs: reconfigure the HTML left column
docs: Rewrite the front page
docs: promote the title of process/index.rst
Documentation: devres: add missing SPI helper
Documentation: devres: add missing PINCTRL helpers
docs: hugetlbpage.rst: fix a typo of hugepage size
docs/zh_CN: Add new translation of admin-guide/bootconfig.rst
...
This patch adds LWN articles about RCU APIs which were released in 2019.
Also, HTTP URLs are replaced by HTTPS.
Signed-off-by: Shao-Tse Hung <ccs100203@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Because the SLAB_TYPESAFE_BY_RCU code does not zero pages that are
to be broken up into slabs, the memory returned by kmem_cache_alloc()
must be fully initialized, including any spinlocks included in the newly
allocated structure. This means that readers attempting to look up an
SLAB_TYPESAFE_BY_RCU object must use a reference-counting approach.
A spinlock may be acquired only after a reference is obtained, which
prevents that object from being passed to kmem_struct_free(), but only
while that reference continues to be held.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
This commit updates the rcu_access_pointer() advice, noting that its
return value should not be assigned to a local variable, and also noting
that there is little point in using rcu_access_pointer() within an RCU
read-side critical section.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
The rcu_access_pointer() macro does not consult lockdep by design because
it is intended to be used outside of RCU read-side critical sections.
This commit therefore makes a separate list for it in whatisRCU.rst.
Similarly, RCU_LOCKDEP_WARN(), rcu_sleep_check(), and RCU_NONIDLE()
do not do anything with pointer access. This commit therefore creates
a separate utility-API list for them.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
The checklist.rst document advises periodic synchronize_rcu() invocations
to prevent callback flooding. However, rcu_barrier() is often a better
choice. This commit therefore adds words to this effect.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
The current checklist.rst file correctly notes that RCU callbacks execute
in BH context, and cannot block. This commit adds words advising people
needing callbacks to block to use workqueues, for example, by replacing
call_rcu() with queue_rcu_work().
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
This commit updates checklist.rst to emphasize the need for explicit
markers for RCU read-side critical sections.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Currently both expedited and regular grace period stall warnings use
a single timeout value that with units of seconds. However, recent
Android use cases problem require a sub-100-millisecond expedited RCU CPU
stall warning. Given that expedited RCU grace periods normally complete
in far less than a single millisecond, especially for small systems,
this is not unreasonable.
Therefore introduce the CONFIG_RCU_EXP_CPU_STALL_TIMEOUT kernel
configuration that defaults to 20 msec on Android and remains the same
as that of the non-expedited stall warnings otherwise. It also can be
changed in run-time via: /sys/.../parameters/rcu_exp_cpu_stall_timeout.
[ paulmck: Default of zero to use CONFIG_RCU_STALL_TIMEOUT. ]
Signed-off-by: Uladzislau Rezki <uladzislau.rezki@sony.com>
Signed-off-by: Uladzislau Rezki (Sony) <urezki@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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
Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
This commit belatedly adds documentation of Tasks Rude RCU and Tasks
Trace RCU to RCU's requirements document.
Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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 <paulmck@kernel.org>
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 <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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 <akiyks@gmail.com>
Signed-off-by: NeilBrown <neilb@suse.de>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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
75c27f119b ("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 <zhouzhouyi@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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 <paulmck@kernel.org>
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 <jlayton@kernel.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
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 <frederic@kernel.org>
Cc: Neeraj Upadhyay <neeraju@codeaurora.org>
Cc: Joel Fernandes <joel@joelfernandes.org>
Cc: Uladzislau Rezki <urezki@gmail.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
[ paulmck: Adjust code block per Akira Yokosawa. ]
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Linus Torvalds
Akhil Raj
Shao-Tse Hung
Paul E. McKenney
Frederic Weisbecker
Uladzislau Rezki
Akira Yokosawa
NeilBrown
Zhouyi Zhou