Text of docs.kernel.org › locking › lockdep-design.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Runtime locking correctness validator — The Linux Kernel documentation

The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Locking Lock types and their rules Runtime locking correctness validator Lock-class State Single-lock state rules: Multi-lock dependency rules: Exception: Nested data dependencies leading to nested locking Annotations Proof of 100% correctness: Performance: Troubleshooting: Recursive read locks: Block conditions on readers/writers of the same lock instance: Dependency types and strong dependency paths: Recursive Read Deadlock Detection: References: Lock Statistics Kernel Lock Torture Test Operation Generic Mutex Subsystem RT-mutex implementation design RT-mutex subsystem with PI support Sequence counters and sequential locks Locking lessons Wound/Wait Deadlock-Proof Mutex Design Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe Lightweight PI-futexes Futex Requeue PI Hardware Spinlock Framework Percpu rw semaphores A description of what robust futexes are The robust futex ABI Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source English Italian Runtime locking correctness validator ¶ started by Ingo Molnar < mingo @ redhat . com > additions by Arjan van de Ven < arjan @ linux . intel . com > Lock-class ¶ The basic object the validator operates upon is a ‘class’ of locks.

A class of locks is a group of locks that are logically the same with respect to locking rules, even if the locks may have multiple (possibly tens of thousands of) instantiations. For example a lock in the inode struct is one class, while each inode has its own instantiation of that lock class. The validator tracks the ‘usage state’ of lock-classes, and it tracks the dependencies between different lock-classes. Lock usage indicates how a lock is used with regard to its IRQ contexts, while lock dependency can be understood as lock order, where L1 -> L2 suggests that a task is attempting to acquire L2 while holding L1.

From lockdep’s perspective, the two locks (L1 and L2) are not necessarily related; that dependency just means the order ever happened. The validator maintains a continuing effort to prove lock usages and dependencies are correct or the validator will shoot a splat if incorrect. A lock-class’s behavior is constructed by its instances collectively: when the first instance of a lock-class is used after bootup the class gets registered, then all (subsequent) instances will be mapped to the class and hence their usages and dependencies will contribute to those of the class.

A lock-class does not go away when a lock instance does, but it can be removed if the memory space of the lock class (static or dynamic) is reclaimed, this happens for example when a module is unloaded or a workqueue is destroyed. State ¶ The validator tracks lock-class usage history and divides the usage into (4 usages * n STATEs + 1) categories: where the 4 usages can be: ‘ever held in STATE context’ ‘ever held as readlock in STATE context’ ‘ever held with STATE enabled’ ‘ever held as readlock with STATE enabled’ where the n STATEs are coded in kernel/locking/lockdep_states.h and as of now they include: hardirq softirq where the last 1 category is: ‘ever used’ [ == !unused ] When locking rules are violated, these usage bits are presented in the locking error messages, inside curlies, with a total of 2 * n STATEs bits.

A contrived example: modprobe/2287 is trying to acquire lock: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24 but task is already holding lock: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24 For a given lock, the bit positions from left to right indicate the usage of the lock and readlock (if exists), for each of the n STATEs listed above respectively, and the character displayed at each bit position indicates: ‘.’ acquired while irqs disabled and not in irq context ‘-’ acquired in irq context ‘+’ acquired with irqs enabled ‘?’ acquired in irq context with irqs enabled.

The bits are illustrated with an example: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24 |||| ||| \-> softirq disabled and not in softirq context || \--> acquired in softirq context | \---> hardirq disabled and not in hardirq context \----> acquired in hardirq context For a given STATE, whether the lock is ever acquired in that STATE context and whether that STATE is enabled yields four possible cases as shown in the table below.

The bit character is able to indicate which exact case is for the lock as of the reporting time. irq enabled irq disabled ever in irq ‘?’ ‘-’ never in irq ‘+’ ‘.’ The character ‘-’ suggests irq is disabled because if otherwise the character ‘?’ would have been shown instead. Similar deduction can be applied for ‘+’ too. Unused locks (e.g., mutexes) cannot be part of the cause of an error. Single-lock state rules: ¶ A lock is irq-safe means it was ever used in an irq context, while a lock is irq-unsafe means it was ever acquired with irq enabled.

A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The following states must be exclusive: only one of them is allowed to be set for any lock-class based on its usage: <hardirq-safe> or <hardirq-unsafe> <softirq-safe> or <softirq-unsafe> This is because if a lock can be used in irq context (irq-safe) then it cannot be ever acquired with irq enabled (irq-unsafe). Otherwise, a deadlock may happen. For example, in the scenario that after this lock was acquired but before released, if the context is interrupted this lock will be attempted to acquire twice, which creates a deadlock, referred to as lock recursion deadlock.

The validator detects and reports lock usage that violates these single-lock state rules. Multi-lock dependency rules: ¶ The same lock-class must not be acquired twice, because this could lead to lock recursion deadlocks. Furthermore, two locks can not be taken in inverse order: <L1> -> <L2> <L2> -> <L1> because this could lead to a deadlock - referred to as lock inversion deadlock - as attempts to acquire the two locks form a circle which could lead to the two contexts waiting for each other permanently.

The validator will find such dependency circle in arbitrary complexity, i.e., there can be any other locking sequence between the acquire-lock operations; the validator will still find whether these locks can be acquired in a circular fashion. Furthermore, the following usage based lock dependencies are not allowed between any two lock-classes: <hardirq-safe> -> <hardirq-unsafe> <softirq-safe> -> <softirq-unsafe> The first rule comes from the fact that a hardirq-safe lock could be taken by a hardirq context, interrupting a hardirq-unsafe lock - and thus could result in a lock inversion deadlock.

Likewise, a softirq-safe lock could be taken by an softirq context, interrupting a softirq-unsafe lock. The above rules are enforced for any locking sequence that occurs in the kernel: when acquiring a new lock, the validator checks whether there is any rule violation between the new lock and any of the held locks. When a lock-class changes its state, the following aspects of the above dependency rules are enforced: if a new hardirq-safe lock is discovered, we check whether it took any hardirq-unsafe lock in the past. if a new softirq-safe lock is discovered, we check whether it took any softirq-unsafe lock in the past. if a

The rest of this page is on the live site.