Enable native debugging for wasm modules/components

Signed-off-by: Doru Blânzeanu <[email protected]>

Author: dblnz

.vscode/launch.json

@@ -1,34 +1,101 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    // this can be used to debug tests 
-    "version": "0.2.0",
+    "inputs": [
+        {
+            "id": "program",
+            "type": "promptString",
+            "default": "x64/debug/wasm_runtime",
+            "description": "Path to the program to debug",
+        }
+    ],
     "configurations": [
         {
             "type": "lldb",
             "request": "launch",
-            "name": "Cargo test",
+            "name": "Debug example 'guest-debugging'",
+            "cargo": {
+                "args": [
+                "build",
+                "--example=guest-debugging",
+                "--package=hyperlight-wasm",
+                "--features=gdb",
+                ],
+                "filter": {
+                "name": "guest-debugging",
+                "kind": "example"
+                }
+            },
+            "env": {
+                "RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm",
+            },
+            "args": [],
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "type": "lldb",
+            "request": "launch",
+            "name": "Debug example 'rust_wasm_examples'",
             "cargo": {
-              "args": [
-                "test",
-                "--profile=dev",
-                "--lib",
-                "--no-run"
-               
-              ],
-              "filter": {
-                "name": "hyperlight_wasm",
-                "kind": "lib"
-              }
+                "args": [
+                "build",
+                "--example=rust_wasm_examples",
+                "--package=hyperlight-wasm",
+                ],
+                "filter": {
+                "name": "rust_wasm_examples",
+                "kind": "example"
+                }
             },
             "env": {
-              "RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm"
+                "RUST_DIR_FOR_DEBUGGING_TESTS": "${workspaceFolder}/src/hyperlight_wasm",
+            },
+            "args": [],
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Remote GDB attach",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${input:program}",
+            "args": [],
+            "stopAtEntry": true,
+            "hardwareBreakpoints": {
+                "require": false,
+                "limit": 4
             },
-            "args": [
-                "--exact",
-                "sandbox::loaded_wasm_sandbox::tests::test_call_host_func_with_vecbytes"
+            "cwd": "${workspaceFolder}",
+            "environment": [],
+            "externalConsole": false,
+            "MIMode": "gdb",
+            "miDebuggerPath": "/usr/bin/gdb",
+            "miDebuggerServerAddress": "localhost:8080",
+            "setupCommands": [
+                {
+                "description": "Enable pretty-printing for gdb",
+                "text": "-enable-pretty-printing",
+                "ignoreFailures": true
+                },
+                {
+                "description": "Set Disassembly Flavor to Intel",
+                "text": "-gdb-set disassembly-flavor intel",
+                "ignoreFailures": true
+                },
+                //{
+                //"description": "Add symbols",
+                //"text": "symbol-file ${workspaceFolder}/x64/debug/rust_wasm_samples.wasm",
+                //"ignoreFailures": true
+                //}
             ]
-        }
+        },
+        {
+            "name": "Remote LLDB attach",
+            "type": "lldb",
+            "request": "launch",
+            "targetCreateCommands": [
+                "target create ${input:program}",
+            ],
+            "processCreateCommands": [
+                "gdb-remote localhost:8080"
+            ],
+        },
     ]
 }

Cargo.lock

@@ -19,7 +19,7 @@ ensure-tools:
     cargo install cargo-component --locked --version 0.21.1
     cargo install wit-bindgen-cli --locked --version 0.43.0
 
-build-all target=default-target: (build target) (build-wasm-examples target) (build-rust-wasm-examples target) (build-rust-component-examples target) (build-wasm-runtime target)
+build-all target=default-target features="": (build target features) (build-wasm-examples target features) (build-rust-wasm-examples target features) (build-rust-component-examples target) (build-wasm-runtime target features)
 
 build target=default-target features="": (fmt-check)
     cargo build {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--no-default-features -F " + features } }} --verbose --profile={{ if target == "debug" {"dev"} else { target } }}
@@ -32,23 +32,23 @@ compile-wit:
     wasm-tools component wit ./src/wasmsamples/components/runcomponent.wit -w -o ./src/wasmsamples/components/runcomponent-world.wasm
     wasm-tools component wit ./src/component_sample/wit/example.wit -w -o ./src/component_sample/wit/component-world.wasm
 
-build-wasm-runtime target=default-target:
-    cd ./src/wasm_runtime && cargo build --verbose --profile={{ if target == "debug" {"dev"} else { target } }} && rm -R target
+build-wasm-runtime target=default-target features="":
+    cd ./src/wasm_runtime && cargo build --verbose {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} --profile={{ if target == "debug" {"dev"} else { target } }} && rm -R target
 
-build-wasm-examples target=default-target: (compile-wit)
-    {{ build-wasm-examples-command }} {{target}}
+build-wasm-examples target=default-target features="": (compile-wit)
+    {{ build-wasm-examples-command }} {{target}} {{features}}
 
-build-rust-wasm-examples target=default-target: (mkdir-redist target)
+build-rust-wasm-examples target=default-target features="": (mkdir-redist target)
     rustup target add wasm32-unknown-unknown
     cd ./src/rust_wasm_samples && cargo build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run -p hyperlight-wasm-aot compile ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile ./src/rust_wasm_samples/target/wasm32-unknown-unknown/{{ target }}/rust_wasm_samples.wasm ./x64/{{ target }}/rust_wasm_samples.aot
 
-build-rust-component-examples target=default-target: (compile-wit)
+build-rust-component-examples target=default-target features="": (compile-wit)
     # use cargo component so we don't get all the wasi imports https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#relationship-with-wasm32-wasip2
     # we also explicitly target wasm32-unknown-unknown since cargo component might try to pull in wasi imports https://github.com/bytecodealliance/cargo-component/issues/290
     rustup target add wasm32-unknown-unknown
     cd ./src/component_sample && cargo component build --target wasm32-unknown-unknown --profile={{ if target == "debug" {"dev"} else { target } }}
-    cargo run -p hyperlight-wasm-aot compile --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
+    cargo run {{ if features =="" {''} else if features=="no-default-features" {"--no-default-features" } else {"--features " + features } }} -p hyperlight-wasm-aot compile --component ./src/component_sample/target/wasm32-unknown-unknown/{{ target }}/component_sample.wasm ./x64/{{ target }}/component_sample.aot
 
 check target=default-target:
     cargo check --profile={{ if target == "debug" {"dev"} else { target } }}

Justfile

@@ -29,6 +29,11 @@ name = "helloworld"
 path = "examples/helloworld/main.rs"
 test = true
 
+[[example]]
+name = "guest-debugging"
+path = "examples/guest-debugging/main.rs"
+test = true
+
 [[example]]
 name = "hostfuncs"
 path = "examples/hostfuncs/main.rs"
@@ -52,6 +57,7 @@ tracing = "0.1.27"
 log = "0.4.27"
 cfg-if = { version = "1" }
 metrics = "0.24.2"
+env_logger = "0.11.8"
 
 [target.'cfg(windows)'.dependencies]
 windows = { version = "0.61", features = ["Win32_System_Threading"] }
@@ -81,6 +87,7 @@ function_call_metrics = ["hyperlight-host/function_call_metrics"]
 seccomp = ["hyperlight-host/seccomp"]
 print_debug = ["hyperlight-host/print_debug"]
 crashdump = ["hyperlight-host/crashdump"]
+gdb = ["hyperlight-host/gdb"]
 kvm = ["hyperlight-host/kvm"]
 mshv2 = ["hyperlight-host/mshv2"]
 mshv3 = ["hyperlight-host/mshv3"]

src/hyperlight_wasm/Cargo.toml

@@ -125,7 +125,7 @@ fn build_wasm_runtime() -> PathBuf {
     env_vars.retain(|(key, _)| !key.starts_with("CARGO_"));
 
     let mut cargo_cmd = std::process::Command::new(&cargo_bin);
-    let cmd = cargo_cmd
+    let mut cmd = cargo_cmd
         .arg("build")
         .arg("--profile")
         .arg(cargo_profile)
@@ -137,6 +137,12 @@ fn build_wasm_runtime() -> PathBuf {
         .envs(env_vars)
         .env("PATH", path_with(&toolchain_dir))
         .env("HYPERLIGHT_GUEST_TOOLCHAIN_ROOT", &toolchain_dir);
+
+    // Add --features gdb if the gdb feature is enabled for this build script
+    if std::env::var("CARGO_FEATURE_GDB").is_ok() {
+        cmd = cmd.arg("--features").arg("gdb");
+    }
+
     let status = cmd
         .status()
         .unwrap_or_else(|e| panic!("could not run cargo build wasm_runtime: {}", e));

src/hyperlight_wasm/build.rs

@@ -0,0 +1,91 @@
+/*
+Copyright 2025 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 examples_common::get_wasm_module_path;
+use hyperlight_host::HyperlightError;
+use hyperlight_wasm::{Result, SandboxBuilder};
+
+fn get_time_since_boot_microsecond() -> Result<i64> {
+    let res = std::time::SystemTime::now()
+        .duration_since(std::time::SystemTime::UNIX_EPOCH)?
+        .as_micros();
+    i64::try_from(res).map_err(HyperlightError::IntConversionFailure)
+}
+
+fn main() -> Result<()> {
+    let tests = [
+        (
+            "HelloWorld.aot",
+            "HelloWorld",
+            "Message from Rust Example to Wasm Function".to_string(),
+        ),
+        // (
+        //     "rust_wasm_samples.aot",
+        //     "add",
+        //     (5i32, 3i32),
+        // ),
+    ];
+    for (idx, case) in tests.iter().enumerate() {
+        let (mod_path, fn_name, params_opt) = case;
+
+        let mut sandbox = SandboxBuilder::new()
+            .with_guest_input_buffer_size(2 * 1024 * 1024) // 2 MiB
+            .with_guest_heap_size(10 * 1024 * 1024) // 4 MiB
+            .with_debugging_enabled(8080)
+            .build()?;
+
+        let wasm_sandbox = match mod_path.starts_with("RunWasm") {
+            true => {
+                sandbox
+                    .register(
+                        "GetTimeSinceBootMicrosecond",
+                        get_time_since_boot_microsecond,
+                    )
+                    .unwrap();
+
+                sandbox.load_runtime()?
+            }
+            false => sandbox.load_runtime()?,
+        };
+
+        let mod_path = get_wasm_module_path(mod_path)?;
+
+        // Load a Wasm module into the sandbox
+        let mut loaded_wasm_sandbox = wasm_sandbox.load_module(mod_path)?;
+
+        if *fn_name == "Echo" {
+            // Call a function in the Wasm module
+            let result: String =
+                loaded_wasm_sandbox.call_guest_function(fn_name, params_opt.clone())?;
+            println!(
+                "Result from calling Echo Function in Wasm Module \
+                test case {idx}) is: {}",
+                result
+            );
+        } else if *fn_name == "HelloWorld" {
+            // Call a function in the Wasm module
+            let result: i32 =
+                loaded_wasm_sandbox.call_guest_function(fn_name, params_opt.clone())?;
+
+            println!(
+                "Result from calling HelloWorld Function in Wasm Module \
+            test case {idx}) is: {}",
+                result
+            );
+        }
+    }
+    Ok(())
+}