riscv-5i

A 5-stage pipelined RISC-V core (RV32I) written in SystemVerilog, verified against the RISCOF compliance suite, and running on a Xilinx Zynq-7000 FPGA.

Running a Fibonacci program on the PYNQ-Z2; LEDs wrap mod 16.

What this is

The classic Patterson & Hennessy 5-stage pipeline (IF, ID, EX, MEM, WB), with full forwarding, load-use stalling, and early branch resolution for JAL. Passes all 482 RISCOF RV32I compliance tests against Spike. Synthesizes on a PYNQ-Z2 at 10 MHz with positive slack, using 1972 LUTs (3.7% of the Zynq-7000) and 3326 flip-flops. The full design fits comfortably with room to spare for caches or peripherals.

What's not there

I scoped this to RV32I and stopped. No M extension (no hardware multiply or divide), no CSRs (SYSTEM and FENCE decode as NOPs), no caches, no exception or interrupt handling. Memory is a single flat region with a memory-mapped LED register at 0x8000_0000 and a tohost test-completion address at 0x8000_1000.

Documentation

Full documentation site

• Architecture overview: datapath, pipeline diagram, design tradeoffs
• Pipeline stages: per-stage RTL with explanations
• Hazards & forwarding: timing diagrams for every hazard case
• Verification: RISCOF results and a bring-up postmortem
• FPGA: synthesis numbers, timing closure, hardware demo
• Setup: toolchain install and build instructions

Quick start

# Install dependencies (Ubuntu/Fedora)
sudo apt-get install -y iverilog gtkwave python3-pip git gcc-riscv64-unknown-elf
pip3 install riscof

# Clone and bootstrap
git clone https://github.com/cshieldsce/riscv-5i.git
cd riscv-5i
./setup_project.sh

# Run the compliance suite
./test/verification/run_compliance.sh

Full setup instructions: Setup page.

Project layout

riscv-5i/
├── src/                  # SystemVerilog RTL
│   ├── pipelined_cpu.sv  # top-level CPU
│   ├── if_stage.sv       # IF, ID, EX, MEM, WB modules
│   ├── id_stage.sv
│   ├── ex_stage.sv
│   ├── mem_stage.sv
│   ├── wb_stage.sv
│   ├── control_unit.sv   # instruction decoder
│   ├── hazard_unit.sv    # stall / flush logic
│   ├── forwarding_unit.sv
│   └── pynq_z2_top.sv    # board top-level
├── test/
│   ├── verification/     # RISCOF compliance plugins + runner
│   ├── tb/               # SystemVerilog testbenches
│   ├── mem/              # .mem hex images for tests
│   └── scripts/          # lint + regression
├── fpga/                 # Vivado project scripts + XDC
└── docs/                 # Jekyll source for the docs site

References

• RISC-V Unprivileged ISA Specification (v20191213)
• Patterson & Hennessy, Computer Organization and Design: The Hardware/Software Interface (RISC-V Edition), chapter 4
• RISC-V Architectural Test Suite

License

MIT: see LICENSE.