feat(virtq): add with_hint function call API

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

Author: andreiltd

src/hyperlight_guest/src/virtq/context.rs

@@ -118,13 +118,35 @@ impl GuestContext {
 
     /// Call a host function via the G2H virtqueue.
     ///
-    /// The reply guard is checked before submitting the readwrite chain
-    /// to ensure G2H capacity is reserved for pending responses.
+    /// Uses the default completion capacity (4096 bytes) for the response
+    /// buffer. For host functions known to return large payloads, use
+    /// [`call_host_function_with_hint`](Self::call_host_function_with_hint).
     pub fn call_host_function<T: TryFrom<ReturnValue>>(
         &mut self,
         function_name: &str,
         parameters: Option<Vec<ParameterValue>>,
         return_type: ReturnType,
+    ) -> Result<T> {
+        self.call_host_function_with_hint(
+            function_name,
+            parameters,
+            return_type,
+            self.g2h_response_cap,
+        )
+    }
+
+    /// Call a host function with an explicit response capacity hint.
+    ///
+    /// `resp_hint` is the total completion buffer size in bytes
+    /// (including wire overhead: VirtqMsgHeader + FlatBuffer framing).
+    /// The BufferPool allocates multiple adjacent slots when the hint
+    /// exceeds a single slot size, so this is zero-copy for the host.
+    pub fn call_host_function_with_hint<T: TryFrom<ReturnValue>>(
+        &mut self,
+        function_name: &str,
+        parameters: Option<Vec<ParameterValue>>,
+        return_type: ReturnType,
+        resp_hint: usize,
     ) -> Result<T> {
         let params = parameters.as_deref().unwrap_or_default();
         let estimated_capacity = estimate_flatbuffer_capacity(function_name, params);
@@ -140,15 +162,15 @@ impl GuestContext {
         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 msg = VirtqMsgHeader::new(MsgKind::Request, reqid, payload.len() as u32);
+        let hdr = bytemuck::bytes_of(&msg);
 
         let entry_len = VirtqMsgHeader::SIZE + payload.len();
 
         // Reply guard: readwrite chains use 2 descriptors, leave room for pending replies.
         self.ensure_reply_capacity(2)?;
 
-        let token = match self.try_send_readwrite(hdr_bytes, payload, entry_len) {
+        let token = match self.try_send_readwrite(hdr, payload, entry_len, resp_hint) {
             Ok(tok) => tok,
             Err(e) if e.is_transient() => {
                 self.g2h_producer.notify_backpressure();
@@ -157,7 +179,7 @@ impl GuestContext {
                     bail!("G2H reclaim: {err}");
                 }
 
-                let Ok(tok) = self.try_send_readwrite(hdr_bytes, payload, entry_len) else {
+                let Ok(tok) = self.try_send_readwrite(hdr, payload, entry_len, resp_hint) else {
                     bail!("G2H call retry");
                 };
 
@@ -436,12 +458,13 @@ impl GuestContext {
         header: &[u8],
         payload: &[u8],
         entry_len: usize,
+        completion_cap: usize,
     ) -> result::Result<Token, virtq::VirtqError> {
         let mut entry = self
             .g2h_producer
             .chain()
             .entry(entry_len)
-            .completion(self.g2h_response_cap)
+            .completion(completion_cap)
             .build()?;
 
         entry.write_all(header)?;

src/hyperlight_guest_bin/src/host_comm.rs

@@ -47,6 +47,24 @@ where
     virtq::with_context(|ctx| ctx.call_host_function(function_name, parameters, return_type))
 }
 
+/// Call a host function with an explicit response capacity hint.
+///
+/// `response_hint` is the total completion buffer size in bytes including wire overhead.
+/// Use this when you know the host function returns a large payload (e.g., >4096 bytes).
+pub fn call_host_function_with_hint<T>(
+    function_name: &str,
+    parameters: Option<Vec<ParameterValue>>,
+    return_type: ReturnType,
+    response_hint: usize,
+) -> Result<T>
+where
+    T: TryFrom<ReturnValue>,
+{
+    virtq::with_context(|ctx| {
+        ctx.call_host_function_with_hint(function_name, parameters, return_type, response_hint)
+    })
+}
+
 pub fn call_host<T>(function_name: impl AsRef<str>, args: impl ParameterTuple) -> Result<T>
 where
     T: SupportedReturnType + TryFrom<ReturnValue>,

src/hyperlight_host/src/sandbox/outb.rs

@@ -273,29 +273,31 @@ fn outb_virtq_call(
         .try_lock()
         .map_err(|e| HandleOutbError::LockFailed(file!(), line!(), e.to_string()))?;
 
-    let mut res = registry
+    let res = registry
         .call_host_function(&name, args)
         .map_err(|e| GuestError::new(ErrorCode::HostFunctionError, e.to_string()));
 
-    // Truncate oversized error messages so the serialized response
-    // fits in the completion buffer the guest pre-allocated.
-    if let Err(err) = &mut res
-        && err.message.len() > wc.capacity()
-    {
-        err.message.truncate(wc.capacity());
-    }
-
-    // Serialize response: VirtqMsgHeader + FunctionCallResult
     let func_result = FunctionCallResult::new(res);
     let mut builder = flatbuffers::FlatBufferBuilder::new();
-    let result_payload = func_result.encode(&mut builder);
+    let mut result_payload = func_result.encode(&mut builder).to_vec();
+
+    let total = VirtqMsgHeader::SIZE + result_payload.len();
+    if total > wc.capacity() {
+        let too_large = GuestError::new(
+            ErrorCode::HostFunctionError,
+            "response too large for completion buffer".into(),
+        );
+        let fallback = FunctionCallResult::new(Err(too_large));
+        let mut fb = flatbuffers::FlatBufferBuilder::new();
+        result_payload = fallback.encode(&mut fb).to_vec();
+    }
 
     let resp_header = VirtqMsgHeader::new(MsgKind::Response, 0, result_payload.len() as u32);
     let resp_header_bytes = bytemuck::bytes_of(&resp_header);
 
     wc.write_all(resp_header_bytes)
         .map_err(|e| HandleOutbError::WriteHostFunctionResponse(format!("{e}")))?;
-    wc.write_all(result_payload)
+    wc.write_all(&result_payload)
         .map_err(|e| HandleOutbError::WriteHostFunctionResponse(format!("{e}")))?;
     consumer
         .complete(wc.into())

src/hyperlight_host/tests/sandbox_host_tests.rs

@@ -564,3 +564,88 @@ fn virtq_multi_descriptor_h2g_repeated_calls() {
         }
     });
 }
+
+/// Helper to create a sandbox with a "GetLargeResponse" host function
+/// that returns `size` bytes filled with 0xAB.
+fn sandbox_with_large_response(cfg: SandboxConfiguration) -> MultiUseSandbox {
+    let mut sandbox = UninitializedSandbox::new(
+        GuestBinary::FilePath(simple_guest_as_string().unwrap()),
+        Some(cfg),
+    )
+    .unwrap();
+    sandbox
+        .register("GetLargeResponse", |size: i32| -> Result<Vec<u8>> {
+            Ok(vec![0xABu8; size as usize])
+        })
+        .unwrap();
+    sandbox.evolve().unwrap()
+}
+
+#[test]
+fn virtq_large_g2h_response_with_hint() {
+    // Host function returns >4096 bytes. Guest uses a sized completion
+    // hint so the pool allocates multiple adjacent slots.
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_g2h_pool_pages(16);
+    let mut sandbox = sandbox_with_large_response(cfg);
+
+    // 8000 bytes of response payload. With FlatBuffer + header overhead,
+    // the wire size is ~8100 bytes. A hint of 3*4096 = 12288 is enough.
+    let hint = 3 * 4096i32;
+    let res: Vec<u8> = sandbox
+        .call("CallGetLargeResponseWithHint", (8000i32, hint))
+        .unwrap();
+    assert_eq!(res.len(), 8000);
+    assert!(res.iter().all(|&b| b == 0xAB));
+}
+
+#[test]
+fn virtq_large_g2h_response_too_large_without_hint() {
+    // Without a hint, the default 4096-byte completion buffer is used.
+    // A response >4096 bytes should trigger the host's "response too
+    // large" fallback error instead of a transport crash.
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_g2h_pool_pages(16);
+    let mut sandbox = sandbox_with_large_response(cfg);
+
+    let res = sandbox.call::<Vec<u8>>("CallGetLargeResponseDefault", 8000i32);
+    assert!(
+        res.is_err(),
+        "expected error for oversized response without hint"
+    );
+}
+
+#[test]
+fn virtq_large_g2h_response_boundary() {
+    // Response that fits exactly in one page (with overhead) should work
+    // without needing a hint.
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_g2h_pool_pages(16);
+    let mut sandbox = sandbox_with_large_response(cfg);
+
+    // Small response that fits in default 4096 buffer
+    let res: Vec<u8> = sandbox
+        .call("CallGetLargeResponseDefault", 1000i32)
+        .unwrap();
+    assert_eq!(res.len(), 1000);
+    assert!(res.iter().all(|&b| b == 0xAB));
+}
+
+#[test]
+fn virtq_large_g2h_response_after_log_backpressure() {
+    // Logs fill the G2H pool, then a large host response (with hint)
+    // needs multi-slot allocation. The backpressure path must drain
+    // completed log entries to free pool slots for the large completion.
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_g2h_pool_pages(16);
+    let mut sandbox = sandbox_with_large_response(cfg);
+
+    // Emit 20 log entries to consume pool slots, then request 8KB
+    // response with a 12KB hint (3 upper-slab slots).
+    let hint = 3 * 4096i32;
+    let res: Vec<u8> = sandbox
+        .call("LogThenLargeResponse", (20i32, 8000i32, hint))
+        .unwrap();
+    assert_eq!(res.len(), 8000);
+    assert!(res.iter().all(|&b| b == 0xAB));
+}

src/tests/rust_guests/simpleguest/src/main.rs

@@ -49,7 +49,8 @@ use hyperlight_guest_bin::exception::arch::{Context, ExceptionInfo};
 use hyperlight_guest_bin::guest_function::definition::{GuestFunc, GuestFunctionDefinition};
 use hyperlight_guest_bin::guest_function::register::register_function;
 use hyperlight_guest_bin::host_comm::{
-    call_host_function, print_output_with_host_print, read_n_bytes_from_user_memory,
+    call_host_function, call_host_function_with_hint, print_output_with_host_print,
+    read_n_bytes_from_user_memory,
 };
 use hyperlight_guest_bin::memory::malloc;
 use hyperlight_guest_bin::{guest_function, guest_logger, host_function};
@@ -379,6 +380,49 @@ fn echo(value: String) -> String {
     value
 }
 
+/// Calls a host function "GetLargeResponse" with an explicit response
+/// capacity hint. The `hint` parameter is the total completion buffer
+/// size in bytes.
+#[guest_function("CallGetLargeResponseWithHint")]
+fn call_get_large_response_with_hint(size: i32, hint: i32) -> Vec<u8> {
+    call_host_function_with_hint::<Vec<u8>>(
+        "GetLargeResponse",
+        Some(vec![ParameterValue::Int(size)]),
+        ReturnType::VecBytes,
+        hint as usize,
+    )
+    .expect("GetLargeResponse call failed")
+}
+
+/// Calls a host function "GetLargeResponse" WITHOUT a hint, using the
+/// default 4096-byte completion buffer.
+#[guest_function("CallGetLargeResponseDefault")]
+fn call_get_large_response_default(size: i32) -> Vec<u8> {
+    call_host_function::<Vec<u8>>(
+        "GetLargeResponse",
+        Some(vec![ParameterValue::Int(size)]),
+        ReturnType::VecBytes,
+    )
+    .expect("GetLargeResponse call failed")
+}
+
+/// Emits `log_count` log entries to fill the G2H queue, then calls
+/// "GetLargeResponse" with a sized hint. Tests that backpressure
+/// draining of logs frees pool slots for the large completion.
+#[guest_function("LogThenLargeResponse")]
+fn log_then_large_response(log_count: i32, size: i32, hint: i32) -> Vec<u8> {
+    for i in 0..log_count {
+        log::info!("backpressure log {}", i);
+    }
+    call_host_function_with_hint::<Vec<u8>>(
+        "GetLargeResponse",
+        Some(vec![ParameterValue::Int(size)]),
+        ReturnType::VecBytes,
+        hint as usize,
+    )
+    .expect("GetLargeResponse after logs failed")
+}
+
 #[guest_function("GetSizePrefixedBuffer")]
 fn get_size_prefixed_buffer(data: Vec<u8>) -> Vec<u8> {
     data