feat: implement virtio based host-guest communication

Cargo.toml

@@ -48,6 +48,7 @@ hyperlight-component-macro = { path = "src/hyperlight_component_macro", version
 
 [workspace.lints.rust]
 unsafe_op_in_unsafe_fn = "deny"
+unexpected_cfgs = { level = "warn", check-cfg = [ 'cfg(loom)' ] }
 
 # this will generate symbols for release builds
 # so is handy for debugging issues in release builds

fuzz/fuzz_targets/guest_trace.rs

@@ -69,8 +69,8 @@ impl<'a> Arbitrary<'a> for FuzzInput {
 fuzz_target!(
     init: {
         let mut cfg = SandboxConfiguration::default();
-        // In local tests, 256 KiB seemed sufficient for deep recursion
-        cfg.set_scratch_size(256 * 1024);
+        // In local tests, 512 KiB seemed sufficient for deep recursion
+        cfg.set_scratch_size(512 * 1024);
         let path = simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing");
         let u_sbox = UninitializedSandbox::new(
             GuestBinary::FilePath(path),

fuzz/fuzz_targets/host_call.rs

@@ -33,9 +33,9 @@ static SANDBOX: OnceLock<Mutex<MultiUseSandbox>> = OnceLock::new();
 fuzz_target!(
     init: {
         let mut cfg = SandboxConfiguration::default();
-        cfg.set_output_data_size(64 * 1024); // 64 KB output buffer
-        cfg.set_input_data_size(64 * 1024); // 64 KB input buffer
-        cfg.set_scratch_size(512 * 1024); // large scratch region to contain those buffers, any data copies, etc.
+        cfg.set_g2h_pool_pages(16); // 64 KB / 4096 = 16 pages
+        cfg.set_h2g_pool_pages(16); // 64 KB / 4096 = 16 pages
+        cfg.set_scratch_size(512 * 1024); // large scratch region
         let u_sbox = UninitializedSandbox::new(
             GuestBinary::FilePath(simple_guest_for_fuzzing_as_string().expect("Guest Binary Missing")),
             Some(cfg)
@@ -61,6 +61,8 @@ fuzz_target!(
                 HyperlightError::GuestError(ErrorCode::HostFunctionError, msg) if msg.contains("The number of arguments to the function is wrong") => {}
                 HyperlightError::ParameterValueConversionFailure(_, _) => {},
                 HyperlightError::GuestError(ErrorCode::HostFunctionError, msg) if msg.contains("Failed To Convert Parameter Value") => {}
+                HyperlightError::GuestError(ErrorCode::HostFunctionError, msg) if msg.contains("The parameter value type is unexpected") => {}
+                HyperlightError::GuestError(ErrorCode::HostFunctionError, msg) if msg.contains("The return value type is unexpected") => {}
 
                 // any other error should be reported
                 _ => panic!("Guest Aborted with Unexpected Error: {:?}", e),

src/hyperlight_common/Cargo.toml

@@ -15,13 +15,18 @@ Hyperlight's components common to host and guest.
 workspace = true
 
 [dependencies]
-flatbuffers = { version = "25.12.19", default-features = false }
+arbitrary = {version = "1.4.2", optional = true, features = ["derive"]}
 anyhow = { version = "1.0.102", default-features = false }
+bitflags = "2.10.0"
+bytemuck = { version = "1.24", features = ["derive"] }
+bytes = { version = "1",  default-features = false }
+fixedbitset = { version = "0.5.7",  default-features = false }
+flatbuffers = { version = "25.12.9", default-features = false }
 log = "0.4.29"
-tracing = { version = "0.1.44", optional = true }
-arbitrary = {version = "1.4.2", optional = true, features = ["derive"]}
+smallvec = "1.15.1"
 spin = "0.10.0"
 thiserror = { version = "2.0.18", default-features = false }
+tracing = { version = "0.1.44", optional = true }
 tracing-core = { version = "0.1.36", default-features = false }
 
 [features]
@@ -33,6 +38,19 @@ mem_profile = []
 std = ["thiserror/std", "log/std", "tracing/std"]
 nanvix-unstable = []
 
+[dev-dependencies]
+criterion = "0.8.1"
+hyperlight-testing = { workspace = true }
+quickcheck = "1.0.3"
+rand = "0.9.2"
+
+[target.'cfg(loom)'.dev-dependencies]
+loom = "0.7"
+
 [lib]
 bench = false # see https://bheisler.github.io/criterion.rs/book/faq.html#cargo-bench-gives-unrecognized-option-errors-for-valid-command-line-options
 doctest = false # reduce noise in test output
+
+[[bench]]
+name = "buffer_pool"
+harness = false

src/hyperlight_common/benches/buffer_pool.rs

@@ -0,0 +1,192 @@
+/*
+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.
+*/
+
+use std::hint::black_box;
+
+use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
+use hyperlight_common::virtq::{BufferPool, BufferProvider};
+
+// Helper to create a pool for benchmarking
+fn make_pool<const L: usize, const U: usize>(size: usize) -> BufferPool<L, U> {
+    let base = 0x10000;
+    BufferPool::<L, U>::new(base, size).unwrap()
+}
+
+// Single allocation performance
+fn bench_alloc_single(c: &mut Criterion) {
+    let mut group = c.benchmark_group("alloc_single");
+
+    for size in [64, 128, 256, 512, 1024, 1500, 4096].iter() {
+        group.throughput(Throughput::Elements(1));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+            b.iter(|| {
+                let alloc = pool.alloc(black_box(size)).unwrap();
+                pool.dealloc(alloc).unwrap();
+            });
+        });
+    }
+    group.finish();
+}
+
+// LIFO recycling
+fn bench_alloc_lifo(c: &mut Criterion) {
+    let mut group = c.benchmark_group("alloc_lifo");
+
+    for size in [256, 1500, 4096].iter() {
+        group.throughput(Throughput::Elements(100));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+            b.iter(|| {
+                for _ in 0..100 {
+                    let alloc = pool.alloc(black_box(size)).unwrap();
+                    pool.dealloc(alloc).unwrap();
+                }
+            });
+        });
+    }
+    group.finish();
+}
+
+// Fragmented allocation worst case
+fn bench_alloc_fragmented(c: &mut Criterion) {
+    let mut group = c.benchmark_group("alloc_fragmented");
+
+    group.bench_function("fragmented_256", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+
+        // Create fragmentation pattern: allocate many, free every other
+        let mut allocations = Vec::new();
+        for _ in 0..100 {
+            allocations.push(pool.alloc(128).unwrap());
+        }
+        for i in (0..100).step_by(2) {
+            pool.dealloc(allocations[i]).unwrap();
+        }
+
+        b.iter(|| {
+            let alloc = pool.alloc(black_box(256)).unwrap();
+            pool.dealloc(alloc).unwrap();
+        });
+    });
+
+    group.finish();
+}
+
+// Realloc operations
+fn bench_realloc(c: &mut Criterion) {
+    let mut group = c.benchmark_group("realloc");
+
+    // In-place grow (same tier)
+    group.bench_function("grow_inplace", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+        b.iter(|| {
+            let alloc = pool.alloc(256).unwrap();
+            let grown = pool.resize(alloc, black_box(512)).unwrap();
+            pool.dealloc(grown).unwrap();
+        });
+    });
+
+    // Relocate grow (cross tier)
+    group.bench_function("grow_relocate", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+        b.iter(|| {
+            let alloc = pool.alloc(128).unwrap();
+            // Block in-place growth
+            let blocker = pool.alloc(256).unwrap();
+            let grown = pool.resize(alloc, black_box(1500)).unwrap();
+            pool.dealloc(grown).unwrap();
+            pool.dealloc(blocker).unwrap();
+        });
+    });
+
+    // Shrink
+    group.bench_function("shrink", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+        b.iter(|| {
+            let alloc = pool.alloc(1500).unwrap();
+            let shrunk = pool.resize(alloc, black_box(256)).unwrap();
+            pool.dealloc(shrunk).unwrap();
+        });
+    });
+
+    group.finish();
+}
+
+// Free performance
+fn bench_free(c: &mut Criterion) {
+    let mut group = c.benchmark_group("free");
+
+    for size in [256, 1500, 4096].iter() {
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+            b.iter(|| {
+                let alloc = pool.alloc(size).unwrap();
+                pool.dealloc(black_box(alloc)).unwrap();
+            });
+        });
+    }
+
+    group.finish();
+}
+
+// Cursor optimization
+fn bench_last_free_run(c: &mut Criterion) {
+    let mut group = c.benchmark_group("last_free_run");
+
+    // With cursor optimization (LIFO)
+    group.bench_function("lifo_pattern", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+        b.iter(|| {
+            let alloc = pool.alloc(256).unwrap();
+            pool.dealloc(alloc).unwrap();
+            let alloc2 = pool.alloc(black_box(256)).unwrap();
+            pool.dealloc(alloc2).unwrap();
+        });
+    });
+
+    // Without cursor benefit (FIFO-like)
+    group.bench_function("fifo_pattern", |b| {
+        let pool = make_pool::<256, 4096>(4 * 1024 * 1024);
+        let mut queue = Vec::new();
+
+        // Pre-fill queue
+        for _ in 0..10 {
+            queue.push(pool.alloc(256).unwrap());
+        }
+
+        b.iter(|| {
+            // FIFO: free oldest, allocate new
+            let old = queue.remove(0);
+            pool.dealloc(old).unwrap();
+            queue.push(pool.alloc(black_box(256)).unwrap());
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(
+    benches,
+    bench_alloc_single,
+    bench_alloc_lifo,
+    bench_alloc_fragmented,
+    bench_realloc,
+    bench_free,
+    bench_last_free_run,
+);
+
+criterion_main!(benches);

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

@@ -20,6 +20,6 @@ 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(_g2h_num_descs: usize, _h2g_num_descs: usize) -> usize {
     unimplemented!("min_scratch_size")
 }

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

@@ -37,8 +37,11 @@ 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 virtqueue rings
+pub fn min_scratch_size(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);
+
+    (g2h_ring_size + h2g_ring_size).next_multiple_of(crate::vmem::PAGE_SIZE)
         + 12 * crate::vmem::PAGE_SIZE
 }

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

@@ -20,6 +20,6 @@ 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(_g2h_num_descs: usize, _h2g_num_descs: usize) -> usize {
     crate::vmem::PAGE_SIZE
 }

src/hyperlight_common/src/layout.rs

@@ -33,11 +33,33 @@ 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_SNAPSHOT_GENERATION_OFFSET: u64 = 0x20;
+pub const SCRATCH_TOP_G2H_RING_GVA_OFFSET: u64 = 0x28;
+pub const SCRATCH_TOP_H2G_RING_GVA_OFFSET: u64 = 0x30;
+pub const SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET: u64 = 0x38;
+pub const SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET: u64 = 0x3A;
+pub const SCRATCH_TOP_G2H_POOL_PAGES_OFFSET: u64 = 0x3C;
+pub const SCRATCH_TOP_H2G_POOL_PAGES_OFFSET: u64 = 0x3E;
+pub const SCRATCH_TOP_H2G_POOL_GVA_OFFSET: u64 = 0x48;
+pub const SCRATCH_TOP_EXN_STACK_OFFSET: u64 = 0x50;
+
+const _: () = {
+    assert!(SCRATCH_TOP_ALLOCATOR_OFFSET >= SCRATCH_TOP_SIZE_OFFSET + 8);
+    assert!(SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET >= SCRATCH_TOP_ALLOCATOR_OFFSET + 8);
+    assert!(SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET >= SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET + 8);
+    assert!(SCRATCH_TOP_G2H_RING_GVA_OFFSET >= SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET + 8);
+    assert!(SCRATCH_TOP_H2G_RING_GVA_OFFSET >= SCRATCH_TOP_G2H_RING_GVA_OFFSET + 8);
+    assert!(SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET >= SCRATCH_TOP_H2G_RING_GVA_OFFSET + 8);
+    assert!(SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET >= SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET + 2);
+    assert!(SCRATCH_TOP_G2H_POOL_PAGES_OFFSET >= SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET + 2);
+    assert!(SCRATCH_TOP_H2G_POOL_PAGES_OFFSET >= SCRATCH_TOP_G2H_POOL_PAGES_OFFSET + 2);
+    assert!(SCRATCH_TOP_H2G_POOL_GVA_OFFSET >= SCRATCH_TOP_H2G_POOL_PAGES_OFFSET + 8);
+    assert!(SCRATCH_TOP_EXN_STACK_OFFSET >= SCRATCH_TOP_H2G_POOL_GVA_OFFSET + 8);
+    assert!(SCRATCH_TOP_EXN_STACK_OFFSET % 0x10 == 0);
+};
 
 /// Offset from the top of scratch memory for a shared host-guest u64 counter.
 ///
@@ -55,5 +77,27 @@ 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.
+///
+/// The G2H ring starts at offset 0, aligned to descriptor alignment.
+pub const fn g2h_ring_scratch_offset() -> usize {
+    0
+}
+
+/// Compute the byte offset from the scratch base to the H2G ring.
+///
+/// The H2G ring follows immediately after the G2H ring, aligned to
+/// descriptor alignment.
+pub const fn h2g_ring_scratch_offset(g2h_num_descs: usize) -> usize {
+    let g2h_size = crate::virtq::Layout::query_size(g2h_num_descs);
+    let align = crate::virtq::Descriptor::ALIGN;
+
+    (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/lib.rs

@@ -18,7 +18,7 @@ limitations under the License.
 #![cfg_attr(not(any(test, debug_assertions)), warn(clippy::expect_used))]
 #![cfg_attr(not(any(test, debug_assertions)), warn(clippy::unwrap_used))]
 // We use Arbitrary during fuzzing, which requires std
-#![cfg_attr(not(feature = "fuzzing"), no_std)]
+#![cfg_attr(not(any(feature = "fuzzing", test, miri)), no_std)]
 
 extern crate alloc;
 
@@ -50,3 +50,6 @@ pub mod vmem;
 
 /// ELF note types for embedding hyperlight version metadata in guest binaries.
 pub mod version_note;
+
+/// cbindgen:ignore
+pub mod virtq;

src/hyperlight_common/src/mem.rs

@@ -68,8 +68,6 @@ impl Default for FileMappingInfo {
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub struct HyperlightPEB {
-    pub input_stack: GuestMemoryRegion,
-    pub output_stack: GuestMemoryRegion,
     pub init_data: GuestMemoryRegion,
     pub guest_heap: GuestMemoryRegion,
     /// File mappings array descriptor.