[PATCH for-v7.5 1/5] doc: Update recent SRCU API additions to whatisRCU.rst

[PATCH for-v7.5 1/5] doc: Update recent SRCU API additions to whatisRCU.rst

[Joel Fernandes]

From: Zqiang <qiang.zhang@linux.dev>

The commit 'dab06d6f9379 ("srcutree: Add an atomic Tree SRCU")'
introduces some new APIs:

srcu_read_lock_atomic
srcu_read_unlock_atomic
synchronize_srcu_atomic
DEFINE_SRCU_ATOMIC
DEFINE_STATIC_SRCU_ATOMIC
init_srcu_struct_atomic

This commit therefore update thems to whatisRCU.rst.

Signed-off-by: Zqiang <qiang.zhang@linux.dev>
Reviewed-by: Joel Fernandes <jfern@kernel.org>
Signed-off-by: Joel Fernandes <jfern@kernel.org>
---
 Documentation/RCU/whatisRCU.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index e6767baff2d3..75c50f2f6d79 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -1209,11 +1209,13 @@ SRCU::
 	srcu_read_lock_nmisafe		start_poll_synchronize_srcu
 	srcu_read_unlock_nmisafe	start_poll_synchronize_srcu_expedited
 	srcu_read_lock_notrace		poll_state_synchronize_srcu
-	srcu_read_unlock_notrace
+	srcu_read_unlock_notrace	synchronize_srcu_atomic
 	srcu_down_read
 	srcu_up_read
 	srcu_down_read_fast
 	srcu_up_read_fast
+	srcu_read_lock_atomic
+	srcu_read_unlock_atomic
 	guard(srcu)()
 	scoped_guard(srcu)
 	srcu_read_lock_held
@@ -1229,8 +1231,11 @@ SRCU: Initialization/cleanup/ordering::
 	DEFINE_STATIC_SRCU
 	DEFINE_SRCU_FAST        // for srcu_read_lock_fast() and friends
 	DEFINE_STATIC_SRCU_FAST // for srcu_read_lock_fast() and friends
+	DEFINE_SRCU_ATOMIC
+	DEFINE_STATIC_SRCU_ATOMIC
 	init_srcu_struct
 	init_srcu_struct_fast
+	init_srcu_struct_atomic
 	cleanup_srcu_struct
 	smp_mb__after_srcu_read_unlock
 
-- 
2.54.0

[PATCH for-v7.5 3/5] doc: Document atomic SRCU in Design/Requirements/Requirements.rst

[Joel Fernandes]

Atomic SRCU (srcu_read_lock_atomic(), srcu_read_unlock_atomic(),
synchronize_srcu_atomic(), init_srcu_struct_atomic(), and friends)
added readers that do not sleep or block, plus an update side that spins
rather than sleeping.

These are missing from Requirements.rst. Add them.

Signed-off-by: Joel Fernandes <jfern@kernel.org>
Acked-by: Paul E. McKenney <paulmck@kernel.org>
---
 .../RCU/Design/Requirements/Requirements.rst  | 28 +++++++++++++++----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index 8101fe6229d5..d43668595872 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -2686,11 +2686,13 @@ The `SRCU API
 <https://lwn.net/Articles/609973/#RCU%20Per-Flavor%20API%20Table>`__
 includes srcu_read_lock(), srcu_read_unlock(),
 srcu_dereference(), srcu_dereference_check(), synchronize_srcu(),
-synchronize_srcu_expedited(), call_srcu(), srcu_barrier(),
-and srcu_read_lock_held(). It also includes DEFINE_SRCU(),
-DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(), DEFINE_STATIC_SRCU_FAST(),
-init_srcu_struct(), and init_srcu_struct_fast() APIs for defining and
-initializing ``srcu_struct`` structures.
+synchronize_srcu_expedited(), synchronize_srcu_atomic(), call_srcu(),
+srcu_barrier(), and srcu_read_lock_held(). It also includes
+DEFINE_SRCU(), DEFINE_STATIC_SRCU(), DEFINE_SRCU_FAST(),
+DEFINE_STATIC_SRCU_FAST(), DEFINE_SRCU_ATOMIC(),
+DEFINE_STATIC_SRCU_ATOMIC(), init_srcu_struct(),
+init_srcu_struct_fast(), and init_srcu_struct_atomic() APIs for
+defining and initializing ``srcu_struct`` structures.
 
 More recently, the SRCU API has added polling interfaces:
 
