Overview

Relevant source files

• Cargo.toml
• src/lib.rs

Purpose and Scope

The axvm crate provides a minimal virtual machine monitor (VMM) for the ArceOS hypervisor ecosystem. It implements core virtualization capabilities including virtual CPU management, memory virtualization, and device emulation across multiple hardware architectures. This document covers the fundamental architecture and capabilities of the axvm hypervisor.

For detailed information about the VM configuration system, see Configuration System. For build and development processes, see Development Guide.

High-Level Architecture

The axvm hypervisor is structured around four core modules that provide a clean abstraction layer for virtualization:

AxVM Core Components

flowchart TD
subgraph subGraph0["Main Exports"]
    AxVM_Export["AxVM"]
    AxVMHal_Export["AxVMHal"]
    AxVCpuRef_Export["AxVCpuRef"]
    AxVMRef_Export["AxVMRef"]
end
LibRS["lib.rsMain Library Interface"]
VM["vm.rsAxVM Core Implementation"]
VCPU["vcpu.rsMulti-Architecture VCPU"]
HAL["hal.rsHardware Abstraction Layer"]
CONFIG["config.rsVM Configuration"]

LibRS --> AxVCpuRef_Export
LibRS --> AxVMHal_Export
LibRS --> AxVMRef_Export
LibRS --> AxVM_Export
LibRS --> CONFIG
LibRS --> HAL
LibRS --> VCPU
LibRS --> VM
VM --> CONFIG
VM --> HAL
VM --> VCPU

The main library interface exports the AxVM struct as the primary virtualization abstraction, along with supporting types for hardware abstraction (AxVMHal) and CPU references (AxVCpuRef, AxVMRef). The has_hardware_support() function provides runtime detection of virtualization capabilities.

Sources: src/lib.rs(L6 - L33)  Cargo.toml(L1 - L8) 

Multi-Architecture Support

The axvm hypervisor provides unified virtualization across x86_64, RISC-V, and AArch64 architectures through architecture-specific backend implementations:

Architecture-Specific Backend Structure

The multi-architecture support is implemented through conditional compilation using cfg-if directives. Each architecture provides its own VCPU implementation while conforming to the common AxArchVCpuImpl interface. The AxVMPerCpu type is defined as axvcpu::AxPerCpu<vcpu::AxVMArchPerCpuImpl<U>> to provide per-CPU state management across all supported architectures.

Sources: Cargo.toml(L29 - L36)  src/lib.rs(L26 - L32)  Cargo.toml(L19 - L21) 

Core Capabilities

The axvm hypervisor provides three primary virtualization capabilities through its modular architecture:

VM Lifecycle and State Management

The VM lifecycle is managed through the core AxVM struct, which coordinates virtual CPU execution, handles VM exits for MMIO and I/O operations, and manages the overall VM state transitions.

Sources: src/lib.rs(L9 - L10)  src/lib.rs(L22 - L24) 

ArceOS Ecosystem Integration

The axvm hypervisor integrates deeply with the ArceOS ecosystem through a set of specialized crates that provide system-level abstractions:

Dependency Architecture

flowchart TD
subgraph subGraph3["External Dependencies"]
    log_crate["logLogging framework"]
    cfg_if["cfg-ifConditional compilation"]
    spin["spinSynchronization primitives"]
end
subgraph subGraph2["ArceOS System Crates"]
    axerrno["axerrnoError handling"]
    memory_addr["memory_addrAddress types"]
    page_table_multiarch["page_table_multiarchMulti-arch page tables"]
    page_table_entry["page_table_entryARM EL2 support"]
    percpu["percpuPer-CPU data structures"]
end
subgraph subGraph1["ArceOS Hypervisor Modules"]
    axvcpu["axvcpuVirtual CPU abstraction"]
    axaddrspace["axaddrspaceAddress space management"]
    axdevice["axdeviceDevice emulation framework"]
    axvmconfig["axvmconfigConfiguration management"]
end
subgraph subGraph0["AxVM Core"]
    axvm["axvm crate"]
end

axvm --> axaddrspace
axvm --> axdevice
axvm --> axerrno
axvm --> axvcpu
axvm --> axvmconfig
axvm --> cfg_if
axvm --> log_crate
axvm --> memory_addr
axvm --> page_table_entry
axvm --> page_table_multiarch
axvm --> percpu
axvm --> spin

The crate uses the no_std environment for embedded and kernel-space deployment. All ArceOS hypervisor modules are sourced from the arceos-hypervisor GitHub organization, providing a cohesive ecosystem for virtualization components.

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

The AxVMHal trait provides the hardware abstraction interface that must be implemented by the hosting environment, enabling axvm to run on different underlying platforms while maintaining a consistent virtualization interface.

Sources: src/lib.rs(L21)