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 	Letting RCU-protected pointers "leak" out of an RCU read-side
76 	-before- letting them out of the RCU read-side critical section.
80 	The whole point of RCU is to permit readers to run without
85 	a.	Use the RCU variants of the list and hlist update
87 		an RCU-protected list.	Alternatively, use the other
88 		RCU-protected data structures that have been added to
105 		appear to be atomic to RCU readers, nor will sequences
125 	reordered to precede earlier stores.  RCU code must take all of
138 		code know exactly which pointers are protected by RCU.
156 		of an RCU read-side critical section.  See lockdep.txt
178 		in their respective types of RCU-protected lists.
181 		type of RCU-protected linked lists.
187 		be traversed by an RCU read-side critical section.
216 7.	As of v4.20, a given kernel implements only one RCU flavor,
217 	which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
260 		used by the RCU-protected data structure, including
274 		RCU grace period.  There are of course many other
298 	offload all of its RCU callbacks onto a single CPU, or if the
301 9.	All RCU list-traversal primitives, which include
303 	list_for_each_safe_rcu(), must be either within an RCU read-side
305 	locks.	RCU read-side critical sections are delimited by
311 	The reason that it is permissible to use RCU list-traversal
317 10.	Conversely, if you are in an RCU read-side critical section,
323 11.	Any lock acquired by an RCU callback must be acquired elsewhere
327 	the RCU softirq handler happens to run your RCU callback while
330 12.	RCU callbacks can be and are executed in parallel.  In many cases,
338 	Do not assume that RCU callbacks will be executed on the same
340 	For example, if a given CPU goes offline while having an RCU
341 	callback pending, then that RCU callback will execute on some
342 	surviving CPU.	(If this was not the case, a self-spawning RCU
345 	have their RCU callbacks executed on some other CPUs, in fact,
349 13.	Unlike other forms of RCU, it -is- permissible to block in an
351 	and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
353 	sections, you should be using RCU rather than SRCU, because RCU
356 	Also unlike other forms of RCU, explicit initialization and
370 	system than RCU would be if RCU's read-side critical sections
378 	being globally amortized as they are for other forms of RCU.
390 	other forms of RCU, but instead of rcu_dereference() you should
405 15.	The various RCU read-side primitives do -not- necessarily contain
407 	and the compiler to freely reorder code into and out of RCU
409 	RCU update-side primitives to deal with this.
415 	__rcu sparse checks to validate your RCU code.	These can help
419 		check that accesses to RCU-protected data
420 		structures are carried out under the proper RCU
427 		same object to call_rcu() (or friends) before an RCU
432 		tag the pointer to the RCU-protected data
460 	So if you need to wait for both an RCU grace period and for