FPGA-Core/ROADMAP.md

# RV32IM CPU Core — Build Roadmap
## Target: Digilent Arty A7 100T / Vivado 2025.2+ / SystemVerilog
## Clock: 50 MHz (100 MHz xtal ÷ 2 via MMCM)
## End goal: Boot Linux on a custom RISC-V core

---

## Memory Map (target — fixed in Phase 0, evolves through Phase 13)

```
0x0000_0000 – 0x0FFF_FFFF   reserved (SPI flash boot region, Phase 13)
0x1000_0000 – 0x1000_0FFF   MMIO (UART; later: timer, PLIC)
0x2000_0000 – 0x2000_FFFF   instruction BRAM (64 KB)
0x8000_0000 – 0x8000_FFFF   data BRAM (64 KB) → DRAM 0x8000_0000–0x8FFF_FFFF in Phase 13
```

Reset PC = `0x2000_0000`. Locking this in now keeps the linker script and crt0
stable across phases.

---

## Phase 0 — Architecture Contract

### 0.1 — SystemVerilog Package
What: Create a `.sv` package file with enums (ALU operations, opcode types, branch
types) and structs (fetch_out_t, decode_out_t, exec_out_t, mem_out_t) that define
the signals passed between pipeline stages.

Why: This is the "API" of your CPU. Every module you build will import this package.
If you get the struct definitions reasonable now, adding new instructions later means
adding a field to a struct — not re-plumbing wires across the whole design.

Future role: These structs stay forever. When you pipeline the core, the pipeline
registers are literally just these structs stored in flip-flops. When you add CSR
instructions, you add a field to decode_out_t. The package grows but never gets
replaced.

### 0.2 — Block Diagram (on paper)
What: Draw the major blocks (fetch, decode, ALU, register file, memory, writeback)
and the signals between them. Label signals with the struct names from 0.1.

Why: You need a physical reference to look at while coding. Screen diagrams get
buried in tabs. Paper on a wall stays visible.

Future role: You'll update this as the design grows. It becomes your architectural
source of truth when things get complex.

---

## Phase 1 — ALU + M Unit

### 1.1 — Combinational ALU + Simulation
What: Build a combinational ALU that handles all RV32I arithmetic/logic ops
(add, sub, and, or, xor, slt, sltu, shifts). Inputs: two 32-bit operands +
operation select from your enum. Outputs: 32-bit result.

Why: The ALU is the computational heart. Building it first gives you a
self-contained module to practice your testbench workflow.

Testbench focus: signed vs unsigned comparisons (SLT vs SLTU), arithmetic shift
right vs logical shift right, signed overflow.

Future role: This module is final. It goes into the finished core unchanged.

### 1.2 — Multi-cycle M Unit + Simulation
What: A separate module for the M extension (mul, mulh, mulhsu, mulhu, div,
divu, rem, remu) with a `start` / `busy` / `done` handshake. Multiply uses
DSP48s and completes in 2-3 cycles; divide is iterative (one bit per cycle,
~33 cycles for 32-bit). Outputs a 32-bit result on `done`.

Why M extension early: GCC emits mul/div constantly; without hardware, libgcc
emulation is slow and painful. Why a separate module: a 32-bit combinational
divider will not meet timing on Artix-7 at any reasonable Fmax — divide must
be iterative. Baking the stall handshake in from day one means the datapath
(Phase 4) is built around it from the start, not retrofitted.

Testbench focus: division by zero (RISC-V spec gives specific results, not an
exception — `div(x,0) = -1`, `rem(x,0) = x`), signed overflow on division
(`INT_MIN / -1` returns `INT_MIN`), `mulh*` upper-half results, back-to-back
operations without dropping `busy`.

Future role: Final. The handshake interface is reused unchanged when the core
is pipelined.

### 1.3 — ALU + M Unit on FPGA with VIO
What: Synthesize both on the Arty. Attach Vivado VIO cores to inputs, outputs,
and the M unit handshake. Use the Vivado hardware manager to drive operands
and read results.

