feat(virtq): replace guest-to-host calls with virtqueue

Signed-off-by: Tomasz Andrzejak <andreiltd@gmail.com>

Author: andreiltd

Cargo.lock

@@ -41,6 +41,7 @@ pub const SCRATCH_TOP_H2G_RING_GVA_OFFSET: u64 = 0x28;
 pub const SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET: u64 = 0x30;
 pub const SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET: u64 = 0x32;
 pub const SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET: u64 = 0x34;
+pub const SCRATCH_TOP_VIRTQ_GENERATION_OFFSET: u64 = 0x36;
 pub const SCRATCH_TOP_EXN_STACK_OFFSET: u64 = 0x40;
 
 const _: () = {
@@ -51,7 +52,8 @@ const _: () = {
     assert!(SCRATCH_TOP_H2G_RING_GVA_OFFSET + 8 <= SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET);
     assert!(SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET + 2 <= SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET);
     assert!(SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET + 2 <= SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET);
-    assert!(SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET + 2 <= SCRATCH_TOP_EXN_STACK_OFFSET);
+    assert!(SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET + 2 <= SCRATCH_TOP_VIRTQ_GENERATION_OFFSET);
+    assert!(SCRATCH_TOP_VIRTQ_GENERATION_OFFSET + 2 <= SCRATCH_TOP_EXN_STACK_OFFSET);
     assert!(SCRATCH_TOP_EXN_STACK_OFFSET % 0x10 == 0);
 };
 

src/hyperlight_common/src/layout.rs

@@ -15,6 +15,7 @@ Provides only the essential building blocks for interacting with the host enviro
 anyhow = { version = "1.0.102", default-features = false }
 serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
 hyperlight-common = { workspace = true, default-features = false }
+bytemuck = { version = "1.24", features = ["derive"] }
 flatbuffers = { version= "25.12.19", default-features = false }
 tracing = { version = "0.1.44", default-features = false, features = ["attributes"] }
 

src/hyperlight_guest/Cargo.toml

@@ -17,10 +17,11 @@ limitations under the License.
 use alloc::format;
 use alloc::string::{String, ToString as _};
 
-use anyhow;
-use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
+pub(crate) use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
+use hyperlight_common::flatbuffer_wrappers::guest_error::GuestError;
 use hyperlight_common::func::Error as FuncError;
-use serde_json;
+use hyperlight_common::virtq::VirtqError;
+use {anyhow, serde_json};
 
 pub type Result<T> = core::result::Result<T, HyperlightGuestError>;
 
@@ -81,6 +82,24 @@ impl From<FuncError> for HyperlightGuestError {
     }
 }
 
+impl From<VirtqError> for HyperlightGuestError {
+    fn from(e: VirtqError) -> Self {
+        Self {
+            kind: ErrorCode::GuestError,
+            message: format!("virtq: {e}"),
+        }
+    }
+}
+
+impl From<GuestError> for HyperlightGuestError {
+    fn from(e: GuestError) -> Self {
+        Self {
+            kind: e.code,
+            message: e.message,
+        }
+    }
+}
+
 /// Extension trait to add context to `Option<T>` and `Result<T, E>` types in guest code,
 /// converting them to `Result<T, HyperlightGuestError>`.
 ///

src/hyperlight_guest/src/error.rs

@@ -25,7 +25,7 @@ pub mod error;
 pub mod exit;
 pub mod layout;
 pub mod prim_alloc;
