rvsim 0.11.0

High-performance RISC-V cycle-accurate system simulator

rvsim

A cycle-accurate RISC-V 64-bit system simulator (RV64IMAFDC) written in Rust with Python bindings. Features a 10-stage superscalar pipeline, multi-level cache hierarchy, branch prediction, and virtual memory. Can boot Linux (experimental).

Pipeline

10-stage in-order pipeline with configurable superscalar width:

Fetch1 → Fetch2 → Decode → Rename → Issue → Execute → Memory1 → Memory2 → Writeback → Commit

• Superscalar: configurable width (1, 2, 4+)
• Reorder buffer for in-order commit with tag-based register scoreboard
• Store buffer with store-to-load forwarding
• Branch prediction: Static, GShare, Tournament, Perceptron, TAGE

Memory System

• MMU: SV39 virtual addressing with separate iTLB and dTLB
• Cache hierarchy: configurable L1i, L1d, L2, L3 with LRU/PLRU/FIFO/Random replacement
• Prefetchers: next-line, stride, stream, tagged
• DRAM controller: row-buffer aware timing (CAS/RAS/precharge)

ISA Support

RV64IMAFDC — base integer, multiply/divide, atomics, single/double float, compressed instructions. Privileged ISA with M/S/U modes, traps, CSRs, and CLINT timer.

Quick Start

Install:

pip install rvsim

Run a program:

from rvsim import Config, Environment

result = Environment(binary="software/bin/programs/mandelbrot.bin").run()
print(result.stats.query("ipc|branch"))

From the command line:

make build
rvsim -f software/bin/programs/qsort.bin

Python API

from rvsim import Config, Cache, BranchPredictor, Environment, Stats

config = Config(
    width=4,
    branch_predictor=BranchPredictor.TAGE(),
    l1d=Cache("64KB", ways=8),
    l2=Cache("512KB", ways=16, latency=10),
)

result = Environment(binary="software/bin/programs/qsort.bin", config=config).run()

# Query specific stats
print(result.stats.query("branch"))
print(result.stats.query("miss"))

# Compare configurations
rows = {}
for w in [1, 2, 4]:
    cfg = Config(width=w, uart_quiet=True)
    r = Environment(binary="software/bin/programs/qsort.bin", config=cfg).run()
    rows[f"w{w}"] = r.stats.query("ipc|cycles")
print(Stats.tabulate(rows, title="Width Scaling"))

Analysis Scripts

Modular scripts for design-space exploration in scripts/analysis/:

Script	Purpose
width_scaling.py	IPC vs pipeline width
branch_predict.py	Compare branch predictor accuracy
cache_sweep.py	L1 D-cache size vs miss rate
inst_mix.py	Instruction class breakdown
stall_breakdown.py	Memory/control/data stall cycles

rvsim scripts/analysis/width_scaling.py --bp TAGE --widths 1 2 4
rvsim scripts/analysis/branch_predict.py --width 2 --programs maze qsort
rvsim scripts/analysis/cache_sweep.py --sizes 4KB 16KB 64KB

Machine model benchmarks in scripts/benchmarks/:

rvsim scripts/benchmarks/p550/run.py
rvsim scripts/benchmarks/m1/run.py
rvsim scripts/benchmarks/tests/compare_p550_m1.py

Project Structure

rvsim/
├── crates/
│   ├── hardware/        # Simulator core (Rust)
│   │   └── src/
│   │       ├── core/    # CPU, pipeline, execution units
│   │       ├── isa/     # RV64IMAFDC decode and execution
│   │       ├── sim/     # Simulator driver, binary loader
│   │       └── soc/     # Bus, UART, PLIC, VirtIO, CLINT
│   └── bindings/        # Python bindings (PyO3)
├── rvsim/               # Python package
├── examples/
│   ├── programs/        # C and assembly source
│   └── benchmarks/      # Microbenchmarks and synthetic workloads
├── software/
│   ├── libc/            # Custom minimal C standard library
│   └── linux/           # Linux boot configuration
├── scripts/
│   ├── analysis/        # Design-space exploration scripts
│   ├── benchmarks/      # Machine model configs (P550, M1)
│   └── setup/           # Linux build helpers
└── docs/                # Architecture and API documentation

Build from Source

Requirements:

• Rust (2024 edition)
• Python 3.10+ with maturin
• riscv64-unknown-elf-gcc cross-compiler (for building example programs)

make build          # Build Python bindings (editable)
make software       # Build libc and example programs
make test           # Run Rust tests
make lint           # Format check + clippy
make clean          # Remove all build artifacts

Linux Boot (Experimental)

The simulator can boot Linux through OpenSBI. Full boot is still in progress.

make linux          # Download and build Linux via Buildroot
make run-linux      # Boot Linux

License

Licensed under either of MIT or Apache-2.0, at your option.