# Qemu Peripheral Modeling

> Use for QEMU peripheral, accelerator, MMIO, qdev, or SysBusDevice modeling. Extends qemu-flow-plan and qemu-rlcr-loop; register-bank modeling must use QEMU's registerinfo framework and qtest verification.

- **Type:** Skill
- **Install:** `agentstack add skill-processmission-oh-my-qemu-qemu-peripheral-modeling`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [processmission](https://agentstack.voostack.com/s/processmission)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [processmission](https://github.com/processmission)
- **Source:** https://github.com/processmission/oh-my-qemu/tree/main/.agents/skills/qemu-peripheral-modeling
- **Website:** https://processmission.github.io/oh-my-qemu/

## Install

```sh
agentstack add skill-processmission-oh-my-qemu-qemu-peripheral-modeling
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# QEMU Peripheral Modeling

Use this domain skill for QEMU hardware blocks: MMIO devices, SysBus/qdev peripherals, interrupt controllers, timers, DMA engines, GPIO/PWM/UART/watchdog blocks, and accelerator-like devices.

## Flow dependencies

1. Start with `qemu-flow-plan` for any non-trivial work.
2. If register facts come from drivers, datasheets, firmware filesystems, or regfiles, run `qemu-register-extraction` first and use its `register-extraction.md` as the source contract.
3. Store all plans, traces, scratch scripts, logs, review notes, and decoded dumps under `build/agent//`.
4. Use `qemu-rlcr-loop` for implementation/debugging rounds.
5. Use `qemu-build` and `qemu-qtest` for build and qtest gates.
6. Use `qemu-model-verification` for runtime/trace/workload evidence.

Do not create `.plan/`, `.humanize/`, root-level notes, or helper files inside QEMU source directories.

## Hard policy boundary

Do not produce source code intended for QEMU upstream submission. QEMU currently declines contributions believed to include or derive from AI-generated content. Do not add DCO or review trailers.

## 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 the plan:

- 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 completed `qemu-register-extraction` markdown handoff 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:

- `SysBusDevice` or the subsystem's existing base class;
- one owned `MemoryRegion` per register window;
- explicit `qemu_irq` outputs;
- reset/realize hooks in the local style;
- `VMStateDescription` for guest-visible migratable state;
- named properties only for real board/SoC variation.

Do not put register side effects in board files.

## RegisterInfo framework requirement

For any peripheral with a guest-visible register bank, the model must be built around QEMU's registerinfo framework from the checked-out QEMU tree. Manual offset-switch MMIO callbacks are not acceptable for normal register banks.

Use the current tree, not remembered API signatures. QEMU versions can differ, so before designing code, inspect the local implementation:

- read `include/hw/core/register.h` for the current `RegisterAccessInfo`, `RegisterInfo`, `RegisterInfoArray`, and `register_init_block*` API;
- read `include/hw/core/registerfields.h` for 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`, and `register_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` plus `include/hw/dma/xlnx-zynq-devcfg.h`;
- IRQ/status register side effects: `hw/intc/xlnx-zynqmp-ipi.c`;
- wrapped read/write handlers that still delegate to registerinfo: `hw/misc/xlnx-versal-trng.c`;
- broader Xilinx-style banks: search `hw/misc`, `hw/dma`, `hw/intc`, `hw/nvram`, and `hw/rtc` for `register_init_block32`.

The model should normally have:

- register offset and field definitions from the registerfields macros;
- register storage sized from the register map;
- a matching `RegisterInfo` array;
- a `RegisterAccessInfo` table describing name, address, reset value, read-only bits, write-one-clear bits, reserved bits, unimplemented bits, and register hooks;
- `MemoryRegionOps` using `register_read_memory` and `register_write_memory`, or thin wrappers that normalize version/SoC quirks and then delegate to registerinfo;
- reset logic that resets the registerinfo entries according to the current tree's convention;
- VMState for guest-visible register storage and other migratable state.

Use registerinfo hooks deliberately:

- use pre-write hooks to filter or transform a write before storage;
- use post-write hooks for IRQ/status/timer/DMA side effects after storage;
- use post-read hooks only for guest-visible read side effects;
- remember that register reset can call write hooks in this framework, so callbacks must be reset-safe.

If a device cannot use registerinfo for a particular window, record the technical reason in `build/agent//plan.md`. The exception must be narrow, and any custom handler should still delegate to registerinfo for ordinary registers.

## MMIO rules

- Use registerinfo for ordinary register-bank reads/writes.
- Use constants/macros for offsets, masks, shifts, reset values, and IDs.
- Keep normal read/write callbacks allocation-free.
- Represent RO, W1C, reserved, clear-on-read, and unimplemented bits in `RegisterAccessInfo` whenever the current API supports them.
- Mask or transform guest writes through registerinfo hooks, not duplicated ad hoc logic.
- Update status before raising/lowering IRQ.
- Keep long-running work out of MMIO callbacks; use timers, bottom halves, workers, or staged execution.
- Validate guest DMA addresses with QEMU address-space/DMA helpers.
- Never edit generated files under `build/`; fix register definitions or source inputs instead.

## qtest expectations

Every material peripheral change should have narrow qtest coverage for:

- reset values;
- read/write masks and reserved bits;
- unsupported access widths when guest-visible;
- W1C/status clear behavior;
- IRQ assert/deassert paths;
- virtual clock behavior for timers;
- DMA memory effects when applicable.
- registerinfo reset/hook behavior for registers with side effects;

## Accelerator addendum

For command-stream or accelerator blocks:

- separate descriptor parsing from execution;
- record command ranges, DMA windows, and output buffers;
- validate skipped/unknown operation counts;
- correlate trace milestones with guest-visible output;
- record image hashes under `build/agent//evidence.md`.

## Anti-patterns

- Generic scratch register banks for real devices.
- Manual offset-switch MMIO handlers for ordinary register banks instead of registerinfo.
- Copying stale registerinfo function signatures from memory instead of inspecting the checked-out tree.
- Fake success paths that only make firmware boot.
- Board-specific behavior hidden in MMIO callbacks.
- Trace-count-only success claims.
- Logging or allocation on every normal MMIO access.

## Upstream references

- QEMU code provenance and AI policy: `docs/devel/code-provenance.rst`.
- QOM and qdev conventions: QEMU `docs/devel/` and nearby `hw/*` devices.
- RegisterInfo API: `include/hw/core/register.h`.
- Register field macros: `include/hw/core/registerfields.h`.
- Tracing: `docs/devel/tracing.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](https://github.com/processmission)
- **Source:** [processmission/oh-my-qemu](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-processmission-oh-my-qemu-qemu-peripheral-modeling
- Seller: https://agentstack.voostack.com/s/processmission
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.