linux-dev/Documentation/RCU, branch master

Merge tag 'docs-6.1' of git://git.lwn.net/linux

2022-10-03T17:23:32Z

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 ...

Delete duplicate words from kernel docs

2022-09-27T19:21:43Z

I have deleted duplicate words like to, guest, trace, when, we Signed-off-by: Akhil Raj Link: https://lore.kernel.org/r/20220829065239.4531-1-lf32.dev@gmail.com Signed-off-by: Jonathan Corbet

doc/rcu: Update LWN article URLs and add 2019 article

2022-08-31T11:58:15Z

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

doc: SLAB_TYPESAFE_BY_RCU uses cannot rely on spinlocks

2022-08-31T11:58:15Z

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

doc: Update rcu_access_pointer() advice in rcu_dereference.rst

2022-08-31T11:58:15Z

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

doc: Fix list: rcu_access_pointer() is not lockdep-checked

2022-08-31T11:58:15Z

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

doc: Use rcu_barrier() to rate-limit RCU callbacks

2022-08-31T11:58:15Z

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

doc: Call out queue_rcu_work() for blocking RCU callbacks

2022-08-31T11:58:14Z

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

doc: Emphasize the need for explicit RCU read-side markers

2022-08-31T11:58:14Z

This commit updates checklist.rst to emphasize the need for explicit markers for RCU read-side critical sections. Signed-off-by: Paul E. McKenney

rcu/context-tracking: Remove unused and/or unecessary middle functions

2022-07-05T20:33:00Z

Some eqs functions are now only used internally by context tracking, so their public declarations can be removed. Also middle functions such as rcu_user_*() and rcu_idle_*() which now directly call to rcu_eqs_enter() and rcu_eqs_exit() can be wiped out as well. Signed-off-by: Frederic Weisbecker Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: Neeraj Upadhyay Cc: Uladzislau Rezki Cc: Joel Fernandes Cc: Boqun Feng Cc: Nicolas Saenz Julienne Cc: Marcelo Tosatti Cc: Xiongfeng Wang Cc: Yu Liao Cc: Phil Auld Cc: Paul Gortmaker Cc: Alex Belits Signed-off-by: Paul E. McKenney Reviewed-by: Nicolas Saenz Julienne Tested-by: Nicolas Saenz Julienne