From e5684bbfc3f03480d6ba2150f133630fb510d3eb Mon Sep 17 00:00:00 2001 From: Juri Lelli Date: Tue, 13 Feb 2018 19:55:18 +0100 Subject: 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. Signed-off-by: Juri Lelli Acked-by: Peter Zijlstra (Intel) Cc: Jonathan Corbet Cc: Linus Torvalds Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: linux-doc@vger.kernel.org Link: http://lkml.kernel.org/r/20180213185519.18186-2-juri.lelli@redhat.com Signed-off-by: Ingo Molnar --- Documentation/locking/lockdep-design.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt index 9de1c158d44c..e341c2f34e68 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.txt @@ -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 ] -- cgit v1.2.3 From a1ea544fe0911492b9f8d101bcbf46cc8c47fbc5 Mon Sep 17 00:00:00 2001 From: Juri Lelli Date: Tue, 13 Feb 2018 19:55:19 +0100 Subject: 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. Signed-off-by: Juri Lelli Acked-by: Peter Zijlstra (Intel) Cc: Jonathan Corbet Cc: Linus Torvalds Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: linux-doc@vger.kernel.org Link: http://lkml.kernel.org/r/20180213185519.18186-3-juri.lelli@redhat.com Signed-off-by: Ingo Molnar --- Documentation/locking/lockdep-design.txt | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) (limited to 'Documentation') diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt index e341c2f34e68..49f58a07ee7b 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.txt @@ -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: -------------------------- -- cgit v1.2.3 From 621df431b0ac931e318679f54047c47eb23cfdd2 Mon Sep 17 00:00:00 2001 From: Andrea Parri Date: Tue, 20 Feb 2018 15:25:07 -0800 Subject: Documentation/memory-barriers.txt: Cross-reference "tools/memory-model/" A memory consistency model is now available for the Linux kernel [1], which "can (roughly speaking) be thought of as an automated version of memory-barriers.txt" and which is (in turn) "accompanied by extensive documentation on its use and its design". Inform the (occasional) reader of memory-barriers.txt of these developments. [1] https://marc.info/?l=linux-kernel&m=151687290114799&w=2 Co-developed-by: Andrea Parri Co-developed-by: Akira Yokosawa Signed-off-by: Andrea Parri Signed-off-by: Akira Yokosawa Signed-off-by: Paul E. McKenney Acked-by: Peter Zijlstra Cc: Linus Torvalds Cc: Thomas Gleixner Cc: boqun.feng@gmail.com Cc: dhowells@redhat.com Cc: j.alglave@ucl.ac.uk Cc: linux-arch@vger.kernel.org Cc: luc.maranget@inria.fr Cc: nborisov@suse.com Cc: npiggin@gmail.com Cc: stern@rowland.harvard.edu Cc: will.deacon@arm.com Link: http://lkml.kernel.org/r/1519169112-20593-7-git-send-email-paulmck@linux.vnet.ibm.com Signed-off-by: Ingo Molnar --- Documentation/memory-barriers.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index a863009849a3..a37d3aff3e73 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -14,7 +14,11 @@ DISCLAIMER This document is not a specification; it is intentionally (for the sake of brevity) and unintentionally (due to being human) incomplete. This document is meant as a guide to using the various memory barriers provided by Linux, but -in case of any doubt (and there are many) please ask. +in case of any doubt (and there are many) please ask. Some doubts may be +resolved by referring to the formal memory consistency model and related +documentation at tools/memory-model/. Nevertheless, even this memory +model should be viewed as the collective opinion of its maintainers rather +than as an infallible oracle. To repeat, this document is not a specification of what Linux expects from hardware. -- cgit v1.2.3 From 51de78892b1294d1521c41226a5ef215a910c25f Mon Sep 17 00:00:00 2001 From: Nikolay Borisov Date: Tue, 20 Feb 2018 15:25:08 -0800 Subject: memory-barriers: Fix description of data dependency barriers In the description of data dependency barriers the words 'before' is used erroneously. Since such barrier order dependent loads one after the other. So substitute 'before' with 'after'. Signed-off-by: Nikolay Borisov Signed-off-by: Paul E. McKenney Acked-by: Peter Zijlstra Cc: Linus Torvalds Cc: Thomas Gleixner Cc: akiyks@gmail.com Cc: boqun.feng@gmail.com Cc: dhowells@redhat.com Cc: j.alglave@ucl.ac.uk Cc: linux-arch@vger.kernel.org Cc: luc.maranget@inria.fr Cc: npiggin@gmail.com Cc: parri.andrea@gmail.com Cc: stern@rowland.harvard.edu Cc: will.deacon@arm.com Link: http://lkml.kernel.org/r/1519169112-20593-8-git-send-email-paulmck@linux.vnet.ibm.com Signed-off-by: Ingo Molnar --- Documentation/memory-barriers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index a37d3aff3e73..da6525bdc3f5 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -403,7 +403,7 @@ Memory barriers come in four basic varieties: where two loads are performed such that the second depends on the result of the first (eg: the first load retrieves the address to which the second load will be directed), a data dependency barrier would be required to - make sure that the target of the second load is updated before the address + make sure that the target of the second load is updated after the address obtained by the first load is accessed. A data dependency barrier is a partial ordering on interdependent loads -- cgit v1.2.3 From f28f0868feb1e79b460131bac37230e303a5f6a4 Mon Sep 17 00:00:00 2001 From: "Paul E. McKenney" Date: Wed, 7 Mar 2018 09:27:37 -0800 Subject: locking/memory-barriers: De-emphasize smp_read_barrier_depends() some more This commit makes further changes to memory-barrier.txt to further de-emphasize smp_read_barrier_depends(), but leaving some discussion for historical purposes. Signed-off-by: Paul E. McKenney Cc: Linus Torvalds Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: akiyks@gmail.com Cc: boqun.feng@gmail.com Cc: dhowells@redhat.com Cc: j.alglave@ucl.ac.uk Cc: linux-arch@vger.kernel.org Cc: luc.maranget@inria.fr Cc: npiggin@gmail.com Cc: parri.andrea@gmail.com Cc: stern@rowland.harvard.edu Cc: will.deacon@arm.com Link: http://lkml.kernel.org/r/1520443660-16858-1-git-send-email-paulmck@linux.vnet.ibm.com Signed-off-by: Ingo Molnar --- Documentation/memory-barriers.txt | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index da6525bdc3f5..6dafc8085acc 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -52,7 +52,7 @@ CONTENTS - Varieties of memory barrier. - What may not be assumed about memory barriers? - - Data dependency barriers. + - Data dependency barriers (historical). - Control dependencies. - SMP barrier pairing. - Examples of memory barrier sequences. @@ -554,8 +554,15 @@ There are certain things that the Linux kernel memory barriers do not guarantee: Documentation/DMA-API.txt -DATA DEPENDENCY BARRIERS ------------------------- +DATA DEPENDENCY BARRIERS (HISTORICAL) +------------------------------------- + +As of v4.15 of the Linux kernel, an smp_read_barrier_depends() was +added to READ_ONCE(), which means that about the only people who +need to pay attention to this section are those working on DEC Alpha +architecture-specific code and those working on READ_ONCE() itself. +For those who need it, and for those who are interested in the history, +here is the story of data-dependency barriers. The usage requirements of data dependency barriers are a little subtle, and it's not always obvious that they're needed. To illustrate, consider the @@ -2843,8 +2850,9 @@ as that committed on CPU 1. To intervene, we need to interpolate a data dependency barrier or a read -barrier between the loads. This will force the cache to commit its coherency -queue before processing any further requests: +barrier between the loads (which as of v4.15 is supplied unconditionally +by the READ_ONCE() macro). This will force the cache to commit its +coherency queue before processing any further requests: CPU 1 CPU 2 COMMENT =============== =============== ======================================= @@ -2873,8 +2881,8 @@ Other CPUs may also have split caches, but must coordinate between the various cachelets for normal memory accesses. The semantics of the Alpha removes the need for hardware coordination in the absence of memory barriers, which permitted Alpha to sport higher CPU clock rates back in the day. However, -please note that smp_read_barrier_depends() should not be used except in -Alpha arch-specific code and within the READ_ONCE() macro. +please note that (again, as of v4.15) smp_read_barrier_depends() should not +be used except in Alpha arch-specific code and within the READ_ONCE() macro. CACHE COHERENCY VS DMA @@ -3039,7 +3047,9 @@ the data dependency barrier really becomes necessary as this synchronises both caches with the memory coherence system, thus making it seem like pointer changes vs new data occur in the right order. -The Alpha defines the Linux kernel's memory barrier model. +The Alpha defines the Linux kernel's memory model, although as of v4.15 +the Linux kernel's addition of smp_read_barrier_depends() to READ_ONCE() +greatly reduced Alpha's impact on the memory model. See the subsection on "Cache Coherency" above. -- cgit v1.2.3