Interrupt Handling: Top/Bottom Halves, softirqs, workqueues

An interrupt is an electrical signal on one of the CPU's dedicated interrupt pins (or a message-signaled interrupt for PCIe devices). When the signal is asserted, the CPU finishes its current instruction, atomically saves the program counter and CPU flags onto the kernel stack, masks the current interrupt line (on x86, clears IF in EFLAGS), and jumps to a fixed address in the Interrupt Descriptor Table (IDT). On ARM the vector table plays the same role; on RISC-V it is the mtvec/stvec register.

The key insight is that this all happens in hardware, before any software runs. The CPU has already switched to kernel mode, saved minimal state, and is about to execute your handler. This is fundamentally different from a system call (which is a deliberate software trap) or a fault (which is caused by a bad instruction). Interrupts are asynchronous — they can arrive at literally any point in the instruction stream.

Interrupt controllers (x86: APIC/IO-APIC; ARM: GIC; RISC-V: PLIC) sit between devices and the CPU. They arbitrate priority, route interrupts to specific CPUs in an SMP system, and provide the mechanism for masking individual lines. The kernel programs these controllers during boot via irq_chip operations (irq_mask, irq_unmask, irq_ack, irq_eoi).

Each hardware interrupt line maps to a Linux IRQ number (a virtual number, not the hardware pin number). The mapping lives in the IRQ domain subsystem. When you call request_irq(irq, handler, ...), you are registering a handler for a Linux IRQ number; the kernel handles the hardware-to-Linux mapping transparently.

/* On x86, the IDT entry for IRQ0 (timer) lives at vector 0x20.
 * After the CPU jumps to the stub, assembly saves registers and calls:
 */

/* arch/x86/kernel/irq.c (simplified) */
void common_interrupt(struct pt_regs *regs, u32 vector)
{
    /* 'regs' points to the full register save area pushed by asm stub */
    struct irq_desc *desc = __this_cpu_read(vector_irq[vector]);
    handle_irq(desc, regs);
}

The primary API for a driver to register an interrupt handler is request_irq(). It takes: the IRQ number (obtained from the platform or PCI subsystem), a handler function pointer, flags, a name for /proc/interrupts, and a dev_id cookie used to identify this specific handler when multiple drivers share the same IRQ line.

The flags are important:

• IRQF_SHARED: allows multiple drivers to share one IRQ line. The kernel calls each registered handler in turn until one returns IRQ_HANDLED.
• IRQF_TRIGGER_RISING / IRQF_TRIGGER_LEVEL: tell the interrupt controller whether this is edge-triggered or level-triggered.
• IRQF_TIMER: marks the handler as a timer interrupt (affects CPU affinity and /proc/interrupts display).

The handler's return value matters: IRQ_HANDLED means 'yes, this was my interrupt'; IRQ_NONE means 'not mine, keep searching'; IRQ_WAKE_THREAD is used with threaded IRQs (covered later).

To unregister, call free_irq(irq, dev_id). The dev_id must match exactly — this is how the kernel finds the right handler to remove when multiple drivers share the line. A classic driver bug is passing NULL as dev_id with IRQF_SHARED; the kernel rejects this for good reason.

The IRQ number for a PCI device comes from pci_irq_vector(pdev, 0) (for MSI/MSI-X) or from the device tree / ACPI table for platform devices.

#include <linux/interrupt.h>

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

    /* Read the device's status register to confirm it raised the IRQ */
    u32 status = readl(dev->base + STATUS_REG);
    if (!(status & IRQ_PENDING))
        return IRQ_NONE;  /* Not our interrupt */

    /* Acknowledge / clear the interrupt at the device level */
    writel(IRQ_CLEAR, dev->base + STATUS_REG);

    /* Top half: wake up bottom half, do nothing else */
    tasklet_schedule(&dev->bh_tasklet);

    return IRQ_HANDLED;
}

