VM Management

Relevant source files

Cargo.lock

src/task.rs

src/vmm/config.rs

src/vmm/mod.rs

src/vmm/vcpus.rs

This document describes how virtual machines (VMs) are created, configured, and managed within the AxVisor hypervisor system. It explains the VM lifecycle from initialization through execution to shutdown, as well as the management of virtual CPUs (VCPUs) within each VM. For information about the underlying hardware abstraction layer, see Hardware Abstraction Layer.

VM Architecture Overview

AxVisor implements a modular VM management system that separates VM configuration, execution, and resource management concerns. The core components work together to create, execute, and monitor virtual machines.

flowchart TD
subgraph subGraph1["Task Management"]
    TaskScheduler["ArceOS Task Scheduler"]
    TaskExt["Task Extensions"]
end
subgraph subGraph0["VM Management System"]
    VMM["VMM Module"]
    VMConfig["VM Configuration"]
    VMList["VM List"]
    VCPUManager["VCPU Manager"]
    ImageLoader["Image Loader"]
    VMs["VMs"]
    VCPUs["VCPUs"]
end

ImageLoader --> VMs
TaskExt --> VCPUs
TaskExt --> VMs
VCPUManager --> TaskScheduler
VCPUManager --> VCPUs
VMConfig --> VMs
VMList --> VMs
VMM --> VMConfig
VMM --> VMs
VMs --> VCPUs

Sources: src/vmm/mod.rs src/task.rs

VM Types and References

The VM management system uses specific types to represent VMs and VCPUs:

Type	Description	Source
VM	Instantiated VM type usingaxvm::AxVM<AxVMHalImpl, AxVCpuHalImpl>	src/vmm/mod.rs16
VMRef	VM reference type (shared viaArc)	src/vmm/mod.rs18
VCpuRef	VCPU reference type (shared viaArc)	src/vmm/mod.rs20

These types provide the foundation for VM management operations, with reference types allowing shared access to VM and VCPU resources across different components and tasks.

Sources: src/vmm/mod.rs(L16 - L20)

VM Lifecycle

The VM lifecycle in AxVisor follows a defined sequence of operations, from initialization through execution to shutdown.

Sources: src/vmm/mod.rs(L28 - L65) src/vmm/vcpus.rs(L275 - L367)

VM Initialization

The VMM initializes VMs through the following process:

Call VMM::init() to initialize guest VMs and set up primary VCPUs
Load VM configurations from TOML files
Create VM instances using VM::new()
Load VM images based on configuration
Set up primary VCPUs for each VM

sequenceDiagram
    participant VMM as VMM
    participant ConfigModule as Config Module
    participant VMInstance as VM Instance
    participant VCPUManager as VCPU Manager

    VMM ->> ConfigModule: init_guest_vms()
    ConfigModule ->> ConfigModule: Parse TOML configs
    ConfigModule ->> VMInstance: Create VM with AxVMConfig
    VMInstance -->> ConfigModule: Return VM instance
    ConfigModule ->> ConfigModule: load_vm_images()
    ConfigModule ->> VMM: Return created VMs
    VMM ->> VCPUManager: setup_vm_primary_vcpu() for each VM
    VCPUManager ->> VCPUManager: Create primary VCPU task

Sources: src/vmm/mod.rs(L28 - L39) src/vmm/config.rs(L25 - L43)

VM Execution

The VMM starts VM execution:

Call VMM::start() to boot all VMs
For each VM, call vm.boot() to start execution
Notify the primary VCPU to begin execution
Increment RUNNING_VM_COUNT for each successfully started VM
Wait until all VMs are stopped (when RUNNING_VM_COUNT reaches 0)

VCPUs execute in their own tasks, handling various exit reasons such as hypercalls, interrupts, halts, and system shutdown events.

Sources: src/vmm/mod.rs(L42 - L65) src/vmm/vcpus.rs(L275 - L367)

VM Configuration

AxVisor uses TOML-based configuration files to define VM properties:

Configuration files are stored in configs/vms/ directory
Default configurations are provided for different architectures (x86_64, aarch64, riscv64)
Configurations define VM properties like ID, name, CPU count, memory regions, etc.
Configuration processing involves:

Parsing TOML into AxVMCrateConfig
Converting to AxVMConfig for VM creation
Using configuration to load appropriate VM images

Sources: src/vmm/config.rs(L1 - L43)

VCPU Management

VCPUs are managed for each VM, with special handling for the primary VCPU:

classDiagram
class VMVCpus {
    -usize _vm_id
    -WaitQueue wait_queue
    -Vec~AxTaskRef~ vcpu_task_list
    -AtomicUsize running_halting_vcpu_count
    +new(VMRef) VMVCpus
    +add_vcpu_task(AxTaskRef)
    +wait()
    +wait_until(F)
    +notify_one()
    +mark_vcpu_running()
    +mark_vcpu_exiting() bool
}

class VCPU_Task {
    +stack_size KERNEL_STACK_SIZE
    +TaskExt ext
    +run() vcpu_run
}

class TaskExt {
    +VMRef vm
    +VCpuRef vcpu
    +new(VMRef, VCpuRef) TaskExt
}

VCPU_Task "1" *-- "1" TaskExt : contains
VMVCpus "1" *-- "*" VCPU_Task : manages

Sources: src/vmm/vcpus.rs(L27 - L40) src/task.rs(L6 - L11)