Safe Rust API

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

Author: mxpv

README.md

@@ -11,7 +11,7 @@
 Build virtualization solutions on top of a lightweight hypervisor using Rust:
 - Full Hypervisor Framework support.
 - Supports Apple Silicon.
-- Rusty API.
+- Safe Rust API.
 
 This repository contains the following crates:
 | Name | Description | Links |
@@ -56,21 +56,20 @@ otherwise `bindgen` may fail to find Hypervisor headers.
 Here is basic "Hello world" example on Apple Silicon:
 ```rust
 // Init VM
-hv::Vm::create_vm(ptr::null_mut())?;
+let vm = Arc::new(hv::Vm::new(std::ptr::null_mut())?);
 
 // Initialize guest memory
-hv::Vm::map(load_addr, GUEST_ADDR as _, MEM_SIZE as _, hv::Memory::READ)?;
+vm.map(load_addr, GUEST_ADDR, MEM_SIZE, hv::Memory::READ)?;
 
 // Create VCPU
-let cpu = hv::Vm::create_cpu()?;
+let cpu = vm.create_cpu()?;
 
 // Set regs
-cpu.set_reg(Reg::PC, GUEST_ADDR)?;
-cpu.set_reg(Reg::X1, GUEST_RESULT_ADDR)?;
+cpu.set_reg(Reg::PC, GUEST_ADDR)?
+cpu.set_reg(Reg::X1, GUEST_RESULT_ADDR)?
 
-// Run CPU
 loop {
-    cpu.run()?;
+    cpu.run().expect("Failed to run CPU");
 
     let info = cpu.exit_info();
     println!("{:?}", info);

hv/README.md

@@ -10,7 +10,7 @@
 Build virtualization solutions on top of a lightweight hypervisor using Rust:
 - Full Hypervisor Framework support.
 - Supports Apple Silicon.
-- Rusty API.
+- Safe Rust API.
 
 Please also see the [repository](https://github.com/mxpv/hv) for latest changes and updates.
 
@@ -43,28 +43,27 @@ otherwise `bindgen` may fail to find Hypervisor headers.
 
 ## Usage
 
-This crate uses [hv-sys]()
+This crate uses [hv-sys](https://crates.io/crates/hv-sys)
 
 ## Example
 
 Here is basic "Hello world" example on Apple Silicon:
 ```rust
 // Init VM
-hv::Vm::create_vm(ptr::null_mut())?;
+let vm = Arc::new(hv::Vm::new(std::ptr::null_mut())?);
 
 // Initialize guest memory
-hv::Vm::map(load_addr, GUEST_ADDR as _, MEM_SIZE as _, hv::Memory::READ)?;
+vm.map(load_addr, GUEST_ADDR, MEM_SIZE, hv::Memory::READ)?;
 
 // Create VCPU
-let cpu = hv::Vm::create_cpu()?;
+let cpu = vm.create_cpu()?;
 
 // Set regs
-cpu.set_reg(Reg::PC, GUEST_ADDR)?;
-cpu.set_reg(Reg::X1, GUEST_RESULT_ADDR)?;
+cpu.set_reg(Reg::PC, GUEST_ADDR)?
+cpu.set_reg(Reg::X1, GUEST_RESULT_ADDR)?
 
