summaryrefslogtreecommitdiffstats
path: root/Documentation/RCU
AgeCommit message (Collapse)AuthorFilesLines
2022-05-11Merge branch 'exp.2022.05.11a' into HEADPaul E. McKenney1-0/+20
exp.2022.05.11a: Expedited-grace-period latency-reduction updates.
2022-05-11rcu: Introduce CONFIG_RCU_EXP_CPU_STALL_TIMEOUTUladzislau Rezki1-0/+20
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>
2022-04-20docs: Update RCU cross-references as suggested in doc-guideAkira Yokosawa8-29/+25
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>
2022-04-20docs: Add documentation for rude and trace RCU flavorsPaul E. McKenney1-0/+32
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>
2021-12-09Merge branches 'doc.2021.11.30c', 'exp.2021.12.07a', 'fastnohz.2021.11.30c', ↵Paul E. McKenney1-11/+0
'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 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.
2021-11-30rcu: Remove the RCU_FAST_NO_HZ Kconfig optionPaul E. McKenney1-11/+0
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>
2021-11-30doc: RCU: Avoid 'Symbol' font-family in SVG figuresAkira Yokosawa11-67/+67
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>
2021-11-30doc: Add refcount analogy to What is RCUNeilBrown1-8/+82
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>
2021-09-13rcu: Fix undefined Kconfig macrosZhouyi Zhou1-37/+32
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 <zhouzhouyi@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-09-13doc: Add another stall-warning root cause in stallwarn.rstPaul E. McKenney1-0/+10
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>
2021-07-20doc: Update stallwarn.rst with recent changesPaul E. McKenney1-6/+15
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>
2021-07-20rcu/doc: Add a quick quiz to explain further why we need ↵Frederic Weisbecker1-0/+29
smp_mb__after_unlock_lock() 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>
2021-07-20docs: Fix a typo in Documentation/RCU/stallwarn.rstHaocheng Xie1-1/+1
Add the missing ')' in the documentation. Signed-off-by: Haocheng Xie <xiehaocheng.cn@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-07-20Documentation/RCU: Fix nested inline markupAkira Yokosawa1-3/+5
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 <akiyks@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-07-20Documentation/RCU: Fix emphasis markersAkira Yokosawa3-19/+19
"-foo-" does not work as emphasis in ReST markdown. Use "*foo*" instead. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-07-04Merge branch 'core-rcu-2021.07.04' of ↵Linus Torvalds1-3/+3
git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu Pull RCU updates from Paul McKenney: - Bitmap parsing support for "all" as an alias for all bits - Documentation updates - Miscellaneous fixes, including some that overlap into mm and lockdep - kvfree_rcu() updates - mem_dump_obj() updates, with acks from one of the slab-allocator maintainers - RCU NOCB CPU updates, including limited deoffloading - SRCU updates - Tasks-RCU updates - Torture-test updates * 'core-rcu-2021.07.04' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu: (78 commits) tasks-rcu: Make show_rcu_tasks_gp_kthreads() be static inline rcu-tasks: Make ksoftirqd provide RCU Tasks quiescent states rcu: Add missing __releases() annotation rcu: Remove obsolete rcu_read_unlock() deadlock commentary rcu: Improve comments describing RCU read-side critical sections rcu: Create an unrcu_pointer() to remove __rcu from a pointer srcu: Early test SRCU polling start rcu: Fix various typos in comments rcu/nocb: Unify timers rcu/nocb: Prepare for fine-grained deferred wakeup rcu/nocb: Only cancel nocb timer if not polling rcu/nocb: Delete bypass_timer upon nocb_gp wakeup rcu/nocb: Cancel nocb_timer upon nocb_gp wakeup rcu/nocb: Allow de-offloading rdp leader rcu/nocb: Directly call __wake_nocb_gp() from bypass timer rcu: Don't penalize priority boosting when there is nothing to boost rcu: Point to documentation of ordering guarantees rcu: Make rcu_gp_cleanup() be noinline for tracing rcu: Restrict RCU_STRICT_GRACE_PERIOD to at most four CPUs rcu: Make show_rcu_gp_kthreads() dump rcu_node structures blocking GP ...
2021-06-24doc: Give XDP as example of non-obvious RCU reader/updater pairingToke Høiland-Jørgensen1-2/+9
This commit gives an example of non-obvious RCU reader/updater pairing in the guise of the XDP feature in networking, which calls BPF programs from network-driver NAPI (softirq) context. Signed-off-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Toke Høiland-Jørgensen <toke@redhat.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20210624160609.292325-4-toke@redhat.com
2021-06-24doc: Clarify and expand RCU updaters and corresponding readersPaul E. McKenney1-21/+27
This commit clarifies which primitives readers can use given that the corresponding updaters have made a specific choice. This commit also adds this information for the various RCU Tasks flavors. While in the area, it removes a paragraph that no longer applies in any straightforward manner. Signed-off-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Toke Høiland-Jørgensen <toke@redhat.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20210624160609.292325-3-toke@redhat.com
2021-05-10doc: Fix diagram references in memory-ordering documentFrederic Weisbecker1-2/+2
The three diagrams describing rcu_gp_init() all spuriously refer to the same figure, probably due to a copy/paste issue. This commit fixes these references. Signed-off-by: Frederic Weisbecker <frederic@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-05-10doc: Fix statement of RCU's memory-ordering requirementsPaul E. McKenney1-1/+1
The sentence defining the relationship of accesses before a grace period to read-side accesses following that same grace period was missing a small word: "not". This commit therefore adds it. Reported-by: Frederic Weisbecker <frederic@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-03-15docs: Correctly spell Stephen Hemminger's namePaul E. McKenney1-1/+1
This commit replaces "Steve" with the his real name, which is "Stephen". Reported-by: Stephen Hemminger <stephen@networkplumber.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-02-22Merge tag 'docs-5.12' of git://git.lwn.net/linuxLinus Torvalds1-47/+47
Pull documentation updates from Jonathan Corbet: "It has been a relatively quiet cycle in docsland. - As promised, the minimum Sphinx version to build the docs is now 1.7, and we have dropped support for Python 2 entirely. That allowed the removal of a bunch of compatibility code. - A set of treewide warning fixups from Mauro that I applied after it became clear nobody else was going to deal with them. - The automarkup mechanism can now create cross-references from relative paths to RST files. - More translations, typo fixes, and warning fixes" * tag 'docs-5.12' of git://git.lwn.net/linux: (75 commits) docs: kernel-hacking: be more civil docs: Remove the Microsoft rhetoric Documentation/admin-guide: kernel-parameters: Update nohlt section doc/admin-guide: fix spelling mistake: "perfomance" -> "performance" docs: Document cross-referencing using relative path docs: Enable usage of relative paths to docs on automarkup docs: thermal: fix spelling mistakes Documentation: admin-guide: Update kvm/xen config option docs: Make syscalls' helpers naming consistent coding-style.rst: Avoid comma statements Documentation: /proc/loadavg: add 3 more field descriptions Documentation/submitting-patches: Add blurb about backtraces in commit messages Docs: drop Python 2 support Move our minimum Sphinx version to 1.7 Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams scripts/kernel-doc: add internal hyperlink to DOC: sections Update Documentation/admin-guide/sysctl/fs.rst docs: Update DTB format references docs: zh_CN: add iio index.rst translation docs/zh_CN: add iio ep93xx_adc.rst translation ...
2021-02-21Merge tag 'core-rcu-2021-02-17' of ↵Linus Torvalds6-377/+412
git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip Pull RCU updates from Ingo Molnar: "These are the latest RCU updates for v5.12: - 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. - nolibc fixes for the torture tests" * tag 'core-rcu-2021-02-17' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (130 commits) percpu_ref: Dump mem_dump_obj() info upon reference-count underflow rcu: Make call_rcu() print mem_dump_obj() info for double-freed callback mm: Make mem_obj_dump() vmalloc() dumps include start and length mm: Make mem_dump_obj() handle vmalloc() memory mm: Make mem_dump_obj() handle NULL and zero-sized pointers mm: Add mem_dump_obj() to print source of memory block tools/rcutorture: Fix position of -lgcc in mkinitrd.sh tools/nolibc: Fix position of -lgcc in the documented example tools/nolibc: Emit detailed error for missing alternate syscall number definitions tools/nolibc: Remove incorrect definitions of __ARCH_WANT_* tools/nolibc: Get timeval, timespec and timezone from linux/time.h tools/nolibc: Implement poll() based on ppoll() tools/nolibc: Implement fork() based on clone() tools/nolibc: Make getpgrp() fall back to getpgid(0) tools/nolibc: Make dup2() rely on dup3() when available tools/nolibc: Add the definition for dup() rcutorture: Add rcutree.use_softirq=0 to RUDE01 and TASKS01 torture: Maintain torture-specific set of CPUs-online books torture: Clean up after torture-test CPU hotplugging rcutorture: Make object_debug also double call_rcu() heap object ...
2021-02-12Merge branch 'for-mingo-rcu' of ↵Ingo Molnar6-377/+412
git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu into core/rcu 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 <mingo@kernel.org>
2021-01-29drivers: Remove CONFIG_OPROFILE supportViresh Kumar1-2/+1
The "oprofile" user-space tools don't use the kernel OPROFILE support any more, and haven't in a long time. User-space has been converted to the perf interfaces. Remove kernel's old oprofile support. Suggested-by: Christoph Hellwig <hch@infradead.org> Suggested-by: Linus Torvalds <torvalds@linux-foundation.org> Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org> Acked-by: Robert Richter <rric@kernel.org> Acked-by: Paul E. McKenney <paulmck@kernel.org> #RCU Acked-by: William Cohen <wcohen@redhat.com> Acked-by: Al Viro <viro@zeniv.linux.org.uk> Acked-by: Thomas Gleixner <tglx@linutronix.de>
2021-01-22Merge branches 'doc.2021.01.06a', 'fixes.2021.01.04b', ↵Paul E. McKenney2-1/+40
'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 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.
2021-01-11Documentation: Replace lkml.org links with loreJoe Perches1-47/+47
Replace the lkml.org links with lore to better use a single source that's more likely to stay available long-term. Done by bash script: cvt_lkml_to_lore () { tmpfile=$(mktemp ./.cvt_links.XXXXXXX) header=$(echo $1 | sed 's@/lkml/@/lkml/headers/@') wget -qO - $header > $tmpfile if [[ $? == 0 ]] ; then link=$(grep -i '^Message-Id:' $tmpfile | head -1 | \ sed -r -e 's/^\s*Message-Id:\s*<\s*//' -e 's/\s*>\s*$//' -e 's@^@https://lore.kernel.org/r/@') # echo "testlink: $link" if [ -n "$link" ] ; then wget -qO - $link > /dev/null if [[ $? == 0 ]] ; then echo $link fi fi fi rm -f $tmpfile } git grep -P -o "\bhttps?://(?:www.)?lkml.org/lkml[\/\w]+" $@ | while read line ; do echo $line file=$(echo $line | cut -f1 -d':') link=$(echo $line | cut -f2- -d':') newlink=$(cvt_lkml_to_lore $link) if [[ -n "$newlink" ]] ; then sed -i -e "s#\b$link\b#$newlink#" $file fi done Link: https://lore.kernel.org/patchwork/patch/1265849/#1462688 Signed-off-by: Joe Perches <joe@perches.com> Link: https://lore.kernel.org/r/77cdb7f32cfb087955bfc3600b86c40bed5d4104.camel@perches.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-01-06rcu: Check and report missed fqs timer wakeup on RCU stallNeeraj Upadhyay1-1/+22
For a new grace period request, the RCU GP kthread transitions through following states: a. [RCU_GP_WAIT_GPS] -> [RCU_GP_DONE_GPS] The RCU_GP_WAIT_GPS state is where the GP kthread waits for a request for a new GP. Once it receives a request (for example, when a new RCU callback is queued), the GP kthread transitions to RCU_GP_DONE_GPS. b. [RCU_GP_DONE_GPS] -> [RCU_GP_ONOFF] Grace period initialization starts in rcu_gp_init(), which records the start of new GP in rcu_state.gp_seq and transitions to RCU_GP_ONOFF. c. [RCU_GP_ONOFF] -> [RCU_GP_INIT] The purpose of the RCU_GP_ONOFF state is to apply the online/offline information that was buffered for any CPUs that recently came online or went offline. This state is maintained in per-leaf rcu_node bitmasks, with the buffered state in ->qsmaskinitnext and the state for the upcoming GP in ->qsmaskinit. At the end of this RCU_GP_ONOFF state, each bit in ->qsmaskinit will correspond to a CPU that must pass through a quiescent state before the upcoming grace period is allowed to complete. However, a leaf rcu_node structure with an all-zeroes ->qsmaskinit cannot necessarily be ignored. In preemptible RCU, there might well be tasks still in RCU read-side critical sections that were first preempted while running on one of the CPUs managed by this structure. Such tasks will be queued on this structure's ->blkd_tasks list. Only after this list fully drains can this leaf rcu_node structure be ignored, and even then only if none of its CPUs have come back online in the meantime. Once that happens, the ->qsmaskinit masks further up the tree will be updated to exclude this leaf rcu_node structure. Once the ->qsmaskinitnext and ->qsmaskinit fields have been updated as needed, the GP kthread transitions to RCU_GP_INIT. d. [RCU_GP_INIT] -> [RCU_GP_WAIT_FQS] The purpose of the RCU_GP_INIT state is to copy each ->qsmaskinit to the ->qsmask field within each rcu_node structure. This copying is done breadth-first from the root to the leaves. Why not just copy directly from ->qsmaskinitnext to ->qsmask? Because the ->qsmaskinitnext masks can change in the meantime as additional CPUs come online or go offline. Such changes would result in inconsistencies in the ->qsmask fields up and down the tree, which could in turn result in too-short grace periods or grace-period hangs. These issues are avoided by snapshotting the leaf rcu_node structures' ->qsmaskinitnext fields into their ->qsmaskinit counterparts, generating a consistent set of ->qsmaskinit fields throughout the tree, and only then copying these consistent ->qsmaskinit fields to their ->qsmask counterparts. Once this initialization step is complete, the GP kthread transitions to RCU_GP_WAIT_FQS, where it waits to do a force-quiescent-state scan on the one hand or for the end of the grace period on the other. e. [RCU_GP_WAIT_FQS] -> [RCU_GP_DOING_FQS] The RCU_GP_WAIT_FQS state waits for one of three things: (1) An explicit request to do a force-quiescent-state scan, (2) The end of the grace period, or (3) A short interval of time, after which it will do a force-quiescent-state (FQS) scan. The explicit request can come from rcutorture or from any CPU that has too many RCU callbacks queued (see the qhimark kernel parameter and the RCU_GP_FLAG_OVLD flag). The aforementioned "short period of time" is specified by the jiffies_till_first_fqs boot parameter for a given grace period's first FQS scan and by the jiffies_till_next_fqs for later FQS scans. Either way, once the wait is over, the GP kthread transitions to RCU_GP_DOING_FQS. f. [RCU_GP_DOING_FQS] -> [RCU_GP_CLEANUP] The RCU_GP_DOING_FQS state performs an FQS scan. Each such scan carries out two functions for any CPU whose bit is still set in its leaf rcu_node structure's ->qsmask field, that is, for any CPU that has not yet reported a quiescent state for the current grace period: i. Report quiescent states on behalf of CPUs that have been observed to be idle (from an RCU perspective) since the beginning of the grace period. ii. If the current grace period is too old, take various actions to encourage holdout CPUs to pass through quiescent states, including enlisting the aid of any calls to cond_resched() and might_sleep(), and even including IPIing the holdout CPUs. These checks are skipped for any leaf rcu_node structure with a all-zero ->qsmask field, however such structures are subject to RCU priority boosting if there are tasks on a given structure blocking the current grace period. The end of the grace period is detected when the root rcu_node structure's ->qsmask is zero and when there are no longer any preempted tasks blocking the current grace period. (No, this last check is not redundant. To see this, consider an rcu_node tree having exactly one structure that serves as both root and leaf.) Once the end of the grace period is detected, the GP kthread transitions to RCU_GP_CLEANUP. g. [RCU_GP_CLEANUP] -> [RCU_GP_CLEANED] The RCU_GP_CLEANUP state marks the end of grace period by updating the rcu_state structure's ->gp_seq field and also all rcu_node structures' ->gp_seq field. As before, the rcu_node tree is traversed in breadth first order. Once this update is complete, the GP kthread transitions to the RCU_GP_CLEANED state. i. [RCU_GP_CLEANED] -> [RCU_GP_INIT] Once in the RCU_GP_CLEANED state, the GP kthread immediately transitions into the RCU_GP_INIT state. j. The role of timers. If there is at least one idle CPU, and if timers are not firing, the transition from RCU_GP_DOING_FQS to RCU_GP_CLEANUP will never happen. Timers can fail to fire for a number of reasons, including issues in timer configuration, issues in the timer framework, and failure to handle softirqs (for example, when there is a storm of interrupts). Whatever the reason, if the timers fail to fire, the GP kthread will never be awakened, resulting in RCU CPU stall warnings and eventually in OOM. However, an RCU CPU stall warning has a large number of potential causes, as documented in Documentation/RCU/stallwarn.rst. This commit therefore adds analysis to the RCU CPU stall-warning code to emit an additional message if the cause of the stall is likely to be timer failure. Signed-off-by: Neeraj Upadhyay <neeraju@codeaurora.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-06doc: Use CONFIG_PREEMPTIONSebastian Andrzej Siewior6-24/+24
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 <bigeasy@linutronix.de> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-06doc: Update RCU's requirements page about the PREEMPT_RT wikiSebastian Andrzej Siewior1-1/+1
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 <bigeasy@linutronix.de> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-04srcu: Document polling interfaces for Tree SRCU grace periodsPaul E. McKenney1-0/+18
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 <kent.overstreet@gmail.com> Reviewed-by: Neeraj Upadhyay <neeraju@codeaurora.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-04doc: Update RCU requirements RCU_INIT_POINTER() descriptionPaul E. McKenney1-2/+1
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 <willy@infradead.org> Acked-by: Linus Torvalds <torvalds@linux-foundation.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-04docs: Fix typos and drop/fix dead links in RCU documentationPaul Gortmaker2-17/+14
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 <michael.opdenacker@free-electrons.com> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-04doc: Remove obsolete RCU-bh and RCU-sched update-side API membersPaul E. McKenney1-14/+14
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 <joel@joelfernandes.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2021-01-04docs: Remove redundant "``" from Requirements.rstPaul E. McKenney1-332/+332
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 <peterz@infradead.org> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net> [ paulmck: Apply Stephen Rothwell feedback. ] Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-12-31docs: Fix reST markup when linking to sectionsNícolas F. R. A. Prado2-14/+14
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 <Section Name_>`__ 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 <nfraprado@protonmail.com> Reviewed-by: Takashi Iwai <tiwai@suse.de> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-11-06docs/rcu: Update the call_rcu() APIHui Su1-2/+1
This commit updates the documented API of call_rcu() to use the rcu_callback_t typedef instead of the open-coded function definition. Signed-off-by: Hui Su <sh_def@163.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-11-06docs: RCU: Requirements.rst: Fix a list blockMauro Carvalho Chehab1-0/+1
As warned by Sphinx: .../Documentation/RCU/Design/Requirements/Requirements.rst:1959: WARNING: Unexpected indentation. The list block is missing a space before it, making Sphinx to get it wrong. This commit therefore adds the missing space characters. Fixes: 2a721e5f0b2c ("docs: Update RCU's hotplug requirements with a bit about design") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-11-06docs: Update RCU's hotplug requirements with a bit about designJoel Fernandes (Google)1-10/+39
The rcu_barrier() section of the "Hotplug CPU" section discusses deadlocks, however the description of deadlocks other than those involving rcu_barrier() is rather incomplete. This commit therefore continues the section by describing how RCU's design handles CPU hotplug in a deadlock-free way. Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-11-02doc: Present the role of READ_ONCE()Paul E. McKenney2-0/+13
This commit adds an explanation of the special cases where READ_ONCE() may be used in place of a member of the rcu_dereference() family. Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-10-09Merge branch 'for-mingo' of ↵Ingo Molnar3-4/+4
git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu into core/rcu Pull v5.10 RCU changes from Paul E. McKenney: - Debugging for smp_call_function(). - Strict grace periods for KASAN. The point of this series is to find RCU-usage bugs, so the corresponding new RCU_STRICT_GRACE_PERIOD Kconfig option depends on both DEBUG_KERNEL and RCU_EXPERT, and is further disabled by dfefault. Finally, the help text includes a goodly list of scary caveats. - New smp_call_function() torture test. - Torture-test updates. - Documentation updates. - Miscellaneous fixes. Signed-off-by: Ingo Molnar <mingo@kernel.org>
2020-08-24docs: Fix function name trailing double-()sKees Cook1-1/+1
I noticed a double-() in the deprecated.rst rendering today. Fix that one and two others in the Documentation/ tree. Acked-by: "Paul E. McKenney" <paulmck@kernel.org> # For RCU Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20200817233207.4083538-1-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-08-24doc: Drop doubled words from RCU requirements documentationRandy Dunlap1-2/+2
Drop the doubled words "to" and "for". Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Cc: "Paul E. McKenney" <paulmck@kernel.org> Cc: Josh Triplett <josh@joshtriplett.org> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> Cc: Lai Jiangshan <jiangshanlai@gmail.com> Cc: Joel Fernandes <joel@joelfernandes.org> Cc: rcu@vger.kernel.org Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-08-24doc: Drop doubled words from RCU Data-Structures.rstRandy Dunlap1-1/+1
Drop the doubled word "the". Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Cc: "Paul E. McKenney" <paulmck@kernel.org> Cc: Josh Triplett <josh@joshtriplett.org> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> Cc: Lai Jiangshan <jiangshanlai@gmail.com> Cc: Joel Fernandes <joel@joelfernandes.org> Cc: rcu@vger.kernel.org Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-08-24docs: Fix typo in synchronize_rcu() function nameTobias Klauser1-1/+1
s/sychronize_rcu/synchronize_rcu/ Signed-off-by: Tobias Klauser <tklauser@distanz.ch> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-08-03Merge tag 'core-rcu-2020-08-03' of ↵Linus Torvalds10-404/+500
git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip Pull RCU updates from Ingo Molnar: - kfree_rcu updates - RCU tasks updates - Read-side scalability tests - SRCU updates - Torture-test updates - Documentation updates - Miscellaneous fixes * tag 'core-rcu-2020-08-03' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (109 commits) torture: Remove obsolete "cd $KVM" torture: Avoid duplicate specification of qemu command torture: Dump ftrace at shutdown only if requested torture: Add kvm-tranform.sh script for qemu-cmd files torture: Add more tracing crib notes to kvm.sh torture: Improve diagnostic for KCSAN-incapable compilers torture: Correctly summarize build-only runs torture: Pass --kmake-arg to all make invocations rcutorture: Check for unwatched readers torture: Abstract out console-log error detection torture: Add a stop-run capability torture: Create qemu-cmd in --buildonly runs rcu/rcutorture: Replace 0 with false torture: Add --allcpus argument to the kvm.sh script torture: Remove whitespace from identify_qemu_vcpus output rcutorture: NULL rcu_torture_current earlier in cleanup code rcutorture: Handle non-statistic bang-string error messages torture: Set configfile variable to current scenario rcutorture: Add races with task-exit processing locktorture: Use true and false to assign to bool variables ...
2020-07-21Documentation/barriers: Remove references to [smp_]read_barrier_depends()Will Deacon1-1/+1
The [smp_]read_barrier_depends() barrier macros no longer exist as part of the Linux memory model, so remove all references to them from the Documentation/ directory. Although this is fairly mechanical on the whole, we drop the "CACHE COHERENCY" section entirely from 'memory-barriers.txt' as it doesn't make any sense now that the dependency barriers have been removed. Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org> Acked-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Will Deacon <will@kernel.org>
2020-06-29doc: Tasks RCU must protect instructions before trampolinePaul E. McKenney1-1/+6
Protecting the code in a trampoline can also require protecting a number of instructions prior to actually entering the trampoline. For example, these earlier instructions might be computing the address of the trampoline. This commit therefore updates RCU's requirements to record this for posterity. Link: https://lore.kernel.org/lkml/20200511154824.09a18c46@gandalf.local.home/ Reported-by: Lai Jiangshan <jiangshanlai@gmail.com> Reported-by: Steven Rostedt <rostedt@goodmis.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-06-29doc: Timer problems can cause RCU CPU stall warningsPaul E. McKenney1-0/+7
Over the past few years, there have been several cases where timekeeping bugs have caused RCU CPU stall warnings, particularly during hardware bringup. This commit therefore adds such bugs to the list of things that can result in RCU CPU stall warnings. Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2020-06-29docs: RCU: Don't duplicate chapter names in rculist_nulls.rstMauro Carvalho Chehab1-0/+6
Since changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst"), auto-references for chapters are generated. This is a nice feature, but has a drawback: no chapters can have the same sumber. So, we need to add two higher hierarchy chapters on this document, in order to avoid such duplication. Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-05 02:55:58 +0000