feat(virtq): add virtqueue ring plumbing in scratch region

Place G2H and H2G packed virtqueue descriptor rings at deterministic
offsets in the scratch region.

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

Author: andreiltd

Cargo.lock

@@ -20,6 +20,11 @@ pub const SNAPSHOT_PT_GVA_MIN: usize = 0xffff_8000_0000_0000;
 pub const SNAPSHOT_PT_GVA_MAX: usize = 0xffff_80ff_ffff_ffff;
 pub const MAX_GPA: usize = 0x0000_000f_ffff_ffff;
 
-pub fn min_scratch_size(_input_data_size: usize, _output_data_size: usize) -> usize {
+pub fn min_scratch_size(
+    _input_data_size: usize,
+    _output_data_size: usize,
+    _g2h_num_descs: usize,
+    _h2g_num_descs: usize,
+) -> usize {
     unimplemented!("min_scratch_size")
 }

src/hyperlight_common/src/arch/aarch64/layout.rs

@@ -37,8 +37,17 @@ pub const MAX_GPA: usize = 0x0000_000f_ffff_ffff;
 /// - A page for the smallest possible non-exception stack
 /// - (up to) 3 pages for mapping that
 /// - Two pages for the exception stack and metadata
-/// - A page-aligned amount of memory for I/O buffers (for now)
-pub fn min_scratch_size(input_data_size: usize, output_data_size: usize) -> usize {
-    (input_data_size + output_data_size).next_multiple_of(crate::vmem::PAGE_SIZE)
+/// - A page-aligned amount of memory for I/O buffers and virtqueue rings
+pub fn min_scratch_size(
+    input_data_size: usize,
+    output_data_size: usize,
+    g2h_num_descs: usize,
+    h2g_num_descs: usize,
+) -> usize {
+    let g2h_ring_size = crate::virtq::Layout::query_size(g2h_num_descs);
+    let h2g_ring_size = crate::virtq::Layout::query_size(h2g_num_descs);
+
+    (input_data_size + output_data_size + g2h_ring_size + h2g_ring_size)
+        .next_multiple_of(crate::vmem::PAGE_SIZE)
         + 12 * crate::vmem::PAGE_SIZE
 }

src/hyperlight_common/src/arch/amd64/layout.rs

@@ -20,6 +20,11 @@ limitations under the License.
 pub const MAX_GVA: usize = 0xffff_ffff;
 pub const MAX_GPA: usize = 0xffff_ffff;
 
-pub fn min_scratch_size(_input_data_size: usize, _output_data_size: usize) -> usize {
+pub fn min_scratch_size(
+    _input_data_size: usize,
+    _output_data_size: usize,
+    _g2h_num_descs: usize,
+    _h2g_num_descs: usize,
+) -> usize {
     crate::vmem::PAGE_SIZE
 }

src/hyperlight_common/src/arch/i686/layout.rs

@@ -33,11 +33,26 @@ pub use arch::{MAX_GPA, MAX_GVA};
 ))]
 pub use arch::{SNAPSHOT_PT_GVA_MAX, SNAPSHOT_PT_GVA_MIN};
 
-// offsets down from the top of scratch memory for various things
 pub const SCRATCH_TOP_SIZE_OFFSET: u64 = 0x08;
 pub const SCRATCH_TOP_ALLOCATOR_OFFSET: u64 = 0x10;
 pub const SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET: u64 = 0x18;
-pub const SCRATCH_TOP_EXN_STACK_OFFSET: u64 = 0x20;
+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_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_EXN_STACK_OFFSET % 0x10 == 0);
+};
 
 /// Offset from the top of scratch memory for a shared host-guest u64 counter.
 ///
@@ -55,5 +70,30 @@ pub fn scratch_base_gva(size: usize) -> u64 {
     (MAX_GVA - size + 1) as u64
 }
 
+/// Compute the byte offset from the scratch base to the G2H ring.
+///
+/// TODO(ring): 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;
+
+    (io_off + align - 1) & !(align - 1)
+}
+
+/// Compute the byte offset from the scratch base to the H2G ring.
+///
+/// TODO(ring): Remove input/output
+pub const fn h2g_ring_scratch_offset(
+    input_data_size: usize,
+    output_data_size: usize,
+    g2h_num_descs: usize,
+) -> usize {
+    let g2h_offset = g2h_ring_scratch_offset(input_data_size, output_data_size);
+    let g2h_size = crate::virtq::Layout::query_size(g2h_num_descs);
+    let align = crate::virtq::Descriptor::ALIGN;
+
+    (g2h_offset + g2h_size + align - 1) & !(align - 1)
+}
+
 /// Compute the minimum scratch region size needed for a sandbox.
 pub use arch::min_scratch_size;