static int my_probe(struct platform_device *pdev)
{
    struct my_device *dev = /* ... alloc ... */;
    int irq = platform_get_irq(pdev, 0);
    int ret;

    ret = request_irq(irq, my_handler,
                      IRQF_SHARED, "my_device", dev);
    if (ret)
        return ret;
    dev->irq = irq;
    return 0;
}

static int my_remove(struct platform_device *pdev)
{
    struct my_device *dev = platform_get_drvdata(pdev);
    free_irq(dev->irq, dev);
    return 0;
}

The top half is the function you register with request_irq. It runs in hardirq context — with interrupts disabled on the current CPU (for non-nested IRQs), no access to sleeping primitives, and under extreme time pressure. Think of it as a surgeon during a code blue: you have thirty seconds to stabilize the patient, not perform a bypass.

The rules in hardirq context are strict and enforced (sometimes only at runtime by WARN_ON or lockdep):

1. Cannot sleep. msleep(), mutex_lock(), kmalloc(GFP_KERNEL) — all forbidden. Any sleep would deadlock the CPU.
2. Cannot hold a spinlock that is also held in process context without disabling IRQs there (use spin_lock_irqsave in process context).
3. Cannot call most blocking kernel APIs — no schedule(), no wait_event(), no copy_to_user().
4. Must be fast. The longer you run, the more interrupt latency you add to every other device on the system.

What should you do in the top half?

• Acknowledge the interrupt at the device (write to a status register to clear the interrupt line; if you skip this, the interrupt fires again immediately in an infinite loop — a classic hardware bug to watch for).
• Read the minimum state you need from hardware registers (they may be reset on the next interrupt).
• Store that state in a per-device buffer or flag.
• Kick a bottom half to do the real work.
• Return IRQ_HANDLED.

The in_hardirq() macro returns true when you are in this context. The kernel uses this internally, and you can use it in assertions.

/* The absolute minimum correct top half for a hypothetical UART */
static irqreturn_t uart_irq(int irq, void *dev_id)
{
    struct uart_port *port = dev_id;
    unsigned int iir = serial_in(port, UART_IIR);

    /* IIR bit 0 = 0 means interrupt pending from THIS device */
    if (iir & UART_IIR_NO_INT)
        return IRQ_NONE;

    /* Read the byte from hardware FIFO before it's overwritten */
    unsigned char ch = serial_in(port, UART_RX);

    /* Store in a circular buffer — this is O(1) and non-blocking */
    kfifo_put(&port->rx_fifo, ch);

    /* Wake the read() waiter — but via a tasklet, not directly */
    tasklet_schedule(&port->rx_tasklet);

    return IRQ_HANDLED;
    /* Total time: ~50ns. Perfect. */
}

The bottom half is the deferred work that the top half set up. The phrase comes from the original split in early Unix drivers: the first half of the driver code ran in interrupt context, the second half ran later with interrupts re-enabled. Linux has evolved three distinct bottom-half mechanisms, each with a different tradeoff between latency, flexibility, and complexity.

Here is the key gradient to understand:

The evolution tells a story: softirqs were first, fast but limited. Tasklets were added as a safe, serialized wrapper. Workqueues came later to handle the 'I need to sleep' case. Threaded IRQs are the modern answer: move the entire handler into a kernel thread, making the API simpler and RT-preemptible.

A mnemonic: softirq = fire-and-forget rocket (fastest, most dangerous), tasklet = tame missile (safe, still no sleep), workqueue = courier with a schedule (slower, can sleep), threaded IRQ = dedicated employee (clean, modern, RT-friendly).

softirqs are the lowest-level deferred work mechanism. There are exactly 10 softirq types compiled into the kernel, each with a fixed priority (index 0 is highest). They are not for driver use directly — they are kernel infrastructure.

