Qemu Model Verification

QEMU Model Verification

Use this skill when a QEMU model, board, TCG change, or debug hypothesis must be proven rather than merely built.

As a flow primitive, use this skill to turn the result of a build, image package, boot run, trace, or debugger session into a clear PASS, FAIL, or INCONCLUSIVE claim.

Flow dependencies

• Use qemu-flow-plan to define the behavior claim and evidence required.
• Store every log, trace, replay file, command transcript, image hash list, and report under build/agent//.
• Use qemu-build, qemu-qtest, and qemu-debug for concrete gates.
• Use qemu-rlcr-loop when verification findings drive source changes.

Hard policy boundary

Do not produce source code intended for QEMU upstream submission. Do not add DCO or review trailers.

Evidence ladder

Use the lowest rung that proves the claim:

1. Static inspection: source/docs establish a fact.
2. Build: touched target compiles.
3. Unit/qtest: register, IRQ, timer, memory, or board contract holds.
4. Trace/log: the expected runtime path executes and the bad path does not.
5. Boot smoke: firmware/kernel reaches a named milestone.
6. Workload: guest output proves the modeled hardware was consumed correctly.
7. Replay/reproduction: failure is deterministic or captured for later analysis.

Do not claim device correctness from a boot banner alone.

Required artifact discipline

Record in build/agent//evidence.md:

• exact command line;
• QEMU binary and build directory;
• image paths and hashes/build IDs;
• accelerator and machine type;
• positive marker expected;
• negative markers checked;
• log/trace/replay paths;
• what the evidence proves;
• what remains unproven.

Failure classification

Classify before changing model code:

• environment/toolchain/build directory;
• stale or wrong image;
• boot ABI mismatch;
• board topology mismatch;
• device register/IRQ/timer/DMA semantics;
• TCG frontend/backend bug;
• guest/application bug unrelated to the model.

Only topology, model-semantics, and TCG categories usually justify source changes.

Device/board verification checklist

• reset state;
• read/write masks and reserved bits;
• W1C/status clear;
• IRQ raise/lower and interrupt-controller route;
• virtual clock/timer behavior;
• DMA guest-memory effect;
• machine creation;
• key memory-map probes;
• reset after dirty state.

Trace validation rules

For accelerators or reverse-engineered paths:

• count events and inspect semantic summaries;
• check skipped/unknown descriptor counts;
• verify command-memory and DMA ranges;
• correlate trace milestones with UART or workload output;
• verify the running image is the image you intended.

Reporting format

Use:

PASS|FAIL|INCONCLUSIVE: 
Command: 
Artifacts: />
Evidence: 
Proves: 
Does not prove: 

Upstream references

• QEMU code provenance and AI policy: docs/devel/code-provenance.rst.
• Testing overview: docs/devel/testing/main.rst.
• qtest docs: docs/devel/testing/qtest.rst.
• Tracing: docs/devel/tracing.rst.
• Replay: docs/system/replay.rst.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: processmission
• Source: processmission/oh-my-qemu
• License: MIT
• Homepage: https://processmission.github.io/oh-my-qemu/

Install and usage instructions live in the source repository linked above.