Hardware Abstraction Layer

Relevant source files

src/hal.rs

The Hardware Abstraction Layer (HAL) provides a standardized interface for platform-specific operations that the axvm hypervisor requires from the underlying host system. This abstraction enables axvm to run on different host operating systems and hypervisors by delegating low-level hardware operations to implementations of the AxVMHal trait.

For information about virtual machine lifecycle management, see Virtual Machine Implementation. For details about multi-architecture CPU support, see Virtual CPU Architecture.

AxVMHal Trait Interface

The core of the hardware abstraction layer is the AxVMHal trait, which defines the contract between axvm and the underlying host system. This trait must be implemented by any host system that wants to run axvm virtual machines.

AxVMHal Trait Structure

classDiagram
class AxVMHal {
    <<trait>>
    +PagingHandler: page_table_multiarch::PagingHandler
    +alloc_memory_region_at(base: HostPhysAddr, size: usize) bool
    +dealloc_memory_region_at(base: HostPhysAddr, size: usize)
    +virt_to_phys(vaddr: HostVirtAddr) HostPhysAddr
    +current_time_nanos() u64
}

class PagingHandler {
    <<interface>>
    +page_table_multiarch::PagingHandler
    
}

class HostPhysAddr {
    +axaddrspace::HostPhysAddr
    
}

class HostVirtAddr {
    +axaddrspace::HostVirtAddr
    
}

AxVMHal  -->  PagingHandler : "associated type"
AxVMHal  -->  HostPhysAddr : "uses"
AxVMHal  -->  HostVirtAddr : "uses"

Sources: src/hal.rs(L1 - L22)

Memory Management Abstraction

The HAL provides two primary memory management operations that abstract the underlying host's memory allocation mechanisms:

Method	Purpose	Return Value
alloc_memory_region_at	Allocates memory at a specific physical address	boolindicating success
dealloc_memory_region_at	Deallocates a previously allocated memory region	()

These methods enable axvm to request specific physical memory regions from the host, which is essential for guest physical memory layout and device memory mapping.

Memory Management Flow

sequenceDiagram
    participant AxVM as "AxVM"
    participant AxVMHalImplementation as "AxVMHal Implementation"
    participant HostSystem as "Host System"

    AxVM ->> AxVMHalImplementation: "alloc_memory_region_at(base, size)"
    AxVMHalImplementation ->> HostSystem: "Request physical memory allocation"
    HostSystem -->> AxVMHalImplementation: "Success/failure"
    AxVMHalImplementation -->> AxVM: "bool result"
    Note over AxVM,HostSystem: "VM operation continues..."
    AxVM ->> AxVMHalImplementation: "dealloc_memory_region_at(base, size)"
    AxVMHalImplementation ->> HostSystem: "Release physical memory"
    HostSystem -->> AxVMHalImplementation: "Memory freed"
    AxVMHalImplementation -->> AxVM: "() completion"

Sources: src/hal.rs(L8 - L14)

Address Translation Interface

The virt_to_phys method provides virtual-to-physical address translation, enabling axvm to convert host virtual addresses to their corresponding physical addresses. This is crucial for setting up guest physical memory mappings and ensuring proper memory coherency.

Address Translation Architecture

flowchart TD
subgraph subGraph2["VM Memory Management"]
    GuestPhys["Guest Physical Memory"]
    HostMapping["Host Memory Mapping"]
end
subgraph subGraph1["Page Table Integration"]
    PagingHandler["PagingHandler(page_table_multiarch)"]
    PageTable["Multi-arch Page Tables"]
end
subgraph subGraph0["Address Translation Layer"]
    VirtAddr["HostVirtAddr(axaddrspace)"]
    VirtToPhys["virt_to_phys()"]
    PhysAddr["HostPhysAddr(axaddrspace)"]
end

PagingHandler --> PageTable
PhysAddr --> GuestPhys
VirtAddr --> HostMapping
VirtAddr --> VirtToPhys
VirtToPhys --> PagingHandler
VirtToPhys --> PhysAddr

Sources: src/hal.rs(L16 - L17) src/hal.rs(L6)

Time Management

The HAL provides time services through the current_time_nanos method, which returns the current time in nanoseconds. This enables axvm to implement time-based features such as:

Performance monitoring and profiling
Timeout mechanisms for VM operations
Guest time synchronization
Event scheduling and timing

Sources: src/hal.rs(L19 - L20)

Integration with ArceOS Ecosystem

The HAL interfaces directly with several components from the ArceOS ecosystem:

HAL Ecosystem Integration

flowchart TD
subgraph subGraph3["Host Implementation"]
    HostOS["Host OS/Hypervisor"]
    MemMgmt["Memory Management"]
    TimeService["Time Services"]
end
subgraph subGraph2["Page Table Infrastructure"]
    PageTableMultiarch["page_table_multiarch"]
    PagingHandlerImpl["PagingHandler impl"]
end
subgraph subGraph1["ArceOS Address Space"]
    HostPhysAddr["HostPhysAddr"]
    HostVirtAddr["HostVirtAddr"]
    AddrSpace["axaddrspace"]
end
subgraph subGraph0["AxVM HAL Layer"]
    AxVMHal["AxVMHal trait"]
    PagingType["PagingHandler type"]
end

AddrSpace --> HostPhysAddr
AddrSpace --> HostVirtAddr
AxVMHal --> HostOS
AxVMHal --> HostPhysAddr
AxVMHal --> HostVirtAddr
MemMgmt --> AxVMHal
PagingHandlerImpl --> PagingType
PagingType --> PageTableMultiarch
TimeService --> AxVMHal

The HAL serves as the critical bridge between axvm's hardware-agnostic virtualization logic and the host system's specific capabilities, enabling portability across different host environments while maintaining performance and functionality.