RCU doc updates for v6.9
Subsystems (5)
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
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
@@ -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
PATCH 2/8 doc: Make whatisRCU.rst note that spinlocks are RCU readers
In reply to Boqun FengFrom: "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
@@ -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
PATCH 3/8 doc: Make checklist.rst note that spinlocks are implied RCU readers
In reply to Boqun FengFrom: "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
@@ -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
PATCH 4/8 doc: Add CONFIG_RCU_STRICT_GRACE_PERIOD to checklist.rst
In reply to Boqun FengFrom: "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
@@ -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
PATCH 5/8 doc: Add EARLY flag to early-parsed kernel boot parameters
In reply to Boqun FengFrom: "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.
--- .../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
@@ -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
PATCH 6/8 context_tracking: Fix kerneldoc headers for __ct_user_{enter,exit}()
In reply to Boqun FengFrom: "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
@@ -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
PATCH 7/8 doc: Clarify use of slab constructors and SLAB_TYPESAFE_BY_RCU
In reply to Boqun FengFrom: "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
@@ -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
PATCH 8/8 doc: Update checklist.rst discussion of callback execution
In reply to Boqun FengFrom: "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
@@ -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