Virtual CPU Architecture

Relevant source files

• src/vcpu.rs

Purpose and Scope

The Virtual CPU Architecture in axvm provides a unified abstraction layer for virtual CPU management across multiple hardware architectures. This system enables axvm to support x86_64, RISC-V, and AArch64 platforms through architecture-specific backends while maintaining a consistent interface for the core hypervisor components.

This document covers the multi-architecture vCPU abstraction, architecture-specific implementations, configuration mechanisms, and hardware support detection. For information about the broader VM lifecycle and management, see Virtual Machine Implementation. For hardware abstraction interfaces beyond vCPUs, see Hardware Abstraction Layer.

Multi-Architecture Abstraction Layer

The vCPU architecture uses compile-time conditional compilation to select the appropriate backend for each target architecture. This design provides zero-cost abstraction while maintaining type safety across different hardware platforms.

Architecture Selection and Type Aliases

The core abstraction is implemented through type aliases that map to architecture-specific implementations based on the compilation target:

flowchart TD
subgraph subGraph3["AArch64 Backend"]
    Aarch64VCpu["Aarch64VCpu"]
    Aarch64PerCpu["Aarch64PerCpu"]
    Aarch64VCpuCreateConfig["Aarch64VCpuCreateConfig"]
    Aarch64HWSupport["ARM EL2 Support Check"]
end
subgraph subGraph2["RISC-V Backend"]
    RISCVVCpu["RISCVVCpu"]
    RISCVPerCpu["RISCVPerCpu"]
    RISCVVCpuCreateConfig["RISCVVCpuCreateConfig"]
    RISCVHWSupport["RISC-V H-Extension Check"]
end
subgraph subGraph1["x86_64 Backend"]
    VmxArchVCpu["VmxArchVCpu"]
    VmxArchPerCpuState["VmxArchPerCpuState"]
    UnitConfig["() Unit Type"]
    VmxHWSupport["VMX Hardware Check"]
end
subgraph subGraph0["Common Interface Types"]
    AxArchVCpuImpl["AxArchVCpuImplMain vCPU Interface"]
    AxVMArchPerCpuImpl["AxVMArchPerCpuImplPer-CPU State"]
    AxVCpuCreateConfig["AxVCpuCreateConfigCreation Configuration"]
    HasHWSupport["has_hardware_supportHardware Detection"]
end

AxArchVCpuImpl --> Aarch64VCpu
AxArchVCpuImpl --> RISCVVCpu
AxArchVCpuImpl --> VmxArchVCpu
AxVCpuCreateConfig --> Aarch64VCpuCreateConfig
AxVCpuCreateConfig --> RISCVVCpuCreateConfig
AxVCpuCreateConfig --> UnitConfig
AxVMArchPerCpuImpl --> Aarch64PerCpu
AxVMArchPerCpuImpl --> RISCVPerCpu
AxVMArchPerCpuImpl --> VmxArchPerCpuState
HasHWSupport --> Aarch64HWSupport
HasHWSupport --> RISCVHWSupport
HasHWSupport --> VmxHWSupport

Sources: src/vcpu.rs(L3 - L27) 

Architecture-Specific Implementations

Each supported architecture provides its own implementation of the vCPU interface, tailored to the specific virtualization capabilities and requirements of that platform.

x86_64 Implementation

The x86_64 backend uses Intel VT-x and AMD-V virtualization extensions through the x86_vcpu crate. This implementation provides VMX-based virtualization with EPT (Extended Page Tables) support.

Sources: src/vcpu.rs(L4 - L8) 

RISC-V Implementation

The RISC-V backend leverages the RISC-V hypervisor extension (H-extension) through the riscv_vcpu crate, providing virtualization support for RISC-V processors.

Sources: src/vcpu.rs(L16 - L20) 

AArch64 Implementation

The AArch64 backend utilizes ARM virtualization extensions (EL2) through the arm_vcpu crate, enabling hypervisor functionality on ARM processors.

Sources: src/vcpu.rs(L21 - L26) 

vCPU Lifecycle and Integration

The vCPU architecture integrates with the broader axvm system through well-defined interfaces that handle creation, configuration, and execution of virtual CPUs.

vCPU Creation and Configuration Flow

sequenceDiagram
    participant AxVM as "AxVM"
    participant AxVCpuCreateConfig as "AxVCpuCreateConfig"
    participant has_hardware_support as "has_hardware_support"
    participant AxArchVCpuImpl as "AxArchVCpuImpl"
    participant AxVMArchPerCpuImpl as "AxVMArchPerCpuImpl"

    AxVM ->> has_hardware_support: "Check virtualization support"
    has_hardware_support -->> AxVM: "Hardware capability result"
    alt Hardware Supported
        AxVM ->> AxVCpuCreateConfig: "Create vCPU configuration"
        AxVM ->> AxArchVCpuImpl: "new(config)"
        AxArchVCpuImpl ->> AxVMArchPerCpuImpl: "Initialize per-CPU state"
        AxVMArchPerCpuImpl -->> AxArchVCpuImpl: "Per-CPU state ready"
        AxArchVCpuImpl -->> AxVM: "vCPU instance created"
    else Hardware Not Supported
        AxVM ->> AxVM: "Return error or fallback"
    end

Sources: src/vcpu.rs(L1 - L27) 

Hardware Support Detection

Each architecture backend provides a has_hardware_support function that performs runtime detection of virtualization capabilities. This enables axvm to gracefully handle systems that may not have the necessary hardware extensions.

The hardware support detection is critical for:

• Determining if the host system can run the hypervisor
• Selecting appropriate virtualization features
• Providing meaningful error messages when virtualization is unavailable

Sources: src/vcpu.rs(L7 - L25) 

Physical Frame Interface Requirements

The x86_64 implementation has a unique requirement where the PhysFrameIf trait must be implemented by the application layer. This design decision aligns with axvm's architecture principle of separating hypervisor functionality from OS resource management.

The PhysFrameIf implementation is handled by the vmm_app component rather than within axvm itself, allowing for flexible memory management strategies while maintaining clear separation of concerns.

Sources: src/vcpu.rs(L10 - L15) 

Integration with VM Core

The vCPU architecture seamlessly integrates with the main AxVM implementation through the standardized interfaces, enabling the VM to manage virtual CPUs without needing architecture-specific knowledge. This abstraction allows the core VM logic to remain architecture-agnostic while leveraging the full capabilities of each supported platform.

Sources: src/vcpu.rs(L1 - L27)