-// Run CPU
 loop {
-    cpu.run()?;
+    cpu.run().expect("Failed to run CPU");
 
     let info = cpu.exit_info();
     println!("{:?}", info);

hv/examples/as.rs

@@ -28,6 +28,8 @@ const GUEST_RESULT_ADDR: usize = GUEST_ADDR + RESULT_OFFSET;
 #[cfg(target_arch = "aarch64")]
 use hv::arm64::{Reg, VcpuExt};
 
+use std::sync::Arc;
+
 #[cfg(target_arch = "aarch64")]
 fn main() -> Result<(), hv::Error> {
     let load_addr = unsafe {
@@ -50,19 +52,18 @@ fn main() -> Result<(), hv::Error> {
     }
 
     // Init VM
-    hv::Vm::create_vm(std::ptr::null_mut()).expect("Failed to create VM");
+    let vm = Arc::new(hv::Vm::new(std::ptr::null_mut())?);
 
     // Initialize guest memory
-    hv::Vm::map(
+    vm.map(
         load_addr,
         GUEST_ADDR as _,
         MEM_SIZE as _,
         hv::Memory::READ | hv::Memory::WRITE | hv::Memory::EXEC,
-    )
-    .expect("Failed to map guest memory");
+    )?;
 
     // Create VCPU
-    let cpu = hv::Vm::create_cpu().expect("Failed to create CPU");
+    let cpu = vm.create_cpu()?;
 
     // Set regs
     cpu.set_reg(Reg::PC, GUEST_ADDR as _)
@@ -86,10 +87,6 @@ fn main() -> Result<(), hv::Error> {
     println!("Result: {}", result);
     assert_eq!(result, 3);
 
-    drop(cpu);
-
-    hv::Vm::destroy()?;
-
     Ok(())
 }
 

hv/examples/caps.rs

@@ -2,17 +2,15 @@
 fn main() -> Result<(), hv::Error> {
     use hv::x86::{Capability, VmExt, VmOptions};
 
-    hv::Vm::create_vm(VmOptions::default())?;
+    let vm = hv::Vm::new(VmOptions::default())?;
 
-    println!("Max vCPUs: {}", hv::Vm::capability(Capability::VcpuMax)?);
+    println!("Max vCPUs: {}", vm.capability(Capability::VcpuMax)?);
 
     println!(
         "Available address spaces: {}",
-        hv::Vm::capability(Capability::AddrSpaceMax)?
+        vm.capability(Capability::AddrSpaceMax)?
     );
 
-    hv::Vm::destroy()?;
-
     Ok(())
 }
 

hv/src/arm64/mod.rs

@@ -77,19 +77,19 @@ impl VcpuExt for Vcpu {
     /// Returns the current value of a vCPU register.
     fn get_reg(&self, reg: regs::Reg) -> Result<u64, Error> {
         let mut out = 0_u64;
-        call!(sys::hv_vcpu_get_reg(self.cpu, reg as _, &mut out))?;
+        call!(sys::hv_vcpu_get_reg(self.id, reg as _, &mut out))?;
         Ok(out)
     }
 
     /// Sets the value of a vCPU register.
     fn set_reg(&self, reg: regs::Reg, value: u64) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_reg(self.cpu, reg as _, value))
+        call!(sys::hv_vcpu_set_reg(self.id, reg as _, value))
     }
 
     /// Returns the current value of a vCPU SIMD & FP register.
     fn get_simd_fp_reg(&self, reg: regs::SimdFpReg) -> Result<regs::SimdFpUchar16, Error> {
         let mut out = 0_u128;
-        call!(sys::hv_vcpu_get_simd_fp_reg(self.cpu, reg as _, &mut out))?;
+        call!(sys::hv_vcpu_get_simd_fp_reg(self.id, reg as _, &mut out))?;
         Ok(out)
     }
 
@@ -99,35 +99,35 @@ impl VcpuExt for Vcpu {
         reg: regs::SimdFpReg,
         value: regs::SimdFpUchar16,
     ) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_simd_fp_reg(self.cpu, reg as _, value))?;
+        call!(sys::hv_vcpu_set_simd_fp_reg(self.id, reg as _, value))?;
         Ok(())
     }
 
     /// Returns the current value of a vCPU system register.
     fn get_sys_reg(&self, reg: regs::SysReg) -> Result<u64, Error> {
         let mut out = 0_u64;
-        call!(sys::hv_vcpu_get_sys_reg(self.cpu, reg as _, &mut out))?;
+        call!(sys::hv_vcpu_get_sys_reg(self.id, reg as _, &mut out))?;
         Ok(out)
     }
 
     /// Sets the value of a vCPU system register.
     fn set_sys_reg(&self, reg: regs::SysReg, value: u64) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_sys_reg(self.cpu, reg as _, value))
+        call!(sys::hv_vcpu_set_sys_reg(self.id, reg as _, value))
     }
 
     /// Gets pending interrupts for a vcpu.
     fn pending_interrupt(&self, ty: InterruptType) -> Result<bool, Error> {
         let mut out = false;
         call!(sys::hv_vcpu_get_pending_interrupt(
-            self.cpu, ty as u32, &mut out
+            self.id, ty as u32, &mut out
         ))?;
         Ok(out)
     }
 
     /// Sets pending interrupts for a vcpu.
     fn set_pending_interrupt(&self, ty: InterruptType, mut pending: bool) -> Result<(), Error> {
         call!(sys::hv_vcpu_get_pending_interrupt(
-            self.cpu,
+            self.id,
             ty as u32,
             &mut pending
         ))
@@ -136,49 +136,49 @@ impl VcpuExt for Vcpu {
     /// Get whether debug exceptions in the guest are trapped to the host.
     fn trap_debug_exceptions(&self) -> Result<bool, Error> {
         let mut out = false;
-        call!(sys::hv_vcpu_get_trap_debug_exceptions(self.cpu, &mut out))?;
+        call!(sys::hv_vcpu_get_trap_debug_exceptions(self.id, &mut out))?;
         Ok(out)
     }
 
     /// Set whether debug exceptions in the guest are trapped to the host.
     fn set_trap_debug_exceptions(&self, enable: bool) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_trap_debug_exceptions(self.cpu, enable))
+        call!(sys::hv_vcpu_set_trap_debug_exceptions(self.id, enable))
     }
 
     /// Get whether debug register accesses in the guest are trapped to the host.
     fn trap_debug_reg_accesses(&self) -> Result<bool, Error> {
         let mut out = false;
-        call!(sys::hv_vcpu_get_trap_debug_reg_accesses(self.cpu, &mut out))?;
+        call!(sys::hv_vcpu_get_trap_debug_reg_accesses(self.id, &mut out))?;
         Ok(out)
     }
 
     /// Set whether debug register accesses in the guest are trapped to the host.
     fn set_trap_debug_reg_accesses(&self, enable: bool) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_trap_debug_reg_accesses(self.cpu, enable))
