Interrupt Handling

The SerenityOS kernel implements a flexible interrupt handling system that manages hardware and software interrupts across multiple architectures. The interrupt subsystem is located in Kernel/Interrupts/ and provides a unified interface for interrupt management.

Core Architecture

GenericInterruptHandler

The base class for all interrupt handlers (Kernel/Interrupts/GenericInterruptHandler.h):

class GenericInterruptHandler {
public:
    virtual bool handle_interrupt() = 0;
    virtual bool eoi() = 0;  // End of interrupt
    
    u8 interrupt_number() const;
    virtual HandlerType type() const = 0;
    virtual StringView purpose() const = 0;
    virtual StringView controller() const = 0;
    
    virtual size_t sharing_devices_count() const = 0;
    virtual bool is_shared_handler() const = 0;
};

Key features:

Abstract interface for all interrupt handlers
Per-CPU interrupt call counters
Registration and unregistration management
Support for shared interrupt lines

Handler Types

The kernel supports multiple handler types:

enum class HandlerType : u8 {
    IRQHandler = 1,              // Standard IRQ handler
    SharedIRQHandler = 2,        // Multiple devices sharing an IRQ
    UnhandledInterruptHandler = 3, // Catch-all for unhandled interrupts
    SpuriousInterruptHandler = 4   // Spurious interrupt detection
};

Using the appropriate handler type ensures correct interrupt routing and statistics tracking.

IRQ Handlers

IRQHandler

Standard interrupt handler for hardware devices (Kernel/Interrupts/IRQHandler.h):

class IRQHandler : public GenericInterruptHandler {
public:
    virtual bool handle_irq() = 0;
    
    void enable_irq();
    void disable_irq();
    
protected:
    explicit IRQHandler(u8 irq);
};

Device drivers derive from IRQHandler and implement handle_irq():

class MyDeviceHandler : public IRQHandler {
public:
    MyDeviceHandler() : IRQHandler(MY_IRQ_NUMBER) {}
    
    virtual bool handle_irq() override {
        // Read device status
        // Process interrupt
        // Clear interrupt source
        return true;  // Interrupt handled
    }
};

Return Value Semantics

The handle_interrupt() return value indicates whether the handler processed the interrupt:

true: Interrupt was handled by this handler
false: Interrupt was not from this device (important for shared IRQs)

Enabling and Disabling IRQs

// Disable IRQ during critical section
my_handler.disable_irq();
// ... critical work ...
my_handler.enable_irq();

IRQs can also be temporarily disabled using InterruptDisabler:

#include <Kernel/Interrupts/InterruptDisabler.h>

{
    InterruptDisabler disabler;
    // All interrupts disabled in this scope
} // Interrupts restored

Prolonged interrupt disabling can cause system latency and missed interrupts. Keep critical sections short.

Shared Interrupts

SharedIRQHandler

Multiple devices can share an interrupt line using SharedIRQHandler (Kernel/Interrupts/SharedIRQHandler.h):

class SharedIRQHandler : public GenericInterruptHandler {
public:
    void register_handler(IRQHandler&);
    void unregister_handler(IRQHandler&);
    
    virtual bool handle_interrupt() override {
        bool handled = false;
        for (auto& handler : m_handlers) {
            if (handler.handle_irq())
                handled = true;
        }
        return handled;
    }
};

When an interrupt occurs on a shared line:

Each registered handler is invoked
Each handler checks if its device triggered the interrupt
Handler returns true only if it processed the interrupt
The shared handler returns true if any handler processed it

PCI IRQ Handlers

PCIIRQHandler (Kernel/Interrupts/PCIIRQHandler.h) extends IRQHandler for PCI devices, handling:

MSI (Message Signaled Interrupts)
MSI-X (Extended MSI)
Legacy INTx interrupts

Special Interrupt Handlers

UnhandledInterruptHandler

Catches interrupts with no registered handler:

class UnhandledInterruptHandler : public GenericInterruptHandler {
public:
    virtual bool handle_interrupt() override {
        // Log unhandled interrupt
        dbgln("Unhandled interrupt: {}", interrupt_number());
        return false;
    }
};

SpuriousInterruptHandler

Detects and handles spurious interrupts:

class SpuriousInterruptHandler : public GenericInterruptHandler {
    // Spurious interrupts occur when:
    // - Edge-triggered interrupt is deasserted before ACK
    // - IRQ line has electrical noise
    // - Interrupt controller issues duplicate interrupt
};