HI_SOFTIRQ       (0) — high-priority tasklets
TIMER_SOFTIRQ    (1) — kernel timers
NET_TX_SOFTIRQ   (2) — network transmit
NET_RX_SOFTIRQ   (3) — network receive  ← most traffic goes here
BLOCK_SOFTIRQ    (4) — block layer completion
IRQ_POLL_SOFTIRQ (5) — IO polling
TASKLET_SOFTIRQ  (6) — tasklets
SCHED_SOFTIRQ    (7) — scheduler load balancing
HRTIMER_SOFTIRQ  (8) — high-res timers
RCU_SOFTIRQ      (9) — RCU callbacks

The key properties of softirqs:

• SMP-parallel: the same softirq can run simultaneously on multiple CPUs. This is why NET_RX is so fast — every CPU can process packets concurrently.
• Not serialized: if you use softirqs, you are responsible for your own per-CPU data or spinlocks.
• Cannot sleep: still in softirq context, no blocking.
• Reentrancy: a softirq can be preempted by a hardware interrupt, but not by another softirq of the same type on the same CPU.

When does softirq processing happen? After a hardirq handler returns, the kernel checks if any softirqs are pending and runs them in __do_softirq(). If too many softirqs are pending (the kernel limits burst size to 10 iterations or 2ms), the remainder are handed to ksoftirqd, a per-CPU kernel thread.

You can raise a softirq from a hardirq handler with raise_softirq(NET_RX_SOFTIRQ). The networking stack does exactly this: the NIC driver's top half raises NET_RX_SOFTIRQ, and the NAPI poll loop runs in NET_RX softirq context.

/* How the network RX path uses softirqs (simplified from net/core/dev.c) */

/* Called from hardirq context by the NIC driver */
void netif_rx(struct sk_buff *skb)
{
    /* Enqueue to per-CPU input queue */
    struct softnet_data *sd = this_cpu_ptr(&softnet_data);
    __skb_queue_tail(&sd->input_pkt_queue, skb);

    /* Raise the softirq — actual processing happens AFTER hardirq returns */
    __raise_softirq_irqoff(NET_RX_SOFTIRQ);
}

/* This runs in softirq context, after hardirq returns */
static void net_rx_action(struct softirq_action *h)
{
    /* Process up to budget packets from all NAPI-registered devices */
    struct list_head *list = this_cpu_ptr(&softnet_data.poll_list);
    int budget = netdev_budget;  /* default: 300 packets */

    while (!list_empty(list)) {
        struct napi_struct *n = list_entry(list->next, ...);
        int work = n->poll(n, budget);  /* driver's NAPI poll fn */
        budget -= work;
        if (budget <= 0) break;  /* hand rest to ksoftirqd */
    }
}

Tasklets are built on top of softirqs (they use TASKLET_SOFTIRQ and HI_SOFTIRQ) but add one crucial guarantee: a given tasklet instance will not run on two CPUs simultaneously. This makes them much easier to use than raw softirqs.

The API is simple:

1. Declare: DECLARE_TASKLET(name, function) or tasklet_init(&t, fn, data) at runtime.
2. Schedule from hardirq: tasklet_schedule(&t) — this sets a bit and raises TASKLET_SOFTIRQ.
3. The function runs in softirq context — still no sleeping.
4. To kill (e.g., in module unload): tasklet_kill(&t) waits for any running instance to finish.

Tasklets are serialized per instance: if you call tasklet_schedule() ten times before the tasklet runs, it runs exactly once. This is the 'pending' bit behavior — a second schedule while the tasklet is already scheduled is a no-op.

When to use tasklets vs workqueues? Tasklets are right when: your bottom half is short (microseconds), does not sleep, and per-CPU parallelism is not needed. They are wrong when: you need to sleep, allocate memory with GFP_KERNEL, call any blocking API, or do significant amounts of work (which would hurt scheduling latency).

Note on deprecation: as of Linux 5.x, tasklets are considered legacy. New drivers are encouraged to use threaded IRQs (or workqueues if they need explicit defer scheduling). But tasklets are everywhere in existing drivers and you will read them constantly.

#include <linux/interrupt.h>

struct my_device {
    struct tasklet_struct rx_tasklet;
    /* ... */
};

