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 | 11. Any lock acquired by an RCU callback must be acquired elsewhere | 319 | 11. 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 given | 321 | spin_lock_bh(), etc. Failing to disable softirq on a given |
| 322 | acquisition of that lock will result in deadlock as soon as | 322 | acquisition of that lock will result in deadlock as soon as |
| 323 | the RCU softirq handler happens to run your RCU callback while | 323 | 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 required | 331 | 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 executed | 334 | 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 offline | 336 | For example, if a given CPU goes offline while having an RCU |
| 337 | while having an RCU callback pending, then that RCU callback | 337 | 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 from | 339 | 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 | ||
| 342 | 13. Unlike other forms of RCU, it -is- permissible to block in an | 345 | 13. 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 on | 382 | 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 to | 385 | 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 | ||
| 385 | 14. The whole point of call_rcu(), synchronize_rcu(), and friends | 389 | 14. The whole point of call_rcu(), synchronize_rcu(), and friends |
| 386 | is to wait until all pre-existing readers have finished before | 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 | read-side critical sections. It is the responsibility of the | 404 | 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 | |||
| 403 | 16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the | 410 | 16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the |
| 404 | __rcu sparse checks to validate your RCU code. These can help | 411 | __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 are | 430 | These debugging aids can help you find problems that are |
| 424 | otherwise extremely difficult to spot. | 431 | otherwise extremely difficult to spot. |
| 425 | 432 | ||
| 426 | 17. If you register a callback using call_rcu() or call_srcu(), | 433 | 17. 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 to | 435 | necessary to wait for all pending callbacks to be invoked after |
| 429 | be invoked after the last invocation and before unloading | 436 | the last invocation and before unloading that module. Note that |
| 430 | that module. Note that it is absolutely -not- sufficient to | 437 | 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 | ||