Skip to contentSkip to conversation

RCU doc updates for v6.9

PATCH New Boqun Feng 1 participant 9 messages Jan 26, 2024

Subsystems (5)
lore
Share & tools
lore

Boqun Feng

author
#0 lore raw

cover RCU doc updates for v6.9

Hi,

This series contains the documentation related changes from RCU for v6.9. You can call find the series at:

	https://github.com/fbq/linux.git rcu-doc.2024.01.25a

Th detailed list of the changes:

Paul E. McKenney (8):
doc: Spinlocks are implied RCU readers
doc: Make whatisRCU.rst note that spinlocks are RCU readers
doc: Make checklist.rst note that spinlocks are implied RCU readers
doc: Add CONFIG_RCU_STRICT_GRACE_PERIOD to checklist.rst
doc: Add EARLY flag to early-parsed kernel boot parameters
context_tracking: Fix kerneldoc headers for __ct_user_{enter,exit}()
doc: Clarify use of slab constructors and SLAB_TYPESAFE_BY_RCU
doc: Update checklist.rst discussion of callback execution

 Documentation/RCU/checklist.rst               |  32 +-
 Documentation/RCU/rcu_dereference.rst         |   5 +-
 Documentation/RCU/whatisRCU.rst               |  19 +-
 .../admin-guide/kernel-parameters.rst         |   1 +
 .../admin-guide/kernel-parameters.txt         | 484 +++++++++---------
 kernel/context_tracking.c                     |   4 +
 6 files changed, 293 insertions(+), 252 deletions(-)
Signature · 1 line
2.43.0
author
#1 lore raw

PATCH 1/8 doc: Spinlocks are implied RCU readers

From: "Paul E. McKenney" <[email protected]>

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.

---
 Documentation/RCU/rcu_dereference.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/RCU/rcu_dereference.rst +4 -1
index 659d5913784d..2524dcdadde2 100644
@@ -408,7 +408,10 @@ member of the rcu_dereference() to use in various situations:
 	RCU flavors, an RCU read-side critical section is entered
 	using rcu_read_lock(), anything that disables bottom halves,
 	anything that disables interrupts, or anything that disables
-	preemption.
+	preemption.  Please note that spinlock critical sections
+	are also implied RCU read-side critical sections, even when
+	they are preemptible, as they are in kernels built with
+	CONFIG_PREEMPT_RT=y.
 
 2.	If the access might be within an RCU read-side critical section
 	on the one hand, or protected by (say) my_lock on the other,
Signature · 1 line
2.43.0
author
#2 lore raw

PATCH 2/8 doc: Make whatisRCU.rst note that spinlocks are RCU readers

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

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.

---
 Documentation/RCU/whatisRCU.rst | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)
Documentation/RCU/whatisRCU.rst +13 -2
index 60ce02475142..246ce0d0b4d1 100644
@@ -172,14 +172,25 @@ rcu_read_lock()
 	critical section.  Reference counts may be used in conjunction
 	with RCU to maintain longer-term references to data structures.
 
+	Note that anything that disables bottom halves, preemption,
+	or interrupts also enters an RCU read-side critical section.
+	Acquiring a spinlock also enters an RCU read-side critical
+	sections, even for spinlocks that do not disable preemption,
+	as is the case in kernels built with CONFIG_PREEMPT_RT=y.
+	Sleeplocks do *not* enter RCU read-side critical sections.
+
 rcu_read_unlock()
 ^^^^^^^^^^^^^^^^^
 	void rcu_read_unlock(void);
 
 	This temporal primitives is used by a reader to inform the
 	reclaimer that the reader is exiting an RCU read-side critical
-	section.  Note that RCU read-side critical sections may be nested
-	and/or overlapping.
+	section.  Anything that enables bottom halves, preemption,
+	or interrupts also exits an RCU read-side critical section.
+	Releasing a spinlock also exits an RCU read-side critical section.
+
+	Note that RCU read-side critical sections may be nested and/or
+	overlapping.
 
 synchronize_rcu()
 ^^^^^^^^^^^^^^^^^
