Debugging: add the debug-main world. by cfallin · Pull Request #12756 · bytecodealliance/wasmtime

cfallin · 2026-03-10T23:13:54Z

This PR "draws the rest of the owl" for the debug-main world (bytecodealliance/rfcs#45). This includes a WIT world that hosts debug components that have access to "host debug powers" via a debugging API, and the ability to load such a debug-component and give it control of the main program as a debuggee when using wasmtime run.

The WIT is namespaced to bytecodealliance:wasmtime and is slightly aspirational in places: for example, the host does not yet implement injection of early return values or exception-throws. I intend to fill out a series of TODO issues once this all lands to track followup ("post-MVP") work.

This PR does not include any debug components. I separately have a gdbstub component, with which I tested and co-developed this host-side implementation. My plan is to land it in a followup PR as a component that will be embedded in/shipped with the Wasmtime CLI and available under an easy-to-use CLI option. Once we have that gdbstub component, we can also implement end-to-end integration tests that boot up LLDB and run through an expected interaction. (Separately, those integration tests will require a release of wasi-sdk to ship an LLDB binary that we can use.) As such, there are no real tests in this PR: interesting behaviors only really occur with a full end-to-end flow.

The integration with the CLI is a little awkward (we internally build another wasmtime run command that invokes the debug component, and tie it together with the debuggee via a special invoke_debugger API; this seemed less bad than reworking all of the WASI setup to be more reusable). Happy to take more ideas here.

cfallin · 2026-03-10T23:14:42Z

(For reference, my plan is to stack a PR on top of this with the gdbstub component as soon as my last PR to upstream gdbstub lands.)

cfallin · 2026-03-10T23:16:42Z

I considered ways to try to break this up into smaller pieces, but a few thoughts:

The linecount on the diff is a little misleading because this (necessarily) replicates all of the wasip2 WITs in deps/; the actual host impl is ~1.6kLoC.
Those 1.6kLoC are tedious but just a bunch of accessors, morally -- landing, say, half of the memory accessors separately wouldn't meaningfully reduce complexity IMHO.

Happy to take any thoughts you have on this though!

This PR "draws the rest of the owl" for the debug-main world (bytecodealliance/rfcs#45). This includes a WIT world that hosts debug components that have access to "host debug powers" via a debugging API, and the ability to load such a debug-component and give it control of the main program as a debuggee when using `wasmtime run`. The WIT is namespaced to `bytecodealliance:wasmtime` and is slightly aspirational in places: for example, the host does not yet implement injection of early return values or exception-throws. I intend to fill out a series of TODO issues once this all lands to track followup ("post-MVP") work. This PR does not include any debug components. I separately have a gdbstub component, with which I tested and co-developed this host-side implementation. My plan is to land it in a followup PR as a component that will be embedded in/shipped with the Wasmtime CLI and available under an easy-to-use CLI option. Once we have that gdbstub component, we can also implement end-to-end integration tests that boot up LLDB and run through an expected interaction. (Separately, those integration tests will require a release of wasi-sdk to ship an LLDB binary that we can use.) As such, there are no real tests in this PR: interesting behaviors only really occur with a full end-to-end flow. The integration with the CLI is a little awkward (we internally build another `wasmtime run` command that invokes the debug component, and tie it together with the debuggee via a special `invoke_debugger` API; this seemed less bad than reworking all of the WASI setup to be more reusable). Happy to take more ideas here.

alexcrichton

Very nice, it's awesome to see this all come together!

W.r.t. PR size -- I think this one's fine. It's all safe code using preexisting APIs and the new boundaries here, primarily the CLI interface, are easy enough to review in isolation. While this could be split up I'm ok landing this pretty much as-is given that all the major foundational decisions have already been sorted out.

W.r.t. tests -- we talked about this but to write this down here too -- I think it'd be good to have a small test suite which tests a few "hello world" interactions of the CLI with custom debugger wasms. The intent here is to build out enough infrastructure to have a place to put regression tests added in the future as opposed to thoroughly testing the entire interface. Most of the testing will probably happen through the gdbstub component for now. My recommendation would be do drop debugger/debuggee pairs in crates/test-programs/src/bin/* and that can be a mixture of Rust/C/C++/Wat. That'd all be woven together probably in a new tests/all/debug/cli.rs or something like that which would be modeled after the existing tests/all/cli_tests.rs.

Also, for stylistic things in this PR (like flattening results) I think it would also be quite reasonable if you'd prefer to defer such changes to future PRs/issues. I think it's most valuable at this juncture to get all your initial work landed and positioned for iteration, and this is all sequestered/fenced off well enough to be pretty easily refactorable without affecting too much else. Basically, feel free to defer comments below where you feel appropriate.

crates/debugger/src/host.rs

crates/debugger/wit/deps/cli.wit

src/commands/run.rs

primoly

Making the API more consistent by having the debuggee parameter in the same position in all functions.

(Sorry for being pedantic, I just noticed those things while reading the API and thought it would be better to tidy this up now than after it has been merged and started to be used in tooling.)

crates/debugger/src/host.rs

crates/debugger/wit/world.wit

…tions for the debug component.

cfallin · 2026-03-12T05:53:42Z

All feedback addressed, I believe (thanks!); I'll add some basic test components and tests to run them tomorrow (then hopefully get the gdbstub component up as my next PR).

src/commands/run.rs

crates/debugger/src/host/opaque.rs

src/commands/run.rs

cfallin · 2026-03-12T21:38:39Z

@alexcrichton I've added some basic tests with a very simple debug component (one that single-steps a few times to smoke-test everything, one that interrupts an infinite loop to check that the async machinery works properly). I think this should be ready for final review now -- thanks!

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

cfallin · 2026-03-13T05:08:11Z

@alexcrichton in addition to addressing review feedback I tracked down a cancelation-safety issue in EventFuture (reproducible locally with taskset 0x1 cargo test ... I guess because it requires a certain amount of serialization causing the DynPollable::ready future to be canceled at least once; the CI machine has less parallelism and triggered this). See c39e049. Thanks!

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

…very epoch yield.

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

cfallin · 2026-03-13T08:02:10Z

Also a bugfix discovered via CI failure in the stacked PR here -- see 6252848.

alexcrichton

I'll admit I don't really understand what happened with the cancellation safety bit (it looked like it should work before), but happy to trust you on that it's fixing things

crates/debugger/src/host.rs

crates/test-programs/src/bin/debugger_component.rs

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

… compilation flow

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

cfallin requested review from a team as code owners March 10, 2026 23:13

cfallin requested review from alexcrichton and removed request for a team March 10, 2026 23:13

cfallin force-pushed the a-whole-wide-world-for-debuggers-to-play-in branch 2 times, most recently from afce165 to e178a98 Compare March 11, 2026 14:21

cfallin force-pushed the a-whole-wide-world-for-debuggers-to-play-in branch from e178a98 to 3dc2544 Compare March 11, 2026 15:01

alexcrichton reviewed Mar 11, 2026

View reviewed changes

primoly suggested changes Mar 11, 2026

View reviewed changes

primoly reviewed Mar 11, 2026

View reviewed changes

crates/debugger/wit/world.wit Show resolved Hide resolved

cfallin added 3 commits March 11, 2026 21:22

Review feedback.

7f542d3

Review feedback.

1caf84f

Review feedback: update vendor-wit.sh.

adec476

cfallin force-pushed the a-whole-wide-world-for-debuggers-to-play-in branch from 5076cab to adec476 Compare March 12, 2026 04:50

cfallin added 6 commits March 11, 2026 21:52

Review feedback: -Ddebugger-arg= -> -Darg=.

d2515bb

Review feedback.

18705e2

Review feedback.

a15e743

Review feedback: factor host.rs into several submodules.

8d5db0d

Review feedback: rename Debugger to Debuggee on host side.

647853b

Review feedback: split inherit_stdin_stdout, and add corresponding op…

dcf03f9

…tions for the debug component.

cfallin force-pushed the a-whole-wide-world-for-debuggers-to-play-in branch from 1806cae to dcf03f9 Compare March 12, 2026 05:52

alexcrichton reviewed Mar 12, 2026

View reviewed changes

src/commands/run.rs Outdated Show resolved Hide resolved

crates/debugger/src/host/opaque.rs Outdated Show resolved Hide resolved

src/commands/run.rs Show resolved Hide resolved

cfallin added 3 commits March 12, 2026 11:29

Review feedback.

49ff2fc

Review feedback.

eaebb70

Add simple debug-component tests.

c9e59a8

cfallin added 6 commits March 12, 2026 16:13

Add wasm32-wasip2 target in a few places in CI

55d6bc8

Cargo vets for wstd dependency.

d0027a6

Add wasm32-wasip2 in more places

59be108

fix debug-component test dependence on componentization byte offsets

329c8d7

Review feedback.

b3fc04d

Fix cancel-safety of EventFuture.

c39e049

Fix: Interrupted events should only occur after interrupt(), not on e…

6252848

…very epoch yield.

alexcrichton approved these changes Mar 13, 2026

View reviewed changes

cfallin added 2 commits March 13, 2026 10:49

Review feedback.

ea1f7a9

Review feedback: strip down WASI imports in debugger world.

2df52d6

cfallin added this pull request to the merge queue Mar 13, 2026

cfallin removed this pull request from the merge queue due to a manual request Mar 13, 2026

fold debugger test component back into wasip1 + adapter test artifact…

d7aa6a2

… compilation flow

cfallin enabled auto-merge March 13, 2026 18:45

cfallin added this pull request to the merge queue Mar 13, 2026

Merged via the queue into bytecodealliance:main with commit 133a0ef Mar 13, 2026
45 checks passed

cfallin deleted the a-whole-wide-world-for-debuggers-to-play-in branch March 13, 2026 19:22

cfallin mentioned this pull request Mar 13, 2026

Debugging: tracking issue for MVP and post-MVP work #12777

Open

10 tasks

Conversation

cfallin commented Mar 10, 2026

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

cfallin commented Mar 10, 2026

Uh oh!

alexcrichton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

primoly left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cfallin commented Mar 12, 2026

Uh oh!

cfallin commented Mar 13, 2026

Uh oh!

cfallin commented Mar 13, 2026

Uh oh!

alexcrichton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants