gdbstub_arch: add a WebAssembly architecture. by cfallin · Pull Request #192 · daniel5151/gdbstub

cfallin · 2026-03-10T16:45:14Z

Description

Builds on #188, #189, #190: add definitions for the WebAssembly architecture to gdbstub_arch. This includes all definitions needed for the Arch trait, as well as utility code for encoding/decoding the synthetic address space used by the gdbstub definitions for this architecture.

Tested with Wasmtime using a (soon to be upstreamed) guest-debugging facility.

API Stability

This PR does not require a breaking API change

Checklist

Documentation
- Ensured any public-facing rustdoc formatting looks good (via cargo doc)
- (if appropriate) Added feature to "Debugging Features" in README.md
Validation
- Included output of running examples/armv4t with RUST_LOG=trace + any relevant GDB output under the "Validation" section below
- Included output of running ./example_no_std/check_size.sh before/after changes under the "Validation" section below
If implementing a new protocol extension IDET
- Included a basic sample implementation in examples/armv4t
- IDET can be optimized out (confirmed via ./example_no_std/check_size.sh)
- OR implementation requires introducing non-optional binary bloat (please elaborate under "Description")
If upstreaming an Arch implementation
- I have tested this code in my project, and to the best of my knowledge, it is working as intended.

Validation

Works in the Wasmtime guest-debugging implementation.

Builds on daniel5151#188, daniel5151#189, daniel5151#190: add definitions for the WebAssembly architecture to `gdbstub_arch`. This includes all definitions needed for the `Arch` trait, as well as utility code for encoding/decoding the synthetic address space used by the gdbstub definitions for this architecture. Tested with Wasmtime using a (soon to be upstreamed) guest-debugging facility.

daniel5151

Awesome! Glad you sent this in!

I took a quick pass through some of the docs (since it's prob easier than a bunch of back and forth).

There are a couple of questions / comments, but broadly speaking - this looks great.

gdbstub_arch/src/wasm/addr.rs

gdbstub_arch/src/wasm/mod.rs

cfallin · 2026-03-10T19:55:17Z

Updated; thanks!

daniel5151

Thanks for the quick turnaround here! I'll merge this in, and cut a new version of gdbstub_arch shortly.

cfallin · 2026-03-10T23:22:11Z

Thanks a bunch for your reviews on all this!

daniel5151 · 2026-03-10T23:28:36Z

Of course! It's always fun to see the ways gdbstub is being used by folks - this little foray into Wasm has been quite enlightening for me (as someone who's been experimenting and keeping an eye on the tech from the sidelines for many years, hah).

gdbstub_arch 0.3.3 is now published to crates.io, and includes the Wasm arch 🚀

This adds a debug component that makes use of the debug-main world defined in bytecodealliance#12756 and serves the gdbstub protocol, with Wasm extensions, compatible with LLDB. This component is built and included inside the Wasmtime binary, and is loaded using the lower-level `-D debugger=...` debug-main option; the user doesn't need to specify the `.wasm` adapter component. Instead, the user simply runs `wasmtime run -g <PORT> program.wasm ...` and Wasmtime will load and prepare to run `program.wasm` as the debuggee, waiting for a gdbstub connection on the given TCP port before continuing. The workflow is: ``` $ wasmtime run -g 1234 program.wasm [ wasmtime starts and waits for connection ] $ /opt/wasi-sdk/bin/lldb # use LLDB from wasi-sdk release 32 or later (lldb) process connect --plugin wasm connect://localhost:1234 Process 1 stopped * thread #1, stop reason = signal SIGTRAP frame #0: 0x40000000000001cc -> 0x40000000000001cc: unreachable 0x40000000000001cd: end 0x40000000000001ce: local.get 0 0x40000000000001d0: call 13 (lldb) si Process 1 stopped * thread #1, stop reason = instruction step into frame #0: 0x4000000000000184 -> 0x4000000000000184: block 0x4000000000000186: block 0x4000000000000188: global.get 1 0x400000000000018e: i32.const 3664 [ ... ] ``` This makes use of the `gdbstub` third-party crate, into which I've upstreamed support for the Wasm extensions in daniel5151/gdbstub#188, daniel5151/gdbstub#189, daniel5151/gdbstub#190, and daniel5151/gdbstub#192. (I'll add vets as part of this PR.)

