Documentation/RCU/checklist.rst

4 Review Checklist for RCU Patches
9 that make use of RCU.  Violating any of the rules listed below will
14 0.	Is RCU being applied to a read-mostly situation?  If the data
17 	performance measurements show that RCU is nonetheless the right
18 	tool for the job.  Yes, RCU does reduce read-side overhead by
20 	of RCU will do much more reading than updating.
22 	Another exception is where performance is not an issue, and RCU
27 	Yet another exception is where the low real-time latency of RCU's
30 	One final exception is where RCU readers are used to prevent
40 	RCU does allow *readers* to run (almost) naked, but *writers* must
59 2.	Do the RCU read-side critical sections make proper use of
66 	As a rough rule of thumb, any dereference of an RCU-protected
72 	spinlock also enters an RCU read-side critical section.
78 	Letting RCU-protected pointers "leak" out of an RCU read-side
82 	*before* letting them out of the RCU read-side critical section.
86 	The whole point of RCU is to permit readers to run without
91 	a.	Use the RCU variants of the list and hlist update
93 		an RCU-protected list.	Alternatively, use the other
94 		RCU-protected data structures that have been added to
111 		appear to be atomic to RCU readers, nor will sequences
136 	reordered to precede earlier stores.  RCU code must take all of
147 		code know exactly which pointers are protected by RCU.
164 		of an RCU read-side critical section.  See lockdep.rst
186 		in their respective types of RCU-protected lists.
189 		type of RCU-protected linked lists.
195 		be traversed by an RCU read-side critical section.
230 7.	As of v4.20, a given kernel implements only one RCU flavor, which
231 	is RCU-sched for PREEMPTION=n and RCU-preempt for PREEMPTION=y.
241 	srcu_struct.  The rules for the expedited RCU grace-period-wait
244 	Similarly, it is necessary to correctly use the RCU Tasks flavors:
266 	network-driver NAPI (softirq) context.	BPF relies heavily on RCU
296 		used by the RCU-protected data structure, including
310 		RCU grace period.  There are of course many other
336 	CPUs has been configured to offload all of its RCU callbacks onto
339 9.	All RCU list-traversal primitives, which include
341 	list_for_each_safe_rcu(), must be either within an RCU read-side
343 	locks.	RCU read-side critical sections are delimited by
349 	The reason that it is permissible to use RCU list-traversal
362 10.	Conversely, if you are in an RCU read-side critical section,
368 11.	Any lock acquired by an RCU callback must be acquired elsewhere
371 	in deadlock as soon as the RCU softirq handler happens to run
372 	your RCU callback while interrupting that acquisition's critical
375 12.	RCU callbacks can be and are executed in parallel.  In many cases,
383 	Do not assume that RCU callbacks will be executed on the same
386 	a given CPU goes offline while having an RCU callback pending,
387 	then that RCU callback will execute on some surviving CPU.
388 	(If this was not the case, a self-spawning RCU callback would
391 	RCU callbacks executed on some other CPUs, in fact, for some
405 13.	Unlike most flavors of RCU, it *is* permissible to block in an
407 	and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
409 	sections, you should be using RCU rather than SRCU, because RCU
412 	Also unlike other forms of RCU, explicit initialization and
426 	system than RCU would be if RCU's read-side critical sections
434 	being globally amortized as they are for other forms of RCU.
445 	It is also permissible to sleep in RCU Tasks Trace read-side
448 	of RCU, and you should not use it without first checking with
452 	other forms of RCU, but instead of rcu_dereference() you should
467 15.	The various RCU read-side primitives do *not* necessarily contain
469 	and the compiler to freely reorder code into and out of RCU
471 	RCU update-side primitives to deal with this.
477 	__rcu sparse checks to validate your RCU code.	These can help
481 		check that accesses to RCU-protected data structures
482 		are carried out under the proper RCU read-side critical
488 		(or friends) before an RCU grace period has elapsed
494 		of RCU read-side critical sections.  This Kconfig
499 		tag the pointer to the RCU-protected data structure
531 	with the pair depending on the flavor of RCU: