Enable native debugging for wasm modules/components

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

Author: dblnz

.vscode/launch.json

@@ -1,34 +1,96 @@
 {
-    // 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
+                },
             ]
-        }
+        },
+        {
+            "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.28"
 cfg-if = { version = "1" }
 metrics = "0.24.2"
+env_logger = "0.11.8"
 
 [target.'cfg(windows)'.dependencies]
 windows = { version = "0.62", features = ["Win32_System_Threading"] }
@@ -68,6 +74,7 @@ metrics-util = "0.20.0"
 metrics-exporter-prometheus = "0.17"
 
 [build-dependencies]
+cfg_aliases = "0.2.1"
 chrono = "0.4"
 blake3 = "1.8"
 built = { version = "0.8.0", features = ["chrono", "git2"] }
@@ -81,6 +88,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));
@@ -239,5 +245,9 @@ fn main() -> Result<()> {
 
     println!("cargo:rerun-if-changed=build.rs");
 
+    cfg_aliases::cfg_aliases! {
+        gdb: { all(feature = "gdb", debug_assertions) },
+    }
+
     Ok(())
 }