Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add processmission/oh-my-qemu --skill qemu-debug

About this skill


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 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>/scripts/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>/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

  1. Reproduce with the same QEMU binary and command line.
  2. Build with debug info if symbols are missing.
  3. Launch under host GDB/LLDB for startup failures, or attach to the running PID for hangs.
  4. Capture all-thread backtrace and the crashing/asserting frame.
  5. Set source breakpoints at the suspected QEMU path and rerun.
  6. Add traces or qtest reproduction only after the host-side failure location is known.
Read the complete source ↗