randomparity / randomparity/kdive

Add the KGDB-over-serial debug transport

Open
#1,828 0 comments 0 reactions 0 assignees View on GitHub
area:debug area:mcp-api effort:L priority:P1 provider:baremetal-bmc provider:powervm status:blocked type:feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.