Core Components

Relevant source files

• src/consts.rs
• src/devops_impl.rs
• src/vgic.rs
• src/vgicc.rs

This document provides an overview of the four primary components that make up the arm_vgic virtual interrupt controller system. These components work together to provide complete ARM GIC (Generic Interrupt Controller) virtualization within the ArceOS hypervisor ecosystem.

For detailed information about system architecture and positioning within the broader virtualization stack, see System Architecture. For dependency analysis and integration details, see Dependencies and Integration.

Component Architecture Overview

The arm_vgic crate is structured around four core components that provide different aspects of interrupt controller virtualization:

Component Architecture

flowchart TD
subgraph subGraph1["External Framework"]
    axdevice_base["axdevice_base::BaseDeviceOps"]
    arm_gicv2["arm_gicv2::GicInterface"]
end
subgraph subGraph0["Core Components"]
    Vgic["VgicMain Controller"]
    VgicInner["VgicInnerProtected State"]
    Vgicc["VgiccCPU Interface"]
    BaseDeviceOps["BaseDeviceOps ImplementationDevice Framework Integration"]
    Constants["Constants ModuleRegister Definitions"]
end

BaseDeviceOps --> Vgic
BaseDeviceOps --> axdevice_base
Constants --> Vgicc
Vgic --> Constants
Vgic --> VgicInner
Vgic --> arm_gicv2
VgicInner --> Vgicc

Sources: src/vgic.rs(L32 - L34)  src/vgicc.rs(L3 - L14)  src/devops_impl.rs(L10)  src/consts.rs(L1 - L19) 

Data Flow and Component Interaction

The components interact through a well-defined data flow that handles virtual machine memory accesses and translates them to physical interrupt controller operations:

Data Flow Between Components

flowchart TD
subgraph subGraph4["Hardware Interface"]
    GicInterface_set_enable["GicInterface::set_enable"]
    GicInterface_set_priority["GicInterface::set_priority"]
end
subgraph subGraph3["State Management"]
    VgicInner_mutex["VgicInner (Mutex)"]
    gicc_vec["Vec"]
    register_arrays["Register State Arrays"]
end
subgraph subGraph2["VGIC Processing"]
    handle_read8["Vgic::handle_read8"]
    handle_read16["Vgic::handle_read16"]
    handle_read32["Vgic::handle_read32"]
    handle_write8["Vgic::handle_write8"]
    handle_write16["Vgic::handle_write16"]
    handle_write32["Vgic::handle_write32"]
end
subgraph subGraph1["Device Framework Layer"]
    handle_read["BaseDeviceOps::handle_read"]
    handle_write["BaseDeviceOps::handle_write"]
    address_range["address_range()0x800_0000-0x800_FFFF"]
end
subgraph subGraph0["VM Access"]
    VM_Read["VM Read Access"]
    VM_Write["VM Write Access"]
end

VM_Read --> handle_read
VM_Write --> handle_write
VgicInner_mutex --> GicInterface_set_enable
VgicInner_mutex --> GicInterface_set_priority
VgicInner_mutex --> gicc_vec
VgicInner_mutex --> register_arrays
handle_read --> handle_read16
handle_read --> handle_read32
handle_read --> handle_read8
handle_write --> handle_write16
handle_write --> handle_write32
handle_write --> handle_write8
handle_write8 --> VgicInner_mutex

Sources: src/devops_impl.rs(L45 - L66)  src/devops_impl.rs(L77 - L98)  src/vgic.rs(L56 - L66)  src/vgic.rs(L68 - L106)  src/vgic.rs(L15 - L30) 

Component Responsibilities

Virtual GIC Controller (Vgic)

The Vgic struct serves as the main controller that orchestrates interrupt virtualization. It maintains thread-safe access to the internal state through a Mutex<VgicInner> and provides the primary interface for handling virtual machine memory accesses to interrupt controller registers.

Key responsibilities:

