← Previous Lecture  |  Next Lecture →

What You Will Learn

• What lockdep actually tracks at runtime, in plain language
• How lockdep predicts a deadlock without one ever occurring
• The idea of a “lock class” and why it matters more than the individual lock instance
• An original driver demonstrating an AB-BA lock ordering bug caught by lockdep
• How to read a lockdep warning in dmesg

Prerequisites

• A kernel 6.x source tree built with CONFIG_PROVE_LOCKING enabled (covered in the previous lecture on linux kernel lock debugging)
• Comfortable with mutexes and the general idea of a deadlock

The Problem Lockdep Solves

A classic deadlock needs two locks taken in opposite order by two different code paths. Thread A takes lock 1 then waits for lock 2. Thread B takes lock 2 then waits for lock 1. Neither can proceed. The frustrating part of this bug is that it might work perfectly for months — it only shows up when both code paths happen to interleave at exactly the wrong moment. Traditional testing can run for years without ever hitting that exact timing window, right up until it does, in production, at 3 a.m.

Lockdep’s entire purpose is to remove timing from the equation. Instead of waiting for the unlucky interleaving to actually occur, it watches every lock acquisition your kernel performs and builds a permanent record of which locks get taken while which other locks are already held. The moment that recorded history contains a cycle, lockdep reports a potential deadlock immediately — even if the two threads never happened to race against each other yet.

Lock Classes, Not Lock Instances

The key idea that makes lockdep practical is the lock class. If you have a driver that creates a hundred instances of the same struct, each with its own mutex, lockdep does not track each of those hundred mutexes separately — it groups them by the source-code location where they were initialized. All hundred mutexes belong to one lock class, because they represent “the same kind of lock” from the code’s point of view. This is what makes it feasible for lockdep to reason about ordering across the entire kernel without drowning in per-instance noise.

Thread A: lock(ClassX) --> lock(ClassY)
   lockdep records edge: ClassX -> ClassY

Thread B: lock(ClassY) --> lock(ClassX)
   lockdep records edge: ClassY -> ClassX

Graph now contains a cycle:
   ClassX -> ClassY -> ClassX

Result: lockdep reports a POSSIBLE DEADLOCK
        the instant Thread B's edge is recorded,
        even if A and B never actually raced.

An Original Demo: Triggering an AB-BA Ordering Bug

The following module is an original example (not derived from any book) with two mutexes and two code paths that intentionally take them in opposite order. On a kernel with CONFIG_PROVE_LOCKING enabled, simply loading this module and exercising both paths once each is enough for lockdep to flag the dangerous ordering — no actual deadlock has to occur.

#include <linux/module.h>
#include <linux/mutex.h>
#include <linux/init.h>
#include <linux/miscdevice.h>
#include <linux/fs.h>

static DEFINE_MUTEX(ep_lock_x);
static DEFINE_MUTEX(ep_lock_y);

/* Path 1: correct order everywhere else in this demo, X then Y */
static void ep_path_normal(void)
{
    mutex_lock(&ep_lock_x);
    mutex_lock(&ep_lock_y);

    pr_info("ep_lockdep_demo: normal path holds X then Y\n");

    mutex_unlock(&ep_lock_y);
    mutex_unlock(&ep_lock_x);
}

/* Path 2: deliberately reversed order, Y then X -- the AB-BA bug */
static void ep_path_reversed(void)
{
    mutex_lock(&ep_lock_y);
    mutex_lock(&ep_lock_x);

    pr_info("ep_lockdep_demo: reversed path holds Y then X\n");

    mutex_unlock(&ep_lock_x);
    mutex_unlock(&ep_lock_y);
}

static int ep_demo_open(struct inode *inode, struct file *file)
{
    ep_path_normal();
    ep_path_reversed();
    return 0;
}

static const struct file_operations ep_demo_fops = {
    .owner = THIS_MODULE,
    .open  = ep_demo_open,
};

static struct miscdevice ep_demo_dev = {
    .minor = MISC_DYNAMIC_MINOR,
    .name  = "ep_lockdep_demo",
    .fops  = &ep_demo_fops,
};

