This commit fixes some issues with Documentation/RCU/checklist.txt.
Unified · Split
| @@ -318,7 +318,7 @@ over a rather long period of time, but improvements are always welcome! · 317 unmodified lines | ||
| 318 | 318 | |
| 319 | 319 | 11. Any lock acquired by an RCU callback must be acquired elsewhere |
| 320 | 320 | 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 | |
| 322 | 322 | acquisition of that lock will result in deadlock as soon as |
| 323 | 323 | the RCU softirq handler happens to run your RCU callback while |
| 324 | 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 | 331 | must use whatever locking or other synchronization is required |
| 332 | 332 | to safely access and/or modify that data structure. |
| 333 | 333 | |
| 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. | |
| 341 | 344 | |
| 342 | 345 | 13. Unlike other forms of RCU, it -is- permissible to block in an |
| 343 | 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 | 382 | never sends IPIs to other CPUs, so it is easier on |
| 380 | 383 | real-time workloads than is synchronize_rcu_expedited(). |
| 381 | 384 | |
| 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. | |
| 384 | 388 | |
| 385 | 389 | 14. The whole point of call_rcu(), synchronize_rcu(), and friends |
| 386 | 390 | 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 | 404 | read-side critical sections. It is the responsibility of the |
| 401 | 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 | + | |
| 403 | 410 | 16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the |
| 404 | 411 | __rcu sparse checks to validate your RCU code. These can help |
| 405 | 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 | 430 | These debugging aids can help you find problems that are |
| 424 | 431 | otherwise extremely difficult to spot. |
| 425 | 432 | |
| 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- | |
| 434 | 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 | 443 | You instead need to use one of the barrier functions: |
| 437 | 444 | |