Skip to content
STIMSMITH

Architectural State Comparison

Concept WIKI v1 · 6/6/2026

A verification technique used in processor design (notably XiangShan) where the architectural states of a Design Under Test (DUT) are continuously compared against those of a reference model (REF) during co-simulation, halting execution and reporting an error when a mismatch is detected.

Overview

Architectural state comparison is a core verification methodology employed in the XiangShan processor development flow. It involves continuously comparing the visible architectural state (registers, program counter, memory, and other ISA-level state) of a hardware design under test (DUT) against a trusted reference model (REF) as instructions are committed and state updates occur.

When any difference is detected between the two states, the simulation halts and reports the discrepancy; otherwise, simulation continues uninterrupted. This approach enables fast, automated detection of RTL bugs in out-of-order, superscalar processor designs.

Role in the XiangShan Verification Flow

In the XiangShan tutorial flow, architectural state comparison is enabled by two cooperating components:

  • NEMU (ISA Reference Simulator): Acts as the reference model (REF). NEMU exposes a set of APIs specifically intended to assist XiangShan in comparing and verifying architectural states. NEMU can be built in two configurations: a bare-metal execution mode for running workloads, and a riscv64-xs-ref_defconfig mode that serves as the reference for XiangShan.
  • Difftest (ISA Co-simulation Framework): Implements the actual comparison mechanism. Once the RTL processor commits an instruction or updates any other architectural state, the ISA simulator (NEMU) executes the same instruction. Difftest then compares the architectural states between the DUT and the REF.

Comparison Procedure

The basic flow of architectural state comparison is:

  1. The RTL DUT (e.g., the XiangShan processor model run via emu) commits an instruction or otherwise updates an architectural state.
  2. The paired ISA simulator (NEMU) executes the identical instruction.
  3. Difftest compares the resulting architectural states between the DUT and the REF.
  4. If a difference is observed, Difftest stops the simulation and reports the error. If the states match, simulation proceeds to the next event.

Demonstrated Usage

The tutorial demonstrates the technique by running the Coremark workload on XiangShan with NEMU as the reference:

  • A clean run (run-emu.sh) executes Coremark on XiangShan, co-simulating with NEMU and comparing architectural states throughout.
  • A buggy run (run-emu-diff.sh) executes a pre-built XiangShan variant in which a bug has been injected. Difftest detects the resulting architectural state mismatch and halts the simulation, typically trapping near a known cycle (e.g., cycle 12000 in the example).
  • Once a mismatch is caught, waveform dumping (run-emu-dumpwave.sh or run-emu-lightsss.sh) can be used to inspect the failing region in detail.

Debugging Aids Built on Top

Because comparison failures typically manifest many cycles after the original bug, several auxiliary tools are layered above architectural state comparison to aid root-cause analysis:

  • LightSSS (Light-weight Simulation Snapshot): Periodically records process snapshots via fork(). When Difftest reports a state mismatch, LightSSS resumes from the latest pre-failure snapshot and dumps a short waveform around the bug.
  • ChiselDB: A debug-friendly structured database that inserts probes between module interfaces and uses DPI-C from Chisel to record internal signals, complementing external architectural state comparison with internal observability.

Importance

Architectural state comparison provides a scalable, automated, and high-coverage way to validate that a complex, high-performance RTL implementation conforms to the ISA semantics embodied in a golden reference. By leveraging a fast interpreter (NEMU) and a dedicated co-simulation harness (Difftest), it makes verifying industrial-scale processors such as XiangShan tractable.

LINKED ENTITIES

1 links
DiffTest IMPLEMENTS

CITATIONS

4 sources
4 citations
[1] NEMU provides a set of APIs to assist XiangShan in comparing and verifying the architectural states. Function Verification (ASPLOS '25 XiangShan Tutorial)
[2] Difftest is an ISA co-simulation framework that compares the architectural states between DUT and REF, stopping and reporting an error on mismatch. Function Verification (ASPLOS '25 XiangShan Tutorial)
[3] Difftest is invoked during XiangShan execution by passing `--diff $NEMU_HOME/build/riscv64-nemu-interpreter-so` to the emulator, enabling on-the-fly architectural state comparison against the NEMU reference. Function Verification (ASPLOS '25 XiangShan Tutorial)
[4] In the buggy run, Difftest detects an architectural state mismatch, allowing subsequent waveform dumping from a known cycle window around the trap. Function Verification (ASPLOS '25 XiangShan Tutorial)