Commit 1b7178b2 authored by Paul E. McKenney's avatar Paul E. McKenney Committed by Neeraj Upadhyay (AMD)
Browse files

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: default avatarSteven Rostedt <rostedt@goodmis.org>
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
Reviewed-by: default avatarMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Reviewed-by: default avatarSteven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: default avatarNeeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
parent 493dffa3

Documentation/RCU/checklist.rst

+16 −9
Original line number Diff line number Diff line
@@ -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,