Dependencies and Integration
Relevant source files
This document explains how the AxVM hypervisor integrates with the ArceOS ecosystem and manages its external dependencies. It covers the modular architecture that enables multi-platform virtualization support and the specific crate dependencies that provide core functionality.
For information about the core VM implementation details, see Virtual Machine Implementation. For architecture-specific virtualization backends, see Virtual CPU Architecture.
ArceOS Ecosystem Integration
AxVM is designed as a core component within the ArceOS hypervisor ecosystem, leveraging specialized crates for different aspects of virtualization. The integration follows a modular design where each major subsystem is provided by a dedicated crate.
Core Hypervisor Dependencies
The primary integration occurs through four key ArceOS-Hypervisor modules that provide the foundational virtualization capabilities:
flowchart TD AXVM["axvmCore Hypervisor"] AXVCPU["axvcpuVirtual CPU Management"] AXADDR["axaddrspaceAddress Space Management"] AXDEV["axdeviceDevice Emulation"] AXCONF["axvmconfigConfiguration Framework"] ARCH_VCPU["Architecture-SpecificvCPU Backends"] PAGETBL["page_table_multiarchMemory Translation"] MMIO["MMIO DeviceImplementations"] TOML["TOML ConfigurationParsing"] AXADDR --> PAGETBL AXCONF --> TOML AXDEV --> MMIO AXVCPU --> ARCH_VCPU AXVM --> AXADDR AXVM --> AXCONF AXVM --> AXDEV AXVM --> AXVCPU
Sources: Cargo.toml(L24 - L27)
Each ArceOS-Hypervisor module serves a specific role in the virtualization stack:
| Crate | Repository | Purpose |
|---|---|---|
| axvcpu | github.com/arceos-hypervisor/axvcpu.git | Provides architecture-agnostic vCPU abstraction and management |
| axaddrspace | github.com/arceos-hypervisor/axaddrspace.git | Handles guest address space management and memory translation |
| axdevice | github.com/arceos-hypervisor/axdevice.git | Implements device emulation and MMIO handling |
| axvmconfig | github.com/arceos-hypervisor/axvmconfig.git | Provides VM configuration parsing and validation |
Sources: Cargo.toml(L24 - L27)
Architecture-Specific Dependencies
AxVM supports multiple hardware architectures through conditional compilation and architecture-specific vCPU backends. This design allows the same codebase to provide native virtualization support across different platforms.
Multi-Architecture Dependency Resolution
flowchart TD
subgraph subGraph1["Architecture Backends"]
X86_VCPU["x86_vcpuIntel VT-x/AMD-V"]
RISCV_VCPU["riscv_vcpuRISC-V H-Extension"]
ARM_VCPU["arm_vcpuARM EL2"]
end
subgraph subGraph0["Target Architecture Selection"]
X86["target_arch = x86_64"]
RISCV["target_arch = riscv64"]
ARM["target_arch = aarch64"]
end
CONFIG["cfg-ifConditional Compilation"]
VTX["VT-x/SVMHardware Features"]
HEXT["HypervisorExtension"]
EL2["Exception Level 2Virtualization"]
ARM --> ARM_VCPU
ARM_VCPU --> EL2
CONFIG --> ARM
CONFIG --> RISCV
CONFIG --> X86
RISCV --> RISCV_VCPU
RISCV_VCPU --> HEXT
X86 --> X86_VCPU
X86_VCPU --> VTX
Sources: Cargo.toml(L29 - L36) Cargo.toml(L12)
The architecture-specific dependencies are resolved at compile time:
| Target Architecture | Crate | Hardware Support |
|---|---|---|
| x86_64 | x86_vcpu | Intel VT-x, AMD-V |
| riscv64 | riscv_vcpu | RISC-V Hypervisor Extension |
| aarch64 | arm_vcpu | ARM Virtualization Extensions (EL2) |
Sources: Cargo.toml(L29 - L36)
System Infrastructure Dependencies
AxVM relies on several ArceOS system-independent crates that provide low-level infrastructure for hypervisor operations.
Memory Management Infrastructure
flowchart TD MEMORY_MGMT["Memory ManagementInfrastructure"] MEMORY_ADDR["memory_addrAddress Abstractions"] PAGE_ENTRY["page_table_entryPage Table Entries"] PAGE_MULTI["page_table_multiarchMulti-arch Page Tables"] PERCPU["percpuPer-CPU Data Storage"] PHYS_ADDR["PhysAddrGuestPhysAddr"] VIRT_ADDR["VirtAddrGuestVirtAddr"] ARM_EL2["ARM EL2Page Entries"] EPT["Extended Page Tables"] NPT["Nested Page Tables"] CPU_STATE["Per-CPU VM State"] VCPU_DATA["vCPU Local Data"] MEMORY_ADDR --> PHYS_ADDR MEMORY_ADDR --> VIRT_ADDR MEMORY_MGMT --> MEMORY_ADDR MEMORY_MGMT --> PAGE_ENTRY MEMORY_MGMT --> PAGE_MULTI MEMORY_MGMT --> PERCPU PAGE_ENTRY --> ARM_EL2 PAGE_MULTI --> EPT PAGE_MULTI --> NPT PERCPU --> CPU_STATE PERCPU --> VCPU_DATA
Sources: Cargo.toml(L18 - L21)
Memory Management Crate Details
| Crate | Version | Features | Purpose |
|---|---|---|---|
| memory_addr | 0.3.1 | - | ProvidesPhysAddr,VirtAddr, and guest address types |
| page_table_entry | 0.5 | arm-el2 | ARM EL2-specific page table entry implementations |
| page_table_multiarch | 0.5 | - | Cross-architecture page table management |
| percpu | 0.2.0 | arm-el2 | Per-CPU data storage with ARM EL2 support |
Sources: Cargo.toml(L18 - L21)
Utility and System Dependencies
AxVM uses several external utility crates for core system functionality including error handling, logging, and synchronization.
External Utility Integration
flowchart TD UTILITIES["System Utilities"] LOG["log v0.4Logging Framework"] SPIN["spin v0.9Synchronization"] CFGIF["cfg-if v1.0Conditional Compilation"] AXERRNO["axerrno v0.1.0Error Handling"] LOG_IMPL["VM Event LoggingDebug Information"] LOCKS["SpinlocksMutex Primitives"] ARCH_SELECT["Architecture SelectionFeature Gates"] ERROR_CODES["Hypervisor Error CodesResult Types"] AXERRNO --> ERROR_CODES CFGIF --> ARCH_SELECT LOG --> LOG_IMPL SPIN --> LOCKS UTILITIES --> AXERRNO UTILITIES --> CFGIF UTILITIES --> LOG UTILITIES --> SPIN
Sources: Cargo.toml(L11 - L16)
Utility Dependency Functions
| Crate | Version | Usage in AxVM |
|---|---|---|
| log | 0.4 | VM event logging, debug output, error reporting |
| spin | 0.9 | Spinlock-based synchronization for VM state |
| cfg-if | 1.0 | Conditional compilation for architecture support |
| axerrno | 0.1.0 | ArceOS-compatible error handling and result types |
Sources: Cargo.toml(L11 - L16)
Feature Configuration
AxVM uses Cargo features to enable optional functionality and architecture-specific optimizations.
Default Feature Set
The hypervisor defines a minimal set of default features focused on x86_64 virtualization:
[features]
default = ["vmx"]
vmx = []
Sources: Cargo.toml(L6 - L8)
The vmx feature enables Intel VT-x and AMD-V support on x86_64 platforms, representing the most common virtualization use case.
Integration Patterns
AxVM follows specific integration patterns that enable clean separation of concerns while maintaining performance and flexibility.
Repository Integration Model
flowchart TD GITHUB["GitHub Organizationarceos-hypervisor"] AXVM_REPO["axvmCore Hypervisor"] AXVCPU_REPO["axvcpuvCPU Abstraction"] AXADDR_REPO["axaddrspaceMemory Management"] AXDEV_REPO["axdeviceDevice Emulation"] AXCONF_REPO["axvmconfigConfiguration"] X86_REPO["x86_vcpux86 Backend"] RISCV_REPO["riscv_vcpuRISC-V Backend"] ARM_REPO["arm_vcpuARM Backend"] AXVCPU_REPO --> ARM_REPO AXVCPU_REPO --> RISCV_REPO AXVCPU_REPO --> X86_REPO AXVM_REPO --> AXADDR_REPO AXVM_REPO --> AXCONF_REPO AXVM_REPO --> AXDEV_REPO AXVM_REPO --> AXVCPU_REPO GITHUB --> ARM_REPO GITHUB --> AXADDR_REPO GITHUB --> AXCONF_REPO GITHUB --> AXDEV_REPO GITHUB --> AXVCPU_REPO GITHUB --> AXVM_REPO GITHUB --> RISCV_REPO GITHUB --> X86_REPO
Sources: Cargo.toml(L24 - L36)
All ArceOS-Hypervisor components are developed in separate repositories under the arceos-hypervisor GitHub organization, enabling independent development cycles while maintaining API compatibility through semantic versioning.