Signature · 1 line
2.43.0
author
#3 lore raw

PATCH 3/8 doc: Make checklist.rst note that spinlocks are implied RCU readers

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

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

---
 Documentation/RCU/checklist.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/RCU/checklist.rst +3 -2
index 2d42998a89a6..98a622f77248 100644
@@ -68,7 +68,8 @@ over a rather long period of time, but improvements are always welcome!
 	rcu_read_lock_sched(), or by the appropriate update-side lock.
 	Explicit disabling of preemption (preempt_disable(), for example)
 	can serve as rcu_read_lock_sched(), but is less readable and
-	prevents lockdep from detecting locking issues.
+	prevents lockdep from detecting locking issues.  Acquiring a
+	spinlock also enters an RCU read-side critical section.
 
 	Please note that you *cannot* rely on code known to be built
 	only in non-preemptible kernels.  Such code can and will break,
@@ -444,7 +445,7 @@ over a rather long period of time, but improvements are always welcome!
 	real-time workloads than is synchronize_rcu_expedited().
 
 	It is also permissible to sleep in RCU Tasks Trace read-side
-	critical, which are delimited by rcu_read_lock_trace() and
+	critical section, which are delimited by rcu_read_lock_trace() and
 	rcu_read_unlock_trace().  However, this is a specialized flavor
 	of RCU, and you should not use it without first checking with
 	its current users.  In most cases, you should instead use SRCU.
Signature · 1 line
2.43.0
author
#4 lore raw

PATCH 4/8 doc: Add CONFIG_RCU_STRICT_GRACE_PERIOD to checklist.rst

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

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

---
 Documentation/RCU/checklist.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/RCU/checklist.rst +6 -0
index 98a622f77248..addd5c1547a4 100644
@@ -491,6 +491,12 @@ over a rather long period of time, but improvements are always welcome!
 		since the last time that you passed that same object to
 		call_rcu() (or friends).
 
+	CONFIG_RCU_STRICT_GRACE_PERIOD:
+		combine with KASAN to check for pointers leaked out
+		of RCU read-side critical sections.  This Kconfig
+		option is tough on both performance and scalability,
+		and so is limited to four-CPU systems.
+
 	__rcu sparse checks:
 		tag the pointer to the RCU-protected data structure
 		with __rcu, and sparse will warn you if you access that
Signature · 1 line
2.43.0
author
#5 lore raw

PATCH 5/8 doc: Add EARLY flag to early-parsed kernel boot parameters

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

Kernel boot parameters declared with early_param() are parsed before embedded parameters are extracted from initrd, and early_param() parameters are not helpful when embedded in initrd. Therefore, mark early_param() kernel boot parameters with "EARLY" in kernel-parameters.txt.

The following early_param() calls declare kernel boot parameters that are undocumented:

