Add support for Wasm-specific commands. by cfallin · Pull Request #188 · daniel5151/gdbstub

cfallin · 2026-03-04T23:00:51Z

Description

This adds support for the commands supported by LLDB when debugging a Wasm target over gdbstub; see the LLDB reference for details.

These commands permit access to the values on the Wasm operand stack and in Wasm locals and globals, which are distinct from the "registers" on this target (only PC is defined as a fixed register). It also permits responding to the qWasmCallStack query, which puts responsibility for walking the stack frames on the target rather than on the debugger via raw frame-memory reads (since Wasm has a protected call stack that is distinct from the linear memory).

This has been tested as part of a work-in-progress gdbstub host in the Wasmtime runtime.

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

I'm not able to show validation with just this PR, as I'll need to contribute one more (upcoming) before this works in the Wasmtime gdbstub host.

This adds support for the commands supported by LLDB when debugging a Wasm target over gdbstub; see the [LLDB reference] for details. These commands permit access to the values on the Wasm operand stack and in Wasm locals and globals, which are distinct from the "registers" on this target (only PC is defined as a fixed register). It also permits responding to the `qWasmCallStack` query, which puts responsibility for walking the stack frames on the target rather than on the debugger via raw frame-memory reads (since Wasm has a protected call stack that is distinct from the linear memory). [LLDB reference]: https://lldb.llvm.org/resources/lldbgdbremote.html#wasm-packets

src/protocol/commands/_qWasmStackValue.rs

src/target/ext/wasm.rs

src/stub/core_impl/wasm.rs

cfallin · 2026-03-06T00:19:27Z

Updated based on feedback -- thanks!

daniel5151

A few more comments / follow-ups.

src/target/ext/wasm.rs

src/protocol/commands/_qWasmCallStack.rs

daniel5151 · 2026-03-06T16:47:41Z

src/target/ext/wasm.rs

+    /// Wasm, as they encode the particular Wasm module plus an offset
+    /// into that module's code space.
+    ///
+    /// [LLDB souce code]: https://github.com/llvm/llvm-project/blob/main/lldb/source/Plugins/Process/wasm/ProcessWasm.h


reading through this code... it kinda seems like gdbstub should be the entity in charge of constructing these wasm_addr_t types on behalf of the user, assuming that wasm_addr_t is an LLDB-specific construct / protocol detail?

It might be nice to have such functionality in gdbstub, yeah, but note that the addresses are not just used for the callstack query -- they are how memory read/write commands, breakpoints, watchpoints, etc., address the multiple Wasm memories and modules. So it would either have to be integrated into all of those APIs (some sort of Addr type projected from Arch with an abstraction for a target-defined encoding?) or a disjoint piece of the API producing a u64 (a little encoder/decoder utility) that the user would then have to wire up to the rest of the API surface.

I think I'd prefer not to think through all of that to try to get this landed (if you don't mind!) but I'm happy to offer my thoughts from the Wasm perspective if you want to try to sketch that out more...

Ooooh, I see. I didn't realize how pervasive it is...

In that case, lets make sure we point out that nuance in the wasm-specific gdbstub docs. Can you hoist some of the current pointers / docs into a new section in the module docs a-la ## LLDB's WASM Program Counter Representation, and then include a brief intra-doc link from wasm_call_stack pointing to it?

FWIW, this is also something that'd be great to call out in the docs of a impl Arch for Wasm. I'm assuming you've got one of those floating around in your project somewhere, so this is also a good opportunity for me to ask if you'd be willing to send it up to gdbstub_arch, hah.

or a disjoint piece of the API producing a u64 (a little encoder/decoder utility) that the user would then have to wire up to the rest of the API surface.

This is certainly something I'd be interested in adding (e.g: as part of this new mod wasm we're adding), but I don't think we need to block landing this PR for that.

The alternative idea of pushing this complexity into the type system itself via some Addr type would def be cool (and if you've got a sketch in your head, no harm in sharing in a new GH Issue!), but yeah, def not something we'd need to get into on this PR.

OK, cool -- I've moved the docs into the doc-comment for the ext::wasm module for now.

Happy to look into upstreaming part of an arch implementation -- the lines are a little blurry wrt my actual Wasmtime adapter glue of course, and I'd have to look at how other architectures have abstracted out the "bottom half" (OS or debug hardware interface).

The Arch impl should be pretty portable I'd imagine, since it covers spec-defined things like register ordering, wire de/serialization, and essential metadata (like the target.xml, and/or LLDB metadata).

It would also be a good in-repo example of the to_reg_id API we're talking about in #190 (well, aside from the toy armv4t example implementation, ofc)

cfallin · 2026-03-09T18:48:45Z

Thanks -- addressed all feedback, I believe!

daniel5151

Just a few more doc related nits, but aside from that - this is just about ready to rock.

src/target/ext/wasm.rs

src/target/mod.rs

Co-authored-by: Daniel Prilik <danielprilik@gmail.com>

cfallin · 2026-03-09T21:04:01Z

Applied; thanks!

daniel5151

Nice!

Thanks for all the iterations here - this looks awesome.

Will wait until the other PRs in the series land, and then cut a fresh gdbstub release :)

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.

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.

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.)

This was referenced Mar 4, 2026

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

Merged

Add support for qProcessInfo and qHostInfo queries. #190

Merged

daniel5151 requested changes Mar 5, 2026

View reviewed changes

Review feedback.

2da4988

daniel5151 requested changes Mar 6, 2026

View reviewed changes

Review feedback.

40937cc

daniel5151 requested changes Mar 9, 2026

View reviewed changes

src/target/ext/wasm.rs Outdated Show resolved Hide resolved

src/target/ext/wasm.rs Outdated Show resolved Hide resolved

src/target/ext/wasm.rs Outdated Show resolved Hide resolved

src/target/mod.rs Outdated Show resolved Hide resolved

cfallin and others added 4 commits March 9, 2026 14:03

Update src/target/mod.rs

8fbc6e9

Co-authored-by: Daniel Prilik <danielprilik@gmail.com>

Update src/target/ext/wasm.rs

eb4f543

Co-authored-by: Daniel Prilik <danielprilik@gmail.com>

Update src/target/ext/wasm.rs

168f64b

Co-authored-by: Daniel Prilik <danielprilik@gmail.com>

Update src/target/ext/wasm.rs

15dd0ec

Co-authored-by: Daniel Prilik <danielprilik@gmail.com>

daniel5151 approved these changes Mar 9, 2026

View reviewed changes

daniel5151 merged commit a0a73c1 into daniel5151:master Mar 9, 2026
2 checks passed

cfallin mentioned this pull request Mar 10, 2026

gdbstub_arch: add a WebAssembly architecture. #192

Merged

9 tasks

cfallin mentioned this pull request Mar 12, 2026

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

Open

Uh oh!

Conversation

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

Uh oh!

Description

API Stability

Checklist

Validation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 6, 2026

Uh oh!

daniel5151 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

daniel5151 Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

cfallin Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cfallin Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

daniel5151 Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

cfallin commented Mar 9, 2026

Uh oh!

daniel5151 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 9, 2026

Uh oh!

daniel5151 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cfallin commented Mar 4, 2026 •

edited

Loading

daniel5151 Mar 9, 2026 •

edited

Loading