Configuration System

Relevant source files

src/config.rs

This document covers the AxVM hypervisor's configuration system, which manages VM setup parameters including CPU allocation, memory regions, device configurations, and image load addresses. The configuration system transforms TOML configuration files into structured data that drives VM creation and initialization.

For information about the VM creation process that uses these configurations, see Virtual Machine Implementation. For details about hardware abstraction interfaces, see Hardware Abstraction Layer.

Configuration Flow Overview

The configuration system follows a two-stage transformation process: external TOML configuration files are first parsed into raw configuration structures, then converted to internal VM configuration objects used during VM creation.

flowchart TD
subgraph subGraph1["Processed Configuration (axvm)"]
    VMConfig["AxVMConfig"]
    CPUConfig["cpu_config: AxVCpuConfig"]
    ImageConfig["image_config: VMImageConfig"]
    MemConfig["memory_regions: Vec"]
    EmuDevices["emu_devices: Vec"]
    PassDevices["pass_through_devices: Vec"]
end
subgraph subGraph0["Raw Configuration (axvmconfig crate)"]
    CrateConfig["AxVMCrateConfig"]
    BaseConfig["base: VM metadata"]
    KernelConfig["kernel: Image addresses"]
    DeviceConfig["devices: Device setup"]
end
TOML["TOML Configuration File"]
VMCreation["AxVM::new(config)"]
AddressSpace["Address Space Setup"]
VCPUSetup["vCPU Creation"]
DeviceSetup["Device Initialization"]

CrateConfig --> BaseConfig
CrateConfig --> DeviceConfig
CrateConfig --> KernelConfig
CrateConfig --> VMConfig
TOML --> CrateConfig
VMConfig --> CPUConfig
VMConfig --> EmuDevices
VMConfig --> ImageConfig
VMConfig --> MemConfig
VMConfig --> PassDevices
VMConfig --> VMCreation
VMCreation --> AddressSpace
VMCreation --> DeviceSetup
VMCreation --> VCPUSetup

Sources: src/config.rs(L1 - L12) src/config.rs(L63 - L87)

Configuration Structure Hierarchy

The configuration system defines several interconnected structures that represent different aspects of VM setup. The main configuration object AxVMConfig aggregates specialized configuration components.

classDiagram
class AxVMConfig {
    -id: usize
    -name: String
    -vm_type: VMType
    -cpu_num: usize
    -phys_cpu_ids: Option~Vec~usize~~
    -phys_cpu_sets: Option~Vec~usize~~
    -cpu_config: AxVCpuConfig
    -image_config: VMImageConfig
    -memory_regions: Vec~VmMemConfig~
    -emu_devices: Vec~EmulatedDeviceConfig~
    -pass_through_devices: Vec~PassThroughDeviceConfig~
    +id() usize
    +name() String
    +get_vcpu_affinities_pcpu_ids() Vec~(usize, Option~usize~, usize) ~
    +bsp_entry() GuestPhysAddr
    +ap_entry() GuestPhysAddr
    +memory_regions() Vec~VmMemConfig~
    +emu_devices() Vec~EmulatedDeviceConfig~
    +pass_through_devices() Vec~PassThroughDeviceConfig~
}

class AxVCpuConfig {
    +bsp_entry: GuestPhysAddr
    +ap_entry: GuestPhysAddr
    
}

class VMImageConfig {
    +kernel_load_gpa: GuestPhysAddr
    +bios_load_gpa: Option~GuestPhysAddr~
    +dtb_load_gpa: Option~GuestPhysAddr~
    +ramdisk_load_gpa: Option~GuestPhysAddr~
    
}

class AxVMCrateConfig {
    +base: BaseConfig
    +kernel: KernelConfig
    +devices: DeviceConfig
    
}

AxVMConfig  *--  AxVCpuConfig
AxVMConfig  *--  VMImageConfig
AxVMConfig  ..>  AxVMCrateConfig : "From trait"

Sources: src/config.rs(L24 - L31) src/config.rs(L34 - L44) src/config.rs(L47 - L61)

Configuration Transformation Process

The From<AxVMCrateConfig> trait implementation handles the conversion from raw TOML-derived configuration to the internal VM configuration format. This transformation maps external configuration fields to internal structures and converts address types to GuestPhysAddr.

Key Transformation Steps