early_param("atmel.pm_modes", at91_pm_modes_select); early_param("mem_fclk_21285", early_fclk);
early_param("ecc", early_ecc);
early_param("cachepolicy", early_cachepolicy);
early_param("nodebugmon", early_debug_disable); early_param("kfence.sample_interval", parse_kfence_early_init); early_param("additional_cpus", setup_additional_cpus); early_param("stram_pool", atari_stram_setup); early_param("disable_octeon_edac", disable_octeon_edac); early_param("rd_start", rd_start_early);
early_param("rd_size", rd_size_early);
early_param("coherentio", setcoherentio);
early_param("nocoherentio", setnocoherentio);
early_param("fadump", early_fadump_param); early_param("fadump_reserve_mem", early_fadump_reserve_mem); early_param("no_stf_barrier", handle_no_stf_barrier); early_param("no_rfi_flush", handle_no_rfi_flush); early_param("smt-enabled", early_smt_enabled); early_param("ppc_pci_reset_phbs", pci_reset_phbs_setup); early_param("ps3fb", early_parse_ps3fb);
early_param("ps3flash", early_parse_ps3flash);
early_param("novx", disable_vector_extension);
early_param("nobp", nobp_setup_early);
early_param("nospec", nospec_setup_early);
early_param("possible_cpus", _setup_possible_cpus);
early_param("stp", early_parse_stp);
early_param("nopfault", nopfault);
early_param("nmi_mode", nmi_mode_setup);
early_param("sh_mv", early_parse_mv);
early_param("pmb", early_pmb);
early_param("hvirq", early_hvirq_major);
early_param("cfi", cfi_parse_cmdline);
early_param("disableapic", setup_disableapic);
early_param("noapictimer", parse_disable_apic_timer); early_param("disable_cpu_apicid", apic_set_disabled_cpu_apicid); early_param("uv_memblksize", parse_mem_block_size); early_param("retbleed", retbleed_parse_cmdline); early_param("no-kvmclock-vsyscall", parse_no_kvmclock_vsyscall); early_param("update_mptable", update_mptable_setup); early_param("alloc_mptable", parse_alloc_mptable_opt); early_param("possible_cpus", _setup_possible_cpus);
early_param("lsmsi", early_parse_ls_scfg_msi); early_param("nokgdbroundup", opt_nokgdbroundup);
early_param("kgdbcon", opt_kgdb_con);
early_param("kasan", early_kasan_flag);
early_param("kasan.mode", early_kasan_mode);
early_param("kasan.vmalloc", early_kasan_flag_vmalloc); early_param("kasan.page_alloc.sample", early_kasan_flag_page_alloc_sample); early_param("kasan.page_alloc.sample.order", early_kasan_flag_page_alloc_sample_order); early_param("kasan.fault", early_kasan_fault); early_param("kasan.stacktrace", early_kasan_flag_stacktrace); early_param("kasan.stack_ring_size", early_kasan_flag_stack_ring_size); early_param("accept_memory", accept_memory_parse); early_param("page_table_check", early_page_table_check_param); sh_early_platform_init("earlytimer", &sh_cmt_device_driver); early_param_on_off("gbpages", "nogbpages", direct_gbpages, CONFIG_X86_DIRECT_GBPAGES);

These are not necessarily bugs, given that some kernel boot parameters are intended for deep debugging rather than general use.

This work does not cover all of the kernel boot parameters declared using cmdline_find_option() and cmdline_find_option_bool(). If these are in fact guaranteed to be early (which appears to be the case), they can be added in a later version of this patch.

Cc Jonathan Corbet <[email protected]>
Cc Masami Hiramatsu <[email protected]>
Cc Petr Malat <[email protected]>
Cc Randy Dunlap <[email protected]>
---
 .../admin-guide/kernel-parameters.rst         |   1 +
 .../admin-guide/kernel-parameters.txt         | 484 +++++++++---------
 2 files changed, 250 insertions(+), 235 deletions(-)
Documentation/admin-guide/kernel-parameters.rst +1 -0
index 102937bc8443..fe4644df4b47 100644
@@ -108,6 +108,7 @@ is applicable::
 	CMA	Contiguous Memory Area support is enabled.
 	DRM	Direct Rendering Management support is enabled.
 	DYNAMIC_DEBUG Build in debug messages and enable them at runtime
+	EARLY	Parameter processed too early to be embedded in initrd.
 	EDD	BIOS Enhanced Disk Drive Services (EDD) is enabled
 	EFI	EFI Partitioning (GPT) is enabled
 	EVM	Extended Verification Module
Documentation/admin-guide/kernel-parameters.txt +249 -235

1,561 lines not on this page · raw message

Signature · 1 line
2.43.0
author
#6 lore raw

PATCH 6/8 context_tracking: Fix kerneldoc headers for __ct_user_{enter,exit}()

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

Document the "state" parameter of both of these functions.

---
 kernel/context_tracking.c | 4 ++++
 1 file changed, 4 insertions(+)