+        call!(sys::hv_vcpu_set_trap_debug_reg_accesses(self.id, enable))
     }
 
     /// Gets the VTimer mask.
     fn vtimer_mask(&self) -> Result<bool, Error> {
         let mut out = false;
-        call!(sys::hv_vcpu_get_vtimer_mask(self.cpu, &mut out))?;
+        call!(sys::hv_vcpu_get_vtimer_mask(self.id, &mut out))?;
         Ok(out)
     }
 
     /// Sets the VTimer mask.
     fn set_vtimer_mask(&self, vtimer_is_masked: bool) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_vtimer_mask(self.cpu, vtimer_is_masked))
+        call!(sys::hv_vcpu_set_vtimer_mask(self.id, vtimer_is_masked))
     }
 
     /// Gets the VTimer offset.
     fn vtimer_offset(&self) -> Result<u64, Error> {
         let mut out = 0_u64;
-        call!(sys::hv_vcpu_get_vtimer_offset(self.cpu, &mut out))?;
+        call!(sys::hv_vcpu_get_vtimer_offset(self.id, &mut out))?;
         Ok(out)
     }
 
     /// Sets the VTimer offset.
     fn set_vtimer_offset(&self, vtimer_offset: u64) -> Result<(), Error> {
-        call!(sys::hv_vcpu_set_vtimer_offset(self.cpu, vtimer_offset))
+        call!(sys::hv_vcpu_set_vtimer_offset(self.id, vtimer_offset))
     }
 
     /// Returns the underlying `hv_vcpu_exit_t` structure.

hv/src/vcpu.rs

@@ -1,14 +1,22 @@
-use crate::{call, sys, Error};
+use crate::{call, sys, Error, Vm};
+use std::sync::Arc;
+
+/// The type that describes a vCPU ID on Intel.
+#[cfg(target_arch = "x86_64")]
+pub type Id = sys::hv_vcpuid_t;
+
+/// The type that describes a vCPU ID on Apple Silicon.
+#[cfg(target_arch = "aarch64")]
+pub type Id = sys::hv_vcpu_t;
 
 /// Represents a single virtual CPU.
 ///
 /// [Vcpu] object is not thread safe, all calls must be performed from
 /// the owning thread.
 pub struct Vcpu {
-    #[cfg(target_arch = "x86_64")]
-    pub(crate) cpu: sys::hv_vcpuid_t,
-    #[cfg(target_arch = "aarch64")]
-    pub(crate) cpu: sys::hv_vcpu_t,
+    #[allow(dead_code)] // VM instance must outlive CPU in order to deallocate things properly.
+    vm: Arc<Vm>,
+    pub(crate) id: Id,
     #[cfg(target_arch = "aarch64")]
     /// The pointer to the vCPU exit information.
     /// The function `hv_vcpu_run` updates this structure on return.
@@ -18,24 +26,24 @@ pub struct Vcpu {
 
 impl Vcpu {
     /// Creates a vCPU instance for the current thread.
-    pub(crate) fn new() -> Result<Vcpu, Error> {
+    pub(crate) fn new(vm: Arc<Vm>) -> Result<Vcpu, Error> {
         #[cfg(target_arch = "x86_64")]
         {
-            let mut cpu = 0;
-            call!(sys::hv_vcpu_create(&mut cpu, 0))?;
-            Ok(Vcpu { cpu })
+            let mut id = 0;
+            call!(sys::hv_vcpu_create(&mut id, 0))?;
+            Ok(Vcpu { vm, id })
         }
 
         #[cfg(target_arch = "aarch64")]
         {
-            let mut cpu = 0;
+            let mut id = 0;
             let mut exit = std::ptr::null_mut();
             call!(sys::hv_vcpu_create(
-                &mut cpu,
+                &mut id,
                 &mut exit,
                 std::ptr::null_mut()
             ))?;
-            Ok(Vcpu { cpu, exit })
+            Ok(Vcpu { vm, id, exit })
         }
     }
 
@@ -54,20 +62,26 @@ impl Vcpu {
     ///
     /// [1]: https://developer.apple.com/documentation/hypervisor/1441231-hv_vcpu_run
     pub fn run(&self) -> Result<(), Error> {
-        call!(sys::hv_vcpu_run(self.cpu))
+        call!(sys::hv_vcpu_run(self.id))
     }
 
     /// Returns the cumulative execution time of a vCPU in nanoseconds.
     pub fn exec_time(&self) -> Result<u64, Error> {
         let mut out = 0_u64;
-        call!(sys::hv_vcpu_get_exec_time(self.cpu, &mut out))?;
+        call!(sys::hv_vcpu_get_exec_time(self.id, &mut out))?;
         Ok(out)
     }
+
+    /// Returns the underlying vCPU ID.
+    #[inline]
+    pub fn id(&self) -> Id {
+        self.id
+    }
 }
 
+/// Destroys the vCPU instance associated with the current thread.
 impl Drop for Vcpu {
-    /// Destroys the vCPU instance associated with the current thread.
     fn drop(&mut self) {
-        let _ = call!(sys::hv_vcpu_destroy(self.cpu));
+        call!(sys::hv_vcpu_destroy(self.id)).unwrap()
     }
 }