Why: Confirms behavior in real hardware and catches synthesis issues early
(timing on the multiply path, divide unit FSM state encoding). Also gets you
comfortable with the VIO workflow.

What is VIO: A Vivado IP that lets you poke values into signals and read them
out through JTAG, right from the Vivado GUI. Think virtual switches and LEDs
with 32-bit width and no board wiring.

Future role: VIO familiarity pays off throughout the project.

---

## Phase 2 — Register File

### 2.1 — Register File Module + Simulation
What: Build the RISC-V register file — 32 registers, each 32 bits wide. Two read
ports (rs1, rs2), one write port (rd). Register x0 is hardwired to zero (writes to
it are ignored, reads always return 0).

Why: Every instruction reads from and/or writes to registers. This is the second
fundamental building block after the ALU. It's simple (it's basically a small RAM
with some special behavior on address 0) but getting the read/write timing right
matters.

Testbench focus: read-after-write in the same cycle (does the new value forward?),
write to x0 then read x0 (must be zero), read two different registers simultaneously.

Future role: This module is final. Might eventually get a third read port if you add
certain extensions, but for RV32IM it's done.

### 2.2 — Optional: VIO validation
What: Put it on FPGA with VIO if you want extra confidence. Usually sim is enough
for a register file since the logic is simple.

---

## Phase 3 — Decoder

### 3.1 — Instruction Decoder + Simulation
What: A combinational module that takes a raw 32-bit instruction word and produces
your decode_out_t struct: ALU operation, source/destination register addresses,
immediate value (sign-extended), memory read/write flags, branch type, etc.

Why: The decoder is the "brain" that tells every other module what to do. RISC-V has
six instruction formats (R, I, S, B, U, J) and the immediate bits are scattered
differently in each. Getting the immediate extraction and sign extension right is the
main challenge.

How to test: Use the RISC-V toolchain as your reference. Write small assembly
snippets, assemble them with `riscv64-unknown-elf-as`, then `objdump -d` to get the
binary encoding. Feed those encodings to your testbench and verify every output field.
This also gets you familiar with the cross-compilation toolchain you'll need later.

Testbench focus: Every instruction format. Pay special attention to immediate sign
extension (bit 31 of the instruction is always the sign bit in RISC-V — that's a
deliberate design choice). Verify that the decoder handles all R-type, I-type, S-type,
B-type, U-type, and J-type correctly.

Future role: When you add CSR instructions (Phase 9), you'll add a new case to the
decoder and a new field to the struct. The structure of the decoder doesn't change.

---

## Phase 4 — First CPU ("It's Alive")

### 4.1 — Fetch + Datapath Integration
What: Create an instruction BRAM initialized from a .mem file, mapped at
`0x2000_0000`. Add a PC register that resets to `0x2000_0000` and advances
by 4 when the next instruction is ready. Wire the chain:
BRAM[PC] → decoder → ALU/M unit → register file writeback. Support R-type and
I-type arithmetic for now (add, sub, addi, and, or, xor, slt, slti, lui,
auipc, shifts), plus the M-extension ops via the M unit's handshake.

Why: This is the first time all your modules work together as a CPU. It can't
branch, it can't access data memory, but it executes a sequence of arithmetic
instructions correctly. The wiring is where most bugs live — wrong bit ranges,
swapped operands, forgetting to connect a signal.

Important — "single-cycle" is a logical model: BRAM has a 1-cycle read
latency, so fetch is registered (PC → address one cycle, instruction available
the next). Each instruction takes 2 cycles end-to-end at minimum, and stalls
extend that whenever the M unit is busy. Plan the control FSM around this:
states like FETCH → EXECUTE, with a stall in EXECUTE while `m_busy` is high.

How to test: Hand-assemble 10-20 instructions into a .mem file. Calculate the
expected register state after each instruction by hand. Compare against what
the CPU actually produces.