@@ -2710,6 +2712,22 @@ certain types of buffer-cache algorithms having multi-stage age-out
 mechanisms.  The idea is that by the time the block has aged completely
 from the cache, an SRCU grace period will be very likely to have elapsed.
 
+A more recent addition to the SRCU API is the atomic flavor:
+srcu_read_lock_atomic(), srcu_read_unlock_atomic(), and
+synchronize_srcu_atomic(). An atomic-SRCU reader runs with preemption
+disabled, must invoke srcu_read_lock_atomic() and
+srcu_read_unlock_atomic() on the same CPU from the same context, and
+must never sleep nor block on anything that might itself depend on
+memory allocation, which allows synchronize_srcu_atomic() to spin
+rather than sleep while waiting for pre-existing readers. This
+requires that all other SRCU usage be excluded from a given atomic
+``srcu_struct`` structure: every reader must use
+srcu_read_lock_atomic() and srcu_read_unlock_atomic() rather than
+srcu_read_lock() or any other SRCU reader flavor, and the structure
+must not be passed to call_srcu(), synchronize_srcu(),
+synchronize_srcu_expedited(), start_poll_synchronize_srcu(),
+srcu_barrier(), or srcu_expedite_current().
+
 Tasks RCU
 ~~~~~~~~~
 
-- 
2.54.0

[PATCH for-v7.5 4/5] doc: Fix stale RCU_GP_WAIT_FQS value in stallwarn.rst

[Joel Fernandes]

From: Yonghao Zhang <hyz3367@gmail.com>

