Overview

Relevant source files

• Cargo.toml
• src/lib.rs

Purpose and Scope

This document provides an overview of the arm_vgic crate, which implements a Virtual Generic Interrupt Controller (VGIC) for ARM-based virtualized systems within the ArceOS hypervisor ecosystem. The crate enables guest virtual machines to interact with a virtualized ARM Generic Interrupt Controller (GIC) interface, providing essential interrupt management capabilities for ARM virtualization scenarios.

This overview covers the crate's architecture, main components, and integration points with the broader ArceOS framework. For detailed implementation specifics of individual components, see Core Components. For dependency analysis and build configuration details, see Dependencies and Integration.

System Purpose and Role

The arm_vgic crate serves as a critical virtualization component that bridges guest operating systems and the physical ARM GIC hardware. It provides:

• Virtual interrupt controller emulation for ARM guest VMs
• Memory-mapped register interface compatible with ARM GIC specifications
• Integration with ArceOS device framework through standardized interfaces
• Thread-safe state management for multi-core virtualization scenarios

The crate operates as an intermediary layer that intercepts guest VM accesses to GIC registers and translates them into appropriate operations on the underlying physical hardware or virtualized state.

Sources: Cargo.toml(L1 - L18)  src/lib.rs(L1 - L10) 

ArceOS Ecosystem Integration

Hypervisor Stack Positioning

flowchart TD
subgraph Physical_Hardware["Physical Hardware"]
    ARM_CPU["ARM CPU Cores"]
    Physical_GIC["Physical GIC Hardware"]
    Memory_HW["Physical Memory"]
end
subgraph ArceOS_Hypervisor["ArceOS Hypervisor Layer"]
    subgraph Hardware_Abstraction["Hardware Abstraction"]
        arm_gicv2["arm_gicv2Physical GIC Driver"]
        memory_addr["memory_addrAddress Types"]
    end
    subgraph Framework_Services["Framework Services"]
        axdevice_base["axdevice_baseDevice Framework"]
        axaddrspace["axaddrspaceMemory Management"]
        axerrno["axerrnoError Handling"]
    end
    subgraph Device_Emulation["Device Emulation"]
        arm_vgic["arm_vgic crateVirtual GIC Controller"]
        OtherDevices["Other Virtual Devices"]
    end
end
subgraph Guest_VM["Guest Virtual Machine"]
    GuestOS["Guest Operating System"]
    GuestDrivers["Device Drivers"]
    GuestKernel["Kernel Interrupt Handlers"]
end

GuestDrivers --> arm_vgic
GuestKernel --> arm_vgic
arm_gicv2 --> Physical_GIC
arm_vgic --> arm_gicv2
arm_vgic --> axaddrspace
arm_vgic --> axdevice_base
axaddrspace --> Memory_HW

Sources: Cargo.toml(L7 - L17) 

Core Architecture Components

Main Code Entity Structure

flowchart TD
subgraph consts_module["consts.rs Module"]
    register_offsets["VGICD Register Offsets"]
    irq_limits["SGI/PPI/SPI ID Limits"]
    lr_config["List Register Configuration"]
end
subgraph devops_impl_module["devops_impl.rs Module"]
    BaseDeviceOps_impl["BaseDeviceOps implementation"]
    address_range["Address Range: 0x800_0000-0x800_FFFF"]
    dispatch_logic["Width-based Dispatch"]
end
subgraph vgicc_module["vgicc.rs Module"]
    Vgicc_struct["Vgicc struct"]
    link_registers["Link Register Arrays"]
    processor_state["Saved Processor State"]
end
subgraph vgic_module["vgic.rs Module"]
    Vgic_struct["Vgic struct"]
    VgicInner_struct["VgicInner struct"]
    handle_read_functions["handle_read8/16/32"]
    handle_write_functions["handle_write8/16/32"]
end
subgraph lib_rs["src/lib.rs - Public API"]
    pub_use_vgic["pub use vgic::Vgic"]
    mod_declarations["mod devops_implmod vgicmod constsmod vgicc"]
end

BaseDeviceOps_impl --> handle_read_functions
BaseDeviceOps_impl --> handle_write_functions
VgicInner_struct --> Vgicc_struct
Vgic_struct --> VgicInner_struct
Vgicc_struct --> link_registers
handle_read_functions --> register_offsets
handle_write_functions --> register_offsets
link_registers --> lr_config
pub_use_vgic --> Vgic_struct

Sources: src/lib.rs(L1 - L10) 

Key Dependencies and Integration Points

The crate integrates with several ArceOS framework components and external libraries:

Component Communication Flow

flowchart TD
subgraph Hardware_Interface["Hardware Interface"]
    arm_gicv2_driver["arm_gicv2::GicInterface"]
    Physical_Operations["Physical GIC Operations"]
end
subgraph VGIC_Processing["arm_vgic Processing"]
    BaseDeviceOps_impl["BaseDeviceOps impl"]
    Vgic_handlers["Vgic read/write handlers"]
    VgicInner_state["VgicInner state"]
    Vgicc_interface["Vgicc CPU interface"]
end
subgraph VM_Access["VM Memory Access"]
    VM_Read["VM Read Operation"]
    VM_Write["VM Write Operation"]
end

BaseDeviceOps_impl --> Vgic_handlers
VM_Read --> BaseDeviceOps_impl
VM_Write --> BaseDeviceOps_impl
VgicInner_state --> Vgicc_interface
Vgic_handlers --> VgicInner_state
Vgic_handlers --> arm_gicv2_driver
arm_gicv2_driver --> Physical_Operations

Sources: Cargo.toml(L7 - L17)  src/lib.rs(L3 - L10) 

Functional Scope

The arm_vgic crate provides virtualization for ARM Generic Interrupt Controller functionality, specifically focusing on:

• Distributor interface emulation - Handles guest accesses to GIC distributor registers
• CPU interface abstraction - Manages per-CPU interrupt controller state
• Interrupt routing and prioritization - Implements ARM GIC interrupt handling semantics
• State persistence - Maintains interrupt controller state across VM operations
• Hardware integration - Coordinates with physical GIC hardware through arm_gicv2

The crate operates within the memory address range 0x800_0000 to 0x800_FFFF, providing a standardized MMIO interface that guest VMs can interact with as if accessing a physical ARM GIC controller.

Sources: Cargo.toml(L1 - L18)  src/lib.rs(L1 - L10)