Documentation/RCU/checklist.rst

1 .. SPDX-License-Identifier: GPL-2.0
14 0.	Is RCU being applied to a read-mostly situation?  If the data
18 	tool for the job.  Yes, RCU does reduce read-side overhead by
19 	increasing write-side overhead, which is exactly why normal uses
27 	Yet another exception is where the low real-time latency of RCU's
28 	read-side primitives is critically important.
33 	counter-intuitive situation where rcu_read_lock() and
49 	them -- even x86 allows later loads to be reordered to precede
54 	relating to itself that other tasks can read, there by definition
59 2.	Do the RCU read-side critical sections make proper use of
63 	under your read-side code, which can greatly increase the
66 	As a rough rule of thumb, any dereference of an RCU-protected
67 	pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(),
68 	rcu_read_lock_sched(), or by the appropriate update-side lock.
74 	only in non-preemptible kernels.  Such code can and will break,
77 	Letting RCU-protected pointers "leak" out of an RCU read-side
81 	*before* letting them out of the RCU read-side critical section.
92 		an RCU-protected list.	Alternatively, use the other
93 		RCU-protected data structures that have been added to
98 	b.	Proceed as in (a) above, but also maintain per-element
99 		locks (that are acquired by both readers and writers)
100 		that guard per-element state.  Fields that the readers
101 		refrain from accessing can be guarded by some other lock
102 		acquired only by updaters, if desired.
113 		thus solving the multiple-field problem by imposing an
122 		usually liberally sprinkle memory-ordering operations
130 		change may be made to appear atomic by updating a pointer
134 	are weakly ordered -- even x86 CPUs allow later loads to be
136 	the following measures to prevent memory-corruption problems:
146 		code know exactly which pointers are protected by RCU.
155 		The rcu_dereference() primitive is used by the
156 		various "_rcu()" list-traversal primitives, such
158 		perfectly legal (if redundant) for update-side code to
159 		use rcu_dereference() and the "_rcu()" list-traversal
163 		of an RCU read-side critical section.  See lockdep.rst
167 		list-traversal primitives can substitute for a good
185 		in their respective types of RCU-protected lists.
188 		type of RCU-protected linked lists.
194 		be traversed by an RCU read-side critical section.
212 	as the non-expedited forms, but expediting is more CPU intensive.
214 	configuration-change operations that would not normally be
215 	undertaken while a real-time workload is running.  Note that
216 	IPI-sensitive real-time workloads can use the rcupdate.rcu_normal
223 	a single non-expedited primitive to cover the entire batch.
226 	of the system, especially to real-time workloads running on the
231 	is RCU-sched for PREEMPTION=n and RCU-preempt for PREEMPTION=y.
235 	and re-enables softirq, for example, rcu_read_lock_bh() and
237 	and re-enables preemption, for example, rcu_read_lock_sched() and
241 	srcu_struct.  The rules for the expedited RCU grace-period-wait
242 	primitives are the same as for their non-expedited counterparts.
256 	when using non-obvious pairs of primitives, commenting is
257 	of course a must.  One example of non-obvious pairing is
259 	network-driver NAPI (softirq) context.	BPF relies heavily on RCU
273 	synchronize_rcu()'s multi-millisecond latency.	So please take
275 	memory-freeing capabilities where it applies.
278 	primitive is that it automatically self-limits: if grace periods
285 	Ways of gaining this self-limiting property when using call_rcu(),
288 	a.	Keeping a count of the number of data-structure elements
289 		used by the RCU-protected data structure, including
296 		One way to stall the updates is to acquire the update-side
297 		mutex.	(Don't try this with a spinlock -- other CPUs
312 	c.	Trusted update -- if updates can only be done manually by
334 9.	All RCU list-traversal primitives, which include
336 	list_for_each_safe_rcu(), must be either within an RCU read-side
337 	critical section or must be protected by appropriate update-side
338 	locks.	RCU read-side critical sections are delimited by
339 	rcu_read_lock() and rcu_read_unlock(), or by similar primitives
344 	The reason that it is permissible to use RCU list-traversal
345 	primitives when the update-side lock is held is that doing so
354 	and the read-side markers (rcu_read_lock() and rcu_read_unlock(),
357 10.	Conversely, if you are in an RCU read-side critical section,
358 	and you don't hold the appropriate update-side lock, you *must*
363 11.	Any lock acquired by an RCU callback must be acquired elsewhere
373 	an issue, the memory-allocator locking handles it).  However,
382 	surviving CPU.	(If this was not the case, a self-spawning RCU
384 	Furthermore, CPUs designated by rcu_nocbs= might well *always*
386 	for some  real-time workloads, this is the whole point of using
391 	same CPU.  Furthermore, do not assume that same-CPU callbacks will
393 	switched between offloaded and de-offloaded callback invocation,
395 	might be concurrently invoked by that CPU's softirq handler and
400 	SRCU read-side critical section (demarked by srcu_read_lock()
402 	Please note that if you don't need to sleep in read-side critical
414 	synchronize_srcu() waits only for SRCU read-side critical
415 	sections governed by srcu_read_lock() and srcu_read_unlock()
417 	is what makes sleeping read-side critical sections tolerable --
420 	system than RCU would be if RCU's read-side critical sections
423 	The ability to sleep in read-side critical sections does not
426 	Second, grace-period-detection overhead is amortized only
430 	only in extremely read-intensive situations, or in situations
431 	requiring SRCU's read-side deadlock immunity or low read-side
437 	real-time workloads than is synchronize_rcu_expedited().
439 	It is also permissible to sleep in RCU Tasks Trace read-side
440 	critical, which are delimited by rcu_read_lock_trace() and
450 	is to wait until all pre-existing readers have finished before
451 	carrying out some otherwise-destructive operation.  It is
453 	that readers can follow that could be affected by the
457 	Because these primitives only wait for pre-existing readers, it
461 15.	The various RCU read-side primitives do *not* necessarily contain
464 	read-side critical sections.  It is the responsibility of the
465 	RCU update-side primitives to deal with this.
475 		check that accesses to RCU-protected data structures
476 		are carried out under the proper RCU read-side critical
487 		tag the pointer to the RCU-protected data structure
507 	-	call_rcu() -> rcu_barrier()
508 	-	call_srcu() -> srcu_barrier()
509 	-	call_rcu_tasks() -> rcu_barrier_tasks()
510 	-	call_rcu_tasks_rude() -> rcu_barrier_tasks_rude()
511 	-	call_rcu_tasks_trace() -> rcu_barrier_tasks_trace()
519 	pre-existing callbacks, you will need to invoke both functions,
522 	-	Either synchronize_rcu() or synchronize_rcu_expedited(),
524 	-	Either synchronize_srcu() or synchronize_srcu_expedited(),
526 	-	synchronize_rcu_tasks() and rcu_barrier_tasks()
527 	-	synchronize_tasks_rude() and rcu_barrier_tasks_rude()
528 	-	synchronize_tasks_trace() and rcu_barrier_tasks_trace()