Dependencies and Integration

Relevant source files

• Cargo.toml

This document explains the axvcpu crate's external dependencies and how it integrates with the ArceOS hypervisor ecosystem. It covers the four core dependencies (axerrno, memory_addr, percpu, axaddrspace) and describes the integration patterns that enable axvcpu to function as a virtualization abstraction layer.

For information about the actual VCPU management functionality, see Core VCPU Management. For details about testing and CI processes, see Testing and Continuous Integration.

Dependency Architecture

The axvcpu crate relies on four core dependencies that provide foundational abstractions for error handling, memory management, per-CPU operations, and address space management.

Dependency Graph

flowchart TD
subgraph subGraph1["axvcpu Core Modules"]
    lib_rs["lib.rs"]
    vcpu_rs["vcpu.rs"]
    exit_rs["exit.rs"]
    arch_vcpu_rs["arch_vcpu.rs"]
    hal_rs["hal.rs"]
    percpu_rs["percpu.rs"]
end
subgraph subGraph0["External Crates"]
    axerrno["axerrnov0.1.0"]
    memory_addr["memory_addrv0.3.1"]
    percpu_crate["percpuv0.2.0"]
    axaddrspace["axaddrspacegit dependency"]
end

axaddrspace --> lib_rs
axerrno --> lib_rs
hal_rs --> axaddrspace
lib_rs --> arch_vcpu_rs
lib_rs --> exit_rs
lib_rs --> hal_rs
lib_rs --> percpu_rs
lib_rs --> vcpu_rs
memory_addr --> lib_rs
percpu_crate --> lib_rs
percpu_rs --> percpu_crate
vcpu_rs --> arch_vcpu_rs
vcpu_rs --> exit_rs

Sources: Cargo.toml(L7 - L12) 

Core Dependencies Analysis

Error Handling Foundation - axerrno

The axerrno crate provides standardized error handling across the ArceOS ecosystem. axvcpu uses this for:

Memory Abstractions - memory_addr

The memory_addr crate provides type-safe memory address abstractions used throughout the VCPU management system:

flowchart TD
subgraph subGraph1["axvcpu Usage"]
    exit_handling["Exit Handling"]
    mmio_ops["MMIO Operations"]
    guest_memory["Guest Memory"]
    host_memory["Host Memory"]
end
subgraph subGraph0["memory_addr Types"]
    VirtAddr["VirtAddr"]
    PhysAddr["PhysAddr"]
    Page["Page"]
    Frame["Frame"]
end

Frame --> host_memory
Page --> guest_memory
PhysAddr --> guest_memory
PhysAddr --> host_memory
VirtAddr --> exit_handling
VirtAddr --> mmio_ops

Sources: Cargo.toml(L9) 

Per-CPU State Management - percpu

The percpu crate enables efficient per-CPU variable management, critical for hypervisor operations where each physical CPU core needs isolated virtualization state:

Address Space Integration - axaddrspace

The axaddrspace dependency is a git-based dependency providing address space management abstractions specifically designed for the ArceOS hypervisor:

flowchart TD
subgraph subGraph1["axvcpu Integration Points"]
    AxVCpuHal["AxVCpuHal trait"]
    hal_impl["hal.rs implementation"]
    guest_mappings["Guest Memory Mappings"]
    host_mappings["Host Memory Mappings"]
end
subgraph subGraph0["axaddrspace Abstractions"]
    AddrSpace["AddrSpace"]
    Mapping["Mapping"]
    Permission["Permission"]
    MemBackend["MemBackend"]
end

AddrSpace --> AxVCpuHal
AxVCpuHal --> hal_impl
Mapping --> hal_impl
MemBackend --> host_mappings
Permission --> guest_mappings
hal_impl --> guest_mappings
hal_impl --> host_mappings

Sources: Cargo.toml(L12) 

Integration Architecture

Trait-Based Integration Pattern

axvcpu uses trait-based abstractions to integrate with its dependencies while maintaining architectural independence:

flowchart TD
subgraph subGraph2["Implementation Layer"]
    arch_impl["Architecture implementations"]
    hal_impl["HAL implementations"]
    percpu_impl["Per-CPU implementations"]
end
subgraph subGraph1["axvcpu Trait Definitions"]
    AxArchVCpu["AxArchVCpu trait"]
    AxVCpuHal["AxVCpuHal trait"]
    AxPerCpu["AxPerCpu trait"]
end
subgraph subGraph0["Dependency Traits"]
    ErrorTrait["axerrno::AxResult"]
    AddrTrait["memory_addr::VirtAddr"]
    PerCpuTrait["percpu::PerCpu"]
    SpaceTrait["axaddrspace::AddrSpace"]
end

AddrTrait --> AxArchVCpu
AxArchVCpu --> arch_impl
AxPerCpu --> percpu_impl
AxVCpuHal --> hal_impl
ErrorTrait --> AxArchVCpu
ErrorTrait --> AxVCpuHal
PerCpuTrait --> AxPerCpu
SpaceTrait --> AxVCpuHal

Sources: Cargo.toml(L7 - L12) 

Build System Integration

The Cargo.toml configuration establishes the integration foundation:

The git dependency on axaddrspace indicates tight coupling with the ArceOS hypervisor ecosystem, while the semantic versioned dependencies provide stable foundations.

Ecosystem Integration Patterns

ArceOS Hypervisor Integration

flowchart TD
subgraph subGraph2["Supporting Ecosystem"]
    axaddrspace_sys["axaddrspace system"]
    error_system["axerrno error system"]
    percpu_system["percpu management"]
end
subgraph subGraph1["axvcpu Interface"]
    AxVCpu["AxVCpu"]
    AxVCpuExitReason["AxVCpuExitReason"]
    vcpu_state["VCpu state machine"]
end
subgraph subGraph0["ArceOS Hypervisor"]
    hypervisor["Hypervisor Core"]
    vm_manager["VM Manager"]
    scheduler["VCPU Scheduler"]
end

AxVCpu --> AxVCpuExitReason
AxVCpu --> axaddrspace_sys
AxVCpu --> error_system
AxVCpu --> percpu_system
AxVCpu --> vcpu_state
hypervisor --> AxVCpu
scheduler --> AxVCpu
vm_manager --> AxVCpu

Multi-Architecture Support Integration

The dependency structure enables cross-platform virtualization support:

Sources: Cargo.toml(L1 - L12) 

Version Management and Compatibility

The dependency version strategy ensures compatibility across the ArceOS ecosystem:

• Stable dependencies: axerrno, memory_addr, percpu use semantic versioning for API stability
• Ecosystem dependency: axaddrspace uses git dependency for coordinated development
• Edition alignment: All components target Rust 2024 edition for language feature consistency

This integration architecture enables axvcpu to provide a stable virtualization abstraction while leveraging specialized components for error handling, memory management, and per-CPU operations within the broader ArceOS hypervisor ecosystem.

Sources: Cargo.toml(L1 - L12)