A small 16-bit, 5-stage pipelined RISC CPU in Verilog, with its own instruction set, assembler, and a Python architectural simulator, plus a handful of MMIO peripherals (UART, VGA text mode, GPIO, a timer).
This project went through a full pass of finding and fixing real bugs -
the RTL and the toolchain were rewritten enough that this is closer to a
clean-room v2 of the ISA than a patch. All of it was validated by
assembling and running programs (tools/bootloader.asm,
tools/fibonacci.asm) end to end through tools/ferrum_sim.py, and by a
regression suite (tools/run_tests.py / make selftest) covering the
specific bugs that got fixed.
make sim now actually runs the RTL pipeline through iverilog, and
doing so found several real bugs the ISA simulator and manual trace both
missed - a fetch-stage PC mistagging bug, hazard-interlock false positives
and misses, a permanent deadlock on the first load/store, phantom
execution of HALT/EI/DI/RETI from an about-to-be-flushed
instruction, a corrupted interrupt return address, and an SoC address
decode bug that left every MMIO peripheral (UART, VGA, GPIO, Timer)
completely unreachable from software. All are fixed; make sim /
make test pass, and fibonacci.asm's loop and a timer interrupt
round-trip have both been run directly against the RTL, not just the ISA
simulator. Still unverified: nothing has been run through verilator
(only iverilog), and no FPGA bitstream has been built or tested against
real hardware. See DOCUMENTATION.md's
Known Limitations for the full,
honest list.
- 5-stage pipelined CPU core (IF/ID/EX/MEM/WB), no forwarding network - a hazard interlock stalls fetch/decode until a dependency's write-back has actually completed. Correct over fast, deliberately.
- 16 general-purpose registers, R0 hardwired to zero.
- 64KB address space: 16KB IMEM, 16KB DMEM, 16KB external memory (via pins), 16KB MMIO.
- UART, VGA (text mode), GPIO, and a timer, all memory-mapped, with a small interrupt controller (UART RX + timer compare-match).
- An assembler (
tools/ferrum_assembler.py) with range-checked immediates and clear errors instead of silent truncation. - An architectural simulator (
tools/ferrum_sim.py) for running programs without a Verilog toolchain. - A regression suite (
tools/run_tests.py) covering the ISA semantics and both example programs.
Full architecture, the complete ISA encoding, memory map, and peripheral register reference live in DOCUMENTATION.md.
rtl/
ferrum_r1600_core.v CPU core: pipeline, ALU, hazard interlock, interrupts
ferrum_memory_controller.v IMEM/DMEM/ext-mem/MMIO address decode
ferrum_uart.v UART (TX/RX, configurable baud)
ferrum_vga.v 640x480 text-mode/graphics VGA controller
ferrum_timer.v Free-running timer with compare-match interrupt
ferrum_r1600_soc.v Top-level SoC integration + interrupt controller
tools/
ferrum_assembler.py Assembler (.asm -> .hex / .bin / .mem)
ferrum_sim.py Architectural ISA simulator
run_tests.py Regression suite (uses the simulator)
ferrum_font_gen.py Generates the VGA character ROM's glyph table
bootloader.asm Boot banner + interrupt-driven UART echo / GPIO blink
fibonacci.asm Loop/arithmetic/memory example
testbench/
ferrum_r1600_tb.v Icarus Verilog testbench
synthesis/
ferrum_r1600_constraints.xdc Xilinx XDC constraints (untested against real hardware)
DOCUMENTATION.md Architecture, ISA reference, build/run guide
# Assemble the example programs
make asm
# Run a program through the architectural simulator
python3 tools/ferrum_sim.py tools/fibonacci.asm --dump-regs
python3 tools/ferrum_sim.py tools/bootloader.asm --rx "hi" --dump-regs
# Run the regression suite (no Verilog toolchain required)
make selftest
# Run the RTL testbench (requires Icarus Verilog)
make sim
make wave # view the waveform (requires gtkwave)make help lists every target.
From tools/fibonacci.asm - no immediate-ALU ops, so a shift amount or a
16-bit constant gets built into a register first:
LDI R8, 8
LDI R5, 0x40
SHL R5, R5, R8 ; R5 = 0x4000, the DMEM base
LDI R1, 0 ; fib(0)
LDI R2, 1 ; fib(1)
fib_loop:
ADD R4, R1, R2 ; next = a + b
ST R4, [R5+0]
ADD R5, R5, R6 ; pointer += 2 (R6 set to 2 earlier)
ADD R1, R2, R0 ; a = b
ADD R2, R4, R0 ; b = next
SUB R9, R9, R7 ; remaining -= 1 (R7 set to 1 earlier)
BNE R9, R0, fib_loop
HALTSee tools/bootloader.asm for a larger example covering subroutine
calls with proper LR save/restore, UART TX/RX, and both interrupt
sources.
MIT - see LICENSE.
Vuk Todorovic - [email protected]