randomparity / randomparity/kdive
Add the KGDB-over-serial debug transport
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 311
Description
Part of #1814
## Problem
On a VM, live kernel debugging attaches to the QEMU gdbstub. **Bare metal has no gdbstub.** The
equivalent is KGDB speaking the GDB remote protocol over a serial line — which, on a BYO host, is
the same OOB serial channel the console collector is already reading.
That collision is the substance of this entry: one serial channel, two consumers. A KGDB session
and console log collection cannot both own the stream naively, and getting the arbitration wrong
means either losing console history during a debug session or corrupting the protocol.
There is also a surface change: the debug transport vocabulary is a **closed literal** with exactly
two members today, so KGDB is not a provider-local addition — it touches shared and core-prefixed
files.
## Evidence
- `src/kdive/providers/ports/lifecycle.py:27` —
`DebugTransportKind = Literal["gdbstub", "drgn-live"]`, and `:28` the matching
`DEBUG_TRANSPORT_KINDS` frozenset. A third kind edits both.
- `src/kdive/services/debug/lifecycle.py:57` consumes that type, and the debug-session registrar
under `mcp/tools/` must accept the new kind — **inside** the portability gate's core prefixes
("the whole `mcp` package including `mcp/tools/*`"), so it needs the allowlist entry #1820 owns.
- `src/kdive/providers/ports/lifecycle.py:215` — `Connector.open_transport`.
- `src/kdive/providers/shared/debug_common/gdbmi/core/engine.py` — the existing gdb/MI engine,
reused rather than reimplemented.
- `src/kdive/providers/shared/debug_common/gdbmi/policy/arch.py:59` — `select_gdb_binary`, and
`:74` `gdb_target_arch_name`; the multiarch selection ADR-0347 already built for ppc64le applies
directly.
- Related prior work under epic #1760: #1777 (KGDB over the shared serial endpoint), #1774 (serial
endpoint leasing and arbitration), #1784 (recover stale serial/KGDB sessions). See #1814's
overlap table.
## Expected outcome
- A third `DebugTransportKind` for KGDB, with `DEBUG_TRANSPORT_KINDS`, the service layer, and the
debug-session registrar updated coherently — and the matching #1820 allowlist entry, so the
portability gate stays honest rather than being silenced.
- `Connector.open_transport` opening a KGDB endpoint on the OOB serial channel, driving the
existing gdb/MI engine with arch-correct gdb selection.
- Serial arbitration implemented per #1815's decision, with the losing consumer's behavior
explicit (either console capture pauses with a recorded gap, or the stream is demultiplexed).
- `kgdboc` on the target cmdline handled by the install plane's cmdline construction.
- The agent-facing contract states how to attach, what the session costs, and how it ends — wrapper
docstring and `Field` text, per the FastMCP rule.
Blocked by #1826
Contributor guide
Research direction
Start with src/kdive/providers/ports/lifecycle.py and the existing gdb/MI engine at src/kdive/providers/shared/debug_common/gdbmi/core/engine.py; read the service and registrar references, plus #1815 and the blocking #1826. Review #1777, #1774, #1784, and #1820 for serial ownership and portability constraints. Done means KGDB is represented coherently, uses the serial channel with explicit arbitration, handles kgdboc, and documents the agent-facing session contract.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- devtools, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100