Handling Hardware Interrupts in Linux Device Drivers (Part 2): Handlers, Threaded IRQs & Bottom Halves

What You Will Learn

Prerequisites

Implementing the Interrupt Handler Routine

The heart of handling hardware interrupts in Linux device drivers is the handler function. This is the routine the kernel calls the moment your device’s interrupt fires. Its signature must match the type introduced in Part 1: it takes the interrupt number and your registered cookie, and returns an irqreturn_t.

static irqreturn_t my_handler(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;

    /* Is this interrupt really from our device? */
    if (!device_interrupt_pending(dev))
        return IRQ_NONE;   /* not ours, let others check */

    /* Acknowledge the interrupt at the device so it stops asserting */
    device_ack_interrupt(dev);

    /* Do the minimum urgent work here, then return */
    handle_device_event(dev);

    return IRQ_HANDLED;
}

Notice the structure: first confirm the interrupt is yours, then acknowledge it in hardware so the line quiets down, then do only the most urgent work. The functions device_interrupt_pending(), device_ack_interrupt(), and handle_device_event() above are placeholders for whatever your specific hardware requires.

The Golden Rules of Interrupt Context

A standard (non-threaded) handler runs in hardware interrupt context, also called atomic context. This context has hard restrictions. Breaking them can freeze or crash the system, so memorize them:

The Threaded Interrupt Model

Some devices sit on slow buses. Reading a register from an I2C or SPI peripheral can take milliseconds, which is far too long to do in atomic interrupt context. To solve this, the kernel provides threaded interrupts. Instead of doing all the work in atomic context, you split it into a small primary handler and a larger threaded handler that runs in ordinary process context, where sleeping is allowed.

You register a threaded interrupt with request_threaded_irq():

#include <linux/interrupt.h>

int request_threaded_irq(unsigned int irq,
                         irq_handler_t handler,      /* primary, hardirq context */
                         irq_handler_t thread_fn,    /* threaded, process context */
                         unsigned long flags,
                         const char *name,
                         void *dev);

The two handlers cooperate. The primary handler runs first in atomic context and does a quick check. If the interrupt belongs to your device, it silences the device and returns IRQ_WAKE_THREAD. The kernel then schedules a dedicated kernel thread (visible as irq/N-name) that runs thread_fn in process context, where it is safe to sleep.

Here is a minimal shape showing both halves working together:

static irqreturn_t my_primary(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;

    if (!device_interrupt_pending(dev))
        return IRQ_NONE;

    /* Silence the device so the line does not keep firing */
    device_mask_interrupt(dev);

    return IRQ_WAKE_THREAD;   /* let the thread do the slow work */
}

static irqreturn_t my_thread_fn(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;

    /* Safe to sleep here: bus reads, mutexes, etc. */
    read_sensor_over_i2c(dev);
    process_data(dev);

    /* Re-enable the device interrupt */
    device_unmask_interrupt(dev);

    return IRQ_HANDLED;
}

Registration then looks like this:

ret = request_threaded_irq(dev->irq,
                           my_primary,
                           my_thread_fn,
                           IRQF_ONESHOT | IRQF_TRIGGER_LOW,
                           "my-device",
                           dev);
if (ret)
    return ret;   /* handle the error */

Enabling and Disabling IRQs

Sometimes a driver needs to temporarily stop a specific interrupt from firing, for example while reconfiguring the device. The kernel provides simple helpers for a single IRQ line:

void disable_irq(unsigned int irq);        /* waits for any running handler to finish */
void disable_irq_nosync(unsigned int irq); /* returns immediately, does not wait */
void enable_irq(unsigned int irq);         /* re-enables the line */

Viewing Allocated Interrupt Lines via /proc

To see which interrupts are registered and how often they have fired, read the special file /proc/interrupts. This is one of the most useful debugging tools when handling hardware interrupts in Linux device drivers.

cat /proc/interrupts

Each row represents an interrupt line. The first column is the IRQ number, the following columns show the count of interrupts handled per CPU, and the final columns identify the interrupt controller and the name you passed to request_irq(). Watching a count rise as you exercise your device confirms your handler is actually running. A count that never moves usually means the wrong number, the wrong trigger flag, or an interrupt that is not enabled in hardware.

Understanding Top Halves and Bottom Halves

Because an interrupt handler must be fast and must not sleep, the kernel splits interrupt work into two conceptual pieces. The top half is the part that runs immediately in interrupt context: it acknowledges the hardware and does the minimum urgent work. The bottom half is the part that runs later, at a more convenient time, to finish the heavier processing.

Linux offers several mechanisms to implement a bottom half. Choosing the right one depends on whether the deferred work needs to sleep and how urgent it is.

Performance Considerations

• Keep the top half minimal; every microsecond spent there adds latency to the whole system.
• Prefer threaded handlers or workqueues for slow work so you do not hold off other interrupts.
• Batch processing where possible; for network receive, NAPI polling reduces per-packet interrupt overhead.
• Watch /proc/interrupts to spot lines firing far more often than expected.

Best Practices

• Confirm the interrupt is yours before touching shared state; return IRQ_NONE when it is not.
• Acknowledge the device early so the line stops asserting.
• Use IRQF_ONESHOT for level-triggered threaded interrupts to prevent storms.
• Balance every disable_irq() with an enable_irq().
• Protect data shared between the handler and the rest of the driver with the correct locks (spinlocks in atomic context).
• Always release the line with free_irq() during cleanup.

Common Mistakes and Troubleshooting

Key Takeaways

Conclusion

You have now completed the practical side of handling hardware interrupts in Linux device drivers. You can write a correct handler, respect the strict rules of interrupt context, split slow work into a threaded handler with request_threaded_irq(), manage individual IRQ lines, read /proc/interrupts for debugging, and choose the right bottom-half mechanism. Together with Part 1, this gives you a complete, modern foundation for interrupt-driven driver development. Keep practicing on real hardware or a virtual machine, and continue with the EmbeddedPathashala free Linux kernel development course and free embedded systems course to build on these skills.

Frequently Asked Questions (FAQ)