Architecture

The design is split so that each piece can be checked on its own. The RTL is the hardware. A golden model written in Python is the specification. The WebAssembly module is the same hardware, seen from the browser.

Memory map

Region	Address	Size	Notes
IMEM	`0x0000_0000`	4 KiB	Loaded by the harness; read-only to the core.
DMEM	`0x0001_0000`	4 KiB	Byte-addressable: LB, LH, LW, SB, SH, SW.
CONSOLE	`0x0002_0000`	1 word	Writing a byte sends it to the console panel.
TOHOST	`0x0002_0004`	1 word	Writing 1 reports PASS and halts the core.
CYCLE	`0x0002_0008`	1 word	Reads the cycle counter.

Instruction and data memory are separate ports (a Harvard design), but they share one address space, so a program can read its own constants from DMEM.

Two cores, one instruction set

Single-cycle: fetch, decode, execute, memory and write-back in one cycle. It is the reference for what the program should do, and its cycle count is exactly its instruction count.
5-stage pipeline: IF, ID, EX, MEM and WB, with pipeline registers between them. It takes the same instructions and produces the same results, but may take more cycles, because of hazards.

Both cores are compiled into the same WebAssembly module, and the app chooses one at run time.

The golden model

The reference is an instruction-set simulator written in Python (sim/golden/iss.py). It executes every instruction and writes a retire record for each one: the program counter, the instruction, the register and memory it changed, and the next program counter. The RTL is checked by comparing its retire records to the model's, instruction by instruction.

Assembler in the browser

The app assembles RV32I source itself. Its output is byte-for-byte what the GNU RISC-V toolchain produces for the same source, which is tested against GNU's output.

The contract between hardware and browser

The WebAssembly module exposes the state of each cycle as a plain object: the five stages, the hazard flags, the registers, the retired instruction, console output and tohost. The field-by-field definition is in docs/STATE_SCHEMA.md, and the browser checks every state it receives against it.