Support loading a wasm module/component via direct mapping

syntactically · syntactically · commit 3b2330b3ddea · 2025-07-10T11:42:23.000+01:00
This adds support for directly mapping a host buffer containing a wasm
module/component into the guest, enabling the use of mmap() on the host
to share a single module/component across multiple sandboxes.

Signed-off-by: Lucy Menon &lt;168595099+syntactically@users.noreply.github.com&gt;
diff --git a/flake.lock b/flake.lock
diff --git a/flake.nix b/flake.nix
@@ -0,0 +1,83 @@
+{
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  inputs.nixpkgs-mozilla.url = "github:mozilla/nixpkgs-mozilla/master";
+  outputs = { self, nixpkgs, nixpkgs-mozilla, ... } @ inputs: 
+let token = "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IktRMnRBY3JFN2xCYVZWR0JtYzVGb2JnZEpvNCIsImtpZCI6IktRMnRBY3JFN2xCYVZWR0JtYzVGb2JnZEpvNCJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNzIyODc3MzM2LCJuYmYiOjE3MjI4NzczMzYsImV4cCI6MTcyMjg4MjAyOCwiX2NsYWltX25hbWVzIjp7Imdyb3VwcyI6InNyYzEifSwiX2NsYWltX3NvdXJjZXMiOnsic3JjMSI6eyJlbmRwb2ludCI6Imh0dHBzOi8vZ3JhcGgud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3VzZXJzLzFkNDgzMWMxLWVhYTgtNGY2OS1hZTVjLTE4MTQwMjBlZTJlYy9nZXRNZW1iZXJPYmplY3RzIn19LCJhY3IiOiIxIiwiYWlvIjoiQVZRQXEvOFhBQUFBK3V0TC9hdXdsU1ppQXp1T1pjdk14aERWay9lTlJaR0tiSFNOTjZXcS9VRTlRZGJTOEdmeWFadDUyM2dsT3FOZVdDckVkQ2E1RFV5c2lHcTdJK1ZMTzJoYW9UVzJ6MFhzVm1VTEMwK1RHUGs9IiwiYW1yIjpbInB3ZCIsInJzYSIsIm1mYSJdLCJhcHBpZCI6IjA0YjA3Nzk1LThkZGItNDYxYS1iYmVlLTAyZjllMWJmN2I0NiIsImFwcGlkYWNyIjoiMCIsImNhcG9saWRzX2xhdGViaW5kIjpbIjI5Mzk5Y2Y5LTliNmItNDIwNS1iNWIzLTEzYTEzNGU5YjIzMyJdLCJkZXZpY2VpZCI6IjVmZThlYWYzLTYzYWUtNGY3Ny1hMDkxLTI4MzcxZTRlZmRlMyIsImZhbWlseV9uYW1lIjoiTWVub24iLCJnaXZlbl9uYW1lIjoiTHVjeSIsImlkdHlwIjoidXNlciIsImlwYWRkciI6IjkyLjQwLjE3MC4yMjAiLCJuYW1lIjoiTHVjeSBNZW5vbiIsIm9pZCI6IjFkNDgzMWMxLWVhYTgtNGY2OS1hZTVjLTE4MTQwMjBlZTJlYyIsIm9ucHJlbV9zaWQiOiJTLTEtNS0yMS0yMTI3NTIxMTg0LTE2MDQwMTI5MjAtMTg4NzkyNzUyNy03ODMzODE4MyIsInB1aWQiOiIxMDAzMjAwM0FBNkI0MTNFIiwicmgiOiIwLkFSb0F2NGo1Y3ZHR3IwR1JxeTE4MEJIYlIwWklmM2tBdXRkUHVrUGF3ZmoyTUJNYUFIUS4iLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJ0bmo3a0hTb1ZIM3V6eGVsYkVfNnRFSEVoaDRBaWVtTGZ4aThDNld1NzBvIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidW5pcXVlX25hbWUiOiJtZW5vbmx1Y3lAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im1lbm9ubHVjeUBtaWNyb3NvZnQuY29tIiwidXRpIjoiaFRXM0lFVmtCRXVaWFRTSnoxNW1BQSIsInZlciI6IjEuMCIsIndpZHMiOlsiYjc5ZmJmNGQtM2VmOS00Njg5LTgxNDMtNzZiMTk0ZTg1NTA5Il0sInhtc19jYWUiOiIxIiwieG1zX2NjIjpbIkNQMSJdLCJ4bXNfZmlsdGVyX2luZGV4IjpbIjI2Il0sInhtc19pZHJlbCI6IjI2IDEiLCJ4bXNfcmQiOiIwLjQyTGxZQlJpbEFJQSIsInhtc19zc20iOiIxIiwieG1zX3RjZHQiOjEyODkyNDE1NDd9.t5d56DG8TDlkLYJPIVHFcftn4PbrPOhzwIQoyJRqe4s1VVgscqhNQH4PYqPjizkHy76lZM0cI6a3lrRfVbr1wXBDk82jLyxQ_AXR0yMN4RmrrTRK5M5p5sKHtXq85rTohHl2RSeu7VsWNNBVMsy1Efh6UN095zFZvzntbn-N2JXjloprrz5JcHb1hasT9-o_tsebIM2jefbj7ggpuiGRcbYM3i5mgLVGd19gYzlpAq7YyiE-SvHtLu3cSSms4KwDeoi3QpZiV_5ok1dsZxaonGplaqXeE_pRM92JCvk1paahCKNmrOjZPcJ4hXUlH4q7OY2Hm6MY4GKcTG_xXXoWaQ"; in
+{
+    devShells.x86_64-linux.default = with import nixpkgs { system = "x86_64-linux"; overlays = [ (import (nixpkgs-mozilla + "/rust-overlay.nix")) ]; }; let
+      stable = rustChannelOf {
+        date = "2025-02-20";
+        channel = "stable";
+        sha256 = "sha256-AJ6LX/Q/Er9kS15bn9iflkUwcgYqRQxiOIL2ToVAXaU=";
+      };
+      nightly = rustChannelOf {
+        date = "2025-06-04";
+        channel = "nightly";
+        sha256 = "sha256-eFuFA5spScrde7b7lSV5QAND1m0+Ds6gbVODfDE3scg=";
+      };
+      rust_stable = stable.rust.override {
+        targets = [ "x86_64-unknown-linux-gnu" "x86_64-pc-windows-msvc" "x86_64-unknown-none" "wasm32-wasip1" "wasm32-unknown-unknown" ];
+      };
+      rust_nightly = nightly.rust.override {
+        targets = [ "x86_64-unknown-linux-gnu" "x86_64-pc-windows-msvc" "x86_64-unknown-none" "wasm32-wasip1" "wasm32-unknown-unknown" ];
+      };
+      rust-platform = makeRustPlatform {
+        cargo = rust_stable;
+        rustc = rust_stable;
+      };
+    in ((rust-platform.buildRustPackage.override { stdenv = clangStdenv; }) rec {
+      pname = "hyperlight";
+      version = "0.0.0";
+      src = lib.cleanSource ./.;
+      #cargoHash = lib.fakeHash;
+      #cargoHash = "sha256-Z4dkYH1BBSUpqiHETkIi+i13FD1q5CyB0NuGHUxhLm0=";
+      cargoHash = "sha256-CsHcz91S5NHdoHgQVLFizyd5rUXMlMDHEN67JrQ6Xls=";
+      nativeBuildInputs = [
+        azure-cli
+        just
+        dotnet-sdk_6
+        clang
+        llvmPackages_18.llvm
+        gh
+        lld
+        valgrind
+        pkg-config
+        ffmpeg
+        mkvtoolnix
+        wasm-tools
+        nodejs # todo - just for now
+        cargo-component
+        wasm-tools
+      ];
+      buildInputs = [
+        pango
+        cairo
+        openssl
+      ];
+      auditable = false;
+      depsExtraArgs = {
+        CARGO_REGISTRIES_HYPERLIGHT_REDIST_TOKEN = token;
+        CARGO_REGISTRIES_HYPERLIGHT_PACKAGES_TOKEN = token;
+      };
+      KVM_SHOULD_BE_PRESENT = "true";
+      LIBCLANG_PATH = "${pkgs.llvmPackages_18.libclang.lib}/lib";
+      RUST_NIGHTLY = "${rust_nightly}";
+      shellHook = ''
+        rustc_nightly() {
+          (export PATH="${rust_nightly}/bin/:$PATH"; ${rust_nightly}/bin/rustc "$@")
+        }
+        rustc_stable() {
+          (export PATH="${rust_stable}/bin/:$PATH"; ${rust_stable}/bin/rustc "$@")
+        }
+        cargo_nightly() {
+          (export PATH="${rust_nightly}/bin/:$PATH"; ${rust_nightly}/bin/cargo "$@")
+        }
+        cargo_stable() {
+          (export PATH="${rust_stable}/bin/:$PATH"; ${rust_stable}/bin/cargo "$@")
+        }
+      '';
+    }).overrideAttrs(oA: {
+      hardeningDisable = [ "all" ];
+    });
+  };
+}
diff --git a/src/hyperlight_wasm/src/sandbox/wasm_sandbox.rs b/src/hyperlight_wasm/src/sandbox/wasm_sandbox.rs
@@ -17,6 +17,7 @@ limitations under the License.
 use std::path::Path;
 
 use hyperlight_host::func::call_ctx::MultiUseGuestCallContext;
