feat(virtq): create G2H producer during guest init

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

Author: andreiltd

src/hyperlight_common/src/layout.rs

@@ -40,17 +40,18 @@ pub const SCRATCH_TOP_G2H_RING_GVA_OFFSET: u64 = 0x20;
 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_EXN_STACK_OFFSET: u64 = 0x40;
 
-// fields must not overlap, and exception stack address must be 16-byte aligned.
 const _: () = {
     assert!(SCRATCH_TOP_SIZE_OFFSET + 8 <= SCRATCH_TOP_ALLOCATOR_OFFSET);
     assert!(SCRATCH_TOP_ALLOCATOR_OFFSET + 8 <= SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET);
     assert!(SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET + 8 <= SCRATCH_TOP_G2H_RING_GVA_OFFSET);
     assert!(SCRATCH_TOP_G2H_RING_GVA_OFFSET + 8 <= SCRATCH_TOP_H2G_RING_GVA_OFFSET);
     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_EXN_STACK_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_EXN_STACK_OFFSET % 0x10 == 0);
 };
 
@@ -70,9 +71,13 @@ pub fn scratch_base_gva(size: usize) -> u64 {
     (MAX_GVA - size + 1) as u64
 }
 
+pub const fn scratch_top_ptr<T>(offset: u64) -> *mut T {
+    (MAX_GVA as u64 - offset + 1) as *mut T
+}
+
 /// Compute the byte offset from the scratch base to the G2H ring.
 ///
