Update lockdep doc and add section about annotations
Subsystems (2)
cover Update lockdep doc and add section about annotations
Hi,
a couple of patches to lockdep docs.
First one is a small fix for that fact that Peter made documentation stale (as usual :P).
Second one is an RFC. I thought that adding some info about lockdep asserts might help spread adoption even wider (mostly regarding lockdep_pin_lock stuff, which is pretty new and maybe got unnoticed outside of the scheduler?).
Best,
- Juri
Juri Lelli (2):
Documentation/locking/lockdep: update info about states Documentation/locking/lockdep: Add section about available annotations
Documentation/locking/lockdep-design.txt | 51 ++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-)
Signature · 1 line
2.14.3
PATCH 1/2 Documentation/locking/lockdep: update info about states
Commit d92a8cfcb37e ("locking/lockdep: Rework FS_RECLAIM annotation") removed reclaim_fs lockdep STATE.
Reflect the change in documentation.
While we are at it, also clarify formula to calculate number of state bits.
--- Documentation/locking/lockdep-design.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/locking/lockdep-design.txt +2 -2
@@ -27,7 +27,8 @@ lock-class. State ----- -The validator tracks lock-class usage history into 4n + 1 separate state bits: +The validator tracks lock-class usage history into 4 * nSTATEs + 1 separate +state bits: - 'ever held in STATE context' - 'ever held as readlock in STATE context'
@@ -37,7 +38,6 @@ The validator tracks lock-class usage history into 4n + 1 separate state bits: Where STATE can be either one of (kernel/locking/lockdep_states.h) - hardirq - softirq - - reclaim_fs - 'ever used' [ == !unused ]
Signature · 1 line
2.14.3
tip-bot for Juri Lelli
merge bot[tip:locking/core] Documentation/locking/lockdep: Update info about states
Documentation/locking/lockdep: Update info about states
Commit-ID: e5684bbfc3f03480d6ba2150f133630fb510d3eb Gitweb: https://git.kernel.org/tip/e5684bbfc3f03480d6ba2150f133630fb510d3eb Author: Juri Lelli <[email protected]> AuthorDate: Tue, 13 Feb 2018 19:55:18 +0100 Committer: Ingo Molnar <[email protected]> CommitDate: Wed, 14 Feb 2018 12:01:22 +0100
Documentation/locking/lockdep: Update info about states
Commit:
d92a8cfcb37e ("locking/lockdep: Rework FS_RECLAIM annotation")
removed the 'reclaim_fs' lockdep STATE.
Reflect the change in the documentation.
While we are at it, also clarify the formula to calculate the number of state bits.
--- Documentation/locking/lockdep-design.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/locking/lockdep-design.txt +2 -2
@@ -27,7 +27,8 @@ lock-class. State ----- -The validator tracks lock-class usage history into 4n + 1 separate state bits: +The validator tracks lock-class usage history into 4 * nSTATEs + 1 separate +state bits: - 'ever held in STATE context' - 'ever held as readlock in STATE context'
@@ -37,7 +38,6 @@ The validator tracks lock-class usage history into 4n + 1 separate state bits: Where STATE can be either one of (kernel/locking/lockdep_states.h) - hardirq - softirq - - reclaim_fs - 'ever used' [ == !unused ]
RFC PATCH 2/2 Documentation/locking/lockdep: Add section about available annotations
In reply to Juri LelliAdd section about annotations that can be used to perform additional runtime checking of locking correctness: assert that certain locks are held and prevent accidental unlocking.
--- Documentation/locking/lockdep-design.txt | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)
Documentation/locking/lockdep-design.txt +47 -0
@@ -169,6 +169,53 @@ Note: When changing code to use the _nested() primitives, be careful and check really thoroughly that the hierarchy is correctly mapped; otherwise you can get false positives or false negatives. +Annotations +----------- + +Two constructs can be used to annotate and check where and if certain locks +must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock). + +As the name suggests, lockdep_assert_held* family of macros assert that a +particular lock is held at a certain time (and generate a WARN otherwise). +This annotation is largely used all over the kernel, e.g. kernel/sched/ +core.c + + void update_rq_clock(struct rq *rq) + { + s64 delta; + + lockdep_assert_held(&rq->lock); + [...] + } + +where holding rq->lock is required to safely update a rq's clock. + +The other family of macros is lockdep_*pin_lock, which is admittedly only +used for rq->lock ATM. Despite their limited adoption these annotations +generate a WARN if the lock of interest is "accidentally" unlocked. This turns +out to be especially helpful to debug code with callbacks, where an upper +layer assumes a lock remains taken, but a lower layer thinks it can maybe drop +and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock +returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock to check +that nobody tampered with the lock, e.g. kernel/sched/sched.h + + static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) + { + rf->cookie = lockdep_pin_lock(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->lock, rf->cookie); + } + +While comments about locking requirements might provide useful information, +the runtime checks performed by annotations are invaluable when debugging +locking problems and they carry the same level of details when inspecting +code. Always prefer annotations when in doubt! + Proof of 100% correctness: --------------------------
Signature · 1 line
2.14.3
tip-bot for Juri Lelli
merge bot[tip:locking/core] Documentation/locking/lockdep: Add section about available annotations
Documentation/locking/lockdep: Add section about available annotations
Commit-ID: a1ea544fe0911492b9f8d101bcbf46cc8c47fbc5 Gitweb: https://git.kernel.org/tip/a1ea544fe0911492b9f8d101bcbf46cc8c47fbc5 Author: Juri Lelli <[email protected]> AuthorDate: Tue, 13 Feb 2018 19:55:19 +0100 Committer: Ingo Molnar <[email protected]> CommitDate: Wed, 14 Feb 2018 12:01:22 +0100
Documentation/locking/lockdep: Add section about available annotations
Add section about annotations that can be used to perform additional runtime checking of locking correctness: assert that certain locks are held and prevent accidental unlocking.
--- Documentation/locking/lockdep-design.txt | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)
Documentation/locking/lockdep-design.txt +47 -0
@@ -169,6 +169,53 @@ Note: When changing code to use the _nested() primitives, be careful and check really thoroughly that the hierarchy is correctly mapped; otherwise you can get false positives or false negatives. +Annotations +----------- + +Two constructs can be used to annotate and check where and if certain locks +must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock). + +As the name suggests, lockdep_assert_held* family of macros assert that a +particular lock is held at a certain time (and generate a WARN() otherwise). +This annotation is largely used all over the kernel, e.g. kernel/sched/ +core.c + + void update_rq_clock(struct rq *rq) + { + s64 delta; + + lockdep_assert_held(&rq->lock); + [...] + } + +where holding rq->lock is required to safely update a rq's clock. + +The other family of macros is lockdep_*pin_lock(), which is admittedly only +used for rq->lock ATM. Despite their limited adoption these annotations +generate a WARN() if the lock of interest is "accidentally" unlocked. This turns +out to be especially helpful to debug code with callbacks, where an upper +layer assumes a lock remains taken, but a lower layer thinks it can maybe drop +and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock() +returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check +that nobody tampered with the lock, e.g. kernel/sched/sched.h + + static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) + { + rf->cookie = lockdep_pin_lock(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->lock, rf->cookie); + } + +While comments about locking requirements might provide useful information, +the runtime checks performed by annotations are invaluable when debugging +locking problems and they carry the same level of details when inspecting +code. Always prefer annotations when in doubt! + Proof of 100% correctness: --------------------------
Quoted 11 lines · Juri Lelli
Hi,
a couple of patches to lockdep docs.
First one is a small fix for that fact that Peter made documentation stale (as usual :P).
Second one is an RFC. I thought that adding some info about lockdep asserts might help spread adoption even wider (mostly regarding
lockdep_pin_lockstuff, which is pretty new and maybe got unnoticed outside of the scheduler?).
Thanks for writing that Juri!