96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0154
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Route Debugger Operations Through VM Sessions
|
|
status: open
|
|
created: 2026-07-05
|
|
ref_decisions: [DEC-0038]
|
|
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
DEC-0038 requires VM-backed mutable execution state to be owned by VM sessions. Normal execution now ticks session-owned VMs, but desktop debugger commands still inspect and mutate `firmware.vm`, the transitional legacy VM. This leaves debugger state, breakpoints, single-step execution, PC snapshots, and stack snapshots inconsistent with the active VM session.
|
|
|
|
## Objective
|
|
|
|
Route host debugger operations through the active VM session rather than the legacy firmware VM. Debugger pause/resume/step/state/breakpoint operations must target the same VM context that foreground execution ticks.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: DEC-0038.
|
|
- Builds on PLN-0148 through PLN-0152.
|
|
- Should be implemented before PLN-0155 removes the legacy firmware VM bridge.
|
|
|
|
## Scope
|
|
|
|
- Add session-aware debugger accessors to `SystemOS`/`VmFacade`.
|
|
- Expose active VM session inspection and mutation operations needed by the debugger:
|
|
- PC;
|
|
- operand stack preview;
|
|
- insert breakpoint;
|
|
- remove breakpoint;
|
|
- list breakpoints;
|
|
- single-instruction debug step;
|
|
- active cartridge identity for handshake and state responses.
|
|
- Update `crates/host/prometeu-host-desktop-winit/src/debugger.rs` so it no longer reads or mutates `firmware.vm` for active VM state.
|
|
- Ensure debugger setup for direct debug boot initializes through normal cartridge/session loading or an explicit session-aware metadata path, not `os.vm().initialize(&mut firmware.vm, ...)`.
|
|
- Keep pause/resume/step-frame control mapped to active VM session runtime state.
|
|
- Add tests that would fail if debugger state came from the legacy VM while the session VM is active.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not remove `Firmware.vm`; that is PLN-0155.
|
|
- Do not redesign the debugger protocol.
|
|
- Do not add multi-client debugging.
|
|
- Do not add background-session debugging beyond active/resident session semantics already supported by DEC-0038.
|
|
|
|
## Execution Method
|
|
|
|
1. Add focused `VmFacade` methods for active-session VM inspection:
|
|
- `active_pc`;
|
|
- `active_operand_stack_top`;
|
|
- `insert_active_breakpoint`;
|
|
- `remove_active_breakpoint`;
|
|
- `active_breakpoints_list`;
|
|
- `debug_step_active_session`.
|
|
2. Define active-session resolution explicitly:
|
|
- foreground VM session first;
|
|
- resident Game session when Hub has foreground but a resident Game is the active debug target;
|
|
- no legacy fallback for debugger mutation once a session exists.
|
|
3. Update `HostDebugger::setup_boot_target` so debug cartridge metadata is loaded without initializing `firmware.vm` as canonical state.
|
|
4. Update `HostDebugger::handle_command` for `Step`, `GetState`, `SetBreakpoint`, `ListBreakpoints`, and `ClearBreakpoint`.
|
|
5. Update `HostDebugger::stream_events` breakpoint-hit PC reporting to read from the active session.
|
|
6. Add tests under `crates/host/prometeu-host-desktop-winit/src/debugger.rs` proving debugger commands observe and mutate the session VM.
|
|
7. Run the host, firmware, and system test suites.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Debugger handshake reports cartridge identity from session/runtime state or preloaded metadata, not from a global VM initialized only for debugger setup.
|
|
- `GetState` returns PC and stack data from the active VM session.
|
|
- `Step` advances the active VM session, not `firmware.vm`.
|
|
- Breakpoint commands mutate the active VM session.
|
|
- Breakpoint-hit events report the active session PC.
|
|
- No debugger command path directly reads or mutates `firmware.vm` for active VM execution state.
|
|
- Existing debugger protocol tests pass.
|
|
|
|
## Tests
|
|
|
|
- `cargo test -p prometeu-host-desktop-winit`
|
|
- `cargo test -p prometeu-firmware`
|
|
- `cargo test -p prometeu-system`
|
|
- `cargo clippy -p prometeu-host-desktop-winit -p prometeu-firmware -p prometeu-system --all-targets -- -D warnings`
|
|
- Add tests for:
|
|
- `GetState` reads session VM PC;
|
|
- `Step` affects session VM;
|
|
- breakpoint insert/list/remove uses session VM;
|
|
- debugger setup does not initialize `firmware.vm` as the canonical app context.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
|
|
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
|
- `crates/console/prometeu-system/src/services/vm_session.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
- Debugger-related tests in host and firmware crates
|