Struct AxVM 

pub struct AxVM<H: AxVMHal, U: AxVCpuHal> { /* private fields */ }

A Virtual Machine.

Implementations

impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U>

pub fn new(config: AxVMConfig) -> AxResult<AxVMRef<H, U>>

Creates a new VM with the given configuration. Returns an error if the configuration is invalid. The VM is not started until boot is called.

pub fn id(&self) -> usize

Returns the VM id.

pub fn init(&self) -> AxResult

Sets up the VM before booting.

pub fn set_vm_status(&self, status: VMStatus)

Sets the VM status.

pub fn vm_status(&self) -> VMStatus

Returns the current VM status.

pub fn vcpu(&self, vcpu_id: usize) -> Option<AxVCpuRef<U>>

Retrieves the vCPU corresponding to the given vcpu_id for the VM. Returns None if the vCPU does not exist.

pub fn vcpu_num(&self) -> usize

Returns the number of vCPUs corresponding to the VM.

pub fn vcpu_list(&self) -> &[AxVCpuRef<U>]

Returns a reference to the list of vCPUs corresponding to the VM.

pub fn ept_root(&self) -> HostPhysAddr

Returns the base address of the two-stage address translation page table for the VM.

pub fn with_config<F, R>(&self, f: F) -> R

where F: FnOnce(&mut AxVMConfig) -> R,

Returns to the VM’s configuration.

pub fn get_image_load_region( &self, image_load_gpa: GuestPhysAddr, image_size: usize, ) -> AxResult<Vec<&'static mut [u8]>>

Returns guest VM image load region in Vec<&'static mut [u8]>, according to the given image_load_gpa and image_size. Vec<&’static mut u8>` is a series of (HVA) address segments, which may correspond to non-contiguous physical addresses,

FIXME: Find a more elegant way to manage potentially non-contiguous physical memory instead of Vec<&'static mut [u8]>.

pub fn boot(&self) -> AxResult

Boots the VM by transitioning to Running state.

pub fn running(&self) -> bool

Returns if the VM is running.

pub fn stopping(&self) -> bool

Returns if the VM is shutting down (in Stopping state).

pub fn suspending(&self) -> bool

Returns if the VM is suspended.

pub fn stopped(&self) -> bool

Returns if the VM is stopped.

pub fn shutdown(&self) -> AxResult

Shuts down the VM by transitioning to Stopping state.

This method sets the VM status to Stopping, which signals all vCPUs to exit. Currently, the “re-init” process of the VM is not implemented. Therefore, a VM can only be booted once. And after the VM is shut down, it cannot be booted again.

pub fn get_devices(&self) -> &AxVmDevices

Returns this VM’s emulated devices.

pub fn run_vcpu(&self, vcpu_id: usize) -> AxResult<AxVCpuExitReason>

Run a vCPU according to the given vcpu_id.

Arguments

• vcpu_id - the id of the vCPU to run.

Returns

• AxVCpuExitReason - the exit reason of the vCPU, wrapped in an AxResult.

pub fn inject_interrupt_to_vcpu( &self, targets: CpuMask<TEMP_MAX_VCPU_NUM>, irq: usize, ) -> AxResult

Injects an interrupt to the vCPU.

pub fn get_vcpu_affinities_pcpu_ids(&self) -> Vec<(usize, Option<usize>, usize)>

Returns vCpu id list and its corresponding pCpu affinity list, as well as its physical id. If the pCpu affinity is None, it means the vCpu will be allocated to any available pCpu randomly. if the pCPU id is not provided, the vCpu’s physical id will be set as vCpu id.

Returns a vector of tuples, each tuple contains:

• The vCpu id.
• The pCpu affinity mask, None if not set.
• The physical id of the vCpu, equal to vCpu id if not provided.

pub fn map_region( &self, gpa: GuestPhysAddr, hpa: HostPhysAddr, size: usize, flags: MappingFlags, ) -> AxResult

Maps a region of host physical memory to guest physical memory.

pub fn unmap_region(&self, gpa: GuestPhysAddr, size: usize) -> AxResult

Unmaps a region of guest physical memory.

pub fn read_from_guest_of<T>(&self, gpa_ptr: GuestPhysAddr) -> AxResult<T>

Reads an object of type T from the guest physical address.

pub fn write_to_guest_of<T>(&self, gpa_ptr: GuestPhysAddr, data: &T) -> AxResult

Writes an object of type T to the guest physical address.

pub fn alloc_ivc_channel( &self, expected_size: usize, ) -> AxResult<(GuestPhysAddr, usize)>

Allocates an IVC channel for inter-VM communication region.

Arguments

• expected_size - The expected size of the IVC channel in bytes.

Returns

• AxResult<(GuestPhysAddr, usize)> - A tuple containing the guest physical address of the allocated IVC channel and its actual size.

pub fn release_ivc_channel(&self, gpa: GuestPhysAddr, size: usize) -> AxResult

Releases an IVC channel for inter-VM communication region.

Arguments

• gpa - The guest physical address of the IVC channel to release.
• size - The size of the IVC channel in bytes.

Returns

• AxResult<()> - An empty result indicating success or failure.

pub fn alloc_memory_region( &self, layout: Layout, gpa: Option<GuestPhysAddr>, ) -> AxResult<&[u8]>

Allocates a new memory region for the VM.

pub fn memory_regions(&self) -> Vec<VMMemoryRegion>

Returns a list of all memory regions in the VM.

pub fn map_reserved_memory_region( &self, layout: Layout, gpa: Option<GuestPhysAddr>, ) -> AxResult<&[u8]>

Maps a reserved memory region for the VM.

Trait Implementations

impl<H: AxVMHal, U: AxVCpuHal> Drop for AxVM<H, U>

fn drop(&mut self)

Executes the destructor for this type.