The sample "kthread starved" splat in stallwarn.rst shows
RCU_GP_WAIT_FQS(3), which was correct when the example was captured,
but has been stale since commit fea3f222d352 ("rcu: Record ->gp_state
for both phases of grace-period initialization") inserted
RCU_GP_ONOFF (3) and RCU_GP_INIT (4) ahead of it, shifting
RCU_GP_WAIT_FQS from 3 to 5.

Update the sample output to show (5), matching the current tree.h
values and the later "kthread timer wakeup" example in the same file.

Fixes: fea3f222d352 ("rcu: Record ->gp_state for both phases of grace-period initialization")
Signed-off-by: Yonghao Zhang <hyz3367@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Zqiang <qiang.zhang@linux.dev>
Link: https://lore.kernel.org/r/20261014063130.3691735-1-hyz3367@gmail.com
Signed-off-by: Joel Fernandes <jfern@kernel.org>
---
 Documentation/RCU/stallwarn.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index a986358a5c27..118c47506753 100644
--- a/Documentation/RCU/stallwarn.rst
+++ b/Documentation/RCU/stallwarn.rst
@@ -314,7 +314,7 @@ If the relevant grace-period kthread has been unable to run prior to
 the stall warning, as was the case in the "All QSes seen" line above,
 the following additional line is printed::
 
-	rcu_sched kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5
+	rcu_sched kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(5) ->state=0x1 ->cpu=5
 	Unless rcu_sched kthread gets sufficient CPU time, OOM is now expected behavior.
 
 Starving the grace-period kthreads of CPU time can of course result
-- 
2.54.0

[PATCH for-v7.5 5/5] doc: Document additional RCU task-stall dump information

[Joel Fernandes]

From: "Paul E. McKenney" <paulmck@kernel.org>

This commit adds explanation for the added task-stall dumps, which can
be as follows:

	Tasks blocked on level-1 rcu_node (CPUs 0-8): P96/1:b..l.B CPU 5 swapper/5 (0) (idle!)

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Joel Fernandes <jfern@kernel.org>
---
 Documentation/RCU/stallwarn.rst | 71 +++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 3 deletions(-)

diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst
index 118c47506753..049694b9c681 100644
--- a/Documentation/RCU/stallwarn.rst
+++ b/Documentation/RCU/stallwarn.rst
@@ -234,6 +234,7 @@ CPU is stalling, it will print a message similar to the following::
 	INFO: rcu_sched detected stalls on CPUs/tasks:
 	2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0
 	16-...: (0 ticks this GP) idle=81c/0/0 softirq=764/764 fqs=0
+	Tasks blocked on level-1 rcu_node (CPUs 0-8): P96/1:b..l.B CPU 5 swapper/5 (0) (idle!)
 	(detected by 32, t=2603 jiffies, g=7075, q=625)
 
 This message indicates that CPU 32 detected that CPUs 2 and 16 were both
@@ -278,6 +279,70 @@ detection passes that the grace-period kthread has made across this
 CPU since the last time that this CPU noted the beginning of a grace
 period.
 
+The "Tasks blocked" line lists the tasks blocked on each leaf ``rcu_node``
+structure.  The "(CPUs 0-8)" indicates that this particular leaf
+``rcu_node`` structure handles the nine CPUs numbered from 0 to 8,
+which indicates an odd but perfectly legal state of affairs ("0-15"
+is typical).  The "P96" indicates that the task with PID 96 is blocking
+the current grace period.
+
+Certain race conditions can prevent the remaining information on this
+line from appearing, most typically that task P96 is currently running on
+some other CPU.  The "/1" indicates that this task was preempted within
+its top-level RCU read-side critical section.  The ":b..l.B" indicates
+task state as follows, with "." indicating that the corresponding state
+is not in effect:
+
+b (blocked)
+   This task has been preempted (blocked) at least once during its
+   current RCU read-side critical section.
+
+q (needs quiescent state)
+   This task has been flagged as running on a CPU from which RCU needs
+   a quiescent state.
+
+e (expedited hint)
+   An expedited RCU grace period is interested in this task.
+
+l (on ->blkd_tasks list)
+   This task is currently on a list of blocked (preempted) tasks that
+   either are or might some day hold up an RCU grace period.  Note that
+   if the task has not yet been preempted, this task will not be on any
+   of these lists, which means that RCU will still be waiting on the
+   CPU the task is running on, not yet the task itself.
+
+R (Running)
+   This task is running (as opposed to just runnable, that is, preempted).
+   This is unusual, but could happen if the task was preempted and
+   started running again before this RCU CPU stall warning.
+
+B (Boosted)
+   This task is currently priority boosted.  There is a narrow window
+   during which the rtmutex has been created with this task as owner,
+   but the rcub task has not yet attempted to acquire that rtmutex.
+   During this narrow window, the task would be reported as being boosted,
+   but would not yet actually be boosted.
+
+The "CPU 5" indicates that the task is in CPU 5’s runqueue and that
+this CPU is online.  If the CPU were offline, this would instead read
+"CPU 5!".  The "swapper/5" is the running task’s ->comm string.
+If there was somehow no task running on CPU 5, this would instead read
+"???".  The "(0)" indicates that the running task’s PID is zero.
+Which is a problem.  If there was somehow no task running on CPU 5,
+this would instead read "(-1)".
+
+The "(idle!)" indicates that the task currently running on CPU 5 is its
+idle task, which is not supposed to happen, other than during small
+windows of time where one CPU wakes up a task that is to run on an
+idle CPU.  (The rescheduling IPI does after all take time to reach the
+idle CPU!)  If there was somehow no task running on CPU 5, this would
+instead read "(no task)".  Otherwise, nothing would be printed.
+
+If there was more than one task queued on this ``rcu_node`` structure,
+for example, suppose that task P192 was also blocking the current RCU
+grace period.  In that case, the line would contine with P192 followed
+optionally by the rest of the per-task information.
+
 The "detected by" line indicates which CPU detected the stall (in this
 case, CPU 32), how many jiffies have elapsed since the start of the grace
 period (in this case 2603), the grace-period sequence number (7075), and
@@ -307,7 +372,7 @@ The "23807" indicates that it has been more than 23 thousand jiffies
 since the grace-period kthread ran.  The "jiffies_till_next_fqs"
 indicates how frequently that kthread should run, giving the number
 of jiffies between force-quiescent-state scans, in this case three,
-which is way less than 23807.  Finally, the root rcu_node structure's
+which is way less than 23807.  Finally, the root ``rcu_node`` structure's
 ->qsmask field is printed, which will normally be zero.
 
 If the relevant grace-period kthread has been unable to run prior to
@@ -382,10 +447,10 @@ jiffies.  The number following the "s:" indicates that the expedited
 grace-period sequence counter is 73.  The fact that this last value is
 odd indicates that an expedited grace period is in flight.  The number
 following "root:" is a bitmask that indicates which children of the root
-rcu_node structure correspond to CPUs and/or tasks that are blocking the
+``rcu_node`` structure correspond to CPUs and/or tasks that are blocking the
 current expedited grace period.  If the tree had more than one level,
 additional hex numbers would be printed for the states of the other
-rcu_node structures in the tree.
+``rcu_node`` structures in the tree.
 
 As with normal grace periods, PREEMPT_RCU builds can be stalled by
 tasks as well as by CPUs, and that the tasks will be indicated by PID,
-- 
2.54.0