* Debugging: add builtin gdbstub component. This adds a debug component that makes use of the debug-main world defined in #12756 and serves the gdbstub protocol, with Wasm extensions, compatible with LLDB. This component is built and included inside the Wasmtime binary, and is loaded using the lower-level `-D debugger=...` debug-main option; the user doesn't need to specify the `.wasm` adapter component. Instead, the user simply runs `wasmtime run -g <PORT> program.wasm ...` and Wasmtime will load and prepare to run `program.wasm` as the debuggee, waiting for a gdbstub connection on the given TCP port before continuing. The workflow is: ``` $ wasmtime run -g 1234 program.wasm [ wasmtime starts and waits for connection ] $ /opt/wasi-sdk/bin/lldb # use LLDB from wasi-sdk release 32 or later (lldb) process connect --plugin wasm connect://localhost:1234 Process 1 stopped * thread #1, stop reason = signal SIGTRAP frame #0: 0x40000000000001cc -> 0x40000000000001cc: unreachable 0x40000000000001cd: end 0x40000000000001ce: local.get 0 0x40000000000001d0: call 13 (lldb) si Process 1 stopped * thread #1, stop reason = instruction step into frame #0: 0x4000000000000184 -> 0x4000000000000184: block 0x4000000000000186: block 0x4000000000000188: global.get 1 0x400000000000018e: i32.const 3664 [ ... ] ``` This makes use of the `gdbstub` third-party crate, into which I've upstreamed support for the Wasm extensions in daniel5151/gdbstub#188, daniel5151/gdbstub#189, daniel5151/gdbstub#190, and daniel5151/gdbstub#192. (I'll add vets as part of this PR.) * cargo vets. * Handle Trap events as well as breakpoints. * Review feedback. * Fix gdbstub artifact build to make it publishable (by disabling it when isolated crates are used). * Review feedback. * fix published-crates list

* Debugging: add builtin gdbstub component. This adds a debug component that makes use of the debug-main world defined in #12756 and serves the gdbstub protocol, with Wasm extensions, compatible with LLDB. This component is built and included inside the Wasmtime binary, and is loaded using the lower-level `-D debugger=...` debug-main option; the user doesn't need to specify the `.wasm` adapter component. Instead, the user simply runs `wasmtime run -g <PORT> program.wasm ...` and Wasmtime will load and prepare to run `program.wasm` as the debuggee, waiting for a gdbstub connection on the given TCP port before continuing. The workflow is: ``` $ wasmtime run -g 1234 program.wasm [ wasmtime starts and waits for connection ] $ /opt/wasi-sdk/bin/lldb # use LLDB from wasi-sdk release 32 or later (lldb) process connect --plugin wasm connect://localhost:1234 Process 1 stopped * thread #1, stop reason = signal SIGTRAP frame #0: 0x40000000000001cc -> 0x40000000000001cc: unreachable 0x40000000000001cd: end 0x40000000000001ce: local.get 0 0x40000000000001d0: call 13 (lldb) si Process 1 stopped * thread #1, stop reason = instruction step into frame #0: 0x4000000000000184 -> 0x4000000000000184: block 0x4000000000000186: block 0x4000000000000188: global.get 1 0x400000000000018e: i32.const 3664 [ ... ] ``` This makes use of the `gdbstub` third-party crate, into which I've upstreamed support for the Wasm extensions in daniel5151/gdbstub#188, daniel5151/gdbstub#189, daniel5151/gdbstub#190, and daniel5151/gdbstub#192. (I'll add vets as part of this PR.) * cargo vets. * Handle Trap events as well as breakpoints. * Review feedback. * Fix gdbstub artifact build to make it publishable (by disabling it when isolated crates are used). * Review feedback. * fix published-crates list * For now, empty gdbstub data but no compile error when artifact crate is published.