/* Bottom half: runs in softirq context, no sleeping */
static void my_rx_tasklet(struct tasklet_struct *t)
{
    struct my_device *dev = from_tasklet(dev, t, rx_tasklet);

    /* Process data that the top half stored in dev->rx_buf */
    while (!kfifo_is_empty(&dev->rx_fifo)) {
        u8 byte;
        kfifo_get(&dev->rx_fifo, &byte);
        /* push byte up to the line discipline / tty layer */
        tty_insert_flip_char(dev->port.state->port.tty, byte, TTY_NORMAL);
    }
    tty_flip_buffer_push(dev->port.state->port.tty);
    /* tty_flip_buffer_push may internally use a workqueue — that's fine,
     * we are not sleeping ourselves */
}

static int my_probe(struct platform_device *pdev)
{
    struct my_device *dev = devm_kzalloc(&pdev->dev, sizeof(*dev), GFP_KERNEL);
    tasklet_setup(&dev->rx_tasklet, my_rx_tasklet);
    /* ... register IRQ ... */
    return 0;
}

Workqueues are the most flexible bottom-half mechanism. A work item runs in a kernel thread (named kworker/N:M in ps output), so it has a process context: it can sleep, allocate memory with GFP_KERNEL, take mutexes, call blocking I/O APIs — essentially anything normal kernel code can do.

The workqueue API:

• Define a work item: DECLARE_WORK(work, fn) or INIT_WORK(&w, fn) at runtime.
• Schedule it: schedule_work(&w) (uses the system workqueue) or queue_work(wq, &w) for a private workqueue.
• Delayed variant: schedule_delayed_work(&dw, delay_jiffies).
• Flush (wait for completion): flush_work(&w) or flush_workqueue(wq).
• Cancel: cancel_work_sync(&w) — cancels and waits for any running instance.

The system workqueue (system_wq) is a shared, concurrency-managed workqueue. The kernel maintains enough threads to keep CPUs busy without excessive parallelism. For most drivers, schedule_work() is the right choice.

For latency-sensitive work, use system_highpri_wq. For long-running work that should not block other work items, create a private workqueue with alloc_workqueue("name", WQ_UNBOUND, max_active).

The classic pattern: top half reads hardware, stores data, calls schedule_work(&dev->rx_work). The work function wakes up in a kworker thread, takes a mutex, processes the data, possibly sleeping while waiting for memory allocation or I/O, then signals userspace via wake_up(). This is how most USB drivers, I2C drivers, and many network drivers work.

#include <linux/workqueue.h>

struct my_device {
    struct work_struct rx_work;
    struct mutex lock;
    /* ... */
};

/* Runs in kworker kernel thread — CAN sleep */
static void my_rx_work(struct work_struct *work)
{
    struct my_device *dev =
        container_of(work, struct my_device, rx_work);

    /* Taking a mutex is fine here — we can sleep */
    mutex_lock(&dev->lock);

    /* GFP_KERNEL allocation is fine — can sleep if memory is tight */
    char *buf = kmalloc(PAGE_SIZE, GFP_KERNEL);
    if (!buf) {
        mutex_unlock(&dev->lock);
        return;
    }

    /* Copy data from hardware ring buffer to buf... */
    size_t len = consume_hw_ring(dev, buf, PAGE_SIZE);

    /* Push to userspace via a character device read queue */
    kfifo_in(&dev->user_fifo, buf, len);
    wake_up_interruptible(&dev->read_queue);

    kfree(buf);
    mutex_unlock(&dev->lock);
}

/* Top half: hardirq context, must be fast */
static irqreturn_t my_irq(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;
    /* Acknowledge hardware interrupt */
    writel(IRQ_ACK, dev->base + STATUS_REG);
    /* Defer real work to kworker */
    schedule_work(&dev->rx_work);
    return IRQ_HANDLED;
}

Threaded IRQs are the cleanest modern solution to interrupt handling. Instead of splitting the handler manually, you give request_threaded_irq() two functions: a short primary handler that runs in hardirq context and a thread handler that runs in a dedicated kernel thread created for this IRQ.

