Prerequisites

What Is Atomic Context?

When your interrupt handler runs, it executes in what the kernel calls atomic context (sometimes called interrupt context). In this mode, the kernel cannot call the scheduler, meaning your code cannot be put to sleep and cannot be preempted by another process the normal way. This is fundamentally different from the process context that a regular system call handler or your driver’s probe() function runs in.

Rule 1: Never Block or Sleep

Because the scheduler cannot run while a hard-IRQ handler is executing, any function that could put the current context to sleep is forbidden. This includes:

Rule 2: Interrupts Are Masked While You Run

By default, while your handler executes, the specific interrupt line is masked on all CPUs, and on the CPU actually running your handler, local interrupts are typically disabled too. This has two effects: your handler is naturally protected from being re-entered by the same interrupt, but it also means the longer you take, the longer other interrupts on that core may be delayed.

Rule 3: Keep It Fast — Measure, Don’t Guess

Two metrics matter for interrupt handler quality: how long your handler runs (interrupt latency it introduces for others) and how long interrupts stay disabled system-wide. On modern kernels you can inspect this with tracer tools such as ftrace‘s irqsoff tracer, which records the worst-case interrupt-disabled duration observed on the system.

# Enable the irqsoff latency tracer (requires CONFIG_IRQSOFF_TRACER)
echo irqsoff > /sys/kernel/tracing/current_tracer
echo 1 > /sys/kernel/tracing/tracing_on
sleep 5
cat /sys/kernel/tracing/trace > /tmp/irq_latency.txt

A Simple, Original Example: Wrong vs Right

The following original example shows a handler that violates the atomic-context rules, followed by a corrected version using a threaded IRQ and a workqueue-friendly pattern.

/* WRONG: allocates with GFP_KERNEL and sleeps inside a hard IRQ handler */
static irqreturn_t bad_isr(int irq, void *dev_id)
{
    void *buf = kmalloc(256, GFP_KERNEL);   /* may sleep -- BUG */
    mutex_lock(&some_driver_mutex);         /* may sleep -- BUG */
    /* ... */
    mutex_unlock(&some_driver_mutex);
    kfree(buf);
    return IRQ_HANDLED;
}

/* RIGHT: hard IRQ just wakes a thread; heavy work happens safely later */
static irqreturn_t good_hard_isr(int irq, void *dev_id)
{
    return IRQ_WAKE_THREAD;
}

static irqreturn_t good_thread_fn(int irq, void *dev_id)
{
    struct mydev *priv = dev_id;
    void *buf = kmalloc(256, GFP_KERNEL);   /* safe here: process context */

    mutex_lock(&priv->lock);                /* safe here: process context */
    /* ... do the real work ... */
    mutex_unlock(&priv->lock);

    kfree(buf);
    return IRQ_HANDLED;
}

Top Half vs Bottom Half: Where Does the Real Work Go?

Because a hard-IRQ handler (“top half”) must be minimal, the kernel offers several mechanisms to defer the rest of the work (“bottom half”) to a safer context.

Note: On current kernels, the recommended default for most device drivers is a threaded IRQ rather than a tasklet, because tasklets are being deprecated in favor of the threaded-IRQ and workqueue model, which is simpler to reason about and avoids atomic-context restrictions entirely.

Common Mistakes

Best Practices

Performance Considerations

On multi-core embedded SoCs, IRQ affinity (which CPU core handles a given interrupt) can be tuned via /proc/irq/<n>/smp_affinity to keep latency-sensitive interrupts off a core that is busy with other real-time work.

Security Considerations

An interrupt handler that takes unpredictably long — for example due to an unbounded loop reading from a misbehaving or malicious peripheral — can be used as a denial-of-service vector against the whole system. Always bound loops and timeouts inside a handler.

Summary / Key Takeaways

Frequently Asked Questions