qemu-debug
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.
processmission · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add processmission/oh-my-qemu --skill qemu-debug技能说明
SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission
SPDX-License-Identifier: MIT
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
Audit workflow
For non-trivial workspace writes, use a stable
.oh-my-qemu/<task-slug>/ directory and create only needed entries:
.oh-my-qemu/<task-slug>/
├── audit.md # Baseline, scope, decisions, evidence, verification, and gaps
├── commands.md # Redacted commands, working directories, and results
├── logs/ # Decisive build, test, runtime, or diagnostic logs
├── scripts/ # Temporary scripts, probes, parsers, and harnesses
└── output/ # Generated deliverables, dependencies, and non-QEMU binaries
Before changing source or mutable artifacts, record the workspace root,
revision, git status --short, pre-existing changes, goal, scope, and
acceptance checks in audit.md. Log exact redacted commands and results in
commands.md; record revisions, configurations, tool versions, and hashes when
they affect reproducibility. Separate observations from inferences and edit
source only when requested.
Keep QEMU builds under source-root builds/build-<target>/; put third-party
dependencies and non-QEMU binaries in task output/. Before writing audit
artifacts or configuring QEMU in a Git worktree, add .agents/,
.oh-my-qemu/, and builds/ to the repository-local file from
git rev-parse --git-path info/exclude; preserve existing entries and avoid
duplicates. Never stage or commit those directories. At handoff, verify them
absent from git status --short. Report the task directory and unresolved gaps.
QEMU upstream boundary
QEMU's official GitLab and mailing lists are upstream project channels. A
patch becomes an upstream contribution when sent to the mailing-list recipients
selected through MAINTAINERS; do not prepare or send agent-generated patches
for that submission. Local branches, commits, patch files, pushes, and pull
requests are not by themselves QEMU upstream contributions. Perform those Git
actions only when requested and follow the workspace's Git policy.
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
Host GDB controls the emulator process; the guest gdbstub controls guest CPU state. Use host GDB or LLDB for QEMU crashes, assertions, hangs, migration bugs, TCG backend emission, or qtest-spawned failures.
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/; - keep guest logs/traces separate from host debugger notes.
Common launch patterns:
gdb --args builds/build-riscv64/qemu-system-riscv64 <qemu-options>
gdb -ex 'run' --args builds/build-riscv64/qemu-system-riscv64 <qemu-options>
lldb -- builds/build-riscv64/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 noprintand 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 astcp::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>/scripts/trace-events.txtfor repeatable runs;- local
trace-eventsfiles 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>/logs/replay.bin; - replay:
-icount shift=auto,rr=replay,rrfile=.oh-my-qemu/<task-slug>/logs/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.