doc: Clarify RCU Tasks reader/updater checklist

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 <rostedt@goodmis.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>

diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index bd3c58c44befdd3a04811c81e4887bad6f321255..2d42998a89a6378a94521d49785c4f1632b25a34 100644 (file)
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -241,15 +241,22 @@ over a rather long period of time, but improvements are always welcome!
        srcu_struct.  The rules for the expedited RCU grace-period-wait
        primitives are the same as for their non-expedited counterparts.
 
-       If the updater uses call_rcu_tasks() or synchronize_rcu_tasks(),
-       then the readers must refrain from executing voluntary
-       context switches, that is, from blocking.  If the updater uses
-       call_rcu_tasks_trace() or synchronize_rcu_tasks_trace(), then
-       the corresponding readers must use rcu_read_lock_trace() and
-       rcu_read_unlock_trace().  If an updater uses call_rcu_tasks_rude()
-       or synchronize_rcu_tasks_rude(), then the corresponding readers
-       must use anything that disables preemption, for example,
-       preempt_disable() and preempt_enable().
+       Similarly, it is necessary to correctly use the RCU Tasks flavors:
+
+       a.      If the updater uses synchronize_rcu_tasks() or
+               call_rcu_tasks(), then the readers must refrain from
+               executing voluntary context switches, that is, from
+               blocking.
+
+       b.      If the updater uses call_rcu_tasks_trace()
+               or synchronize_rcu_tasks_trace(), then the
+               corresponding readers must use rcu_read_lock_trace()
+               and rcu_read_unlock_trace().
+
+       c.      If an updater uses call_rcu_tasks_rude() or
+               synchronize_rcu_tasks_rude(), then the corresponding
+               readers must use anything that disables preemption,
+               for example, preempt_disable() and preempt_enable().
 
        Mixing things up will result in confusion and broken kernels, and
        has even resulted in an exploitable security issue.  Therefore,