History

doc: Fix typos and otherwise modernize checklist.txt

This commit fixes some issues with Documentation/RCU/checklist.txt.

Paul E. McKenney committed 7 years ago

Commit 884b4291 parent d1b493b1 file · +25 −18Browse files

Unified · Split

Documentation/RCU/checklist.txt+25−18
@@ -318,7 +318,7 @@ over a rather long period of time, but improvements are always welcome! · 317 unmodified lines
318 318
31911. Any lock acquired by an RCU callback must be acquired elsewhere31911. Any lock acquired by an RCU callback must be acquired elsewhere
320 with softirq disabled, e.g., via spin_lock_irqsave(),320 with softirq disabled, e.g., via spin_lock_irqsave(),
321 spin_lock_bh(), etc. Failing to disable irq on a given321 spin_lock_bh(), etc. Failing to disable softirq on a given
322 acquisition of that lock will result in deadlock as soon as322 acquisition of that lock will result in deadlock as soon as
323 the RCU softirq handler happens to run your RCU callback while323 the RCU softirq handler happens to run your RCU callback while
324 interrupting that acquisition's critical section.324 interrupting that acquisition's critical section.
@@ -331,13 +331,16 @@ over a rather long period of time, but improvements are always welcome! · 6 unmodified lines
331 must use whatever locking or other synchronization is required331 must use whatever locking or other synchronization is required
332 to safely access and/or modify that data structure.332 to safely access and/or modify that data structure.
333 333
334 RCU callbacks are -usually- executed on the same CPU that executed334 Do not assume that RCU callbacks will be executed on the same
335 the corresponding call_rcu() or call_srcu(). but are by -no-335 CPU that executed the corresponding call_rcu() or call_srcu().
336 means guaranteed to be. For example, if a given CPU goes offline336 For example, if a given CPU goes offline while having an RCU
337 while having an RCU callback pending, then that RCU callback337 callback pending, then that RCU callback will execute on some
338 will execute on some surviving CPU. (If this was not the case,338 surviving CPU. (If this was not the case, a self-spawning RCU
339 a self-spawning RCU callback would prevent the victim CPU from339 callback would prevent the victim CPU from ever going offline.)
340 ever going offline.)340 Furthermore, CPUs designated by rcu_nocbs= might well -always-
341 have their RCU callbacks executed on some other CPUs, in fact,
342 for some real-time workloads, this is the whole point of using
343 the rcu_nocbs= kernel boot parameter.
341 344
34213. Unlike other forms of RCU, it -is- permissible to block in an34513. Unlike other forms of RCU, it -is- permissible to block in an
343 SRCU read-side critical section (demarked by srcu_read_lock()346 SRCU read-side critical section (demarked by srcu_read_lock()
@@ -379,8 +382,9 @@ over a rather long period of time, but improvements are always welcome! · 35 unmodified lines
379 never sends IPIs to other CPUs, so it is easier on382 never sends IPIs to other CPUs, so it is easier on
380 real-time workloads than is synchronize_rcu_expedited().383 real-time workloads than is synchronize_rcu_expedited().
381 384
382 Note that rcu_dereference() and rcu_assign_pointer() relate to385 Note that rcu_assign_pointer() relates to SRCU just as it does to
383 SRCU just as they do to other forms of RCU.386 other forms of RCU, but instead of rcu_dereference() you should
387 use srcu_dereference() in order to avoid lockdep splats.
384 388
38514. The whole point of call_rcu(), synchronize_rcu(), and friends38914. The whole point of call_rcu(), synchronize_rcu(), and friends
386 is to wait until all pre-existing readers have finished before390 is to wait until all pre-existing readers have finished before
@@ -400,6 +404,9 @@ over a rather long period of time, but improvements are always welcome! · 13 unmodified lines
400 read-side critical sections. It is the responsibility of the404 read-side critical sections. It is the responsibility of the
401 RCU update-side primitives to deal with this.405 RCU update-side primitives to deal with this.
402 406
407 For SRCU readers, you can use smp_mb__after_srcu_read_unlock()
408 immediately after an srcu_read_unlock() to get a full barrier.
409
40316. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the41016. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
404 __rcu sparse checks to validate your RCU code. These can help411 __rcu sparse checks to validate your RCU code. These can help
405 find problems as follows:412 find problems as follows:
@@ -423,15 +430,15 @@ over a rather long period of time, but improvements are always welcome! · 17 unmodified lines
423 These debugging aids can help you find problems that are430 These debugging aids can help you find problems that are
424 otherwise extremely difficult to spot.431 otherwise extremely difficult to spot.
425 432
42617. If you register a callback using call_rcu() or call_srcu(),43317. If you register a callback using call_rcu() or call_srcu(), and
427 and pass in a function defined within a loadable module,434 pass in a function defined within a loadable module, then it in
428 then it in necessary to wait for all pending callbacks to435 necessary to wait for all pending callbacks to be invoked after
429 be invoked after the last invocation and before unloading436 the last invocation and before unloading that module. Note that
430 that module. Note that it is absolutely -not- sufficient to437 it is absolutely -not- sufficient to wait for a grace period!
431 wait for a grace period! The current (say) synchronize_rcu()438 The current (say) synchronize_rcu() implementation is -not-
432 implementation waits only for all previous callbacks registered
433 on the CPU that synchronize_rcu() is running on, but it is -not-
434 guaranteed to wait for callbacks registered on other CPUs.439 guaranteed to wait for callbacks registered on other CPUs.
440 Or even on the current CPU if that CPU recently went offline
441 and came back online.
435 442
436 You instead need to use one of the barrier functions:443 You instead need to use one of the barrier functions:
437 444

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t