# Phase 8.5 - riscv-tests Compliance

## Context

Official instruction tests catch ISA bugs that ad hoc tests miss. Run them before adding
trap, interrupt, and privilege complexity.

## Goals

- Build and run `rv32ui-p-*` and `rv32um-p-*`.
- Create a simulation harness that loads test programs.
- Establish regression coverage for later phases.

## New Concepts

- Compliance test: focused program checking architectural behavior.
- Harness: wrapper that provides memory, stop condition, and pass/fail reporting.
- Signature region: memory region where tests record results.
- Regression: test suite run repeatedly to catch breakage.

## How To Think About It

Do not treat compliance tests as optional polish. They are how you avoid stacking new
features on top of unknown ISA bugs.

## Learning Tasks

- Understand how a riscv-test indicates pass/fail.
- Learn how ELF sections map into your BRAM model.
- Categorize failures by decode, execute, memory, or control-flow likely cause.

## Pitfalls

- Running tests with the wrong ISA target.
- Assuming the test harness memory layout matches your hardware automatically.
- Ignoring one failing test because normal firmware seems to work.

## Tooling And Testing

- Automate running all tests once the harness exists.
- Keep failing waveforms short and reproducible.
- Re-run the suite after every meaningful datapath change.

## References

- riscv-tests repository: https://github.com/riscv-software-src/riscv-tests
- RISC-V architectural tests: https://github.com/riscv-non-isa/riscv-arch-test
- RISC-V unprivileged ISA: https://riscv.org/technical/specifications/