Where Debugfs Fits in the Kernel Stack

Debugfs is a small, purpose-built virtual filesystem, conceptually similar to procfs and sysfs but without their ABI-stability rules. A driver registers a directory and a set of files against it; the VFS layer takes care of routing user-space open(), read(), and write() calls into the callbacks your driver supplied. Because there’s no schema to validate and no compatibility promise to keep, kernel maintainers treat debugfs as free real estate for internal state — which is exactly why so many subsystems lean on it.

Patterns Borrowed From Real Subsystems

Rather than reproducing any single driver’s source, it’s more useful to study the recurring patterns that show up across the tree, because these are the design choices you’ll want to copy into your own driver.

1. Storage drivers: exposing live device state

Block and storage subsystems commonly expose a per-device debugfs directory containing small, read-only status files — things like current power state, error counters, or negotiated bus parameters. The pattern is always the same: one top-level directory per physical device instance, so multiple cards or controllers don’t collide.

2. Wireless drivers: per-interface diagnostics

Wireless networking drivers tend to go further, using debugfs heavily for firmware statistics, per-station link quality, and channel information — often with dozens of files per network interface. Because wireless stacks juggle a lot of transient radio state, debugfs is a natural fit: nothing here needs to be ABI-stable, and developers frequently add or remove files between kernel releases without worrying about breaking user space.

3. Graphics drivers: pipeline and buffer introspection

GPU and display drivers commonly expose debugfs files to dump internal pipeline state, list currently allocated GPU buffer objects, or force specific test patterns — invaluable when bisecting a rendering regression without needing specialized hardware debug tools.

Building a Scalable Debugfs Tree of Your Own

Once your driver manages more than one device instance, a flat debugfs layout breaks down quickly. The fix, borrowed directly from the patterns above, is to create one subdirectory per instance, named after something unique like the device’s bus address:

#include <linux/debugfs.h>
#include <linux/device.h>

struct ep_dev_ctx {
    struct dentry *dbg_dir;
    u32 error_count;
    u32 link_speed;
};

static int ep_dev_debugfs_setup(struct ep_dev_ctx *ctx, const char *devname)
{
    ctx->dbg_dir = debugfs_create_dir(devname, NULL);
    if (IS_ERR(ctx->dbg_dir))
        return PTR_ERR(ctx->dbg_dir);

    debugfs_create_u32("error_count", 0444, ctx->dbg_dir, &ctx->error_count);
    debugfs_create_u32("link_speed", 0444, ctx->dbg_dir, &ctx->link_speed);
    return 0;
}

static void ep_dev_debugfs_teardown(struct ep_dev_ctx *ctx)
{
    debugfs_remove_recursive(ctx->dbg_dir);
    ctx->dbg_dir = NULL;
}

Notice the file permissions: 0444 makes these read-only counters, which is the right default for anything that only reports state. Reserve read-write (0644) files for genuine control knobs, such as toggling a debug trace level.

Read-Only vs. Read-Write Debugfs Files

File Type	Typical Use	Recommended Mode
Status / counters	Reporting live hardware or driver state	0444 (read-only)
Trace / log level	Toggling verbosity at runtime	0644 (read-write)
Fault injection	Forcing an error path for testing	0200 (write-only), root-restricted

When Debugfs Is the Wrong Tool

Not every real-world driver uses debugfs for everything, and knowing the boundary matters as much as knowing the API. Anything that user-space tooling depends on for correct operation belongs in sysfs (which does carry ABI stability rules) or a dedicated ioctl/netlink interface — never debugfs. A good litmus test: if removing the file tomorrow would break someone’s script, it should never have been in debugfs in the first place.

Best Practices Checklist

• One top-level debugfs directory per driver, one subdirectory per device instance.
• Default to read-only (0444) for anything that only reports state.
• Never expose raw pointers, keys, or security-sensitive buffers through a debugfs file.
• Always pair every debugfs_create_dir() with a corresponding debugfs_remove_recursive() in the teardown path.
• Keep debugfs optional in your driver — check for IS_ERR() but don’t fail probe() just because debugfs is unavailable.

Key Takeaways

• Debugfs is heavily used across storage, wireless, and graphics subsystems in mainline Linux.
• A per-instance subdirectory layout keeps multi-device drivers organized and collision-free.
• File permissions should reflect intent: read-only for status, read-write only for real controls.
• Debugfs must never carry functionality user space depends on — that’s what sysfs and formal APIs are for.

Conclusion

Studying how production drivers structure their debugfs trees turns an abstract API into a set of concrete, reusable habits: one directory per device, sensible permissions, and a teardown path that mirrors setup exactly. Apply these patterns and your own driver’s debug interface will scale cleanly as you add more devices and more diagnostics. That wraps up this lesson in our free Linux kernel programming course — see you in the next one.

FAQ