Uhyve Interface V2

Cargo.toml

@@ -55,7 +55,7 @@ mac_address = "1.1"
 thiserror = "2.0"
 time = "0.3"
 tun-tap = { version = "0.1.3", default-features = false }
-uhyve-interface = { version = "0.1.1", path = "uhyve-interface", features = ["std"] }
+uhyve-interface = { version = "0.2.0", path = "uhyve-interface", features = ["std"] }
 virtio-bindings = { version = "0.2", features = ["virtio-v4_14_0"] }
 rftrace = { version = "0.1", optional = true }
 rftrace-frontend = { version = "0.1", optional = true }

src/hypercall.rs

@@ -4,7 +4,10 @@ use std::{
 	os::unix::ffi::OsStrExt,
 };
 
-use uhyve_interface::{parameters::*, GuestPhysAddr, Hypercall, HypercallAddress, MAX_ARGC_ENVC};
+use uhyve_interface::{
+	v1::{parameters::*, Hypercall, HypercallAddress, MAX_ARGC_ENVC},
+	GuestPhysAddr,
+};
 
 use crate::{
 	consts::BOOT_PML4,

src/linux/x86_64/kvm_cpu.rs

@@ -2,7 +2,7 @@ use std::sync::Arc;
 
 use kvm_bindings::*;
 use kvm_ioctls::{VcpuExit, VcpuFd, VmFd};
-use uhyve_interface::{GuestPhysAddr, Hypercall};
+use uhyve_interface::{v1::Hypercall, GuestPhysAddr};
 use vmm_sys_util::eventfd::EventFd;
 use x86_64::registers::control::{Cr0Flags, Cr4Flags};
 

src/macos/aarch64/vcpu.rs

@@ -4,7 +4,7 @@
 use std::sync::Arc;
 
 use log::debug;
-use uhyve_interface::{GuestPhysAddr, Hypercall};
+use uhyve_interface::{v1::Hypercall, GuestPhysAddr};
 use xhypervisor::{
 	self, create_vm, map_mem, MemPerm, Register, SystemRegister, VirtualCpuExitReason,
 };

src/macos/x86_64/vcpu.rs

@@ -7,7 +7,7 @@ use std::{
 
 use burst::x86::{disassemble_64, InstructionOperation, OperandType};
 use log::{debug, trace};
-use uhyve_interface::{GuestPhysAddr, Hypercall};
+use uhyve_interface::{v1::Hypercall, GuestPhysAddr};
 use x86_64::{
 	registers::control::{Cr0Flags, Cr4Flags},
 	structures::gdt::SegmentSelector,

src/vm.rs

@@ -268,7 +268,7 @@ impl<VirtBackend: VirtualizationBackend> UhyveVm<VirtBackend> {
 				phys_addr_range: self.mem.guest_address.as_u64()
 					..self.mem.guest_address.as_u64() + self.mem.memory_size as u64,
 				serial_port_base: self.verbose().then(|| {
-					SerialPortBase::new((uhyve_interface::HypercallAddress::Uart as u16).into())
+					SerialPortBase::new((uhyve_interface::v1::HypercallAddress::Uart as u16).into())
 						.unwrap()
 				}),
 				device_tree: Some(FDT_ADDR.as_u64().try_into().unwrap()),

tests/test-kernels/src/bin/serial.rs

@@ -1,6 +1,9 @@
 #[cfg(target_os = "hermit")]
 use hermit as _;
-use uhyve_interface::{parameters::SerialWriteBufferParams, GuestPhysAddr, HypercallAddress};
+use uhyve_interface::{
+	v1::{parameters::SerialWriteBufferParams, HypercallAddress},
+	GuestPhysAddr,
+};
 #[cfg(target_arch = "x86_64")]
 use x86_64::{
 	instructions::port::Port,

uhyve-interface/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "uhyve-interface"
-version = "0.1.2"
+version = "0.2.0"
 edition = "2021"
 authors = [
   "Jonathan Klimt <[email protected]>",
@@ -15,6 +15,7 @@ categories = ["os"]
 [dependencies]
 num_enum = { version = "0.7", default-features = false }
 log = { version = "0.4", optional = true }
+bitflags = "2.6.0"
 
 [features]
 std = ["dep:log"]

uhyve-interface/README.md

@@ -0,0 +1,7 @@
+<img width="200" align="right" src="https://raw.githubusercontent.com/hermit-os/uhyve/f4070692729c5f1fa1dbf6df67004acbfef39104/img/uhyve.svg" />
+
+# Uhyve Hypercall Interface
+[![crates.io](https://img.shields.io/crates/v/uhyve.svg)](https://crates.io/crates/uhyve)
+
+This crate specifies the interface between the [Hermit Unikernel](https://github.com/hermit-os/kernel) and the hypervisor [Uhyve](https://github.com/hermit-os/uhyve).
+It includes the definition of the hypercalls and hypercall parameters and is intended to be used in both projects to ensure a coherent and well defined interface.

uhyve-interface/src/lib.rs

@@ -1,19 +1,21 @@
-//! # Uhyve Hypervisor Interface
+#![doc(
+	html_favicon_url = "https://media.githubusercontent.com/media/hermit-os/uhyve/main/img/uhyve_128.png"
+)]
+#![doc(
+	html_logo_url = "https://media.githubusercontent.com/media/hermit-os/uhyve/main/img/uhyve_512.png"
+)]
+//! # Uhyve Hypercall Interface
 //!
-//! The Uhyve hypercall interface works as follows:
-//!
-//! - On `x86_64` you use an out port instruction. The address of the `out`-port corresponds to the
-//!   hypercall you want to use. You can obtain it from the [`IoPorts`] enum. The data send to
-//!   that port is the physical memory address (of the VM) of the parameters of that hypercall.
-//! - On `aarch64` you write to the respective [`HypercallAddress`]. The 64-bit value written to that location is the guest's physical memory address of the hypercall's parameter.
+//! This crate specifies the interface between the [Hermit Unikernel](https://github.com/hermit-os/kernel) and the hypervisor [Uhyve](https://github.com/hermit-os/uhyve).
+//! It includes the definition of the hypercalls and hypercall parameters and is intended to be used in both projects to ensure a coherent and well defined interface.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
-// TODO: Throw this out, once https://github.com/rust-lang/rfcs/issues/2783 or https://github.com/rust-lang/rust/issues/86772 is resolved
-use num_enum::TryFromPrimitive;
-
 pub mod elf;
-pub mod parameters;
+/// Version 1 of the Hypercall Interface
+pub mod v1;
+/// Version 2 of the Hypercall Interface
+pub mod v2;
 
 #[cfg(target_arch = "aarch64")]
 pub use ::aarch64::paging::PhysAddr as GuestPhysAddr;
@@ -26,123 +28,7 @@ pub use ::x86_64::addr::VirtAddr as GuestVirtAddr;
 
 #[cfg(not(target_pointer_width = "64"))]
 compile_error!("Using uhyve-interface on a non-64-bit system is not (yet?) supported");
-use parameters::*;
 
 /// The version of the Uhyve interface. Note: This is not the same as the semver of the crate but
 /// should be increased on every version bump that changes the API.
-pub const UHYVE_INTERFACE_VERSION: u32 = 1;
-
-/// Enum containing all valid port mappings for hypercalls.
-///
-/// The discriminants of this enum are the respective ports, so one can get the code by calling
-/// e.g., `HypercallPorts::FileWrite as u16`.
-#[non_exhaustive]
-#[repr(u16)]
-#[derive(Debug, Eq, PartialEq, TryFromPrimitive)]
-pub enum HypercallAddress {
-	/// Port address = `0x400`
-	FileWrite = 0x400,
-	/// Port address = `0x440`
-	FileOpen = 0x440,
-	/// Port address = `0x480`
-	FileClose = 0x480,
-	/// Port address = `0x500`
-	FileRead = 0x500,
-	/// Port address = `0x540`
-	Exit = 0x540,
-	/// Port address = `0x580`
-	FileLseek = 0x580,
-	#[deprecated = "was never really in use"]
-	/// Port address = `0x640`
-	Netwrite = 0x640,
-	#[deprecated = "was never really in use"]
-	/// Port address = `0x680`
-	Netread = 0x680,
-	#[deprecated = "was never really in use"]
-	/// Port address = `0x700`
-	Netstat = 0x700,
-	/// Port address = `0x740`
-	Cmdsize = 0x740,
-	/// Port address = `0x780`
-	Cmdval = 0x780,
-	/// Port address = `0x800`
-	Uart = 0x800,
-	/// Port address = `0x840`
-	FileUnlink = 0x840,
-	/// Port address = `0x880`
-	SerialBufferWrite = 0x880,
-}
-// TODO: Remove this in the next major version
-impl From<Hypercall<'_>> for HypercallAddress {
-	fn from(value: Hypercall) -> Self {
-		match value {
-			Hypercall::Cmdsize(_) => Self::Cmdsize,
-			Hypercall::Cmdval(_) => Self::Cmdval,
-			Hypercall::Exit(_) => Self::Exit,
-			Hypercall::FileClose(_) => Self::FileClose,
-			Hypercall::FileLseek(_) => Self::FileLseek,
-			Hypercall::FileOpen(_) => Self::FileOpen,
-			Hypercall::FileRead(_) => Self::FileRead,
-			Hypercall::FileWrite(_) => Self::FileWrite,
-			Hypercall::FileUnlink(_) => Self::FileUnlink,
-			Hypercall::SerialWriteByte(_) => Self::Uart,
-			Hypercall::SerialWriteBuffer(_) => Self::SerialBufferWrite,
-		}
-	}
-}
-impl From<&Hypercall<'_>> for HypercallAddress {
-	fn from(value: &Hypercall) -> Self {
-		match value {
-			Hypercall::Cmdsize(_) => Self::Cmdsize,
-			Hypercall::Cmdval(_) => Self::Cmdval,
-			Hypercall::Exit(_) => Self::Exit,
-			Hypercall::FileClose(_) => Self::FileClose,
-			Hypercall::FileLseek(_) => Self::FileLseek,
-			Hypercall::FileOpen(_) => Self::FileOpen,
-			Hypercall::FileRead(_) => Self::FileRead,
-			Hypercall::FileWrite(_) => Self::FileWrite,
-			Hypercall::FileUnlink(_) => Self::FileUnlink,
-			Hypercall::SerialWriteByte(_) => Self::Uart,
-			Hypercall::SerialWriteBuffer(_) => Self::SerialBufferWrite,
-		}
-	}
-}
-
-/// Hypervisor calls available in Uhyve with their respective parameters. See the [module level documentation](crate) on how to invoke them.
-#[non_exhaustive]
-#[derive(Debug)]
-pub enum Hypercall<'a> {
-	/// Get the size of the argument and environment strings. Used to allocate memory for
-	/// [`Hypercall::Cmdval`].
-	Cmdsize(&'a mut CmdsizeParams),
-	/// Copy the argument and environment strings into the VM. Usually preceeeded by
-	/// [`Hypercall::Cmdsize`] so that the guest can allocate the memory for this call.
-	Cmdval(&'a CmdvalParams),
-	/// Exit the VM and return a status.
-	Exit(&'a ExitParams),
-	FileClose(&'a mut CloseParams),
-	FileLseek(&'a mut LseekParams),
-	FileOpen(&'a mut OpenParams),
-	FileRead(&'a mut ReadParams),
-	FileWrite(&'a WriteParams),
-	FileUnlink(&'a mut UnlinkParams),
-	/// Write a char to the terminal.
-	SerialWriteByte(u8),
-	/// Write a buffer to the terminal.
-	SerialWriteBuffer(&'a SerialWriteBufferParams),
-}
-impl<'a> Hypercall<'a> {
-	// TODO: Remove this in the next major version
-	/// Get a hypercall's port address.
-	pub fn port(self) -> u16 {
-		HypercallAddress::from(self) as u16
-	}
-}
-
-// Networkports (not used at the moment)
-// TODO: Remove this
-pub const UHYVE_PORT_NETWRITE: u16 = 0x640;
-
-// FIXME: Do not use a fix number of arguments
-/// The maximum number of items in an argument of environment vector.
-pub const MAX_ARGC_ENVC: usize = 128;
+pub const UHYVE_INTERFACE_VERSION: u32 = 2;

uhyve-interface/src/v1/mod.rs

@@ -0,0 +1,111 @@
+//! # Uhyve Hypervisor Interface V1
+//!
+//! The Uhyve hypercall interface works as follows:
+//!
+//! - On `x86_64` you use an out port instruction. The address of the `out`-port corresponds to the
+//!   hypercall you want to use. You can obtain it from the [`HypercallAddress`](v1::HypercallAddress) enum. The data send to
+//!   that port is the physical memory address (of the VM) of the parameters of that hypercall.
+//! - On `aarch64` you write to the respective [`HypercallAddress`](v1::HypercallAddress). The 64-bit value written to that location is the guest's physical memory address of the hypercall's parameter.
+
+// TODO: Throw this out, once https://github.com/rust-lang/rfcs/issues/2783 or https://github.com/rust-lang/rust/issues/86772 is resolved
+
+use num_enum::TryFromPrimitive;
+
+pub mod parameters;
+use crate::v1::parameters::*;
+
+/// Enum containing all valid port mappings for hypercalls.
+///
+/// The discriminants of this enum are the respective ports, so one can get the code by calling
+/// e.g., `HypercallPorts::FileWrite as u16`.
+#[non_exhaustive]
+#[repr(u16)]
+#[derive(Debug, Eq, PartialEq, TryFromPrimitive)]
+pub enum HypercallAddress {
+	/// Port address = `0x400`
+	FileWrite = 0x400,
+	/// Port address = `0x440`
+	FileOpen = 0x440,
+	/// Port address = `0x480`
+	FileClose = 0x480,
+	/// Port address = `0x500`
+	FileRead = 0x500,
+	/// Port address = `0x540`
+	Exit = 0x540,
+	/// Port address = `0x580`
+	FileLseek = 0x580,
+	#[deprecated = "was never really in use"]
+	/// Port address = `0x640`
+	Netwrite = 0x640,
+	#[deprecated = "was never really in use"]
+	/// Port address = `0x680`
+	Netread = 0x680,
+	#[deprecated = "was never really in use"]
+	/// Port address = `0x700`
+	Netstat = 0x700,
+	/// Port address = `0x740`
+	Cmdsize = 0x740,
+	/// Port address = `0x780`
+	Cmdval = 0x780,
+	/// Port address = `0x800`
+	Uart = 0x800,
+	/// Port address = `0x840`
+	FileUnlink = 0x840,
+	/// Port address = `0x880`
+	SerialBufferWrite = 0x880,
+}
+impl From<Hypercall<'_>> for HypercallAddress {
+	fn from(value: Hypercall) -> Self {
+		match value {
+			Hypercall::Cmdsize(_) => Self::Cmdsize,
+			Hypercall::Cmdval(_) => Self::Cmdval,
+			Hypercall::Exit(_) => Self::Exit,
+			Hypercall::FileClose(_) => Self::FileClose,
+			Hypercall::FileLseek(_) => Self::FileLseek,
+			Hypercall::FileOpen(_) => Self::FileOpen,
+			Hypercall::FileRead(_) => Self::FileRead,
+			Hypercall::FileWrite(_) => Self::FileWrite,
+			Hypercall::FileUnlink(_) => Self::FileUnlink,
+			Hypercall::SerialWriteByte(_) => Self::Uart,
+			Hypercall::SerialWriteBuffer(_) => Self::SerialBufferWrite,
+		}
+	}
+}
+
+/// Hypervisor calls available in Uhyve with their respective parameters. See the [module level documentation](crate) on how to invoke them.
+#[non_exhaustive]
+#[derive(Debug)]
+pub enum Hypercall<'a> {
+	/// Get the size of the argument and environment strings. Used to allocate memory for
+	/// [`Hypercall::Cmdval`].
+	Cmdsize(&'a mut CmdsizeParams),
+	/// Copy the argument and environment strings into the VM. Usually preceeeded by
+	/// [`Hypercall::Cmdsize`] so that the guest can allocate the memory for this call.
+	Cmdval(&'a CmdvalParams),
+	/// Exit the VM and return a status.
+	Exit(&'a ExitParams),
+	FileClose(&'a mut CloseParams),
+	FileLseek(&'a mut LseekParams),
+	FileOpen(&'a mut OpenParams),
+	FileRead(&'a mut ReadParams),
+	FileWrite(&'a WriteParams),
+	FileUnlink(&'a mut UnlinkParams),
+	/// Write a char to the terminal.
+	SerialWriteByte(u8),
+	/// Write a buffer to the terminal.
+	SerialWriteBuffer(&'a SerialWriteBufferParams),
+}
+impl<'a> Hypercall<'a> {
+	/// Get a hypercall's port address.
+	pub fn port(self) -> u16 {
+		HypercallAddress::from(self) as u16
+	}
+}
+
+// Networkports (not used at the moment)
+// TODO: Remove this
+pub const UHYVE_PORT_NETWRITE: u16 = 0x640;
+
+// FIXME: Do not use a fix number of arguments
+/// The maximum number of items in an argument of environment vector.
+pub const MAX_ARGC_ENVC: usize = 128;