Skip to content
todorwPublic

About

A small 16-bit, 5-stage pipelined RISC CPU in Verilog, with its own instruction set, assembler, and Python architectural simulator.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

62 Commits

Folders and files

Repository files navigation

Ferrum-R1600

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).

License HDL

Status

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.

What's here

  • 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.

Project structure

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

Quick start

# 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.

Example: what the ISA looks like

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
    HALT

See tools/bootloader.asm for a larger example covering subroutine calls with proper LR save/restore, UART TX/RX, and both interrupt sources.

License

MIT - see LICENSE.

Contact

Vuk Todorovic - [email protected]

About

A small 16-bit, 5-stage pipelined RISC CPU in Verilog, with its own instruction set, assembler, and Python architectural simulator.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages