What You Will Learn

Prerequisites

What Is debugfs and Why Does It Exist?

debugfs is a special, lightweight, RAM-only virtual filesystem built into the Linux kernel with one goal: give kernel and driver developers a completely unrestricted way to export debug information to user space. Unlike procfs and sysfs, debugfs was never meant to be a stable, user-facing ABI. There are no rules about file formats, no “one value per file” convention, and no promise that entries will exist in every kernel build. That freedom is precisely what makes it so convenient during development and bring-up of new drivers.

On almost every modern distribution, debugfs is automatically mounted at boot. You can confirm this yourself:

$ mount | grep debugfs
debugfs on /sys/kernel/debug type debugfs (rw,relatime)

If it isn’t mounted, you (as root) can mount it manually:

$ sudo mount -t debugfs none /sys/kernel/debug

debugfs vs procfs vs sysfs: Which Should You Use?

Most beginners in a free Linux device drivers course get confused about when to use debugfs versus procfs or sysfs. Here’s a quick comparison table to clear that up:

Step 1: Create a debugfs Directory for Your Module

Every well-behaved debugfs user creates its own subdirectory so its debug files stay organized and don’t clutter the top level. This uses debugfs_create_dir(), which takes a name and an optional parent directory (pass NULL for the top level):

#include <linux/debugfs.h>

#define DRVNAME "ep_debugfs_demo"

static struct dentry *ep_dbgfs_root;

static int __init ep_debugfs_demo_init(void)
{
    ep_dbgfs_root = debugfs_create_dir(DRVNAME, NULL);
    if (IS_ERR(ep_dbgfs_root)) {
        pr_err("%s: failed to create debugfs directory\n", DRVNAME);
        return PTR_ERR(ep_dbgfs_root);
    }

    pr_info("%s: debugfs directory created at /sys/kernel/debug/%s\n",
            DRVNAME, DRVNAME);
    return 0;
}

Note: On very old kernels, several debugfs creation functions returned error pointers on failure. On current 6.x kernels, most of the “helper” creation APIs return void and simply fail silently if debugfs is disabled, so always check your kernel documentation for the exact return type you are compiling against.

Step 2: Expose a Read-Only Debug File with a Custom Callback

Suppose your driver keeps a small runtime context structure and you want to dump it whenever someone reads a debugfs file. First, define the callback and wire it into a file_operations structure:

struct ep_ctx {
    u32 events_seen;
    u32 error_count;
    u64 last_ts;
};

static struct ep_ctx *g_ctx;
static DEFINE_MUTEX(ep_ctx_lock);

static ssize_t ep_dbgfs_dump_read(struct file *filp, char __user *ubuf,
                                   size_t count, loff_t *fpos)
{
    struct ep_ctx *ctx = filp->f_inode->i_private;
    char buf[200];
    int len;

    mutex_lock(&ep_ctx_lock);
    ctx->last_ts = jiffies;
    len = scnprintf(buf, sizeof(buf),
                     "events_seen:%u\nerror_count:%u\nlast_ts:%llu\n",
                     ctx->events_seen, ctx->error_count, ctx->last_ts);
    mutex_unlock(&ep_ctx_lock);

    return simple_read_from_buffer(ubuf, count, fpos, buf, len);
}

static const struct file_operations ep_dbgfs_dump_fops = {
    .owner = THIS_MODULE,
    .read  = ep_dbgfs_dump_read,
};

Notice the pattern: your read callback pulls its private data straight out of filp->f_inode->i_private. This lets you register the same callback for multiple instances of a device, each carrying its own context pointer, instead of relying on a single global variable.

Now register the file inside your init function, passing the context pointer as the fourth argument — it is stored automatically into i_private for you:

    g_ctx = kzalloc(sizeof(*g_ctx), GFP_KERNEL);
    if (!g_ctx)
        return -ENOMEM;

    debugfs_create_file("dump_context", 0440, ep_dbgfs_root,
                         g_ctx, &ep_dbgfs_dump_fops);

