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
318318
319319 11. Any lock acquired by an RCU callback must be acquired elsewhere
320320 with softirq disabled, e.g., via spin_lock_irqsave(),
321− spin_lock_bh(), etc. Failing to disable irq on a given
321+ spin_lock_bh(), etc. Failing to disable softirq on a given
322322 acquisition of that lock will result in deadlock as soon as
323323 the RCU softirq handler happens to run your RCU callback while
324324 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
331331 must use whatever locking or other synchronization is required
332332 to safely access and/or modify that data structure.
333333
334− RCU callbacks are -usually- executed on the same CPU that executed
335− the corresponding call_rcu() or call_srcu(). but are by -no-
336− means guaranteed to be. For example, if a given CPU goes offline
337− while having an RCU callback pending, then that RCU callback
338− will execute on some surviving CPU. (If this was not the case,
339− a self-spawning RCU callback would prevent the victim CPU from
340− ever going offline.)
334+ Do not assume that RCU callbacks will be executed on the same
335+ CPU that executed the corresponding call_rcu() or call_srcu().
336+ For example, if a given CPU goes offline while having an RCU
337+ callback pending, then that RCU callback will execute on some
338+ surviving CPU. (If this was not the case, a self-spawning RCU
339+ callback would prevent the victim CPU from 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.
341344
342345 13. Unlike other forms of RCU, it -is- permissible to block in an
343346 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
379382 never sends IPIs to other CPUs, so it is easier on
380383 real-time workloads than is synchronize_rcu_expedited().
381384
382− Note that rcu_dereference() and rcu_assign_pointer() relate to
383− SRCU just as they do to other forms of RCU.
385+ Note that rcu_assign_pointer() relates to SRCU just as it does to
386+ other forms of RCU, but instead of rcu_dereference() you should
387+ use srcu_dereference() in order to avoid lockdep splats.
384388
385389 14. The whole point of call_rcu(), synchronize_rcu(), and friends
386390 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
400404 read-side critical sections. It is the responsibility of the
401405 RCU update-side primitives to deal with this.
402406
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+
403410 16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
404411 __rcu sparse checks to validate your RCU code. These can help
405412 find problems as follows:
@@ -423,15 +430,15 @@ over a rather long period of time, but improvements are always welcome! · 17 unmodified lines
423430 These debugging aids can help you find problems that are
424431 otherwise extremely difficult to spot.
425432
426−17. If you register a callback using call_rcu() or call_srcu(),
427− and pass in a function defined within a loadable module,
428− then it in necessary to wait for all pending callbacks to
429− be invoked after the last invocation and before unloading
430− that module. Note that it is absolutely -not- sufficient to
431− wait for a grace period! The current (say) synchronize_rcu()
432− implementation waits only for all previous callbacks registered
433− on the CPU that synchronize_rcu() is running on, but it is -not-
433+17. If you register a callback using call_rcu() or call_srcu(), and
434+ pass in a function defined within a loadable module, then it in
435+ necessary to wait for all pending callbacks to be invoked after
436+ the last invocation and before unloading that module. Note that
437+ it is absolutely -not- sufficient to wait for a grace period!
438+ The current (say) synchronize_rcu() implementation is -not-
434439 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.
435442
436443 You instead need to use one of the barrier functions:
437444

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