• Memory-mapped register access handling via handle_read8/16/32 and handle_write8/16/32 methods
• Thread-safe state management through VgicInner mutex protection
• Physical interrupt controller coordination via arm_gicv2::GicInterface
• Interrupt enable/disable control and priority management

For comprehensive details, see Virtual GIC Controller (Vgic).

Sources: src/vgic.rs(L32 - L34)  src/vgic.rs(L36 - L54) 

CPU Interface (Vgicc)

The Vgicc struct manages per-CPU interrupt controller state, including link registers for interrupt delivery and saved processor state for context switching operations.

Key responsibilities:

• Per-CPU interrupt state management with unique id field
• Link register arrays for interrupt queuing (pending_lr, saved_lr)
• Processor state preservation (saved_elsr0, saved_apr, saved_hcr)
• Local interrupt enable/priority configuration (isenabler, priorityr)

For detailed analysis, see CPU Interface (Vgicc).

Sources: src/vgicc.rs(L3 - L14) 

Device Operations Interface

The BaseDeviceOps trait implementation bridges the Vgic controller with the ArceOS device framework, providing standardized device emulation capabilities.

Key responsibilities:

• Device type identification via emu_type() returning EmuDeviceTGicdV2
• Address space definition through address_range() covering 0x800_0000 to 0x800_FFFF
• Width-based memory access dispatch (8/16/32-bit operations)
• Address masking and alignment handling

For implementation details, see Device Operations Interface.

Sources: src/devops_impl.rs(L10)  src/devops_impl.rs(L18 - L31) 

Constants and Register Layout

The constants module defines critical system parameters, interrupt ID limits, and register offset mappings that govern the virtual interrupt controller behavior.

Key definitions:

• Interrupt ID boundaries: SGI_ID_MAX, PPI_ID_MAX, SPI_ID_MAX
• Link register configuration: GICD_LR_NUM
• VGICD register offsets: VGICD_CTLR, VGICD_ISENABLER_*, VGICD_ICENABLER_*
• Control and configuration register addresses

For complete reference, see Constants and Register Layout.

Sources: src/consts.rs(L1 - L19) 

Integration Architecture

Component Integration with External Systems

flowchart TD
subgraph subGraph3["System Utilities"]
    spin_mutex["spin::Mutex"]
    log_macros["log::error!"]
    alloc_vec["alloc::Vec"]
end
subgraph subGraph2["Hardware Abstraction"]
    arm_gicv2_interface["arm_gicv2::GicInterface"]
    memory_addr_range["memory_addr::AddrRange"]
end
subgraph subGraph1["ArceOS Framework"]
    BaseDeviceOps_trait["BaseDeviceOps trait"]
    axdevice_base_crate["axdevice_base crate"]
    axaddrspace_addr["axaddrspace::GuestPhysAddr"]
    axerrno_result["axerrno::AxResult"]
end
subgraph subGraph0["arm_vgic Components"]
    Vgic_main["Vgic"]
    VgicInner_state["VgicInner"]
    Vgicc_cpu["Vgicc"]
    consts_defs["Constants"]
end

BaseDeviceOps_trait --> axaddrspace_addr
BaseDeviceOps_trait --> axdevice_base_crate
BaseDeviceOps_trait --> axerrno_result
BaseDeviceOps_trait --> memory_addr_range
VgicInner_state --> Vgicc_cpu
VgicInner_state --> alloc_vec
VgicInner_state --> spin_mutex
Vgic_main --> BaseDeviceOps_trait
Vgic_main --> VgicInner_state
Vgic_main --> arm_gicv2_interface
Vgic_main --> consts_defs
Vgic_main --> log_macros

Sources: src/vgic.rs(L1 - L11)  src/devops_impl.rs(L1 - L8)  src/vgicc.rs(L2) 

The four core components work together to provide a complete virtual interrupt controller implementation that integrates seamlessly with the ArceOS hypervisor framework while maintaining efficient virtualization of ARM GIC functionality.