What is a .mem file: A text file with hex values, one per line. Vivado can
initialize BRAMs from these. Each line is one 32-bit instruction.

Future role: This is your core. Everything from here on adds capabilities to it.

### 4.2 — ILA Verification on FPGA
What: Synthesize the CPU on the Arty. Attach ILA (Integrated Logic Analyzer) probes
to the PC, register write port, and ALU output. Set a trigger (e.g., when PC reaches
the last instruction). Inspect the captured waveform.

Why: Confirms hardware behavior matches simulation. Gets you comfortable with ILA,
which becomes your primary debugging tool for all future phases.

What is ILA: A Vivado IP that captures signal values over time into on-chip memory,
like an oscilloscope for internal FPGA signals. You set trigger conditions and view
waveforms in the Vivado hardware manager.

Future role: You'll drop ILA probes on different signals throughout the project.
Knowing how to use it well is arguably the most important FPGA debug skill.

---

## Phase 5 — Branches and Jumps (Control Flow)

### 5.1 — Branch Instructions
What: Add a branch comparator (separate from the ALU — it checks rs1 vs rs2 for
equality, less-than, etc.) and a mux that selects between PC+4 and the branch target.
Implement all B-type branches: beq, bne, blt, bge, bltu, bgeu.

Why: Without branches, the CPU can only run straight-line code. Branches give
you loops and conditionals — the core of any real program. Keeping the branch
comparator separate from the ALU is mostly a clarity choice: branches and
arithmetic have different semantics, and the comparator is small. (Whether you
resolve branches in decode or execute when you pipeline later is a separate
trade-off involving forwarding paths — don't lock that decision in now.)

Test: A loop that increments a register from 0 to 10, then falls through. Verify with
ILA that the branch is taken exactly 10 times and the final register value is 10.

Future role: When you pipeline, branch handling becomes the source of pipeline hazards
and you'll add branch prediction. But the comparator logic stays.

### 5.2 — Jump Instructions (jal, jalr)
What: Add jal (jump and link — PC-relative) and jalr (jump and link register —
absolute). Both store PC+4 into the destination register before jumping.

Why: jal/jalr are how RISC-V implements function calls and returns. `jal` calls a
function, `jalr` returns from it (by jumping to the address saved in the link
register). Without these, you can't have functions — and C is nothing but functions.

Test: Write a call/return sequence. Main calls a subroutine via jal, subroutine does
some work, returns via jalr. Verify the return address is correct and execution
resumes in the right place.

Future role: Final. These instructions don't change.

---

## Phase 6 — Load/Store (Data Memory)

### 6.1 — Word Load/Store (lw, sw)
What: Add a data BRAM mapped at `0x8000_0000` (64 KB) and a load/store unit.
For now, only 32-bit aligned access (lw and sw). Define a simple memory bus
interface with address, write data, read data, write enable, and valid/ready
signals.

Note: BRAM is 1-cycle read latency, so a load takes one extra cycle beyond
the EXECUTE state. The control FSM extends to FETCH → EXECUTE → MEM_WAIT →
WRITEBACK for loads. This is exactly why valid/ready is in the bus from
day one.

Why: A CPU without data memory can only work with 32 values (the registers). Load/
store connects the CPU to the outside world. Starting with word-only access keeps the
byte-lane logic simple while you verify the memory path works.

Why valid/ready now: BRAM responds in one cycle, so ready is always high. But when
you swap in DRAM later, responses take many cycles. If your interface already has
valid/ready handshaking, the swap is painless. If you hardwire it now, you'll have
to redesign the memory path later. Five minutes of future-proofing saves a weekend
of rework.

Test: Store values to various addresses, load them back, verify they match.

Future role: The bus interface is the foundation for your entire memory map (BRAM,
DRAM, UART, timer, interrupt controller — all hang off this bus).

### 6.2 — Byte and Halfword Access (lb, lbu, lh, lhu, sb, sh)
What: Add byte and halfword loads (signed and unsigned) and stores. This means byte
lane selection (which byte within a 32-bit word) and sign extension (lb sign-extends
to 32 bits, lbu zero-extends).

Why: C uses char (byte) and short (halfword) types constantly. String operations are
byte-by-byte. You can't run real C code without these.

Testbench focus: Sign extension (loading 0xFF as signed byte should give 0xFFFFFFFF,
as unsigned should give 0x000000FF). Unaligned access behavior (RISC-V base spec says
misaligned access can trap — decide if you want to support it or trap).

Future role: Final. These instructions don't change.

### 6.3 — ILA on the Memory Bus
What: Attach ILA to the memory bus signals. Run a program that computes Fibonacci
numbers and stores them into a data array. Verify the memory contents.

Why: Memory bugs are subtle (off-by-one addresses, wrong byte lane, sign extension
errors). ILA on the bus lets you see exactly what's happening each cycle.

---

## Phase 7 — Memory-Mapped UART

### 7.1 — UART TX Module
What: A standalone UART transmitter. Baud rate 115200, 8 data bits, no parity,
1 stop bit (8N1). At 50 MHz the baud divisor is `50_000_000 / 115_200 ≈ 434`
clocks per bit. Interface: input byte, send signal, busy flag.

Why: This is your CPU's mouth. Once connected, the CPU can print to a serial terminal.
This replaces ILA as your primary debug tool for software — you can printf-debug your
C programs.

Test standalone: Wrap it in a tiny FSM that sends "hello\n" on reset. Synthesize,
connect to your terminal at 115200 baud. If you want, verify the waveform on your
scope — you'll see actual start bits, data bits, stop bits on the TX pin.

Future role: This exact module gets memory-mapped in 7.3 and eventually becomes the
console for your BIOS and Linux.

### 7.2 — UART RX Module
What: A standalone UART receiver. Same 8N1 format. Oversamples the input (typically
16x baud rate) to find bit centers. Outputs received byte + valid flag.

Why: This is your CPU's ear. Needed for any interactive console — typing commands,
sending data to the board.

Test: Send bytes from your terminal, verify they appear correctly. If you want to be
extra thorough, use your Eclypse + DAC zmod to generate serial waveforms with
deliberate timing skew and verify the receiver handles it.

Future role: Same as TX — becomes the console UART.

### 7.3 — Bus Decoder + Memory-Mapped I/O
What: Add an address decoder to your memory bus. Routing:

```
0x2000_0000 – 0x2000_FFFF   instruction BRAM
0x8000_0000 – 0x8000_FFFF   data BRAM
0x1000_0000                 UART TX data    (W: byte to send)
0x1000_0004                 UART RX data    (R: pops one byte from RX FIFO)
0x1000_0008                 UART status     (R: bit0 = tx_busy, bit1 = rx_valid)
```

Note this is a split register layout (separate TX/RX/status addresses), not
a 16550-style shared data register. Cleaner for a learning core; can be
reshaped later if you want a 16550-compatible model.

Why: Memory-mapped I/O is how CPUs talk to peripherals in the real world. The
CPU doesn't know it's talking to a UART — it just does a store to an address,
and the bus decoder routes it to the right place. This is the same pattern
used by every SoC ever.

Test: Write a program that stores ASCII bytes to `0x1000_0000` in a loop,
polling `0x1000_0008` bit 0 between writes. See the message in your terminal.
This is the most important milestone in the project — your CPU is now a
computer that communicates with the outside world through software.

Future role: The bus decoder grows as you add peripherals (timer, PLIC, DRAM)
but the structure stays. UART mapping stays at these addresses.

### 7.4 — "Hello World" (Hand-Assembled)
What: Hand-write an assembly program that prints "hello from rv32" to the UART
address (`0x1000_0000`), polling status bit 0 to wait for `tx_busy` to clear.
Assemble it, load into BRAM, run.

Why: Pure emotional milestone. Your CPU, your UART, your program, your message on
screen.

---

## Phase 8 — GCC Toolchain Integration

### 8.1 — Linker Script + Startup Code
What: Write a linker script that tells GCC where your instruction memory, data
memory, and stack live. Anchor `.text`/`.rodata` at `0x2000_0000`,
`.data`/`.bss` at `0x8000_0000`, stack growing down from the top of data BRAM
(`0x8001_0000`). Write crt0.S (C runtime startup): set the stack pointer,
zero out the BSS section (uninitialized global variables), call main.

Why: GCC doesn't just compile C to instructions — it expects a runtime environment.
The linker script defines the memory layout, and crt0 sets up the minimal environment
that C code assumes exists (a stack, zeroed globals).

Future role: The linker script evolves as your memory map grows (adding DRAM, flash).
crt0 grows when you add CSRs (setting up trap vectors in startup).

### 8.2 — First GCC Program
What: Write a trivial main() that prints a string to the UART by writing bytes
to `0x1000_0000`. Compile with:
```
riscv64-unknown-elf-gcc -march=rv32im_zicsr_zifencei -mabi=ilp32 \
    -nostdlib -T linker.ld -o firmware.elf crt0.S main.c
```
Convert: `objcopy -O binary firmware.elf firmware.bin`. Convert binary to
`.mem` format. Load into BRAM. Run.

Why the long march string: GCC 11+ split `Zicsr` and `Zifencei` out of the
RV32I base. `-march=rv32im` alone fails or warns. `Zifencei` is harmless
(`fence.i` is a NOP until you have caches); `Zicsr` will only be emitted by
code that uses CSR ops, so it's safe to advertise even before Phase 9.

Why: This proves your CPU is compatible with a real compiler. Any bugs in your
instruction implementation will surface here — GCC will use instructions in
combinations you never thought to hand-test.

Expect to iterate: GCC will probably emit an instruction you haven't implemented yet.
That's fine — check the illegal instruction, add it, resynthesize. This is normal.

### 8.3 — Fill Remaining RV32I Gaps
What: Implement any RV32I instructions you deferred. Common ones: all shift variants
(sll, srl, sra, slli, srli, srai), set-less-than variants (slti, sltiu), fence (NOP
for now — you have no cache), ecall/ebreak (NOP for now — you have no trap handling).

Why: GCC's output will exercise the full ISA. You need complete RV32I coverage for
any non-trivial C code to work.

Test: Compile progressively more complex C programs. String manipulation, struct
usage, switch statements (these generate jump tables — exercises jalr with computed
addresses), recursive functions.

### 8.4 — Milestone: Meaningful C Program
What: Write something real — a serial monitor that accepts commands over UART
and responds. Or a tiny Forth interpreter. Something interactive that proves
the core is solid.

Why: Confidence builder. You now have a working RISC-V computer that runs
compiled C and talks over serial. Everything after this is enrichment.

### 8.5 — riscv-tests Compliance
What: Clone `riscv-software-src/riscv-tests`. Build the `rv32ui-p-*` and
`rv32um-p-*` tests (the "p" variant assumes physical addressing, no virtual
memory — perfect for this stage). Each test is a tiny program that exercises
one or more instructions and writes a pass/fail code to a known address.
Write a small testbench harness that loads each test ELF into instruction
BRAM, runs the core until the test signals completion, and reports pass/fail.

Why: Hand-written testbenches catch the bugs you thought to look for. The
official suite catches the ones you didn't — corner cases in shifts, sign
extension on byte loads, immediate decoding for every format, M-extension
overflow cases. Doing this *before* Phase 9 means you're building trap
handling on a known-good ISA implementation, not stacking unknowns.

Expect to find bugs. That's the point. Fix each one, re-run the suite, move
on when rv32ui and rv32um pass clean.

Future role: Re-run the suite after every meaningful change to the core. It
becomes regression coverage for the rest of the project.

---

## Phase 9 — CSRs + M-Mode Trap Handling

What: Add Control and Status Registers (mstatus, mtvec, mepc, mcause, mtval, mie,
mip) and the CSR instructions (csrrw, csrrs, csrrc, csrrwi, csrrsi, csrrci). Add
mret (return from trap). Implement the trap entry mechanism: on an exception or
interrupt, save PC to mepc, jump to mtvec, set mcause.

Why: Traps and interrupts are how the CPU handles errors (illegal instruction, bad
memory access) and hardware events (timer fired, UART received a byte). No operating
system can function without this. M-mode (machine mode) is the highest privilege
level and the only one you need for bare-metal code and simple kernels.

Future role: This is the foundation for all OS-level functionality. Linux needs this
plus S-mode (supervisor mode), which you'll add later.

---

## Phase 10 — Timer

What: Implement mtime (a free-running 64-bit counter) and mtimecmp (comparison
register). When mtime >= mtimecmp, a timer interrupt fires.

Why: Every operating system needs a timer tick for scheduling. Even bare-metal
firmware needs delays and timeouts. This is your first interrupt source, which also
validates that the trap handling from Phase 9 actually works end-to-end.

---

## Phase 11 — Interrupt Controller

What: Build a minimal PLIC (Platform-Level Interrupt Controller) or a simplified
version. Connect UART RX as an interrupt source. Implement interrupt priority and
enable/disable.

Why: Polling the UART wastes CPU cycles. With interrupts, the CPU does other work
and only handles UART when data arrives. A real system has many interrupt sources —
the PLIC manages them. This is required for Linux.

---

## Phase 12 — Pipeline (Optional but educational)

What: Insert pipeline registers between your stages (fetch|decode|execute|memory|
writeback). Handle data hazards (forwarding/stalling) and control hazards (branch
prediction or pipeline flush).

Why: Your single-cycle core's clock speed is limited by the longest combinational
path (probably through the ALU). Pipelining lets each stage run in one short cycle.
This is the classic computer architecture exercise and deeply educational.

Why optional: A single-cycle core can run at maybe 50-80 MHz on the Artix-7. That's
plenty for booting Linux. Pipeline if you want to learn, not because you must.

---

## Phase 13 — SPI Flash Boot + DRAM

What: Add an SPI flash controller to boot from the on-board flash (instead of BRAM
initialization). Integrate AMD/Xilinx MIG IP for the DDR3 on the Arty A7. Update
your memory map: flash at boot, copy to DRAM, jump to DRAM.

Why: BRAM is tiny (a few hundred KB on Artix-7 100T). Linux needs megabytes. DRAM
gives you 256MB. Flash gives you persistent storage for the bootloader. This is
how real embedded systems boot.

---

## Phase 14 — S-Mode, U-Mode, Sv32 Virtual Memory

What: Add supervisor and user privilege modes. Implement Sv32 page table walking
(two-level page tables, 4KB pages). Add the satp CSR, page fault exceptions, and
sfence.vma.

Why: Linux runs the kernel in S-mode, user programs in U-mode. Virtual memory gives
each process its own address space and protects the kernel from user code. This is the
last major architectural piece before Linux.

---

## Phase 15 — Linux

What: Port a minimal Linux kernel (or use an existing RISC-V port). Write a device
tree for your SoC. Build an initramfs with BusyBox. Boot to a shell prompt.

Why: This is the summit. A Linux shell running on a CPU you built from scratch.

---

## Quick Reference: What You Need Installed

- Vivado 2025.2 or later (synthesis, simulation, ILA, VIO)
- RISC-V GCC toolchain (`riscv64-unknown-elf-gcc`, multilib build — needs to
  support `rv32im_zicsr_zifencei` / `ilp32`)
- `riscv-tests` repo cloned and buildable (Phase 8.5 onward)
- Terminal program (minicom, picocom, or PuTTY) for UART, 115200 8N1
- Text editor you like for SystemVerilog
- The RISC-V ISA spec (Volume 1: Unprivileged, Volume 2: Privileged) — free PDFs