+use hyperlight_host::mem::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionType};
 use hyperlight_host::sandbox::Callable;
 use hyperlight_host::sandbox_state::sandbox::{EvolvableSandbox, Sandbox};
 use hyperlight_host::sandbox_state::transition::MultiUseContextCallback;
@@ -42,6 +43,7 @@ pub struct WasmSandbox {
 
 impl Sandbox for WasmSandbox {}
 
+const MAPPED_BINARY_VA: u64 = 0x1_0000_0000u64;
 impl WasmSandbox {
     /// Create a new WasmSandBox from a `MultiUseSandbox`.
     /// This function should be used to create a new `WasmSandbox` from a ProtoWasmSandbox.
@@ -59,34 +61,87 @@ impl WasmSandbox {
     /// Before you can call guest functions in the sandbox, you must call
     /// this function and use the returned value to call guest functions.
     pub fn load_module(self, file: impl AsRef<Path>) -> Result<LoadedWasmSandbox> {
-        let wasm_bytes = std::fs::read(file)?;
-        self.load_module_inner(wasm_bytes)
+        let func = Box::new(move |call_ctx: &mut MultiUseGuestCallContext| {
+            if let Ok(len) = call_ctx.map_file_cow(file.as_ref(), MAPPED_BINARY_VA) {
+                call_ctx.call("LoadWasmModulePhys", (MAPPED_BINARY_VA, len))
+            } else {
+                let wasm_bytes = std::fs::read(file)?;
+                Self::load_module_from_buffer_transition_func(wasm_bytes)(call_ctx)
+            }
+        });
+        self.load_module_inner(func)
     }
 
-    /// Load a Wasm module from a buffer of bytes into the sandbox and return a `LoadedWasmSandbox`
-    /// able to execute code in the loaded Wasm Module.
+    /// Load a Wasm module that is currently present in a buffer in
+    /// host memory, by mapping the host memory directly into the
+    /// sandbox.
     ///
-    /// Before you can call guest functions in the sandbox, you must call
-    /// this function and use the returned value to call guest functions.
-    pub fn load_module_from_buffer(self, buffer: &[u8]) -> Result<LoadedWasmSandbox> {
-        self.load_module_inner(buffer.to_vec())
+    /// Depending on the host platform, there are likely alignment
+    /// requirements of at least one page for base and len
+    ///
+    /// # Safety
+    /// It is the caller's responsibility to ensure that the host side
+    /// of the region remains intact and is not written to until the
+    /// produced LoadedWasmSandbox is discarded or devolved.
+    pub unsafe fn load_module_by_mapping(
+        self,
+        base: *mut libc::c_void,
+        len: usize,
+    ) -> Result<LoadedWasmSandbox> {
+        let func = Box::new(move |call_ctx: &mut MultiUseGuestCallContext| {
+            let guest_base: usize = MAPPED_BINARY_VA as usize;
+            let rgn = MemoryRegion {
+                host_region: base as usize..base.wrapping_add(len) as usize,
+                guest_region: guest_base..guest_base + len,
+                flags: MemoryRegionFlags::READ | MemoryRegionFlags::EXECUTE,
+                region_type: MemoryRegionType::Heap,
+            };
+            if let Ok(()) = unsafe { call_ctx.map_region(&rgn) } {
+                call_ctx.call("LoadWasmModulePhys", (MAPPED_BINARY_VA, len as u64))
+            } else {
+                let wasm_bytes =
+                    unsafe { std::slice::from_raw_parts(base as *const u8, len).to_vec() };
+                Self::load_module_from_buffer_transition_func(wasm_bytes)(call_ctx)
+            }
+        });
+        self.load_module_inner(func)
     }
 
-    fn load_module_inner(mut self, wasm_bytes: Vec<u8>) -> Result<LoadedWasmSandbox> {
-        let func = Box::new(move |call_ctx: &mut MultiUseGuestCallContext| {
-            let len = wasm_bytes.len() as i32;
-            let res: i32 = call_ctx.call("LoadWasmModule", (wasm_bytes, len))?;
+    // todo: take a slice rather than a vec (requires somewhat
+    // refactoring the flatbuffers stuff maybe)
+    fn load_module_from_buffer_transition_func(
+        buffer: Vec<u8>,
+    ) -> impl FnOnce(&mut MultiUseGuestCallContext) -> Result<()> {
+        move |call_ctx: &mut MultiUseGuestCallContext| {
+            let len = buffer.len() as i32;
+            let res: i32 = call_ctx.call("LoadWasmModule", (buffer, len))?;
             if res != 0 {
                 return Err(new_error!(
                     "LoadWasmModule Failed with error code {:?}",
                     res
                 ));
             }
             Ok(())
-        });
+        }
+    }
 
-        let transition_func = MultiUseContextCallback::from(func);
+    /// Load a Wasm module from a buffer of bytes into the sandbox and return a `LoadedWasmSandbox`
+    /// able to execute code in the loaded Wasm Module.
+    ///
+    /// Before you can call guest functions in the sandbox, you must call
+    /// this function and use the returned value to call guest functions.
+    pub fn load_module_from_buffer(self, buffer: &[u8]) -> Result<LoadedWasmSandbox> {
+        // TODO: get rid of this clone
+        let func = Self::load_module_from_buffer_transition_func(buffer.to_vec());
 
+        self.load_module_inner(func)
+    }
+
+    fn load_module_inner<F: FnOnce(&mut MultiUseGuestCallContext) -> Result<()>>(
+        mut self,
+        func: F,
+    ) -> Result<LoadedWasmSandbox> {
+        let transition_func = MultiUseContextCallback::from(func);
         match self.inner.take() {
             Some(sbox) => {
                 let new_sbox: MultiUseSandbox = sbox.evolve(transition_func)?;
diff --git a/src/wasm_runtime/src/component.rs b/src/wasm_runtime/src/component.rs
@@ -47,6 +47,17 @@ fn init_wasm_runtime(_function_call: &FunctionCall) -> Result<Vec<u8>> {
     Ok(get_flatbuffer_result::<i32>(0))
 }
 
+fn load_component_common(engine: &Engine, component: Component) -> Result<()> {
+    let mut store = Store::new(engine, ());
+    let instance = (*CUR_LINKER.lock())
+        .as_ref()
+        .unwrap()
+        .instantiate(&mut store, &component)?;
+    *CUR_STORE.lock() = Some(store);
+    *CUR_INSTANCE.lock() = Some(instance);
+    Ok(())
+}
+
 fn load_wasm_module(function_call: &FunctionCall) -> Result<Vec<u8>> {
     if let (
         ParameterValue::VecBytes(ref wasm_bytes),
@@ -58,13 +69,7 @@ fn load_wasm_module(function_call: &FunctionCall) -> Result<Vec<u8>> {
         &*CUR_ENGINE.lock(),
     ) {
         let component = unsafe { Component::deserialize(engine, wasm_bytes)? };
-        let mut store = Store::new(engine, ());
-        let instance = (*CUR_LINKER.lock())
-            .as_ref()
-            .unwrap()
-            .instantiate(&mut store, &component)?;
-        *CUR_STORE.lock() = Some(store);
-        *CUR_INSTANCE.lock() = Some(instance);
+        load_component_common(engine, component)?;
         Ok(get_flatbuffer_result::<i32>(0))
     } else {
         Err(HyperlightGuestError::new(
@@ -74,6 +79,24 @@ fn load_wasm_module(function_call: &FunctionCall) -> Result<Vec<u8>> {
     }
 }
 
+fn load_wasm_module_phys(function_call: &FunctionCall) -> Result<Vec<u8>> {
+    if let (ParameterValue::ULong(ref phys), ParameterValue::ULong(ref len), Some(ref engine)) = (
+        &function_call.parameters.as_ref().unwrap()[0],
+        &function_call.parameters.as_ref().unwrap()[1],
+        &*CUR_ENGINE.lock(),
+    ) {
+        let component =
+            unsafe { Component::deserialize_raw(engine, platform::map_buffer(*phys, *len))? };
+        load_component_common(engine, component)?;
+        Ok(get_flatbuffer_result::<()>(()))
+    } else {
+        Err(HyperlightGuestError::new(
+            ErrorCode::GuestFunctionParameterTypeMismatch,
+            "Invalid parameters passed to LoadWasmModulePhys".to_string(),
+        ))
+    }
+}
+
 #[no_mangle]
 pub extern "C" fn hyperlight_main() {
     platform::register_page_fault_handler();
@@ -83,6 +106,7 @@ pub extern "C" fn hyperlight_main() {
     config.memory_guard_size(0);
     config.memory_reservation_for_growth(0);
     config.guard_before_linear_memory(false);
+    config.with_custom_code_memory(Some(alloc::sync::Arc::new(platform::WasmtimeCodeMemory {})));
     let engine = Engine::new(&config).unwrap();
     let linker = Linker::new(&engine);
     *CUR_ENGINE.lock() = Some(engine);
@@ -102,6 +126,12 @@ pub extern "C" fn hyperlight_main() {
         ReturnType::Int,
         load_wasm_module as usize,
     ));
+    register_function(GuestFunctionDefinition::new(
+        "LoadWasmModulePhys".to_string(),
+        vec![ParameterType::ULong, ParameterType::ULong],
+        ReturnType::Void,
+        load_wasm_module_phys as usize,
+    ));
 }
 
 #[no_mangle]
diff --git a/src/wasm_runtime/src/module.rs b/src/wasm_runtime/src/module.rs
@@ -93,6 +93,7 @@ fn init_wasm_runtime() -> Result<Vec<u8>> {
     config.memory_guard_size(0);
     config.memory_reservation_for_growth(0);
     config.guard_before_linear_memory(false);
+    config.with_custom_code_memory(Some(alloc::sync::Arc::new(platform::WasmtimeCodeMemory {})));
     let engine = Engine::new(&config)?;
     let mut linker = Linker::new(&engine);
     wasip1::register_handlers(&mut linker)?;
@@ -138,6 +139,23 @@ fn load_wasm_module(function_call: &FunctionCall) -> Result<Vec<u8>> {
     }
 }
 
+fn load_wasm_module_phys(function_call: &FunctionCall) -> Result<Vec<u8>> {
+    if let (ParameterValue::ULong(ref phys), ParameterValue::ULong(ref len), Some(ref engine)) = (
+        &function_call.parameters.as_ref().unwrap()[0],
+        &function_call.parameters.as_ref().unwrap()[1],
+        &*CUR_ENGINE.lock(),
+    ) {
+        let module = unsafe { Module::deserialize_raw(engine, platform::map_buffer(*phys, *len))? };
+        *CUR_MODULE.lock() = Some(module);
+        Ok(get_flatbuffer_result::<()>(()))
+    } else {
+        Err(HyperlightGuestError::new(
+            ErrorCode::GuestFunctionParameterTypeMismatch,
+            "Invalid parameters passed to LoadWasmModulePhys".to_string(),
+        ))
+    }
+}
+
 #[no_mangle]
 #[allow(clippy::fn_to_numeric_cast)] // GuestFunctionDefinition expects a function pointer as i64
 pub extern "C" fn hyperlight_main() {
@@ -163,4 +181,10 @@ pub extern "C" fn hyperlight_main() {
         ReturnType::Int,
         load_wasm_module as usize,
     ));
+    register_function(GuestFunctionDefinition::new(
+        "LoadWasmModulePhys".to_string(),
+        vec![ParameterType::ULong, ParameterType::ULong],
+        ReturnType::Void,
+        load_wasm_module_phys as usize,
+    ));
 }
diff --git a/src/wasm_runtime/src/platform.rs b/src/wasm_runtime/src/platform.rs