The primary handler does only what must be done in hardirq context: check if the interrupt is ours, acknowledge it at hardware level, then return IRQ_WAKE_THREAD. The kernel then wakes the IRQ thread, which runs the thread handler in process context — with full ability to sleep.

Advantages over tasklets/workqueues:

1. RT-preemptible: with PREEMPT_RT, the IRQ thread is a normal real-time thread with configurable priority (irq/<n>-name in ps).
2. Simpler code: one natural function for each 'phase', no manual work item management.
3. Automatic synchronization: free_irq() waits for the thread handler to complete — no cancel_work_sync needed.
4. Forced threaded mode: boot with threadirqs kernel parameter to make all interrupt handlers threaded (useful for RT debugging).

The IRQF_ONESHOT flag is critical: it tells the kernel to keep the interrupt line masked until the thread handler finishes. Without it, the hardware can re-raise the interrupt before the thread handler reads the status register, causing a spurious second invocation. For level-triggered interrupts, IRQF_ONESHOT is almost always required.

For the vast majority of new driver code written today, threaded IRQs are the recommended approach.

#include <linux/interrupt.h>

/* Primary handler: hardirq context, must be minimal */
static irqreturn_t my_primary_handler(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;

    /* Confirm interrupt is ours */
    if (!(readl(dev->base + STATUS) & DATA_READY))
        return IRQ_NONE;

    /* Do NOT read data here — let the thread do it.
     * Just tell the kernel: wake the thread. */
    return IRQ_WAKE_THREAD;
}

/* Thread handler: process context, CAN sleep */
static irqreturn_t my_thread_handler(int irq, void *dev_id)
{
    struct my_device *dev = dev_id;

    /* Read all pending data from hardware — may take many microseconds */
    while (readl(dev->base + STATUS) & DATA_READY) {
        u32 data = readl(dev->base + DATA_REG);
        kfifo_put(&dev->rx_fifo, data);
    }

    wake_up_interruptible(&dev->read_queue);
    return IRQ_HANDLED;
}

static int my_probe(struct platform_device *pdev)
{
    struct my_device *dev = /* ... */;
    int irq = platform_get_irq(pdev, 0);

    /* IRQF_ONESHOT: keep IRQ masked until thread_handler finishes */
    return request_threaded_irq(irq,
                                my_primary_handler,
                                my_thread_handler,
                                IRQF_ONESHOT | IRQF_TRIGGER_LOW,
                                "my_device", dev);
}

The single most important mental model for kernel interrupt code is knowing what context you are in. The kernel provides predicates for this:

• in_irq() or in_hardirq(): true if executing a hardware interrupt handler.
• in_softirq(): true in a softirq or tasklet.
• in_interrupt(): true in either hardirq or softirq context.
• in_task(): true in process context (normal kernel code or kernel thread).

These are checked by might_sleep() — the kernel's assertion that the current call site is allowed to sleep. Every path through the kernel that can sleep calls might_sleep() or might_resched(), and these will fire a warning (with a stack trace) if you are in interrupt context. This is how lockdep and the kernel's runtime checking catch your bugs at development time.

The locking corollary: if data is shared between a hardirq handler and process context code, protect it with a spinlock, but you must use spin_lock_irqsave() in process context (not plain spin_lock()). Why? Because if you hold the spinlock in process context and an interrupt fires on the same CPU, the interrupt handler tries to take the same spinlock — deadlock. spin_lock_irqsave() disables interrupts on the local CPU while the lock is held, preventing this.

If data is shared between a tasklet/softirq and process context, spin_lock_bh() / spin_unlock_bh() disables softirqs (bottom halves) on the local CPU — sufficient because tasklets do not preempt process context on SMP; they only run on the same CPU if that CPU is not in process context.

The rule of thumb: the higher the preemption level, the heavier the locking needed in the lower levels.

/* Correct locking for data shared between hardirq and process context */
struct my_dev {
    spinlock_t lock;
    u32 counter;  /* written in IRQ handler, read in read() */
};

