Gh0st
/
linux
mirror of https://github.com/torvalds/linux.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: Update for SRCU-fast definitions and initialization 

This commit documents the DEFINE_SRCU_FAST(), DEFINE_STATIC_SRCU_FAST(),
and init_srcu_struct_fast() API members.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Cc: <bpf@vger.kernel.org>
Signed-off-by: Frederic Weisbecker <frederic@kernel.org>
This commit is contained in:
Paul E. McKenney 2025-11-05 12:32:09 -08:00 committed by Frederic Weisbecker
parent ac51c40c2c
commit 8c8250ee3b
3 changed files with 27 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Documentation/RCU/Design/Requirements/Requirements.rst
View File

@ -2637,15 +2637,16 @@ synchronize_srcu() for some other domain ``ss1``, and if an
that was held across as ``ss``-domain synchronize_srcu(), deadlock that was held across as ``ss``-domain synchronize_srcu(), deadlock
would again be possible. Such a deadlock cycle could extend across an would again be possible. Such a deadlock cycle could extend across an
arbitrarily large number of different SRCU domains. Again, with great arbitrarily large number of different SRCU domains. Again, with great
power comes great responsibility. power comes great responsibility, though lockdep is now able to detect
this sort of deadlock.
Unlike the other RCU flavors, SRCU read-side critical sections can run Unlike the other RCU flavors, SRCU read-side critical sections can run on
on idle and even offline CPUs. This ability requires that idle and even offline CPUs, with the exception of srcu_read_lock_fast()
srcu_read_lock() and srcu_read_unlock() contain memory barriers, and friends. This ability requires that srcu_read_lock() and
which means that SRCU readers will run a bit slower than would RCU srcu_read_unlock() contain memory barriers, which means that SRCU
readers. It also motivates the smp_mb__after_srcu_read_unlock() API, readers will run a bit slower than would RCU readers. It also motivates
which, in combination with srcu_read_unlock(), guarantees a full the smp_mb__after_srcu_read_unlock() API, which, in combination with
memory barrier. srcu_read_unlock(), guarantees a full memory barrier.
Also unlike other RCU flavors, synchronize_srcu() may **not** be Also unlike other RCU flavors, synchronize_srcu() may **not** be
invoked from CPU-hotplug notifiers, due to the fact that SRCU grace invoked from CPU-hotplug notifiers, due to the fact that SRCU grace
@ -2681,15 +2682,15 @@ run some tests first. SRCU just might need a few adjustment to deal with
that sort of load. Of course, your mileage may vary based on the speed that sort of load. Of course, your mileage may vary based on the speed
of your CPUs and the size of your memory. of your CPUs and the size of your memory.
The `SRCU The `SRCU API
API <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__ <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
includes srcu_read_lock(), srcu_read_unlock(), includes srcu_read_lock(), srcu_read_unlock(),
srcu_dereference(), srcu_dereference_check(), srcu_dereference(), srcu_dereference_check(), synchronize_srcu(),
synchronize_srcu(), synchronize_srcu_expedited(), synchronize_srcu_expedited(), call_srcu(), srcu_barrier(),
call_srcu(), srcu_barrier(), and srcu_read_lock_held(). It and srcu_read_lock_held(). It also includes DEFINE_SRCU(),
also includes DEFINE_SRCU(), DEFINE_STATIC_SRCU(), and DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(), DEFINE_STATIC_SRCU_FAST(),
init_srcu_struct() APIs for defining and initializing init_srcu_struct(), and init_srcu_struct_fast() APIs for defining and
``srcu_struct`` structures. initializing ``srcu_struct`` structures.
More recently, the SRCU API has added polling interfaces: More recently, the SRCU API has added polling interfaces:

12
Documentation/RCU/checklist.rst
View File

@ -417,11 +417,13 @@ over a rather long period of time, but improvements are always welcome!
you should be using RCU rather than SRCU, because RCU is almost you should be using RCU rather than SRCU, because RCU is almost
always faster and easier to use than is SRCU. always faster and easier to use than is SRCU.
Also unlike other forms of RCU, explicit initialization and Also unlike other forms of RCU, explicit initialization
cleanup is required either at build time via DEFINE_SRCU() and cleanup is required either at build time via
or DEFINE_STATIC_SRCU() or at runtime via init_srcu_struct() DEFINE_SRCU(), DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(),
and cleanup_srcu_struct(). These last two are passed a or DEFINE_STATIC_SRCU_FAST() or at runtime via either
"struct srcu_struct" that defines the scope of a given init_srcu_struct() or init_srcu_struct_fast() and
cleanup_srcu_struct(). These last three are passed a
`struct srcu_struct` that defines the scope of a given
SRCU domain. Once initialized, the srcu_struct is passed SRCU domain. Once initialized, the srcu_struct is passed
to srcu_read_lock(), srcu_read_unlock() synchronize_srcu(), to srcu_read_lock(), srcu_read_unlock() synchronize_srcu(),
synchronize_srcu_expedited(), and call_srcu(). A given synchronize_srcu_expedited(), and call_srcu(). A given

3
Documentation/RCU/whatisRCU.rst
View File

@ -1227,7 +1227,10 @@ SRCU: Initialization/cleanup/ordering::
DEFINE_SRCU DEFINE_SRCU
DEFINE_STATIC_SRCU DEFINE_STATIC_SRCU
DEFINE_SRCU_FAST // for srcu_read_lock_fast() and friends
DEFINE_STATIC_SRCU_FAST // for srcu_read_lock_fast() and friends
init_srcu_struct init_srcu_struct
init_srcu_struct_fast
cleanup_srcu_struct cleanup_srcu_struct
smp_mb__after_srcu_read_unlock smp_mb__after_srcu_read_unlock