kernel/linux.git/Documentation/RCU/Design/Requirements, branch v5.19

docs: Update RCU cross-references as suggested in doc-guide

2022-04-20T23:13:52+00:00

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 Reviewed-by: Steven Rostedt (Google) Signed-off-by: Akira Yokosawa Signed-off-by: Paul E. McKenney

docs: Add documentation for rude and trace RCU flavors

2022-04-20T22:57:02+00:00

This commit belatedly adds documentation of Tasks Rude RCU and Tasks Trace RCU to RCU's requirements document. Tested-by: Bagas Sanjaya Reviewed-by: Steven Rostedt (Google) 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

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

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