Interrupt Classification System

Relevant source files

• src/lib.rs

Purpose and Scope

This document covers the interrupt classification system implemented in the ARM GICv2 crate, which categorizes interrupts into three distinct types based on their ID ranges and intended usage patterns. The classification system provides the foundation for interrupt routing, priority management, and inter-processor communication within the GIC architecture.

For detailed information about how these classified interrupts are processed through the system, see Interrupt Processing Pipeline. For specific implementation details of Software Generated Interrupts, see Software Generated Interrupts.

Interrupt Type Classification

The ARM GICv2 specification defines three fundamental interrupt types, each with specific characteristics and use cases. The crate implements this classification through predefined ranges and an enumeration system.

Interrupt Type Definitions

flowchart TD
subgraph subGraph2["Range Constants"]
    SGI_RANGE_CONST["SGI_RANGE: 0..16"]
    PPI_RANGE_CONST["PPI_RANGE: 16..32"]
    SPI_RANGE_CONST["SPI_RANGE: 32..1020"]
end
subgraph subGraph1["InterruptType Enum"]
    SGI_ENUM["InterruptType::SGI"]
    PPI_ENUM["InterruptType::PPI"]
    SPI_ENUM["InterruptType::SPI"]
end
subgraph subGraph0["Interrupt ID Space (0-1019)"]
    SGI_IDS["SGI Range: 0-15Software Generated"]
    PPI_IDS["PPI Range: 16-31Private Peripheral"]
    SPI_IDS["SPI Range: 32-1019Shared Peripheral"]
    RESERVED["Reserved: 1020-1023"]
end

PPI_ENUM --> PPI_RANGE_CONST
PPI_IDS --> PPI_ENUM
SGI_ENUM --> SGI_RANGE_CONST
SGI_IDS --> SGI_ENUM
SPI_ENUM --> SPI_RANGE_CONST
SPI_IDS --> SPI_ENUM

Sources: src/lib.rs(L14 - L29)  src/lib.rs(L74 - L89) 

Software Generated Interrupts (SGI)

SGIs occupy interrupt IDs 0-15 and are generated through software writes to the GICD_SGIR register. These interrupts enable communication between processors in multi-core systems.

Key Characteristics:

• Always generated by software, never by hardware peripherals
• Can target specific CPUs or groups of CPUs
• Used for synchronization and coordination between cores
• Highest priority in the interrupt ID space

Private Peripheral Interrupts (PPI)

PPIs occupy interrupt IDs 16-31 and are specific to individual processors. Each CPU core has its own private set of these interrupt sources.

Key Characteristics:

• Processor-specific interrupt sources
• Cannot be routed to other CPUs
• Typically used for CPU timers, PMU events, and other core-local peripherals
• Each CPU core sees the same PPI ID but from different physical sources

Shared Peripheral Interrupts (SPI)

SPIs occupy interrupt IDs 32-1019 and represent the largest category of interrupts. These can be routed to any available CPU in the system.

Key Characteristics:

• System-wide interrupt sources
• Configurable CPU targeting and routing
• Generated by external peripherals and devices
• Support for load balancing and affinity settings

Interrupt Translation Mechanism

The crate provides a translation function that converts relative interrupt IDs within each type to absolute GIC interrupt IDs.

flowchart TD
subgraph Output["Output"]
    ABS_ID["Absolute GIC ID(0-1019)"]
    NONE_VAL["None (invalid input)"]
end
subgraph subGraph1["translate_irq Function"]
    VALIDATE["Validate ID againsttype-specific limits"]
    CALCULATE["Calculate absoluteGIC interrupt ID"]
    RETURN["Return Option"]
end
subgraph subGraph0["Input Parameters"]
    REL_ID["Relative ID(within type)"]
    INT_TYPE["InterruptType(SGI/PPI/SPI)"]
end

CALCULATE --> RETURN
INT_TYPE --> VALIDATE
REL_ID --> VALIDATE
RETURN --> ABS_ID
RETURN --> NONE_VAL
VALIDATE --> CALCULATE

Sources: src/lib.rs(L91 - L116) 

The translate_irq function performs the following transformations:

Range Validation Logic

The translation function includes bounds checking to ensure valid interrupt IDs:

• SGI validation: id < SGI_RANGE.end (must be < 16)
• PPI validation: id < PPI_RANGE.end - PPI_RANGE.start (must be < 16)
• SPI validation: id < SPI_RANGE.end - SPI_RANGE.start (must be < 988)

Invalid inputs return None, providing safe interrupt ID translation.

System Integration

The interrupt classification system integrates with the broader GIC architecture through well-defined constants and type-safe interfaces.

flowchart TD
subgraph subGraph2["Usage Examples"]
    ENABLE_INT["Enable interrupt by type"]
    SET_PRIORITY["Set interrupt priority"]
    ROUTE_CPU["Route SPI to CPU"]
    SEND_SGI["Generate SGI"]
end
subgraph subGraph1["Core GIC Components"]
    DISTRIBUTOR["GicDistributor"]
    CPU_INTERFACE["GicCpuInterface"]
end
subgraph subGraph0["Classification Constants"]
    SGI_RANGE["SGI_RANGE: Range"]
    PPI_RANGE["PPI_RANGE: Range"]
    SPI_RANGE["SPI_RANGE: Range"]
    GIC_MAX_IRQ["GIC_MAX_IRQ: usize"]
end

CPU_INTERFACE --> ENABLE_INT
DISTRIBUTOR --> ENABLE_INT
DISTRIBUTOR --> ROUTE_CPU
DISTRIBUTOR --> SEND_SGI
DISTRIBUTOR --> SET_PRIORITY
GIC_MAX_IRQ --> DISTRIBUTOR
PPI_RANGE --> DISTRIBUTOR
SGI_RANGE --> DISTRIBUTOR
SPI_RANGE --> DISTRIBUTOR

Sources: src/lib.rs(L14 - L32)  src/lib.rs(L12) 

Configuration Constants

The system defines several key constants that govern interrupt handling:

• GIC_MAX_IRQ: Maximum interrupt count (1024)
• GIC_CONFIG_BITS: Bits per interrupt configuration (2)
• Range constants: Define valid ID spaces for each interrupt type

These constants ensure consistent behavior across the GIC implementation and provide compile-time guarantees about interrupt ID validity.

Sources: src/lib.rs(L31 - L35)