-/// TODO(ring): Remove input/output
+/// TODO(virtq): Remove input/output
 pub const fn g2h_ring_scratch_offset(input_data_size: usize, output_data_size: usize) -> usize {
     let io_off = input_data_size + output_data_size;
     let align = crate::virtq::Descriptor::ALIGN;

src/hyperlight_common/src/virtq/pool.rs

@@ -126,6 +126,30 @@ pub trait BufferProvider {
     fn resize(&self, old_alloc: Allocation, new_len: usize) -> Result<Allocation, AllocError>;
 }
 
+impl<T: BufferProvider> BufferProvider for alloc::rc::Rc<T> {
+    fn alloc(&self, len: usize) -> Result<Allocation, AllocError> {
+        (**self).alloc(len)
+    }
+    fn dealloc(&self, alloc: Allocation) -> Result<(), AllocError> {
+        (**self).dealloc(alloc)
+    }
+    fn resize(&self, old_alloc: Allocation, new_len: usize) -> Result<Allocation, AllocError> {
+        (**self).resize(old_alloc, new_len)
+    }
+}
+
+impl<T: BufferProvider> BufferProvider for alloc::sync::Arc<T> {
+    fn alloc(&self, len: usize) -> Result<Allocation, AllocError> {
+        (**self).alloc(len)
+    }
+    fn dealloc(&self, alloc: Allocation) -> Result<(), AllocError> {
+        (**self).dealloc(alloc)
+    }
+    fn resize(&self, old_alloc: Allocation, new_len: usize) -> Result<Allocation, AllocError> {
+        (**self).resize(old_alloc, new_len)
+    }
+}
+
 /// The owner of a mapped buffer, ensuring its lifetime.
 ///
 /// Holds a pool allocation and provides direct access to the underlying

src/hyperlight_guest_bin/src/lib.rs

@@ -52,7 +52,7 @@ pub mod host_comm;
 pub mod memory;
 #[cfg(target_arch = "x86_64")]
 pub mod paging;
-mod virtq_init;
+mod virtq;
 
 // Globals
 #[cfg(all(feature = "mem_profile", target_arch = "x86_64"))]
@@ -237,7 +237,7 @@ pub(crate) extern "C" fn generic_init(
     }
 
     // Initialize virtqueues
-    virtq_init::init_virtqueues();
+    virtq::init_virtqueues();
 
     // set up the logger
     let guest_log_level_filter =

src/hyperlight_guest_bin/src/virtq/mod.rs

@@ -0,0 +1,68 @@
+/*
+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 initialization.
+//!
+//! Zeroes ring memory and creates VirtqProducer instances by allocating
+//! buffer pool pages from the scratch page allocator.
+
+pub(crate) mod state;
+
+use hyperlight_common::layout::{
+    SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET, SCRATCH_TOP_G2H_RING_GVA_OFFSET,
+    SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET, SCRATCH_TOP_H2G_RING_GVA_OFFSET,
+    SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET, scratch_top_ptr,
+};
+use hyperlight_common::mem::PAGE_SIZE_USIZE;
+use hyperlight_common::virtq::Layout as VirtqLayout;
+use hyperlight_guest::prim_alloc::alloc_phys_pages;
+
+use crate::paging::phys_to_virt;
+
+/// Initialize virtqueue producers for G2H and H2G queues.
+pub(crate) fn init_virtqueues() {
+    let g2h_gva = unsafe { *scratch_top_ptr::<u64>(SCRATCH_TOP_G2H_RING_GVA_OFFSET) };
+    let g2h_depth = unsafe { *scratch_top_ptr::<u16>(SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET) };
+    let h2g_gva = unsafe { *scratch_top_ptr::<u64>(SCRATCH_TOP_H2G_RING_GVA_OFFSET) };
+    let h2g_depth = unsafe { *scratch_top_ptr::<u16>(SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET) };
+    let pool_pages = unsafe { *scratch_top_ptr::<u16>(SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET) } as u64;
+
+    assert!(g2h_depth > 0 && h2g_depth > 0);
+    assert!(g2h_gva != 0 && h2g_gva != 0);
+    assert!(pool_pages > 0);
+
+    // Zero ring memory
+    let g2h_ring_size = VirtqLayout::query_size(g2h_depth as usize);
+    unsafe { core::ptr::write_bytes(g2h_gva as *mut u8, 0, g2h_ring_size) };
+
+    let h2g_ring_size = VirtqLayout::query_size(h2g_depth as usize);
+    unsafe { core::ptr::write_bytes(h2g_gva as *mut u8, 0, h2g_ring_size) };
+
+    // Allocate buffer pool from physical pages
+    let pool_gpa = unsafe { alloc_phys_pages(pool_pages) };
+    let pool_ptr = phys_to_virt(pool_gpa).expect("failed to map pool pages");
+    let pool_gva = pool_ptr as u64;
+    let pool_size = pool_pages as usize * PAGE_SIZE_USIZE;
+    unsafe { core::ptr::write_bytes(pool_ptr, 0, pool_size) };
+
+    // Create G2H producer
+    unsafe {
+        state::init_g2h_producer(g2h_gva, g2h_depth, pool_gva, pool_size);
+    }
+
+    // TODO(virtq): add other direction's producer
+    let _ = (h2g_gva, h2g_depth);
+}

src/hyperlight_guest_bin/src/virtq/state.rs

@@ -0,0 +1,75 @@
+/*
+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 state and initialization.
+//!
+//! Holds the global VirtqProducer instances for G2H and H2G queues.
+//! The producers are created during guest init (from `hyperlight_guest_bin`)
+//! and used by the guest host-call path in `host_comm`.
+
+use alloc::rc::Rc;
+use core::cell::RefCell;
+use core::num::NonZeroU16;
+
+use hyperlight_common::virtq::{BufferPool, Layout, Notifier, QueueStats, VirtqProducer};
+use hyperlight_guest::virtq_mem::GuestMemOps;
+
+/// Wrapper to mark types as Sync for single-threaded guest execution.
+struct SyncWrap<T>(T);
+
+// SAFETY: guest execution is single-threaded.
+unsafe impl<T> Sync for SyncWrap<T> {}
+
+/// Guest-side notifier (no-op).
+#[derive(Clone, Copy)]
+pub struct GuestNotifier;
+
+impl Notifier for GuestNotifier {
+    fn notify(&self, _stats: QueueStats) {}
+}
+
+/// Type alias for the guest-side producer.
+pub type GuestProducer = VirtqProducer<GuestMemOps, GuestNotifier, Rc<BufferPool>>;
+/// Global G2H producer instance, initialized during guest init.
+static G2H_PRODUCER: SyncWrap<RefCell<Option<GuestProducer>>> = SyncWrap(RefCell::new(None));
+
+/// Borrow the G2H producer mutably.
+///
+/// # Panics
+///
+/// Panics if the G2H producer has not been initialized or is already
+/// borrowed.
+pub fn with_g2h_producer<R>(f: impl FnOnce(&mut GuestProducer) -> R) -> R {
+    let mut guard = G2H_PRODUCER.0.borrow_mut();
+    let producer = guard.as_mut().expect("G2H producer not initialized");
+    f(producer)
+}
+
+/// Initialize the G2H producer
+///
+/// # Safety
+///
+/// The ring GVA must point to valid, zeroed ring memory of the
+/// appropriate size. The pool GVA must point to valid, zeroed memory.
+pub unsafe fn init_g2h_producer(ring_gva: u64, num_descs: u16, pool_gva: u64, pool_size: usize) {
+    let nz = NonZeroU16::new(num_descs).expect("G2H queue depth must be non-zero");
+    let pool = BufferPool::new(pool_gva, pool_size).expect("failed to create G2H buffer pool");
+
+    let layout = unsafe { Layout::from_base(ring_gva, nz) }.expect("invalid G2H ring layout");
+    let producer = VirtqProducer::new(layout, GuestMemOps, GuestNotifier, Rc::new(pool));
+
+    *G2H_PRODUCER.0.borrow_mut() = Some(producer);
+}

src/hyperlight_guest_bin/src/virtq_init.rs

@@ -574,6 +574,10 @@ impl SandboxMemoryManager<HostSharedMemory> {
             scratch_size - SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET as usize,
             self.layout.sandbox_memory_config.get_h2g_queue_depth() as u16,
         )?;
+        self.scratch_mem.write::<u16>(
+            scratch_size - SCRATCH_TOP_VIRTQ_POOL_PAGES_OFFSET as usize,
+            self.layout.sandbox_memory_config.get_virtq_pool_pages() as u16,
+        )?;
 
         // Copy the page tables into the scratch region
         let snapshot_pt_end = self.shared_mem.mem_size();

src/hyperlight_host/src/mem/mgr.rs

@@ -80,6 +80,9 @@ pub struct SandboxConfiguration {
     /// Number of descriptors for the host-to-guest virtqueue. Must be a power of 2.
     /// Default: 32
     h2g_queue_depth: usize,
+    /// Number of physical pages to allocate for each virtqueue's buffer pool.
+    /// Default: 8 pages (32KB).
+    virtq_pool_pages: usize,
 }
 
 impl SandboxConfiguration {
@@ -103,6 +106,8 @@ impl SandboxConfiguration {
     pub const DEFAULT_G2H_QUEUE_DEPTH: usize = 64;
     /// The default H2G virtqueue depth (number of descriptors, must be power of 2)
     pub const DEFAULT_H2G_QUEUE_DEPTH: usize = 32;
+    /// The default number of physical pages per virtqueue buffer pool
+    pub const DEFAULT_VIRTQ_POOL_PAGES: usize = 8;
 
     #[allow(clippy::too_many_arguments)]
     /// Create a new configuration for a sandbox with the given sizes.
@@ -126,6 +131,7 @@ impl SandboxConfiguration {
             interrupt_vcpu_sigrtmin_offset,
             g2h_queue_depth: Self::DEFAULT_G2H_QUEUE_DEPTH,
             h2g_queue_depth: Self::DEFAULT_H2G_QUEUE_DEPTH,
+            virtq_pool_pages: Self::DEFAULT_VIRTQ_POOL_PAGES,
             #[cfg(gdb)]
             guest_debug_info,
             #[cfg(crashdump)]
@@ -231,6 +237,26 @@ impl SandboxConfiguration {
         self.h2g_queue_depth
     }
 
+    /// Get the number of physical pages per virtqueue buffer pool.
+    pub fn get_virtq_pool_pages(&self) -> usize {
+        self.virtq_pool_pages
+    }
+
+    /// Set the G2H virtqueue depth (number of descriptors, must be power of 2).
+    pub fn set_g2h_queue_depth(&mut self, depth: usize) {
+        self.g2h_queue_depth = depth;
+    }
+
+    /// Set the H2G virtqueue depth (number of descriptors, must be power of 2).
+    pub fn set_h2g_queue_depth(&mut self, depth: usize) {
+        self.h2g_queue_depth = depth;
+    }
+
+    /// Set the number of physical pages per virtqueue buffer pool.
+    pub fn set_virtq_pool_pages(&mut self, pages: usize) {
+        self.virtq_pool_pages = pages;
+    }
+
     /// Set the size of the scratch regiong
     #[instrument(skip_all, parent = Span::current(), level= "Trace")]
     pub fn set_scratch_size(&mut self, scratch_size: usize) {

src/hyperlight_host/src/sandbox/config.rs

@@ -545,6 +545,9 @@ fn guest_malloc_abort() {
 
     let mut cfg = SandboxConfiguration::default();
     cfg.set_heap_size(heap_size);
+    cfg.set_g2h_queue_depth(2);
+    cfg.set_h2g_queue_depth(2);
+    cfg.set_virtq_pool_pages(2);
     with_rust_sandbox_cfg(cfg, |mut sbox2| {
         let err = sbox2
             .call::<i32>(
@@ -621,6 +624,9 @@ fn guest_panic_no_alloc() {
 
     let mut cfg = SandboxConfiguration::default();
     cfg.set_heap_size(heap_size);
+    cfg.set_g2h_queue_depth(2);
+    cfg.set_h2g_queue_depth(2);
+    cfg.set_virtq_pool_pages(2);
     with_rust_sandbox_cfg(cfg, |mut sbox| {
         let res = sbox
             .call::<i32>(
@@ -1680,7 +1686,9 @@ fn exception_handler_installation_and_validation() {
 /// This validates that the exception handling path does not require heap allocations.
 #[test]
 fn fill_heap_and_cause_exception() {
-    with_rust_sandbox(|mut sandbox| {
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_virtq_pool_pages(2);
+    with_rust_sandbox_cfg(cfg, |mut sandbox| {
         let result = sandbox.call::<()>("FillHeapAndCauseException", ());
 
         // The call should fail with an exception error since there's no handler installed