Align common API for platforms

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

Author: mxpv

hv/src/lib.rs

@@ -1,6 +1,7 @@
 //! `hv` is a high level safe Rust crate to access Hypervisor Framework.
 
 use std::error;
+use std::ffi::c_void;
 use std::fmt;
 
 /// Low level access to generated bindings.
@@ -14,6 +15,14 @@ pub mod vm;
 #[cfg(target_arch = "x86_64")]
 pub mod x86;
 
+pub type Size = u64;
+
+/// Type of a user virtual address.
+pub type Addr = *const c_void;
+
+/// Type of a guest physical address.
+pub type GPAddr = u64;
+
 /// Helper macro to call unsafe Hypervisor functions and map returned error codes to [Error] type.
 #[macro_export]
 macro_rules! call {

hv/src/vcpu.rs

@@ -1,47 +1,73 @@
 use crate::{call, sys, Error};
 
-#[cfg(target_arch = "x86_64")]
-type Handle = sys::hv_vcpuid_t;
-#[cfg(target_arch = "aarch64")]
-type Handle = 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(pub(crate) Handle);
+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,
+    #[cfg(target_arch = "aarch64")]
+    /// The pointer to the vCPU exit information.
+    /// The function `hv_vcpu_run` updates this structure on return.
+    /// Apple silicon only.
+    pub(crate) exit: *const sys::hv_vcpu_exit_t,
+}
 
 impl Vcpu {
     /// Creates a vCPU instance for the current thread.
     pub(crate) fn new() -> Result<Vcpu, Error> {
-        let mut handle = 0;
         #[cfg(target_arch = "x86_64")]
-        call!(sys::hv_vcpu_create(&mut handle, 0))?;
-        Ok(Vcpu(handle))
+        {
+            let mut cpu = 0;
+            call!(sys::hv_vcpu_create(&mut cpu, 0))?;
+            Ok(Vcpu { cpu })
+        }
+
+        #[cfg(target_arch = "aarch64")]
+        {
+            let mut cpu = 0;
+            let mut exit = std::ptr::null_mut();
+            call!(sys::hv_vcpu_create(
+                &mut cpu,
+                &mut exit,
+                std::ptr::null_mut()
+            ))?;
+            Ok(Vcpu { cpu, exit })
+        }
     }
 
     /// Executes a vCPU.
+    ///
+    /// Call blocks until the next exit of the vCPU [1].
+    /// The owning thread must call this function.
+    ///
+    /// # Intel
+    /// On an Intel-based Mac, `hv_vcpu_run` exits from causes external to the guest.
+    /// To avoid the overhead of spurious exits use `hv_vcpu_run_until` with the deadline `HV_DEADLINE_FOREVER`.
+    ///
+    /// # Apple Silicon
+    /// If the exit is of type `HV_EXIT_REASON_VTIMER_ACTIVATED`, the VTimer is automatically masked.
+    /// As a result, no timer fires until the timer is unmasked with `hv_vcpu_set_vtimer_mask`.
+    ///
+    /// [1]: https://developer.apple.com/documentation/hypervisor/1441231-hv_vcpu_run
     pub fn run(&self) -> Result<(), Error> {
-        call!(sys::hv_vcpu_run(self.0))
-    }
-
-    /// Executes a vCPU until the given deadline.
-    #[cfg(feature = "hv_10_15")]
-    pub fn run_until(&self, deadline: u64) -> Result<(), Error> {
-        call!(sys::hv_vcpu_run_until(self.0, deadline))
+        call!(sys::hv_vcpu_run(self.cpu))
     }
 
     /// 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.0, &mut out))?;
+        call!(sys::hv_vcpu_get_exec_time(self.cpu, &mut out))?;
         Ok(out)
     }
 }
 
 impl Drop for Vcpu {
     /// Destroys the vCPU instance associated with the current thread.
     fn drop(&mut self) {
-        let _ = call!(sys::hv_vcpu_destroy(self.0));
+        let _ = call!(sys::hv_vcpu_destroy(self.cpu));
     }
 }

hv/src/vm.rs

@@ -1,4 +1,6 @@
-use crate::{call, sys, Error, Vcpu};
+use std::ffi::c_void;
+
+use crate::{call, sys, Addr, Error, GPAddr, Size, Vcpu};
 
 bitflags::bitflags! {
     /// Guest physical memory region permissions.
@@ -19,6 +21,48 @@ impl Vm {
         Vcpu::new()
     }
 
+    /// Maps a region in the virtual address space of the current task into the guest physical
+    /// address space of the VM.
+    ///
+    /// The host memory must encompass a single VM region, typically allocated with `mmap` or
+    /// `mach_vm_allocate` instead of `malloc`. [1]
+    ///
+    /// # Arguments
+    /// * `uva` - Page aligned virtual address in the current task.
+    /// * `gpa` - Page aligned address in the guest physical address space.
+    /// * `size` - Size in bytes of the region to be mapped.
+    /// * `flags` - READ, WRITE and EXECUTE permissions of the region
+    ///
+    /// [1]: https://developer.apple.com/documentation/hypervisor/1441187-hv_vm_map
+    ///
+    pub fn map(uva: Addr, gpa: GPAddr, size: Size, flags: Memory) -> Result<(), Error> {
+        call!(sys::hv_vm_map(
+            uva as *mut c_void,
+            gpa,
+            size,
+            flags.bits().into()
+        ))
+    }
+
+    /// Unmaps a region in the guest physical address space of the VM
+    ///
+    /// # Arguments
+    /// * `gpa` - Page aligned address in the guest physical address space.
+    /// * `size` - Size in bytes of the region to be unmapped.
+    pub fn unmap(gpa: GPAddr, size: Size) -> Result<(), Error> {
+        call!(sys::hv_vm_unmap(gpa, size))
+    }
+
+    /// Modifies the permissions of a region in the guest physical address space of the VM.
+    ///
+    /// # Arguments
+    /// * `gpa` - Page aligned address in the guest physical address space.
+    /// * `size` - Size in bytes of the region to be modified.
+    /// * `flags` - New READ, WRITE and EXECUTE permissions of the region.
+    pub fn protect(gpa: GPAddr, size: Size, flags: Memory) -> Result<(), Error> {
+        call!(sys::hv_vm_protect(gpa, size, flags.bits().into()))
+    }
+
     /// Destroys the VM instance associated with the current process.
     pub fn destroy() -> Result<(), Error> {
         call!(sys::hv_vm_destroy())