/* In hardirq handler: plain spin_lock is fine — IRQs are already off */
static irqreturn_t my_irq(int irq, void *dev_id)
{
    struct my_dev *d = dev_id;
    spin_lock(&d->lock);  /* IRQs already disabled by CPU */
    d->counter++;
    spin_unlock(&d->lock);
    return IRQ_HANDLED;
}

/* In process context (e.g., read syscall): MUST use irqsave variant */
ssize_t my_read(struct file *f, char __user *buf, size_t n, loff_t *off)
{
    struct my_dev *d = f->private_data;
    unsigned long flags;
    u32 val;

    /* Disable IRQs on this CPU while holding lock, save old IF state */
    spin_lock_irqsave(&d->lock, flags);
    val = d->counter;
    spin_unlock_irqrestore(&d->lock, flags);
    /* IRQs are re-enabled here */

    return copy_to_user(buf, &val, sizeof(val)) ? -EFAULT : sizeof(val);
}

On a modern multi-core system, which CPU handles an interrupt matters enormously for performance. The IO-APIC (x86) or GIC (ARM) can route IRQs to specific CPUs. /proc/irq/N/smp_affinity is a CPU bitmask controlling this. For a 10Gbps NIC with 16 queues and 16 CPUs, binding each queue's IRQ to a dedicated CPU means sixteen CPUs can process packets in parallel without contention.

The irqbalance daemon dynamically adjusts IRQ affinity based on load. For latency-sensitive workloads (HPC, real-time), you often pin IRQs manually and isolate CPUs with isolcpus= and nohz_full= kernel parameters.

NAPI (New API) is the Linux network driver interrupt mitigation technique, and it is a beautiful example of interrupt engineering:

1. First packet arrives → NIC raises IRQ → hardirq handler disables the interrupt on that NIC queue and schedules a NAPI poll.
2. softirq (NET_RX) calls the driver's poll() function, which processes up to budget packets from the hardware ring buffer in a tight loop.
3. If the ring is empty, re-enable the NIC interrupt and return.
4. If the budget was exhausted (more packets waiting), yield and reschedule — without re-enabling the interrupt.

This means under high load, the NIC interrupt fires once, and then the driver polls until the ring drains. Under low load, every packet gets a dedicated interrupt. NAPI automatically adapts between interrupt-driven and polling mode, giving you the latency of interrupts and the throughput of polling. The Linux e1000, igb, and mlx5 drivers all use NAPI.

/* Minimal NAPI driver skeleton */
struct my_nic {
    struct napi_struct napi;
    /* ... ring buffer, register base ... */
};

/* NAPI poll: runs in NET_RX softirq context */
static int my_poll(struct napi_struct *napi, int budget)
{
    struct my_nic *nic = container_of(napi, struct my_nic, napi);
    int work = 0;

    while (work < budget && hw_ring_has_packet(nic)) {
        struct sk_buff *skb = build_skb_from_ring(nic);
        netif_receive_skb(skb);  /* push up the network stack */
        work++;
    }

    if (work < budget) {
        /* Ring drained — re-arm interrupt and exit polling mode */
        napi_complete_done(napi, work);
        enable_hw_irq(nic);  /* writel to NIC register */
    }
    return work;
}

/* Top half: disable IRQ, schedule poll */
static irqreturn_t my_nic_irq(int irq, void *dev_id)
{
    struct my_nic *nic = dev_id;
    disable_hw_irq(nic);       /* prevent re-entry while polling */
    napi_schedule(&nic->napi); /* raise NET_RX_SOFTIRQ */
    return IRQ_HANDLED;
}

static int my_nic_probe(struct pci_dev *pdev, ...)
{
    struct my_nic *nic = /* ... */;
    netif_napi_add(nic->netdev, &nic->napi, my_poll);
    /* ... request_irq(pdev->irq, my_nic_irq, ...) ... */
    napi_enable(&nic->napi);
    return 0;
}