src/hyperlight_common/src/layout.rs

@@ -105,6 +105,8 @@ pub enum OutBAction {
     TraceMemoryAlloc = 105,
     #[cfg(feature = "mem_profile")]
     TraceMemoryFree = 106,
+    /// Notification that entries are available on a virtqueue.
+    VirtqNotify = 109,
 }
 
 /// IO-port actions intercepted at the hypervisor level (in `run_vcpu`)
@@ -137,6 +139,7 @@ impl TryFrom<u16> for OutBAction {
             105 => Ok(OutBAction::TraceMemoryAlloc),
             #[cfg(feature = "mem_profile")]
             106 => Ok(OutBAction::TraceMemoryFree),
+            109 => Ok(OutBAction::VirtqNotify),
             _ => Err(anyhow::anyhow!("Invalid OutBAction value: {}", val)),
         }
     }

src/hyperlight_common/src/outb.rs

@@ -59,14 +59,16 @@ pub struct Descriptor {
 }
 
 const _: () = assert!(core::mem::size_of::<Descriptor>() == 16);
+const _: () = assert!(Descriptor::ALIGN == 16);
 const _: () = assert!(Descriptor::ADDR_OFFSET == 0);
 const _: () = assert!(Descriptor::LEN_OFFSET == 8);
 const _: () = assert!(Descriptor::ID_OFFSET == 12);
 const _: () = assert!(Descriptor::FLAGS_OFFSET == 14);
 
 impl Descriptor {
+    // VIRTIO spec requires 16-byte alignment for descriptors
+    pub const ALIGN: usize = 16;
     pub const SIZE: usize = core::mem::size_of::<Self>();
-    pub const ALIGN: usize = core::mem::align_of::<Self>();
 
     pub const ADDR_OFFSET: usize = core::mem::offset_of!(Self, addr);
     pub const LEN_OFFSET: usize = core::mem::offset_of!(Self, len);

src/hyperlight_common/src/virtq/desc.rs

@@ -154,6 +154,7 @@ mod access;
 mod consumer;
 mod desc;
 mod event;
+pub mod msg;
 mod pool;
 mod producer;
 mod ring;

src/hyperlight_common/src/virtq/mod.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.
+*/
+
+//! Wire format header for all virtqueue messages.
+//!
+//! Every payload on both the G2H and H2G queues starts with this
+//! fixed 8-byte header, enabling message type discrimination and
+//! request/response correlation.
+
+/// Message types for the virtqueue wire protocol.
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MsgKind {
+    /// A function call request (FunctionCall payload follows).
+    Request = 0x01,
+    /// A function call response (FunctionCallResult payload follows).
+    Response = 0x02,
+    /// A stream data chunk.
+    StreamChunk = 0x03,
+    /// End-of-stream marker.
+    StreamEnd = 0x04,
+    /// Cancel a pending request.
+    Cancel = 0x05,
+}
+
+/// Wire header for all virtqueue messages
+#[derive(Debug, Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
+#[repr(C)]
+pub struct VirtqMsgHeader {
+    /// Discriminates the message type.
+    pub kind: u8,
+    /// Per-type flags TODO(ring): add flags type.
+    pub flags: u8,
+    /// Caller-assigned correlation ID. Responses echo the request's ID.
+    pub req_id: u16,
+    /// Byte length of the payload following this header.
+    pub payload_len: u32,
+}
+
+impl VirtqMsgHeader {
+    pub const SIZE: usize = core::mem::size_of::<Self>();
+
+    /// Create a new message header.
+    pub const fn new(kind: MsgKind, req_id: u16, payload_len: u32) -> Self {
+        Self {
+            kind: kind as u8,
+            flags: 0,
+            req_id,
+            payload_len,
+        }
+    }
+
+    /// Create a new header with flags.
+    pub const fn with_flags(kind: MsgKind, flags: u8, req_id: u16, payload_len: u32) -> Self {
+        Self {
+            kind: kind as u8,
+            flags,
+            req_id,
+            payload_len,
+        }
+    }
+}

src/hyperlight_common/src/virtq/msg.rs

@@ -52,6 +52,7 @@ pub mod host_comm;
 pub mod memory;
 #[cfg(target_arch = "x86_64")]
 pub mod paging;
+mod virtq_init;
 
 // Globals
 #[cfg(all(feature = "mem_profile", target_arch = "x86_64"))]
@@ -235,6 +236,9 @@ pub(crate) extern "C" fn generic_init(
         OS_PAGE_SIZE = ops as u32;
     }
 
+    // Initialize virtqueues
+    virtq_init::init_virtqueues();
+
     // set up the logger
     let guest_log_level_filter =
         GuestLogFilter::try_from(max_log_level).expect("Invalid log level");