static int __init ep_lockdep_demo_init(void)
{
    return misc_register(&ep_demo_dev);
}

static void __exit ep_lockdep_demo_exit(void)
{
    misc_deregister(&ep_demo_dev);
}

module_init(ep_lockdep_demo_init);
module_exit(ep_lockdep_demo_exit);
MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("EmbeddedPathashala original lockdep AB-BA ordering demo");

Load the module and read from /dev/ep_lockdep_demo once, for example with cat /dev/ep_lockdep_demo. Check dmesg immediately afterward. On a lockdep-enabled kernel you will see a clear “possible circular locking dependency detected” report identifying both call sites, both lock classes, and the exact ordering conflict — all from a single process running both paths back to back, with no second thread and no timing luck required at all.

Reading a Lockdep Warning

Lockdep vs Lock Debugging Options: How They Relate

It’s worth being precise about the division of labor here, since the previous lecture covered several related options together.

These are complementary, not competing — a serious debug kernel configuration enables all of them together.

Performance Considerations

Lockdep adds overhead on every single lock acquisition and release in the kernel, since it has to consult and update its dependency graph. This overhead is proportional to how lock-heavy your workload is, and it is one of the reasons lockdep-enabled kernels are strictly a development and CI tool rather than something you’d run in a latency-sensitive production system.

Security Considerations

Lockdep reports include kernel stack traces and internal addressing information, which is appropriate for a development machine but not something you want exposed on a production or externally-facing system. Keep lockdep-enabled builds inside your development and test environments.

Common Mistakes

• Dismissing a “possible” deadlock report because nothing actually froze. Lockdep reports the possibility based on recorded ordering, which is the entire point — it’s warning you before the unlucky timing occurs, not after.
• Fixing the symptom instead of the ordering. The correct fix for an AB-BA report is almost always to establish and document a strict, consistent lock-acquisition order everywhere in the driver.
• Assuming lockdep needs two threads to trigger. As the demo above shows, a single thread executing two mismatched code paths back-to-back is enough, because lockdep tracks history, not live contention.

Best Practices

• Pick one global lock-acquisition order per subsystem and document it directly above the lock declarations.
• Run your full driver test suite at least once with lockdep enabled before every merge.
• Treat any lockdep circular-dependency warning as a required fix, not a warning to silence.

Summary / Key Takeaways

• Lockdep predicts deadlocks by recording lock-acquisition ordering, not by waiting for one to actually happen.
• It groups locks into lock classes by their source-code initialization site, keeping the dependency graph practical at kernel scale.
• A single thread exercising two conflicting orderings is enough to trigger a lockdep warning.
• Lockdep is complementary to per-lock debugging options like CONFIG_DEBUG_MUTEXES, not a replacement for them.

Conclusion

Lockdep turns one of the hardest classes of kernel bugs — timing-dependent deadlocks — into something you can catch reliably and immediately during ordinary development testing. Once you understand that it works by tracking lock-class ordering history rather than watching for an actual deadlock to occur, its warnings stop feeling mysterious and start feeling like exactly what they are: an early, precise bug report handed to you before your users ever see a hang. That wraps up this pair of lectures on kernel lock debugging tooling in our free Linux kernel development course.

FAQ

Q1. Does lockdep require two real threads racing to trigger a warning?
No. It only needs both lock orderings to have been recorded at least once, even from a single thread executing two different code paths.

Q2. What is a lock class in lockdep terms?
A group of lock instances that share the same initialization source-code location — lockdep reasons about ordering per class, not per individual lock instance.

Q3. Can lockdep have false positives?
Rarely, and mostly in cases where nested locks of the same class are genuinely safe by design; the kernel provides nested-locking annotations for these specific cases.

Q4. Is lockdep only useful for mutexes?
No — it also tracks spinlocks, rwlocks, and other kernel locking primitives.

Q5. Should lockdep be enabled in a CI pipeline?
Yes, this is one of the most effective ways to catch lock-ordering regressions automatically before merge.

Q6. What should I do when lockdep reports a circular dependency?
Establish one consistent, documented lock-acquisition order across all code paths that touch both locks, and fix whichever path violates it.

← Previous Lecture  |  Next Lecture →