qemu-peripheral-modeling
Use for QEMU peripheral, accelerator, MMIO, qdev, or SysBusDevice modeling with register contracts, an explicit register framework decision, and qtest-backed verification.
processmission · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add processmission/oh-my-qemu --skill qemu-peripheral-modeling技能说明
SPDX-FileCopyrightText: Copyright (c) 2026 Process Mission
SPDX-License-Identifier: MIT
name: qemu-peripheral-modeling description: Use for QEMU peripheral, accelerator, MMIO, qdev, or SysBusDevice modeling with register contracts, an explicit register framework decision, and qtest-backed verification.
QEMU Peripheral Modeling
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.
Workflow
- Freeze the register, IRQ, DMA, reset, migration, and allowed-path contract.
- When facts come from drivers, datasheets, firmware, or regfiles, extract a source-cited register contract before modeling; do not fill gaps from memory.
- Work in small reviewable source-change rounds and record each round's paths,
verification, review result, and gaps in
audit.md. - Build the affected target and map each modeled behavior to focused qtests.
- Use traces or workload evidence for integration claims and state what remains unproven.
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.
Device modeling contract
A real hardware block should be a first-class device. Board code wires topology; device code owns behavior.
For each device, define in audit.md:
- MMIO base(s), size(s), endianness, and accepted access widths;
- register reset values, masks, read/write behavior, W1C bits, aliases, and reserved-bit behavior;
- cross-register dependencies, feature flows, and register-bit combinations needed to enable or observe a function;
- IRQ outputs and level/edge semantics;
- timer, clock, reset, DMA, and bus dependencies;
- migration-visible state vs local caches;
- existing stub/unimplemented boundary;
- reference evidence: datasheet, SDK driver, firmware trace, sibling QEMU device.
When the source of truth is external to QEMU, do not begin modeling from memory or from a partial driver skim. Require a source-cited register contract with register facts, cross-register dependencies, behavioral sequences, conflicts, confidence levels, and qtest candidates.
QEMU object shape
Default shape unless nearby code uses a clearer convention:
SysBusDeviceor the subsystem's existing base class;- one owned
MemoryRegionper register window; - explicit
qemu_irqoutputs; - reset/realize hooks in the local style;
VMStateDescriptionfor guest-visible migratable state;- named properties only for real board/SoC variation.
Do not put register side effects in board files.
Register bank framework decision
Before designing a guest-visible control/status register bank:
- Read applicable policy files present in the target QEMU workspace.
- If they do not decide, use the user's explicit compatible framework direction.
- If neither decides, inspect nearby devices in the same subsystem for a clear maintained convention.
- Select
RegisterInfoor manual MMIO callbacks and record the evidence and rationale in.oh-my-qemu/<task-slug>/audit.md.
Stop at the first decisive input. Use RegisterInfo from the checked-out QEMU
tree as the default when none decides. Manual MMIO callbacks are permitted when
this decision gate justifies them; they are not a failure merely because they
do not use RegisterInfo.
For the RegisterInfo path, use the current tree rather than remembered API
signatures. QEMU versions can differ, so inspect the local implementation:
- read
include/hw/core/register.hfor the currentRegisterAccessInfo,RegisterInfo,RegisterInfoArray, andregister_init_block*API; - read
include/hw/core/registerfields.hfor the current register/field macros; - search the checked-out tree for
RegisterAccessInfo,register_init_block8,register_init_block32,register_init_block64,register_read_memory,register_write_memory,register_reset, andregister_array_get_owner; - prefer examples in the same subsystem or nearby architecture before using generic examples;
- if a named reference path is absent in another QEMU version, re-search by symbol instead of assuming the old path.
Current-tree reference families to inspect first:
- simple register bank with callbacks and VMState:
hw/dma/xlnx-zynq-devcfg.c; inspect its header o