Refactor dependencies and enhance AxVM lifecycle management, remove hal, bump to v0.3.0 (#54)

* refactor: deps git to crates-io

* fix: feature

* refactor: support guest dyn entry

* refactor: add Clone trait to VMImageConfig

* fix: update arm_vcpu branch to 'next'

* add fdt support and add some AxVMConfig impl

* fix fmt bug

* fix bug: when no phys_cpu_ids panic

* add function map_reserved_memory_region (#28)

* add function map_reserved_memory_region

* add passthrough address (#29)

* add pass_through address

 

---------

Co-authored-by: szy <songzhyo@qq.com>

* add VMStatus enum and integrate into AxVM lifecycle management (#31)

* feat: update axerrno to 0.2 (#33)

* feat: update axerrno to 0.2

* fix: clippy

* update toolchain

* update dependencies

* remove `AxVCpuHal`

* remove type parameter on `AxVMInnerMut`

* remove all type parameters

* formatted

* Update riscv_vcpu dependency source (#39)

* fix(riscv): Fix RISC-V vCPU initialization and I/O handling

* chore: Update riscv_vcpu dependency source

* chore: specify axdevice branch and fix code formatting

* docs: add missing documentation comments

* Use local path for merged components (axdevice, axvmconfig)

* update dependencies

* fixes after code merging

* formatted

* fix clippy

* bump version to v0.3.0

* remove `AxVMHal`

---------

Co-authored-by: 周睿 <zrufo747@outlook.com>
Co-authored-by: szy <songzhyo@qq.com>
Co-authored-by: bhxh <32200913+buhenxihuan@users.noreply.github.com>
Co-authored-by: szy <673586548@qq.com>
Co-authored-by: TQ <128586861+YanLien@users.noreply.github.com>
Co-authored-by: 朝倉水希 <asakuramizu111@gmail.com>

Author: 7 people

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "axvm"
 authors = ["aarkegz <aarkegz@gmail.com>"]
-version = "0.2.2"
+version = "0.3.0"
 edition = "2024"
 categories = ["virtualization", "no-std"]
 description = "Virtual Machine resource management crate for ArceOS's hypervisor variant."
@@ -12,12 +12,12 @@ license = "Apache-2.0"
 [features]
 default = ["vmx"]
 vmx = []
-4-level-ept = ["axaddrspace/4-level-ept"]   # TODO: Realize 4-level-ept on x86_64 and riscv64.
+4-level-ept = []   # TODO: Realize 4-level-ept on x86_64 and riscv64.
 
 [dependencies]
 log = "0.4"
 cfg-if = "1.0"
-spin = "0.9"
+spin = "0.10"
 
 # System independent crates provided by ArceOS.
 axerrno = "0.2"
@@ -29,18 +29,19 @@ page_table_multiarch = "0.6"
 percpu = { version = "0.2.0", features = ["arm-el2"] }
 
 # System dependent modules provided by ArceOS-Hypervisor.
-axvcpu = "0.2"
-axaddrspace = "0.1.4"
-axdevice = "0.2.1"
-axdevice_base = "0.2.1"
-axvmconfig = { version = "0.2", default-features = false }
+axvcpu = "0.3"
+axaddrspace = "0.3"
+axvisor_api = "0.3"
+axdevice = "0.2.2"
+axdevice_base = "0.2.2"
+axvmconfig = { version = "0.2.2", default-features = false }
 
 [target.'cfg(target_arch = "x86_64")'.dependencies]
-x86_vcpu = "0.2.1"
+x86_vcpu = "0.3"
 
 [target.'cfg(target_arch = "riscv64")'.dependencies]
-riscv_vcpu = "0.2.1"
+riscv_vcpu = "0.3"
 
 [target.'cfg(target_arch = "aarch64")'.dependencies]
-arm_vcpu = "0.2.1"
-arm_vgic = { version = "0.2.1", features = ["vgicv3"] }
+arm_vcpu = "0.3"
+arm_vgic = { version = "0.2.2", features = ["vgicv3"] }

rust-toolchain.toml

@@ -0,0 +1,10 @@
+[toolchain]
+profile = "minimal"
+channel = "nightly-2025-05-20"
+components = ["rust-src", "llvm-tools", "rustfmt", "clippy"]
+targets = [
+    "x86_64-unknown-none",
+    "riscv64gc-unknown-none-elf",
+    "aarch64-unknown-none-softfloat",
+    "loongarch64-unknown-none-softfloat",
+]

src/hal.rs

@@ -12,39 +12,41 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use axaddrspace::{HostPhysAddr, HostVirtAddr};
-use axerrno::AxResult;
-
-/// The interfaces which the underlying software (kernel or hypervisor) must implement.
-pub trait AxVMHal: Sized {
-    /// The low-level **OS-dependent** helpers that must be provided for physical address management.
-    type PagingHandler: page_table_multiarch::PagingHandler;
-
-    /// Converts a virtual address to the corresponding physical address.
-    fn virt_to_phys(vaddr: HostVirtAddr) -> HostPhysAddr;
-
-    /// Current time in nanoseconds.
-    fn current_time_nanos() -> u64;
-
-    /// Current VM ID.
-    fn current_vm_id() -> usize;
-
-    /// Current Virtual CPU ID.
-    fn current_vcpu_id() -> usize;
-
-    /// Current Physical CPU ID.
-    fn current_pcpu_id() -> usize;
-
-    /// Get the Physical CPU ID where the specified VCPU of the current VM resides.
-    ///
-    /// Returns an error if the VCPU is not found.
-    fn vcpu_resides_on(vm_id: usize, vcpu_id: usize) -> AxResult<usize>;
-
-    /// Inject an IRQ to the specified VCPU.
-    ///
-    /// This method should find the physical CPU where the specified VCPU resides and inject the IRQ
-    /// to it on that physical CPU with [`axvcpu::AxVCpu::inject_interrupt`].
-    ///
-    /// Returns an error if the VCPU is not found.
-    fn inject_irq_to_vcpu(vm_id: usize, vcpu_id: usize, irq: usize) -> AxResult;
+use memory_addr::{PAGE_SIZE_4K, PhysAddr, VirtAddr};
+use page_table_multiarch::PagingHandler;
+
+pub struct PagingHandlerImpl;
+
+impl PagingHandler for PagingHandlerImpl {
+    fn alloc_frames(num: usize, align: usize) -> Option<PhysAddr> {
+        let align_frames = if align.is_multiple_of(PAGE_SIZE_4K) {
+            align / PAGE_SIZE_4K
+        } else {
+            panic!("align must be multiple of PAGE_SIZE_4K")
+        };
+
+        let align_frames_pow2 = if align_frames.is_power_of_two() {
+            align_frames.trailing_zeros()
+        } else {
+            panic!("align must be a power of 2")
+        };
+
+        axvisor_api::memory::alloc_contiguous_frames(num, align_frames_pow2 as _)
+    }
+
+    fn dealloc_frames(paddr: PhysAddr, num: usize) {
+        axvisor_api::memory::dealloc_contiguous_frames(paddr, num);
+    }
+
+    fn alloc_frame() -> Option<PhysAddr> {
+        axvisor_api::memory::alloc_frame()
+    }
+
+    fn dealloc_frame(paddr: PhysAddr) {
+        axvisor_api::memory::dealloc_frame(paddr)
+    }
+
+    fn phys_to_virt(paddr: PhysAddr) -> VirtAddr {
+        axvisor_api::memory::phys_to_virt(paddr)
+    }
 }

src/lib.rs

@@ -33,15 +33,10 @@ mod vm;
 
 pub mod config;
 
-pub use hal::AxVMHal;
-pub use vm::AxVCpuRef;
-pub use vm::AxVM;
-pub use vm::AxVMRef;
-pub use vm::VMMemoryRegion;
-pub use vm::VMStatus;
+pub use vm::{AxVCpuRef, AxVM, AxVMRef, VMMemoryRegion, VMStatus};
 
 /// The architecture-independent per-CPU type.
-pub type AxVMPerCpu<U> = axvcpu::AxPerCpu<vcpu::AxVMArchPerCpuImpl<U>>;
+pub type AxVMPerCpu = axvcpu::AxPerCpu<vcpu::AxVMArchPerCpuImpl>;
 
 /// Whether the hardware has virtualization support.
 pub fn has_hardware_support() -> bool {

src/vm.rs

@@ -18,46 +18,46 @@ use alloc::sync::Arc;
 use alloc::vec::Vec;
 use axaddrspace::HostVirtAddr;
 use axerrno::{AxError, AxResult, ax_err, ax_err_type};
+use axvisor_api::vmm::InterruptVector;
 use core::alloc::Layout;
 use core::fmt;
 use memory_addr::{align_down_4k, align_up_4k};
 use spin::{Mutex, Once};
 
 use axaddrspace::{AddrSpace, GuestPhysAddr, HostPhysAddr, MappingFlags, device::AccessWidth};
 use axdevice::{AxVmDeviceConfig, AxVmDevices};
-use axvcpu::{AxVCpu, AxVCpuExitReason, AxVCpuHal};
+use axvcpu::{AxVCpu, AxVCpuExitReason};
 use cpumask::CpuMask;
 
 use crate::config::{AxVMConfig, PhysCpuList};
+use crate::hal::PagingHandlerImpl;
+use crate::has_hardware_support;
 use crate::vcpu::AxArchVCpuImpl;
-use crate::{AxVMHal, has_hardware_support};
 
-#[cfg(target_arch = "riscv64")]
+#[cfg(not(target_arch = "x86_64"))]
 use crate::vcpu::AxVCpuCreateConfig;
+
 #[cfg(target_arch = "aarch64")]
-use crate::vcpu::{AxVCpuCreateConfig, get_sysreg_device};
+use crate::vcpu::get_sysreg_device;
 
 const VM_ASPACE_BASE: usize = 0x0;
 const VM_ASPACE_SIZE: usize = 0x7fff_ffff_f000;
 
 /// A vCPU with architecture-independent interface.
-#[allow(type_alias_bounds)]
-type VCpu<U: AxVCpuHal> = AxVCpu<AxArchVCpuImpl<U>>;
+type VCpu = AxVCpu<AxArchVCpuImpl>;
 /// A reference to a vCPU.
-#[allow(type_alias_bounds)]
-pub type AxVCpuRef<U: AxVCpuHal> = Arc<VCpu<U>>;
+pub type AxVCpuRef = Arc<VCpu>;
 /// A reference to a VM.
-#[allow(type_alias_bounds)]
-pub type AxVMRef<H: AxVMHal, U: AxVCpuHal> = Arc<AxVM<H, U>>; // we know the bound is not enforced here, we keep it for clarity
+pub type AxVMRef = Arc<AxVM>;
 
-struct AxVMInnerConst<U: AxVCpuHal> {
+struct AxVMInnerConst {
     phys_cpu_ls: PhysCpuList,
-    vcpu_list: Box<[AxVCpuRef<U>]>,
+    vcpu_list: Box<[AxVCpuRef]>,
     devices: AxVmDevices,
 }
 
-unsafe impl<U: AxVCpuHal> Send for AxVMInnerConst<U> {}
-unsafe impl<U: AxVCpuHal> Sync for AxVMInnerConst<U> {}
+unsafe impl Send for AxVMInnerConst {}
+unsafe impl Sync for AxVMInnerConst {}
 
 /// Represents a memory region in a virtual machine.
 #[derive(Debug, Clone)]
@@ -84,13 +84,12 @@ impl VMMemoryRegion {
     }
 }
 
-struct AxVMInnerMut<H: AxVMHal> {
+struct AxVMInnerMut {
     // Todo: use more efficient lock.
-    address_space: AddrSpace<H::PagingHandler>,
+    address_space: AddrSpace<PagingHandlerImpl>,
     memory_regions: Vec<VMMemoryRegion>,
     config: AxVMConfig,
     vm_status: VMStatus,
-    _marker: core::marker::PhantomData<H>,
 }
 
 /// VM status enumeration representing the lifecycle states of a virtual machine
@@ -145,19 +144,20 @@ impl fmt::Display for VMStatus {
 const TEMP_MAX_VCPU_NUM: usize = 64;
 
 /// A Virtual Machine.
-pub struct AxVM<H: AxVMHal, U: AxVCpuHal> {
+pub struct AxVM {
     id: usize,
-    inner_const: Once<AxVMInnerConst<U>>,
-    inner_mut: Mutex<AxVMInnerMut<H>>,
+    inner_const: Once<AxVMInnerConst>,
+    inner_mut: Mutex<AxVMInnerMut>,
 }
 
-impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
+impl AxVM {
     /// 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 new(config: AxVMConfig) -> AxResult<AxVMRef<H, U>> {
+    pub fn new(config: AxVMConfig) -> AxResult<AxVMRef> {
         let address_space =
-            AddrSpace::new_empty(GuestPhysAddr::from(VM_ASPACE_BASE), VM_ASPACE_SIZE)?;
+            // TODO: read level from config
+            AddrSpace::new_empty(4, GuestPhysAddr::from(VM_ASPACE_BASE), VM_ASPACE_SIZE)?;
 
         let result = Arc::new(Self {
             id: config.id(),
@@ -167,7 +167,6 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
                 config,
                 memory_regions: Vec::new(),
                 vm_status: VMStatus::Loading,
-                _marker: core::marker::PhantomData,
             }),
         });
 
@@ -189,7 +188,7 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
         let dtb_addr = inner_mut.config.image_config().dtb_load_gpa;
         let vcpu_id_pcpu_sets = inner_mut.config.phys_cpu_ls.get_vcpu_affinities_pcpu_ids();
 
-        info!("dtb_load_gpa: {:?}", dtb_addr);
+        info!("dtb_load_gpa: {dtb_addr:?}");
         debug!("id: {}, VCpuIdPCpuSets: {vcpu_id_pcpu_sets:#x?}", self.id());
 
         let mut vcpu_list = Vec::with_capacity(vcpu_id_pcpu_sets.len());
@@ -205,6 +204,10 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
                 dtb_addr: dtb_addr.unwrap_or_default().as_usize(),
             };
 
+            // FIXME: VCpu is neither `Send` nor `Sync` by design, check whether
+            // 1. we should make it `Send` and `Sync`, or
+            // 2. we can guarantee that no cross-thread access is performed
+            #[allow(clippy::arc_with_non_send_sync)]
             vcpu_list.push(Arc::new(VCpu::new(
                 self.id(),
                 vcpu_id,
@@ -278,14 +281,10 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
             )?;
         }
 
-        #[cfg(target_arch = "aarch64")]
+        #[cfg_attr(not(target_arch = "aarch64"), expect(unused_mut))]
         let mut devices = axdevice::AxVmDevices::new(AxVmDeviceConfig {
             emu_configs: inner_mut.config.emu_devices().to_vec(),
         });
-        #[cfg(not(target_arch = "aarch64"))]
-        let devices = axdevice::AxVmDevices::new(AxVmDeviceConfig {
-            emu_configs: inner_mut.config.emu_devices().to_vec(),
-        });
 
         #[cfg(target_arch = "aarch64")]
         {
@@ -346,6 +345,9 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
                     passthrough_timer: passthrough,
                 }
             };
+            #[cfg(not(target_arch = "aarch64"))]
+            #[allow(clippy::let_unit_value)]
+            let setup_config = <AxArchVCpuImpl as axvcpu::AxArchVCpu>::SetupConfig::default();
 
             let entry = if vcpu.id() == 0 {
                 inner_mut.config.bsp_entry()
@@ -358,10 +360,7 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
             vcpu.setup(
                 entry,
                 inner_mut.address_space.page_table_root(),
-                #[cfg(target_arch = "aarch64")]
                 setup_config,
-                #[cfg(not(target_arch = "aarch64"))]
-                (),
             )?;
         }
         info!("VM setup: id={}", self.id());
@@ -383,7 +382,7 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
     /// Retrieves the vCPU corresponding to the given vcpu_id for the VM.
     /// Returns None if the vCPU does not exist.
     #[inline]
-    pub fn vcpu(&self, vcpu_id: usize) -> Option<AxVCpuRef<U>> {
+    pub fn vcpu(&self, vcpu_id: usize) -> Option<AxVCpuRef> {
         self.vcpu_list().get(vcpu_id).cloned()
     }
 
@@ -393,15 +392,15 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
         self.inner_const().vcpu_list.len()
     }
 
-    fn inner_const(&self) -> &AxVMInnerConst<U> {
+    fn inner_const(&self) -> &AxVMInnerConst {
         self.inner_const
             .get()
             .expect("VM inner_const not initialized")
     }
 
     /// Returns a reference to the list of vCPUs corresponding to the VM.
     #[inline]
-    pub fn vcpu_list(&self) -> &[AxVCpuRef<U>] {
+    pub fn vcpu_list(&self) -> &[AxVCpuRef] {
         &self.inner_const().vcpu_list
     }
 
@@ -594,13 +593,12 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
         // It is not supported to inject interrupt to a vcpu in another VM yet.
         //
         // It may be supported in the future, as a essential feature for cross-VM communication.
-        if H::current_vm_id() != self.id() {
+        let current_running_vm = axvisor_api::vmm::current_vm_id();
+        if current_running_vm != vm_id {
             panic!("Injecting interrupt to a vcpu in another VM is not supported");
         }
 
-        for target_vcpu in &targets {
-            H::inject_irq_to_vcpu(vm_id, target_vcpu, irq)?;
-        }
+        axvisor_api::vmm::inject_interrupt_to_cpus(vm_id, targets, irq as InterruptVector);
 
         Ok(())
     }
@@ -757,7 +755,7 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
         let s = unsafe { core::slice::from_raw_parts_mut(hva, layout.size()) };
         let hva = HostVirtAddr::from_mut_ptr_of(hva);
 
-        let hpa = H::virt_to_phys(hva);
+        let hpa = axvisor_api::memory::virt_to_phys(hva);
 
         let gpa = gpa.unwrap_or_else(|| hpa.as_usize().into());
 
@@ -923,7 +921,7 @@ impl<H: AxVMHal, U: AxVCpuHal> AxVM<H, U> {
     }
 }
 
-impl<H: AxVMHal, U: AxVCpuHal> Drop for AxVM<H, U> {
+impl Drop for AxVM {
     fn drop(&mut self) {
         info!("Dropping VM[{}]", self.id());