* Debugging: add builtin gdbstub component. This adds a debug component that makes use of the debug-main world defined in #12756 and serves the gdbstub protocol, with Wasm extensions, compatible with LLDB. This component is built and included inside the Wasmtime binary, and is loaded using the lower-level `-D debugger=...` debug-main option; the user doesn't need to specify the `.wasm` adapter component. Instead, the user simply runs `wasmtime run -g <PORT> program.wasm ...` and Wasmtime will load and prepare to run `program.wasm` as the debuggee, waiting for a gdbstub connection on the given TCP port before continuing. The workflow is: ``` $ wasmtime run -g 1234 program.wasm [ wasmtime starts and waits for connection ] $ /opt/wasi-sdk/bin/lldb # use LLDB from wasi-sdk release 32 or later (lldb) process connect --plugin wasm connect://localhost:1234 Process 1 stopped * thread #1, stop reason = signal SIGTRAP frame #0: 0x40000000000001cc -> 0x40000000000001cc: unreachable 0x40000000000001cd: end 0x40000000000001ce: local.get 0 0x40000000000001d0: call 13 (lldb) si Process 1 stopped * thread #1, stop reason = instruction step into frame #0: 0x4000000000000184 -> 0x4000000000000184: block 0x4000000000000186: block 0x4000000000000188: global.get 1 0x400000000000018e: i32.const 3664 [ ... ] ``` This makes use of the `gdbstub` third-party crate, into which I've upstreamed support for the Wasm extensions in daniel5151/gdbstub#188, daniel5151/gdbstub#189, daniel5151/gdbstub#190, and daniel5151/gdbstub#192. (I'll add vets as part of this PR.) * cargo vets. * Handle Trap events as well as breakpoints. * Review feedback. * Fix gdbstub artifact build to make it publishable (by disabling it when isolated crates are used). * Review feedback. * fix published-crates list * For now, empty gdbstub data but no compile error when artifact crate is published. * add some more Cargo metadata: version for artifact crate dep

cfallin mentioned this pull request Mar 10, 2026

Add support for "expedited registers" in T-stop packets. #189

Merged

5 tasks

cfallin force-pushed the wasm-arch branch from 56f1981 to ae15574 Compare March 10, 2026 16:47

cfallin force-pushed the wasm-arch branch from ae15574 to 8000e2a Compare March 10, 2026 17:18

quick docs pass

5eda875

daniel5151 reviewed Mar 10, 2026

View reviewed changes

gdbstub_arch/src/wasm/addr.rs Outdated Show resolved Hide resolved

gdbstub_arch/src/wasm/addr.rs Outdated Show resolved Hide resolved

gdbstub_arch/src/wasm/mod.rs Show resolved Hide resolved

Review feedback.

ccc213b

Add documentation on how to set up and use a Wasm target.

f9f9b57

cfallin force-pushed the wasm-arch branch from f1f3f7f to f9f9b57 Compare March 10, 2026 21:09

minor doc fixes

a0d3000

daniel5151 approved these changes Mar 10, 2026

View reviewed changes

not a real doc test

9866b4e

daniel5151 merged commit f3652bd into daniel5151:master Mar 10, 2026
2 checks passed

cfallin mentioned this pull request Mar 12, 2026

Debugging: add builtin gdbstub component. bytecodealliance/wasmtime#12771

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

gdbstub_arch: add a WebAssembly architecture.#192

gdbstub_arch: add a WebAssembly architecture.#192
daniel5151 merged 6 commits intodaniel5151:masterfrom
cfallin:wasm-arch

cfallin commented Mar 10, 2026 •

edited

Loading

Uh oh!

daniel5151 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

daniel5151 left a comment

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

Uh oh!

daniel5151 commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

cfallin commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

API Stability

Checklist

Validation

Uh oh!

daniel5151 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

daniel5151 left a comment

Choose a reason for hiding this comment

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

Uh oh!

daniel5151 commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cfallin commented Mar 10, 2026 •

edited

Loading