SimRV: Dual-Width Explainable RISC-V System Simulator

An explainable, dual-width (RV32 / RV64) RISC-V research simulator with an interactive terminal workbench (TUI), cycle-accurate in-order pipeline modeling, cache hierarchy inspection, and full-system Linux OS emulation.

---

Key Highlights

Explainable Dual-Width ArchitectureCycle-Accurate Pipeline TimingInteractive TUI WorkbenchFull-System Linux Emulation

SimRV provides compile-time fixed 32-bit and 64-bit simulator targets (RV32GCBV and RV64GCBV). It supports Base Integer (I/E), Multiply/Divide (M), Atomics (A), Single/Double Floating Point (F/D), Compressed (C), Bit Manipulation (B), and Vector 1.0 (V) extensions with Sv32/Sv39 virtual memory translation.

Features a cycle-accurate in-order pipeline execution kernel modeling instruction latency, data hazard stalls, forwarding paths, branch prediction (Bimodal, 2-level adaptive, RAS, and BTB), and multi-way L1 instruction and data cache hierarchies.

A rich terminal user interface (TUI) providing live split-screen inspection of integer, floating-point, and vector register banks, pipeline slots, cache set tags, hazard indicators, instruction decoding explainers, memory viewers, and guest terminal PTY interaction.

Boots un-modified RISC-V Linux kernels with OpenSBI/BBL, featuring a 16550A UART serial console, VirtIO block storage, CLINT timer interrupts, and PLIC interrupt controller routing.

---

Quickstart

1. Build from Source

SimRV requires a modern C++23 compiler (Clang 20+ or GCC 14+), CMake 3.20+, and Ninja.

RV64 Target (Default)RV32 Target

git clone https://github.com/archlab-sciencetokyo/SimRV.git
cd SimRV

# Configure and build RV64 release target
cmake --preset rv64-release
cmake --build --preset rv64-release -j$(nproc)

git clone https://github.com/archlab-sciencetokyo/SimRV.git
cd SimRV

# Configure and build RV32 release target
cmake --preset rv32-release
cmake --build --preset rv32-release -j$(nproc)

2. Run Your First Workload

Interactive TUI Mode (Default)Headless Fast CLI ExecutionCycle-Accurate SimulationFull-System Linux Boot

# Launch interactive terminal workbench with a baremetal binary
./build/rv64-release/SimRV -b -m img/hello.bin

# Fast functional execution without TUI
./build/rv64-release/SimRV -b -m img/hello.bin --cli

# Run in cycle-accurate mode with step limit
./build/rv64-release/SimRV -b -m img/hello.bin --ca --cli -s 1000000

# Boot Linux kernel with root filesystem and devicetree
./build/rv64-release/SimRV --os \
  -m linux-images/rv64/fw_payload.bin \
  -D linux-images/rv64/root.bin \
  -f linux-images/rv64/devicetree.dtb

---

Documentation

• User Guide

  ---

  Quickstart, CLI flags, interactive TUI controls, hotkeys, and execution modes.

• Architecture & Compliance

  ---

  Core execution units, pipeline modeling, cache hierarchy, MMU, and ISA compliance scope.

• Bare-Metal & Linux

  ---

  Bare-metal development, memory map, peripheral MMIO, and booting full-system Linux.

• Development & Verification

  ---

  Contributing standards, CTest gate suites, reviewer reproduction guide, and release qualification.

---

Citation

If you use SimRV in your academic research, please cite:

@software{simrv,
  title = {{SimRV: A Dual-Width Explainable RISC-V System Simulator}},
  author = {{SimRV Contributors}},
  url = {https://github.com/archlab-sciencetokyo/SimRV},
  version = {2.0.2},
  year = {2026}
}