| name | qemu-debug |
| description | Use for debugging QEMU itself or guests under QEMU with host-side gdb/lldb, guest gdbstub, QEMU log flags, trace events, replay, one-insn-per-tb, and structured .oh-my-qemu artifacts. |
QEMU Debug
Use this skill to reproduce, classify, and narrow QEMU failures: QEMU process crashes/assertions, guest boot hangs, wrong device behavior, TCG bugs, migration/runtime assertions, or intermittent behavior.
Primitive Boundary
This primitive owns only failure reproduction and narrowing: host debugger,
guest gdbstub, QEMU logs, trace events, replay, and instruction-window data.
It consumes a reproducer command, failure marker, relevant artifacts, and an
artifact root supplied by the caller. It does not choose build, boot-run,
verification, or iterative-fix workflow steps.
Hard policy boundary
Do not produce source code intended for QEMU upstream submission. Do not add DCO or review trailers.
Classify first
Identify the debug target:
- guest code;
- QEMU device model;
- board topology/boot ABI;
- QEMU core runtime;
- TCG frontend;
- TCG backend;
- stale image/build/environment.
Do not assume a model bug before command line and image provenance are known.
Host-side debugging of the QEMU process
Use host-side GDB or LLDB when debugging QEMU itself: crashes, assertions, hangs in device code, main-loop issues, migration bugs, TCG backend emission, or qtest-spawned QEMU failures. This is separate from the guest gdbstub: host GDB controls the emulator process; guest gdbstub controls guest CPU state.
Before attaching:
- ensure the relevant binary is built with debug info;
- record the exact QEMU command in
.oh-my-qemu/<task-slug>/commands.md;
- put debugger transcripts and notes under
.oh-my-qemu/<task-slug>/logs/ or .oh-my-qemu/<task-slug>/debugger.md;
- keep guest logs/traces separate from host debugger notes.
Common launch patterns:
gdb --args build/qemu-system-riscv64 <qemu-options>
gdb -ex 'run' --args build/qemu-system-riscv64 <qemu-options>
lldb -- build/qemu-system-riscv64 <qemu-options>
Common attach patterns:
gdb -p <qemu-pid>
lldb -p <qemu-pid>
For qtest-spawned QEMU, use verbose qtest output to recover the exact command/environment. QTEST_STOP=1 can stop the spawned QEMU early so a host debugger can attach before the test continues.
Useful host-debugger checks:
- backtrace of all threads;
- current thread and frame around QEMU assertions;
- breakpoints in device MMIO callbacks, reset hooks, realize paths, TCG translation, or qemu_ld/st helpers;
- watchpoints on device state when corruption is suspected;
handle SIGPIPE nostop noprint and similar signal policy only after confirming it matches the failure;- thread names and event-loop state for hangs.
If guest execution must be paused while host debugging, combine host GDB with QEMU -S or an early qtest stop. Do not confuse a guest breakpoint with a host breakpoint.
Guest debugging with gdbstub
Use:
-s: listen on TCP port 1234;-S: start paused;-gdb dev: choose another backend, such as tcp::3117, unix socket, chardev, or stdio.
For multi-cluster machines, use GDB target extended-remote, add-inferior, inferior N, attach N, and set schedule-multiple on.
Useful GDB checks:
- registers;
- disassembly at PC;
- virtual memory;
- gdbstub physical memory mode;
- QEMU single-step mask when IRQ/timer stepping matters.
QEMU logs and traces
Use -d item1,... with -D .oh-my-qemu/<task-slug>/logs/qemu.log. Use -d help on the target binary to discover log items.
Use -dfilter when a target PC range is known. Use -accel tcg,one-insn-per-tb=on to isolate guest-instruction boundaries.
Use trace events for structured evidence:
--trace "pattern" for quick checks;--trace events=.oh-my-qemu/<task-slug>/trace-events.txt for repeatable runs;- local
trace-events files for source-side event definitions.
Replay and determinism
For intermittent bugs, use record/replay when applicable:
- record:
-icount shift=auto,rr=record,rrfile=.oh-my-qemu/<task-slug>/replay.bin;
- replay:
-icount shift=auto,rr=replay,rrfile=.oh-my-qemu/<task-slug>/replay.bin.
Record QEMU binary, image hashes, machine options, and replay file path.
Debug ladders
QEMU process
- Reproduce with the same QEMU binary and command line.
- Build with debug info if symbols are missing.
- Launch under host GDB/LLDB for startup failures, or attach to the running PID for hangs.
- Capture all-thread backtrace and the crashing/asserting frame.
- Set source breakpoints at the suspected QEMU path and rerun.
- Add traces or qtest reproduction only after the host-side failure location is known.
Device/board
- Confirm image and command line.
- qtest the MMIO/IRQ path if possible.
- Enable targeted traces.
- Check reset state and interrupt-controller route.
- Only then interpret full boot logs.
TCG
- Reproduce under
-accel tcg.
- Use
one-insn-per-tb for instruction boundary issues.
- Compare guest instruction, TCG IR, and host code logs.
- Check frontend feature gates and PC/TB state.
- Check backend constraints, optional flags, and emitted code.
Debug report
Write reports under .oh-my-qemu/<task-slug>/ and include:
- command;
- build directory and QEMU binary;
- whether debugger target is host QEMU process or guest CPU state;
- image hashes;
- failure marker;
- decisive log/trace paths;
- classification;
- next narrow check.
Upstream references
- QEMU code provenance and AI policy:
docs/devel/code-provenance.rst.
- GDB usage:
docs/system/gdb.rst.
- CLI debug options:
qemu-options.hx.
- Tracing:
docs/devel/tracing.rst.
- Replay:
docs/system/replay.rst.
- TCG internals:
docs/devel/tcg.rst and docs/devel/tcg-ops.rst.