-pub mod virtq_mem;
+pub mod virtq;
 
 pub mod guest_handle {
     pub mod handle;

src/hyperlight_guest/src/lib.rs

@@ -0,0 +1,159 @@
+/*
+Copyright 2026  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+//! Guest virtqueue context.
+
+use alloc::sync::Arc;
+use alloc::vec::Vec;
+use core::num::NonZeroU16;
+use core::sync::atomic::AtomicU16;
+use core::sync::atomic::Ordering::Relaxed;
+
+use flatbuffers::FlatBufferBuilder;
+use hyperlight_common::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
+use hyperlight_common::flatbuffer_wrappers::function_types::{
+    FunctionCallResult, ParameterValue, ReturnType, ReturnValue,
+};
+use hyperlight_common::flatbuffer_wrappers::util::estimate_flatbuffer_capacity;
+use hyperlight_common::outb::OutBAction;
+use hyperlight_common::virtq::msg::{MsgKind, VirtqMsgHeader};
+use hyperlight_common::virtq::{BufferPool, Layout, Notifier, QueueStats, VirtqProducer};
+
+use super::GuestMemOps;
+use crate::bail;
+use crate::error::Result;
+
+static REQUEST_ID: AtomicU16 = AtomicU16::new(0);
+const MAX_RESPONSE_CAP: usize = 4096;
+
+/// Guest-side notifier that triggers a VM exit via outb.
+#[derive(Clone, Copy)]
+pub struct GuestNotifier;
+
+impl Notifier for GuestNotifier {
+    fn notify(&self, _stats: QueueStats) {
+        unsafe { crate::exit::out32(OutBAction::VirtqNotify as u16, 0) };
+    }
+}
+
+/// Type alias for the guest-side G2H producer.
+pub type G2hProducer = VirtqProducer<GuestMemOps, GuestNotifier, Arc<BufferPool>>;
+
+/// Virtqueue runtime state for guest-host communication.
+pub struct GuestContext {
+    g2h_pool: Arc<BufferPool>,
+    g2h_producer: G2hProducer,
+    generation: u16,
+}
+
+impl GuestContext {
+    /// Create a new context with a G2H queue.
+    ///
+    /// # Safety
+    ///
+    /// `ring_gva` must point to valid, zeroed ring memory.
+    /// `pool_gva` must point to valid, zeroed memory.
+    pub unsafe fn new(
+        ring_gva: u64,
+        num_descs: u16,
+        pool_gva: u64,
+        pool_size: usize,
+        generation: u16,
+    ) -> Self {
+        let pool = Arc::new(
+            BufferPool::new(pool_gva, pool_size).expect("failed to create G2H buffer pool"),
+        );
+        let nz = NonZeroU16::new(num_descs).expect("G2H queue depth must be non-zero");
+        let layout = unsafe { Layout::from_base(ring_gva, nz) }.expect("invalid G2H ring layout");
+        let producer = VirtqProducer::new(layout, GuestMemOps, GuestNotifier, pool.clone());
+
+        Self {
+            g2h_pool: pool,
+            g2h_producer: producer,
+            generation,
+        }
+    }
+
+    /// Call a host function via the G2H virtqueue.
+    pub fn call_host_function<T: TryFrom<ReturnValue>>(
+        &mut self,
+        function_name: &str,
+        parameters: Option<Vec<ParameterValue>>,
+        return_type: ReturnType,
+    ) -> Result<T> {
+        let params = parameters.as_deref().unwrap_or_default();
+        let estimated_capacity = estimate_flatbuffer_capacity(function_name, params);
+
+        let fc = FunctionCall::new(
+            function_name.into(),
+            parameters,
+            FunctionCallType::Host,
+            return_type,
+        );
+
+        let mut builder = FlatBufferBuilder::with_capacity(estimated_capacity);
+        let payload = fc.encode(&mut builder);
+
+        let reqid = REQUEST_ID.fetch_add(1, Relaxed);
+        let hdr = VirtqMsgHeader::new(MsgKind::Request, reqid, payload.len() as u32);
+        let hdr_bytes = bytemuck::bytes_of(&hdr);
+
+        let entry_len = VirtqMsgHeader::SIZE + payload.len();
+
+        let mut entry = self
+            .g2h_producer
+            .chain()
+            .entry(entry_len)
+            .completion(MAX_RESPONSE_CAP)
+            .build()?;
+
+        entry.write_all(hdr_bytes)?;
+        entry.write_all(payload)?;
+        self.g2h_producer.submit(entry)?;
+
+        let Some(completion) = self.g2h_producer.poll()? else {
+            bail!("G2H: no completion received");
+        };
+
+        let result_bytes = &completion.data;
+        if result_bytes.len() > MAX_RESPONSE_CAP {
+            bail!("G2H: response is too large");
+        }
+
+        let payload_bytes = &result_bytes[VirtqMsgHeader::SIZE..];
+        let Ok(fcr) = FunctionCallResult::try_from(payload_bytes) else {
+            bail!("G2H: malformed response");
+        };
+
+        let ret = fcr.into_inner()?;
+        let Ok(ret) = T::try_from(ret) else {
+            bail!("G2H: host return value type mismatch");
+        };
+
+        Ok(ret)
+    }
+
+    /// Reset ring and pool state after snapshot restore.
+    pub(super) fn reset(&mut self, new_generation: u16) {
+        self.g2h_producer.reset();
+        self.g2h_pool.reset();
+        self.generation = new_generation;
+    }
+
+    pub(super) fn generation(&self) -> u16 {
+        self.generation
+    }
+}

src/hyperlight_guest/src/virtq/context.rs

@@ -31,29 +31,21 @@ impl MemOps for GuestMemOps {
     type Error = Infallible;
 
     fn read(&self, addr: u64, dst: &mut [u8]) -> Result<usize, Self::Error> {
-        let src = addr as *const u8;
-        unsafe {
-            ptr::copy_nonoverlapping(src, dst.as_mut_ptr(), dst.len());
-        }
+        unsafe { ptr::copy_nonoverlapping(addr as *const u8, dst.as_mut_ptr(), dst.len()) };
         Ok(dst.len())
     }
 
     fn write(&self, addr: u64, src: &[u8]) -> Result<usize, Self::Error> {
-        let dst = addr as *mut u8;
-        unsafe {
-            ptr::copy_nonoverlapping(src.as_ptr(), dst, src.len());
-        }
+        unsafe { ptr::copy_nonoverlapping(src.as_ptr(), addr as *mut u8, src.len()) };
         Ok(src.len())
     }
 
     fn load_acquire(&self, addr: u64) -> Result<u16, Self::Error> {
-        let ptr = addr as *const AtomicU16;
-        Ok(unsafe { (*ptr).load(Ordering::Acquire) })
+        Ok(unsafe { (*(addr as *const AtomicU16)).load(Ordering::Acquire) })
     }
 
     fn store_release(&self, addr: u64, val: u16) -> Result<(), Self::Error> {
-        let ptr = addr as *const AtomicU16;
-        unsafe { (*ptr).store(val, Ordering::Release) };
+        unsafe { (*(addr as *const AtomicU16)).store(val, Ordering::Release) };
         Ok(())
     }
 

src/hyperlight_guest/src/virtq_mem.rs src/hyperlight_guest/src/virtq/mem.rssrc/hyperlight_guest/src/virtq_mem.rs renamed to src/hyperlight_guest/src/virtq/mem.rs

@@ -0,0 +1,99 @@
+/*
+Copyright 2026  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+//! Guest-side virtqueue support.
+//!
+//! Global context is installed once via [`set_global_context`] and
+//! accessed via [`with_context`].
+
+pub mod context;
+pub mod mem;
+
+use core::cell::UnsafeCell;
+use core::sync::atomic::{AtomicU8, Ordering};
+
+use context::GuestContext;
+use hyperlight_common::layout::{SCRATCH_TOP_VIRTQ_GENERATION_OFFSET, scratch_top_ptr};
+pub use mem::GuestMemOps;
+
+// Init state machine
+const UNINITIALIZED: u8 = 0;
+const INITIALIZED: u8 = 1;
+static INIT_STATE: AtomicU8 = AtomicU8::new(UNINITIALIZED);
+
+/// Check if the global context has been initialized.
+pub fn is_initialized() -> bool {
+    INIT_STATE.load(Ordering::Acquire) == INITIALIZED
+}
+
+// Storage: UnsafeCell guarded by atomic init state.
+struct SyncWrap<T>(T);
+unsafe impl<T> Sync for SyncWrap<T> {}
+
+static GLOBAL_CONTEXT: SyncWrap<UnsafeCell<Option<GuestContext>>> = SyncWrap(UnsafeCell::new(None));
+
+/// Access the global guest context via closure.
+///
+/// # Panics
+///
+/// Panics if the context has not been initialized.
+pub fn with_context<R>(f: impl FnOnce(&mut GuestContext) -> R) -> R {
+    assert!(
+        INIT_STATE.load(Ordering::Acquire) == INITIALIZED,
+        "guest context not initialized"
+    );
+    let ctx = unsafe { &mut *GLOBAL_CONTEXT.0.get() };
+    f(ctx.as_mut().unwrap())
+}
+
+/// Install the global guest context. Called once during guest init.
+///
+/// # Panics
+///
+/// Panics if called more than once.
+pub fn set_global_context(ctx: GuestContext) {
+    if INIT_STATE
+        .compare_exchange(
+            UNINITIALIZED,
+            INITIALIZED,
+            Ordering::SeqCst,
+            Ordering::SeqCst,
+        )
+        .is_err()
+    {
+        panic!("guest context already initialized");
+    }
+    unsafe { *GLOBAL_CONTEXT.0.get() = Some(ctx) };
+}
+
+/// Reset the global context if a snapshot restore was detected.
+/// Compares the virtq generation counter in scratch-top metadata.
+pub fn reset_global_context() {
+    if !is_initialized() {
+        return;
+    }
+    let current_gen = read_gen();
+    with_context(|ctx| {
+        if current_gen != ctx.generation() {
+            ctx.reset(current_gen);
+        }
+    });
+}
+
+/// Read the current virtqueue generation from scratch-top metadata.
+fn read_gen() -> u16 {
+    unsafe { *scratch_top_ptr::<u16>(SCRATCH_TOP_VIRTQ_GENERATION_OFFSET) }
+}

src/hyperlight_guest/src/virtq/mod.rs

@@ -14,9 +14,10 @@ and third-party code used by our C-API needed to build a native hyperlight-guest
 """
 
 [features]
-default = ["libc", "printf", "macros"]
+default = ["libc", "printf", "macros", "virtq"]
 libc = [] # compile musl libc
 printf = [ "libc" ] # compile printf
+virtq = [] # use virtqueue for guest-to-host calls
 trace_guest = ["hyperlight-common/trace_guest", "hyperlight-guest/trace_guest", "hyperlight-guest-tracing/trace"]
 mem_profile = ["hyperlight-common/mem_profile"]
 macros = ["dep:hyperlight-guest-macro", "dep:linkme"]