Interrupt Controllers

SerenityOS supports multiple interrupt controller architectures:

x86_64 Controllers

PIC (Programmable Interrupt Controller) (Kernel/Arch/x86_64/Interrupts/PIC.h)

Legacy 8259 PIC support
Two cascaded controllers (master/slave)
15 IRQ lines total
Used on older systems or as fallback

APIC (Advanced Programmable Interrupt Controller) (Kernel/Arch/x86_64/Interrupts/APIC.h)

Modern interrupt controller
Supports multiple CPUs
Local APIC per CPU
I/O APIC for peripheral interrupts

IOAPIC (Kernel/Arch/x86_64/Interrupts/IOAPIC.h)

Routes interrupts to CPU Local APICs
Supports interrupt remapping
Programmable interrupt distribution

APIC vs PIC

PIC Limitations:

Maximum 15 IRQs
No SMP support
Fixed priority scheme
Edge and level-triggered modes

APIC Advantages:

Up to 256 interrupt vectors
Per-CPU interrupt delivery
Advanced priority and routing
Better performance on SMP systems
Message-signaled interrupts (MSI)

ARM64 Controllers

GICv2 (Generic Interrupt Controller v2) (Kernel/Arch/aarch64/Interrupts/GICv2.h)

Standard ARM interrupt controller
Supports up to 8 CPUs
1020 interrupt sources

GICv3 (Kernel/Arch/aarch64/Interrupts/GICv3.h)

Modern ARM interrupt controller
Improved scalability (supports more CPUs)
Interrupt routing to specific CPUs
LPI (Locality-specific Peripheral Interrupts)

RISC-V Controllers

PLIC (Platform-Level Interrupt Controller) (Kernel/Arch/riscv64/Interrupts/PLIC.h)

Standard RISC-V interrupt controller
Programmable priorities
Per-hart (hardware thread) interrupt delivery

Interrupt Flow

Interrupt Processing Sequence

Hardware Event: Device asserts interrupt line
Controller: Interrupt controller receives signal
CPU: Controller signals CPU interrupt
Handler Entry: CPU vectors to interrupt handler
Handler Dispatch: Kernel identifies handler for IRQ number
Device Handler: Device-specific handler processes interrupt
EOI: Handler sends End-of-Interrupt to controller
Return: Resume interrupted execution

Device → IRQ Line → Interrupt Controller → CPU
                                          ↓
                                    GenericInterruptHandler::handle_interrupt()
                                          ↓
                                    IRQHandler::handle_irq()
                                          ↓
                                    Device Driver Processing
                                          ↓
                                    EOI to Controller

End of Interrupt (EOI)

After processing an interrupt, the handler must signal completion:

virtual bool eoi() override {
    // Signal interrupt controller
    m_responsible_irq_controller->eoi(*this);
    return true;
}

Failure to send EOI prevents further interrupts from that source.

Interrupt Statistics

The kernel tracks interrupt statistics per CPU:

ReadonlySpan<u32> per_cpu_call_counts() const;
void increment_call_count();

Statistics include:

Total interrupt count per IRQ
Per-CPU interrupt counts
Handler invocation counts

Access via /sys/kernel/interrupts in the filesystem.

Registration and Lifecycle

Registering an IRQ Handler

class MyDevice : public IRQHandler {
public:
    MyDevice(u8 irq) : IRQHandler(irq) {
        register_interrupt_handler();
        enable_irq();
    }
    
    ~MyDevice() {
        disable_irq();
        unregister_interrupt_handler();
    }
};

Handler Lifecycle

Construction: Create handler with IRQ number
Registration: Call register_interrupt_handler()
Enable: Call enable_irq() to start receiving interrupts
Active: Handle interrupts via handle_irq()
Disable: Call disable_irq() before cleanup
Unregister: Call unregister_interrupt_handler()
Destruction: Destroy handler object

Always disable and unregister handlers before destruction to prevent use-after-free bugs.

Architecture-Specific Handling

While the GenericInterruptHandler interface is architecture-independent, the underlying implementation varies: x86_64:

Uses IDT (Interrupt Descriptor Table)
256 interrupt vectors
Vectors 0-31: CPU exceptions
Vectors 32-255: Hardware interrupts

