VR16 CPU 🔗

08-04-2025

GitHub repository: link

Docs up-to-date with: 82f862f
Updated on: 20-03-2026.

This is a simple 16-bit RISC CPU built from scratch. This is the full-on documentation for the VR16 CPU (which is the name for it).

VR16 runs on it’s own instruction set called VR16-ISA.

This is not a RISC-V CPU, but a RISC one.

Specifications 🔗

The following mention the specifications of VR16:

• single-stage, multi-cycle cpu
• 16-bit cpu (this is the 2nd time I’ve mentioned that lol)
• has 4 general purpose registers (r0, r1, r2, r3)
• supports immediate values.
• supports conditional and unconditional branching.

Documentation Links 🔗

• Working

• Instruction Set

• Assembler

• Compiler

Setup 🔗

How to run this project on your local machine.

Python environment 🔗

This is required for assembler/compiler and the helper scripts. Tested with Python 3.10 to 3.12.

Create and activate a virtual environment from the repo root:

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

RTL simulation prerequisites 🔗

Install the simulator + waveform viewer:

• iverilog
• gtkwave

Then run:

$ ./compile.sh
$ ./sim.sh

Assembler/Compiler-only usage (no RTL simulation) 🔗

If you only want to use the toolchain (VRASM / VRScript), you only need the Python setup above (virtual environment + pip install -r requirements.txt). iverilog and gtkwave are not required unless you plan to run ./compile.sh / ./sim.sh.

Verification 🔗

Python testbench checks 🔗

Frontend Python testbench regressions live under src/frontend/tb/test_*.py and are expected to be run with pytest from the repository root:

$ pytest src/frontend/tb/test_*.py

RTL simulation checks 🔗

For RTL flow validation, run the simulation scripts in order:

$ ./compile.sh
$ ./sim.sh

Roadmap 🔗

• Finish basic RTL.
• Finish toolchain:
  • assembler (only have to implement pseudo instructions)
  • compiler
• Physical design to generate GDSII file for tapeout.

Misc. 🔗

The below list out all the dev-blogs I’ve written while developing this:

• RTL is complete! - Mar 20, 2026

• VR16 Update - Jul 02, 2025

• VR16 - ALU I HATE YOU!!!! - Apr 02, 2025

• VR16 Devblog 1 - Mar 28, 2025