Source Field	Target Field	Transformation
cfg.base.id	id	Direct assignment
cfg.base.name	name	Direct assignment
cfg.base.cpu_num	cpu_num	Direct assignment
cfg.kernel.entry_point	cpu_config.bsp_entry	GuestPhysAddr::from()
cfg.kernel.kernel_load_addr	image_config.kernel_load_gpa	GuestPhysAddr::from()
cfg.kernel.bios_load_addr	image_config.bios_load_gpa	Option::map(GuestPhysAddr::from)
cfg.devices.emu_devices	emu_devices	Direct assignment

Sources: src/config.rs(L63 - L87)

CPU Configuration

The CPU configuration system manages virtual CPU allocation, entry points, and physical CPU affinity mapping. The AxVCpuConfig structure defines entry addresses for both Bootstrap Processor (BSP) and Application Processor (AP) initialization.

vCPU Affinity Management

The get_vcpu_affinities_pcpu_ids method returns CPU mapping information as tuples containing:

vCPU ID (0 to cpu_num-1)
Physical CPU affinity mask (optional bitmap)
Physical CPU ID (defaults to vCPU ID if not specified)

flowchart TD
subgraph subGraph0["CPU Configuration"]
    CPUNum["cpu_num: usize"]
    VCPUIDs["vCPU IDs: 0..cpu_num"]
    PhysCPUIDs["phys_cpu_ids: Option>"]
    PhysIDs["Physical IDs mapping"]
    PhysCPUSets["phys_cpu_sets: Option>"]
    AffinityMask["Affinity bitmasks"]
    TupleGen["get_vcpu_affinities_pcpu_ids()"]
    Result["Vec<(vcpu_id, affinity_mask, phys_id)>"]
end

AffinityMask --> TupleGen
CPUNum --> VCPUIDs
PhysCPUIDs --> PhysIDs
PhysCPUSets --> AffinityMask
PhysIDs --> TupleGen
TupleGen --> Result
VCPUIDs --> TupleGen

Sources: src/config.rs(L24 - L31) src/config.rs(L108 - L124)

Memory Configuration

Memory configuration defines the guest physical memory layout through a vector of VmMemConfig structures. Each memory region specifies mapping type, guest physical address ranges, and access permissions.

The VMImageConfig structure manages load addresses for different VM image components:

Image Component	Configuration Field	Purpose
Kernel	kernel_load_gpa	Main kernel image load address
BIOS	bios_load_gpa	Optional BIOS/firmware load address
Device Tree	dtb_load_gpa	Optional device tree blob address
Ramdisk	ramdisk_load_gpa	Optional initial ramdisk address

Sources: src/config.rs(L34 - L44) src/config.rs(L144 - L146)

Device Configuration

The device configuration system supports two types of devices: emulated devices and passthrough devices. Device configurations are stored in separate vectors and accessed through dedicated getter methods.

flowchart TD
subgraph subGraph1["External Types (axvmconfig)"]
    EmulatedDeviceConfig["EmulatedDeviceConfig"]
    PassThroughDeviceConfig["PassThroughDeviceConfig"]
end
subgraph subGraph0["Device Configuration"]
    DeviceConfig["devices section (TOML)"]
    EmuDevices["emu_devices: Vec"]
    PassDevices["passthrough_devices: Vec"]
    EmuGetter["emu_devices() getter"]
    PassGetter["pass_through_devices() getter"]
    VMSetup["VM Device Setup"]
end

DeviceConfig --> EmuDevices
DeviceConfig --> PassDevices
EmuDevices --> EmuGetter
EmuDevices --> EmulatedDeviceConfig
EmuGetter --> VMSetup
PassDevices --> PassGetter
PassDevices --> PassThroughDeviceConfig
PassGetter --> VMSetup

Sources: src/config.rs(L9 - L12) src/config.rs(L149 - L156)

Configuration Usage in VM Creation

The AxVMConfig object serves as the primary input to VM creation, providing all necessary parameters for initializing VM components. The configuration system exposes specific getter methods that VM creation logic uses to access different configuration aspects.

Configuration Access Methods

The configuration provides specialized accessor methods for different VM subsystems:

bsp_entry() / ap_entry(): CPU entry points for processor initialization
image_config(): Image load addresses for kernel and auxiliary components
memory_regions(): Memory layout and mapping configuration
emu_devices() / pass_through_devices(): Device configuration for emulation and passthrough
get_vcpu_affinities_pcpu_ids(): CPU affinity and physical mapping information

Sources: src/config.rs(L126 - L156)

AxVisor Crates Book