The mode 0440 means read-only for the owner (root) and root’s group — a sensible default for information that shouldn’t be writable.

Step 3: Skip the Boilerplate with debugfs_create_u32()

Writing a full file_operations structure for every single integer knob gets tedious fast. debugfs provides ready-made helper functions — debugfs_create_u8(), debugfs_create_u16(), debugfs_create_u32(), debugfs_create_u64(), and debugfs_create_bool() — that bind a debugfs file directly to a kernel variable. No callback code required:

static u32 ep_debug_level; /* controllable from user space */

    debugfs_create_u32("debug_level", 0640, ep_dbgfs_root, &ep_debug_level);

With this single line, reading the file returns the current value of ep_debug_level, and writing an integer to it updates the variable inside the kernel — debugfs handles all the parsing and formatting internally.

Step 4: Clean Up on Module Removal

Always remove your debugfs entries in the module’s exit function. The safest approach is a single recursive removal of the root directory, which takes every child file with it:

static void __exit ep_debugfs_demo_exit(void)
{
    debugfs_remove_recursive(ep_dbgfs_root);
    kfree(g_ctx);
    pr_info("%s: debugfs entries removed, module unloaded\n", DRVNAME);
}

module_init(ep_debugfs_demo_init);
module_exit(ep_debugfs_demo_exit);
MODULE_LICENSE("GPL");

Forgetting this step leaves stale dentries behind, and on some kernels this can trigger warnings or crashes the next time the module is reloaded — so treat cleanup as mandatory, not optional.

Testing Your debugfs Interface

After loading the module with insmod, verify the files exist and behave as expected:

$ sudo ls -l /sys/kernel/debug/ep_debugfs_demo
-r--r----- 1 root root 0 dump_context
-rw-r----- 1 root root 0 debug_level

$ sudo cat /sys/kernel/debug/ep_debugfs_demo/dump_context
events_seen:0
error_count:0
last_ts:4301928123

$ sudo cat /sys/kernel/debug/ep_debugfs_demo/debug_level
0

$ echo 3 | sudo tee /sys/kernel/debug/ep_debugfs_demo/debug_level
3

If any file is missing, double-check that CONFIG_DEBUG_FS is enabled in your kernel configuration — debugfs support can be compiled out entirely on hardened or minimal kernel builds.

Common Mistakes and Troubleshooting Tips

Best Practices for Production-Safe Debug Code

Security Considerations

debugfs is deliberately restricted to root by default (/sys/kernel/debug is typically mode 0700), and that restriction exists for a reason: because debugfs has no format rules, it’s easy to accidentally leak sensitive kernel addresses, buffer contents, or hardware state to anyone who can read those files. On production and hardened systems, many distributions disable debugfs entirely or restrict it further with lockdown mode. When designing your debug interface, assume that anything you write to a debugfs file could eventually be read by someone debugging a live system, and avoid exposing raw pointers or security-sensitive values without good reason.

Real-World Use Cases

debugfs is used extensively throughout the mainline kernel itself. Wireless and Bluetooth drivers expose radio statistics and firmware state; GPU drivers dump memory allocation and scheduler queues; the CPU frequency governor exposes internal tuning knobs; and block I/O schedulers surface queue depth and latency histograms — all through debugfs, precisely because none of that information needs a stable, long-term ABI guarantee.

Summary and Key Takeaways

Conclusion

This Linux kernel debugfs tutorial walked you through building a complete, working debug interface from an empty kernel module: creating a directory, wiring a custom read callback, using the i_private trick to pass context, and taking the fast path with helper APIs for simple variables. debugfs remains one of the quickest tools in a kernel developer’s toolbox for inspecting driver state without the overhead of designing a formal sysfs attribute set. Practice building your own debugfs files on a test VM, and continue with the next lecture in this free Linux kernel programming course to explore procfs and sysfs interfaces in depth.

Frequently Asked Questions