← Previous Lecture    Next Lecture →

What You Will Learn

Prerequisites

Why Do We Need Threaded Interrupt Handlers?

A hardware interrupt handler normally runs in what the kernel calls hard interrupt context. This context has strict rules: it must be fast, it cannot sleep, and it cannot take a mutex or perform any operation that might block, such as reading a register over I2C or SPI.

But many real devices — touchscreens, sensors, audio codecs — are connected over I2C or SPI. Reading their status registers takes time and may sleep while waiting for the bus. Doing that work directly inside a hard interrupt handler is not allowed, because it would stall the entire system.

The kernel’s answer to this problem is the threaded interrupt handler. It splits the work into two parts that run in two different contexts.

The Primary Handler: What Its Job Really Is

The first function you pass to request_threaded_irq() is the primary handler. It still runs in hard interrupt context, so the same restrictions apply: keep it fast, do not sleep. Its only three jobs are:

If you don’t need this quick check at all, you can pass NULL as the primary handler. The kernel then installs a default primary handler that simply wakes your thread every time the interrupt fires.

The Threaded Handler: Where the Real Work Happens

The threaded handler runs as a dedicated kernel thread, in normal process context. This is where it is safe to:

You can watch these threads on a running system:

$ ps -eLo pid,comm | grep "irq/"
  188 irq/27-mmc0
  191 irq/45-touchscreen

Understanding IRQF_ONESHOT

This is the flag beginners get wrong most often. Normally, once the primary handler finishes, the kernel re-enables the interrupt line right away — even before your threaded handler has run. For a level-triggered interrupt, that is dangerous: if the device is still asserting the line because it hasn’t been serviced yet, the interrupt fires again immediately, and again, and again. This is called an interrupt storm.

IRQF_ONESHOT tells the kernel: keep the interrupt line masked until the threaded handler has completely finished. Only then does the kernel unmask it. This guarantees exactly one clean handling cycle per event.

Because of this risk, the kernel enforces the flag: if you supply a threaded handler along with the default (NULL) primary handler, the kernel silently forces IRQF_ONESHOT on for you. If you supply your own primary handler and forget the flag on a level-triggered line, the request can fail outright.

A Simple Original Example: GPIO Button on a Modern Kernel

Below is a small, original threaded interrupt example written for current (6.x) kernels using the modern gpiod descriptor-based GPIO API. It is deliberately kept simple for a beginner-friendly course.

#include <linux/module.h>
#include <linux/interrupt.h>
#include <linux/gpio/consumer.h>
#include <linux/platform_device.h>

struct my_button_dev {
    struct gpio_desc *gpiod;
    int irq;
};

/* Primary handler: hardirq context, must be fast */
static irqreturn_t button_primary_handler(int irq, void *data)
{
    struct my_button_dev *btn = data;

    if (!btn)
        return IRQ_NONE;

    /* nothing to quiet on a simple GPIO line, just wake the thread */
    return IRQ_WAKE_THREAD;
}

/* Threaded handler: process context, may sleep */
static irqreturn_t button_thread_fn(int irq, void *data)
{
    struct my_button_dev *btn = data;
    int value = gpiod_get_value_cansleep(btn->gpiod);

    pr_info("my_button: press event, line value = %d\n", value);

    /* debounce-friendly delay is safe here because we are in process context */
    msleep(20);

    return IRQ_HANDLED;
}

static int my_button_probe(struct platform_device *pdev)
{
    struct my_button_dev *btn;
    int ret;

    btn = devm_kzalloc(&pdev->dev, sizeof(*btn), GFP_KERNEL);
    if (!btn)
        return -ENOMEM;

    btn->gpiod = devm_gpiod_get(&pdev->dev, "button", GPIOD_IN);
    if (IS_ERR(btn->gpiod))
        return PTR_ERR(btn->gpiod);

    btn->irq = gpiod_to_irq(btn->gpiod);
    if (btn->irq < 0)
        return btn->irq;

    ret = request_threaded_irq(btn->irq, button_primary_handler,
                                button_thread_fn,
                                IRQF_TRIGGER_FALLING | IRQF_ONESHOT,
                                "my_button", btn);
    if (ret) {
        dev_err(&pdev->dev, "failed to request threaded irq: %d\n", ret);
        return ret;
    }

    platform_set_drvdata(pdev, btn);
    return 0;
}

static void my_button_remove(struct platform_device *pdev)
{
    struct my_button_dev *btn = platform_get_drvdata(pdev);

    free_irq(btn->irq, btn);
}

static struct platform_driver my_button_driver = {
    .probe  = my_button_probe,
    .remove = my_button_remove,
    .driver = {
        .name = "my_button",
    },
};
module_platform_driver(my_button_driver);

MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("Simple threaded interrupt GPIO button example");

What’s happening: the primary handler runs instantly and just requests a wake-up. The real work — reading the GPIO value and applying a small debounce delay — happens safely in the threaded handler, in process context, where sleeping is allowed.

The threadirqs Kernel Boot Parameter

Linux also supports a kernel command-line option, threadirqs, which forces almost all interrupt handlers on the system to run threaded, except those explicitly marked with IRQF_NO_THREAD. This is mainly used for real-time (PREEMPT_RT) systems, where keeping hard interrupt context as short as possible is critical for predictable latency.

# Example: adding threadirqs via GRUB kernel command line
GRUB_CMDLINE_LINUX="threadirqs"

Common Mistakes and Troubleshooting

Best Practices

Key Takeaways

FAQ

← Previous Lecture    Next Lecture →