| name | machina-qemu-oracle |
| description | Use when comparing Machina behavior with QEMU, using difftest/oracle tooling, or debugging CPU, interrupt, memory, or device-model parity. |
| license | MIT |
Machina QEMU Oracle
Use QEMU as a reference when behavior should match established machine or
device semantics.
Starting Points
- Read
tests/src/oracle.rs for the oracle contract.
- Search
tests/src/ for existing hardware regression tests.
- Check
tools/oracle/ and tools/difftest/ before adding new tooling.
- Use
docs/en/reference.md for test architecture notes.
Workflow
- Reproduce the Machina behavior with the narrowest existing test or command.
- Run the comparable QEMU oracle path when available.
- Capture access width, address, value, IRQ line, CPU id, and reset state.
- Add or update a centralized test in
tests/ before changing behavior.
- Keep device fixes local to the owning
hw/ crate unless a shared contract
is wrong.
Common Parity Areas
- RISC-V PLIC, ACLINT, APLIC, and IPI interrupt behavior.
- LoongArch IOCSR, EIOINTC, IPI, and PCH-PIC behavior.
- MMIO access widths and read/write side effects.
- Reset ordering and multi-CPU delivery.
Rules
- Do not paper over a mismatch by weakening oracle assertions.
- Preserve exact QEMU observations in test names, comments, or failure output.
- Treat missing QEMU or tool dependencies as a skip only when the existing test
harness already models that skip contract.