kernel/context_tracking.c +4 -0
index 6ef0b35fc28c..70ae70d03823 100644
@@ -458,6 +458,8 @@ static __always_inline void context_tracking_recursion_exit(void)
  * __ct_user_enter - Inform the context tracking that the CPU is going
  *		     to enter user or guest space mode.
  *
+ * @state: userspace context-tracking state to enter.
+ *
  * This function must be called right before we switch from the kernel
  * to user or guest space, when it's guaranteed the remaining kernel
  * instructions to execute won't use any RCU read side critical section
@@ -595,6 +597,8 @@ NOKPROBE_SYMBOL(user_enter_callable);
  * __ct_user_exit - Inform the context tracking that the CPU is
  *		    exiting user or guest mode and entering the kernel.
  *
+ * @state: userspace context-tracking state being exited from.
+ *
  * This function must be called after we entered the kernel from user or
  * guest space before any use of RCU read side critical section. This
  * potentially include any high level kernel code like syscalls, exceptions,
Signature · 1 line
2.43.0
author
#7 lore raw

PATCH 7/8 doc: Clarify use of slab constructors and SLAB_TYPESAFE_BY_RCU

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

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

---
 Documentation/RCU/whatisRCU.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/whatisRCU.rst +2 -2
index 246ce0d0b4d1..872ac665223f 100644
@@ -963,8 +963,8 @@ unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be
 initialized after each and every call to kmem_cache_alloc(), which renders
 reference-free spinlock acquisition completely unsafe.  Therefore, when
 using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter.
-(Those willing to use a kmem_cache constructor may also use locking,
-including cache-friendly sequence locking.)
+(Those willing to initialize their locks in a kmem_cache constructor
+may also use locking, including cache-friendly sequence locking.)
 
 With traditional reference counting -- such as that implemented by the
 kref library in Linux -- there is typically code that runs when the last
Signature · 1 line
2.43.0
author
#8 lore raw

PATCH 8/8 doc: Update checklist.rst discussion of callback execution

In reply to Boqun Feng

From: "Paul E. McKenney" <[email protected]>

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.

---
 Documentation/RCU/checklist.rst | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
Documentation/RCU/checklist.rst +11 -10
index addd5c1547a4..3e6407de231c 100644
@@ -383,16 +383,17 @@ over a rather long period of time, but improvements are always welcome!
 	must use whatever locking or other synchronization is required
 	to safely access and/or modify that data structure.
 
-	Do not assume that RCU callbacks will be executed on the same
-	CPU that executed the corresponding call_rcu() or call_srcu().
-	For example, if a given CPU goes offline while having an RCU
-	callback pending, then that RCU callback will execute on some
-	surviving CPU.	(If this was not the case, a self-spawning RCU
-	callback would prevent the victim CPU from ever going offline.)
-	Furthermore, CPUs designated by rcu_nocbs= might well *always*
-	have their RCU callbacks executed on some other CPUs, in fact,
-	for some  real-time workloads, this is the whole point of using
-	the rcu_nocbs= kernel boot parameter.
+	Do not assume that RCU callbacks will be executed on
+	the same CPU that executed the corresponding call_rcu(),
+	call_srcu(), call_rcu_tasks(), call_rcu_tasks_rude(), or
+	call_rcu_tasks_trace().  For example, if a given CPU goes offline
+	while having an RCU callback pending, then that RCU callback
+	will execute on some surviving CPU.  (If this was not the case,
+	a self-spawning RCU callback would prevent the victim CPU from
+	ever going offline.)  Furthermore, CPUs designated by rcu_nocbs=
+	might well *always* have their RCU callbacks executed on some
+	other CPUs, in fact, for some  real-time workloads, this is the
+	whole point of using the rcu_nocbs= kernel boot parameter.
 
 	In addition, do not assume that callbacks queued in a given order
 	will be invoked in that order, even if they all are queued on the
Signature · 1 line
2.43.0