AArch64:

Exception vector table
Four exception levels (EL0-EL3)
IRQ and FIQ interrupt types

RISC-V:

Trap vector table
Machine and Supervisor mode interrupts
Interrupt delegation to S-mode

Best Practices

Handler Implementation

Minimize Work: Do minimal work in interrupt context
Defer Processing: Use work queues for heavy processing
Return Quickly: Long handlers increase interrupt latency
Check Source: Verify interrupt is from your device (for shared IRQs)
Clear Source: Acknowledge interrupt at device level

Synchronization

class MyDevice : public IRQHandler {
    Spinlock<LockRank::None> m_lock;
    
public:
    void regular_function() {
        SpinlockLocker locker(m_lock);
        // Access shared data
    }
    
    virtual bool handle_irq() override {
        SpinlockLocker locker(m_lock);
        // Access same shared data safely
        return true;
    }
};

Use spinlocks, not mutexes, for synchronization between interrupt handlers and regular code. Mutexes may sleep, which is forbidden in interrupt context.

Debugging Interrupts

Useful debugging techniques:

// Log interrupt calls
virtual bool handle_irq() override {
    dbgln("MyDevice IRQ {} triggered", interrupt_number());
    return handle_device_interrupt();
}

// Check interrupt counts
auto counts = handler.per_cpu_call_counts();
for (size_t i = 0; i < counts.size(); i++)
    dbgln("CPU {}: {} interrupts", i, counts[i]);

Kernel/Interrupts/GenericInterruptHandler.{h,cpp} - Base handler class
Kernel/Interrupts/IRQHandler.{h,cpp} - Standard IRQ handler
Kernel/Interrupts/SharedIRQHandler.{h,cpp} - Shared interrupt support
Kernel/Interrupts/InterruptDisabler.h - Interrupt disabling utility
Kernel/Arch/*/Interrupts/ - Architecture-specific controllers

Overview

Core Systems

Subsystems

Core Architecture

GenericInterruptHandler

Handler Types

IRQ Handlers

IRQHandler

Return Value Semantics

Enabling and Disabling IRQs

Shared Interrupts

SharedIRQHandler

PCI IRQ Handlers

Special Interrupt Handlers

UnhandledInterruptHandler

SpuriousInterruptHandler

Interrupt Controllers

x86_64 Controllers

ARM64 Controllers

RISC-V Controllers

Interrupt Flow

Interrupt Processing Sequence

End of Interrupt (EOI)

Interrupt Statistics

Registration and Lifecycle

Registering an IRQ Handler

Handler Lifecycle

Architecture-Specific Handling

Best Practices

Handler Implementation

Synchronization

Debugging Interrupts

Build docs developers (and LLMs) love

Overview

Core Systems

Subsystems

​Core Architecture

​GenericInterruptHandler

​Handler Types

​IRQ Handlers

​IRQHandler

​Return Value Semantics

​Enabling and Disabling IRQs

​Shared Interrupts

​SharedIRQHandler

​PCI IRQ Handlers

​Special Interrupt Handlers

​UnhandledInterruptHandler

​SpuriousInterruptHandler

​Interrupt Controllers

​x86_64 Controllers

​ARM64 Controllers

​RISC-V Controllers

​Interrupt Flow

​Interrupt Processing Sequence

​End of Interrupt (EOI)

​Interrupt Statistics

​Registration and Lifecycle

​Registering an IRQ Handler

​Handler Lifecycle

​Architecture-Specific Handling

​Best Practices

​Handler Implementation

​Synchronization

​Debugging Interrupts

​Related Files

Build docs developers (and LLMs) love

Core Architecture

GenericInterruptHandler

Handler Types

IRQ Handlers

IRQHandler

Return Value Semantics

Enabling and Disabling IRQs

Shared Interrupts

SharedIRQHandler

PCI IRQ Handlers

Special Interrupt Handlers

UnhandledInterruptHandler

SpuriousInterruptHandler

Interrupt Controllers

x86_64 Controllers

ARM64 Controllers

RISC-V Controllers

Interrupt Flow

Interrupt Processing Sequence

End of Interrupt (EOI)

Interrupt Statistics

Registration and Lifecycle

Registering an IRQ Handler

Handler Lifecycle

Architecture-Specific Handling

Best Practices

Handler Implementation

Synchronization

Debugging Interrupts

Related Files