Connect to a gdbstub and register the session under name.

For QEMU, start it with -s (stub on tcp::1234) or -gdb tcp::PORT, and add -S to halt the CPU before the first instruction so you can set breakpoints before anything runs. With qemu-mcp, pass these via qemu_boot's extra_args, e.g. extra_args="-s -S". elf is the kernel image with symbols (and ideally DWARF debug info); it enables symbol names, file:line breakpoints and source locations. load_bias is added to every ELF address, for images loaded somewhere other than their link address (0 for a normally linked kernel). The target stays halted after connecting.

Remove breakpoints, detach from the stub so the guest keeps running, and forget the session. A running target is halted first.

List active debug sessions.

Read registers. Target must be halted.

registers is a comma-separated list (e.g. "eip,esp,cr2,cr3"); default is the general set from the stub's g packet. all=True also reads every extra register the target describes (control registers, segment bases, FPU/SSE...). Flag registers (eflags, cr0, cr4...) are decoded.

Write a register. value is an address expression (0x10, symbol, ...).

Read guest memory (virtual addresses, as the CPU currently sees them).

address accepts 0x1234, symbol, symbol+0x10, file.c:42 or $esp+8. format: "hex" (hexdump with ASCII), "words" (pointer-sized words, symbolized), or "string" (NUL-terminated string at address). length is capped at 4096 bytes.

Write raw bytes (hex string, e.g. "90 90 cc") to guest memory.

Set a breakpoint or watchpoint.

location: 0x1234, symbol, symbol+0x10, or file.c:42. kind: "sw" (software breakpoint), "hw" (hardware breakpoint - use this before paging is enabled or for code that isn't loaded yet), or a watchpoint: "write", "read", "access" (length bytes, default one word).

Remove a breakpoint/watchpoint by its # id.

List breakpoints and watchpoints.

Resume the target and wait up to timeout_s for it to stop.

If it hasn't stopped by then it keeps running: call debug_wait to keep waiting, or debug_interrupt to halt it where it is.

Wait for a running target to stop (after debug_continue timed out).

Halt a running target immediately (like Ctrl-C in gdb).

Single-step count machine instructions (1..1000) and show where it stopped.

Show the call stack.

mode "fp" walks the frame-pointer chain (exact, but only if the kernel was built with frame pointers, e.g. -fno-omit-frame-pointer); "scan" scans the stack for return addresses (works on -O2 kernels without frame pointers, x86 only, needs elf; may include stale frames); "auto" tries fp and falls back to scan if the chain is empty.

Disassemble count instructions from address (default: current pc).

bits overrides the decode mode on x86 (16 for real mode, 32, 64) - useful in bootloader code that runs before the CPU mode matches the ELF.

Look up symbols without touching the target.

query: an address (0x100abc) -> symbol+offset and source line; a symbol or symbol+off -> its address, size and source line; or file.c:42 -> address. Uses the session's ELF (name=) or a standalone ELF path (elf=).

Explain a crash / triple fault from a QEMU interrupt log.

Produce the log by running QEMU with -d int,cpu_reset -D <log_path> (add -no-reboot so a triple fault stops the VM instead of looping). Decodes the exception chain (vector names, page-fault and selector error codes, CR2), filters out timer IRQs and software interrupts, points at the root cause, and symbolizes addresses when elf is given. x86 only.