linux-stable.git/Documentation/RCU, branch v6.9

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

2024-03-12T22:18:34+00:00

Pull documentation updates from Jonathan Corbet:
 "A moderatly busy cycle for development this time around.

   - Some cleanup of the main index page for easier navigation

   - Rework some of the other top-level pages for better readability
     and, with luck, fewer merge conflicts in the future.

   - Submit-checklist improvements, hopefully the first of many.

   - New Italian translations

   - A fair number of kernel-doc fixes and improvements. We have also
     dropped the recommendation to use an old version of Sphinx.

   - A new document from Thorsten on bisection

  ... and lots of fixes and updates"

* tag 'docs-6.9' of git://git.lwn.net/linux: (54 commits)
  docs: verify/bisect: fixes, finetuning, and support for Arch
  docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs
  docs: Move ja_JP/howto.rst to ja_JP/process/howto.rst
  docs: submit-checklist: use subheadings
  docs: submit-checklist: structure by category
  docs: new text on bisecting which also covers bug validation
  docs: drop the version constraints for sphinx and dependencies
  docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4
  docs: Restore "smart quotes" for quotes
  docs/zh_CN: accurate translation of "function"
  docs: Include simplified link titles in main index
  docs: Correct formatting of title in admin-guide/index.rst
  docs: kernel_feat.py: fix build error for missing files
  MAINTAINERS: Set the field name for subsystem profile section
  kasan: Add documentation for CONFIG_KASAN_EXTRA_INFO
  Fixed case issue with 'fault-injection' in documentation
  kernel-doc: handle #if in enums as well
  Documentation: update mailing list addresses
  doc: kerneldoc.py: fix indentation
  scripts/kernel-doc: simplify signature printing
  ...

doc: Update checklist.rst discussion of callback execution

2024-02-14T15:53:50+00:00

This commit completes the list of call_rcu*() functions that are not
guaranteed to have their callbacks executing on the same CPU.  While in
the area, fix an unrelated typo.

Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc: Clarify use of slab constructors and SLAB_TYPESAFE_BY_RCU

2024-02-14T15:53:50+00:00

This commit explicitly states that you should initialize any locks to
be used by readers in your SLAB_TYPESAFE_BY_RCU constructor.

Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc: Add CONFIG_RCU_STRICT_GRACE_PERIOD to checklist.rst

2024-02-14T15:53:49+00:00

This commit adds CONFIG_RCU_STRICT_GRACE_PERIOD to the list of debugging
Kconfig options in checklist.rst.

Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc: Make checklist.rst note that spinlocks are implied RCU readers

2024-02-14T15:53:49+00:00

In kernels built with CONFIG_PREEMPT_RT=n, spinlock critical sections
are RCU readers because they disable preemption.  However, they are also
RCU readers in CONFIG_PREEMPT_RT=y because in that case the locking
primitives contain rcu_read_lock() and rcu_read_unlock().  Therefore,
upgrade checklist.rst to document this non-obvious case.

While in the area, fix a typo by changing "read-side critical" to
"read-side critical section".

Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc: Make whatisRCU.rst note that spinlocks are RCU readers

2024-02-14T15:53:49+00:00

In kernels built with CONFIG_PREEMPT_RT=n, spinlock critical sections
are RCU readers because they disable preemption.  However, they are also
RCU readers in CONFIG_PREEMPT_RT=y because in that case the locking
primitives contain rcu_read_lock() and rcu_read_unlock().  Therefore,
upgrade whatisRCU.rst to document this non-obvious case.

Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc: Spinlocks are implied RCU readers

2024-02-14T15:53:49+00:00

In kernels built with CONFIG_PREEMPT_RT=n, spinlock critical sections
are RCU readers because they disable preemption.  However, they are also
RCU readers in CONFIG_PREEMPT_RT=y because the -rt locking primitives
contain rcu_read_lock() and rcu_read_unlock().  Therefore, upgrade
rcu_dereference.rst to document this non-obvious case.

Reported-by: Linus Torvalds 
Closes: https://lore.kernel.org/lkml/CAHk-=whGKvjHCtJ6W4pQ0_h_k9fiFQ8V2GpM=BqYnB2X=SJ+XQ@mail.gmail.com/
Signed-off-by: Paul E. McKenney 
Signed-off-by: Boqun Feng

doc:it_IT: first translation for locking/

2024-01-30T20:32:00+00:00

To begin with:
    - locking/index.rst
    - locking/lockdep-design.rst
    - locking/lockstat.rst
    - locking/lockturture.rst
    - locking/locktypes.rst

And RCU/torture.rst to avoid broken references.

Signed-off-by: Federico Vaga 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240106233820.30454-1-federico.vaga@vaga.pv.it

doc: Mention address and data dependencies in rcu_dereference.rst

2023-12-13T19:46:28+00:00

This commit adds discussion of address and data dependencies to the
beginning of rcu_dereference.rst in order to enable readers to more
easily make the connection to the Linux-kernel memory model in general
and to memory-barriers.txt in particular.

Reported-by: Jonas Oberhauser 
Reported-by: Akira Yokosawa 
Signed-off-by: Paul E. McKenney 
Signed-off-by: Neeraj Upadhyay (AMD)

doc: Clarify RCU Tasks reader/updater checklist

2023-12-13T19:45:52+00:00

Currently, the reader/updater compatibility rules for the three RCU
Tasks flavors are squished together in a single paragraph, which can
result in confusion.  This commit therefore splits them out into a list,
clearly showing the distinction between these flavors.

Link: https://lore.kernel.org/all/20231002211936.5948253e@gandalf.local.home/

Reported-by: Steven Rostedt 
Signed-off-by: Paul E. McKenney 
Reviewed-by: Mathieu Desnoyers 
Reviewed-by: Steven Rostedt (Google) 
Signed-off-by: Neeraj Upadhyay (AMD)