feat: RISC-V SoC with a memory-mapped systolic-array NPU accelerator

A full system-on-chip: a 5-stage pipelined RV32I CPU, boot ROM, RAM, and a
memory-mapped systolic matrix-multiply NPU on one address-decoded data bus.
Real firmware (assembled by an included RV32I assembler) loads two matrices into
the accelerator, starts it, polls STATUS until done, reads the result back, and
writes it to RAM -- hardware/software co-design with a start/done offload
handshake. Testbench boots the SoC and verifies the NPU-computed product
[[1,2],[3,4]] x [[5,6],[7,8]] = [[19,22],[43,50]] (4/4). Verified on Icarus + CI.

Author: efedemi

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: sim
+on: [push, pull_request]
+
+jobs:
+  icarus:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Icarus Verilog
+        run: sudo apt-get update && sudo apt-get install -y iverilog
+      - name: Re-assemble firmware (sanity check the toolchain)
+        run: |
+          python3 tools/assemble.py firmware/firmware.s > /tmp/fw.hex
+          echo "assembled $(wc -l < /tmp/fw.hex) instructions"
+      - name: Compile
+        run: iverilog -g2012 -o sim.out rtl/rv32i_core.sv rtl/systolic_mm.sv rtl/npu_periph.sv rtl/soc_top.sv tb/soc_tb.sv
+      - name: Run self-checking testbench
+        run: |
+          vvp sim.out | tee sim.log
+          grep -q "ALL TESTS PASSED" sim.log

.gitignore

@@ -0,0 +1,13 @@
+# Simulation artifacts
+*.vcd
+*.out
+sim.out
+*.hex
+work/
+*.jou
+*.log
+xsim.dir/
+.Xil/
+*.wdb
+*.pb
+__pycache__/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Efe Demir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,17 @@
+# RISC-V NPU SoC — simulation shortcuts
+SRC := rtl/rv32i_core.sv rtl/systolic_mm.sv rtl/npu_periph.sv rtl/soc_top.sv tb/soc_tb.sv
+
+sim:          ## Compile + run the SoC testbench
+	iverilog -g2012 -o sim.out $(SRC)
+	vvp sim.out
+
+firmware:     ## Re-assemble firmware.s -> hex
+	python tools/assemble.py firmware/firmware.s
+
+wave: sim     ## Run, then open waveforms in GTKWave
+	gtkwave soc.vcd
+
+clean:
+	rm -f sim.out *.vcd *.log
+
+.PHONY: sim firmware wave clean

README.md

@@ -0,0 +1,85 @@
+# RISC-V SoC with an NPU Accelerator (SystemVerilog)
+
+[![sim](https://github.com/efedemi/riscv-npu-soc/actions/workflows/ci.yml/badge.svg)](https://github.com/efedemi/riscv-npu-soc/actions/workflows/ci.yml)
+
+A complete **system-on-chip**: a pipelined RISC-V CPU, a boot ROM, RAM, and a
+**memory-mapped systolic matrix-multiply NPU** on one data bus — running real
+firmware. The CPU's program loads two matrices into the accelerator, starts it,
+polls for completion, reads the result back, and writes it to memory. This is
+**hardware/software co-design**: the same offload-to-an-accelerator pattern every
+real AI chip uses, built from the ground up and verified end to end.
+
+```
+   ┌───────────────┐  instructions  ┌───────────────┐
+   │  Boot ROM     │───────────────▶│   RV32I CPU   │
+   │  (firmware)   │                │  (5-stage     │
+   └───────────────┘                │   pipeline)   │
+                                    └───────┬───────┘
+                                  data bus  │  (address-decoded)
+                          ┌─────────────────┴──────────────────┐
+                    addr[31]=0                            addr[31]=1
+                          │                                    │
+                    ┌─────▼─────┐                     ┌────────▼────────┐
+                    │    RAM    │                     │  NPU  (memory-  │
+                    │           │                     │  mapped systolic │
+                    └───────────┘                     │  matrix-multiply)│
+                                                      └─────────────────┘
+```
+
+## What happens when it runs
+
+The firmware (`firmware/firmware.s`) executes on the CPU and:
+1. writes matrix **A** and matrix **B** into the NPU's operand registers (stores
+   to `0x8000_00xx`),
+2. writes the **CONTROL** register to start the multiply,
+3. **polls STATUS** until the NPU raises `done`,
+4. reads the result matrix **C** back and stores it to RAM.
+
+The testbench boots the SoC and confirms RAM holds
+`[[1,2],[3,4]] × [[5,6],[7,8]] = [[19,22],[43,50]]` — **computed by the NPU,
+orchestrated entirely by software running on the CPU.**
+
+## Built from
+- **CPU:** [riscv-rv32i-pipeline](https://github.com/efedemi/riscv-rv32i-pipeline) — the 5-stage core, reused here.
+- **NPU datapath:** [systolic-matmul](https://github.com/efedemi/systolic-matmul) — the systolic array, wrapped (`rtl/npu_periph.sv`) as a memory-mapped accelerator with a start/done control FSM.
+- **Toolchain:** `tools/assemble.py` — a small RV32I assembler I wrote; it turns `firmware/firmware.s` into the machine code in the boot ROM (no hand-typed hex).
+
+## Simulate
+
+```bash
+# (optional) re-assemble the firmware
+python tools/assemble.py firmware/firmware.s
+
+# build + run the SoC
+iverilog -g2012 -o sim.out rtl/rv32i_core.sv rtl/systolic_mm.sv \
+         rtl/npu_periph.sv rtl/soc_top.sv tb/soc_tb.sv
+vvp sim.out
+```
+
+## NPU register map (base `0x8000_0000`)
+
+| Offset | Register | Access |
+|---|---|---|
+| `0x00`–`0x0C` | `A[0][0] … A[1][1]` | write |
+| `0x10`–`0x1C` | `B[0][0] … B[1][1]` | write |
+| `0x20` | `CONTROL` (bit0 = start) | write |
+| `0x24` | `STATUS` (bit0 = done) | read |
+| `0x30`–`0x3C` | `C[0][0] … C[1][1]` | read |
+
+## Design notes
+
+- **Memory-mapped accelerator.** The NPU lives in the CPU's address space, so the
+  CPU talks to it with plain `lw`/`sw` — exactly how a driver pokes registers on
+  real hardware. No special instructions needed.
+- **Decoupled, multi-cycle offload.** The matrix multiply takes many cycles, so
+  the NPU exposes a `start`/`done` handshake and the CPU **polls STATUS** — the
+  same pattern as a DMA engine or GPU command queue. Compute and control run
+  concurrently.
+- **Address decode** is a single bit (`addr[31]`): high → NPU, low → RAM. Trivial
+  to extend to more peripherals with a wider decode.
+- **One-bit-at-a-time bring-up.** Each block (CPU, array, NPU wrapper) was verified
+  in isolation first; only then integrated — which is why the full system passed
+  on the first boot.
+
+---
+*Built by Efe Demir.*

firmware/firmware.s

@@ -0,0 +1,52 @@
+# =============================================================================
+# firmware.s  -  runs on the RV32I CPU; offloads a 2x2 matrix multiply to the
+# memory-mapped NPU accelerator, then writes the result matrix into RAM.
+#
+#   NPU register map (base 0x8000_0000):
+#     0x00..0x0C : A[0][0] A[0][1] A[1][0] A[1][1]   (write)
+#     0x10..0x1C : B[0][0] B[0][1] B[1][0] B[1][1]   (write)
+#     0x20       : CONTROL  (write 1 -> start)
+#     0x24       : STATUS   (read bit0 -> done)
+#     0x30..0x3C : C[0][0] C[0][1] C[1][0] C[1][1]   (read)
+#
+#   Computes  A=[[1,2],[3,4]]  x  B=[[5,6],[7,8]]  =  [[19,22],[43,50]]
+#   and stores C into RAM words 0..3.
+# =============================================================================
+    lui  x1, 0x80000      # x1 = NPU base address (0x8000_0000)
+
+    addi x2, x0, 1
+    sw   x2, 0(x1)        # A[0][0] = 1
+    addi x2, x0, 2
+    sw   x2, 4(x1)        # A[0][1] = 2
+    addi x2, x0, 3
+    sw   x2, 8(x1)        # A[1][0] = 3
+    addi x2, x0, 4
+    sw   x2, 12(x1)       # A[1][1] = 4
+
+    addi x2, x0, 5
+    sw   x2, 16(x1)       # B[0][0] = 5
+    addi x2, x0, 6
+    sw   x2, 20(x1)       # B[0][1] = 6
+    addi x2, x0, 7
+    sw   x2, 24(x1)       # B[1][0] = 7
+    addi x2, x0, 8
+    sw   x2, 28(x1)       # B[1][1] = 8
+
+    addi x2, x0, 1
+    sw   x2, 32(x1)       # CONTROL = 1  -> start the NPU
+
+poll:
+    lw   x3, 36(x1)       # read STATUS
+    beq  x3, x0, poll     # spin until done != 0
+
+    lw   x4, 48(x1)       # C[0][0]
+    sw   x4, 0(x0)        # RAM[0]
+    lw   x4, 52(x1)       # C[0][1]
+    sw   x4, 4(x0)        # RAM[1]
+    lw   x4, 56(x1)       # C[1][0]
+    sw   x4, 8(x0)        # RAM[2]
+    lw   x4, 60(x1)       # C[1][1]
+    sw   x4, 12(x0)       # RAM[3]
+
+done:
+    jal  x0, done         # halt

rtl/npu_periph.sv

@@ -0,0 +1,112 @@
+// =============================================================================
+// npu_periph.sv  —  the systolic NPU wrapped as a memory-mapped accelerator
+// -----------------------------------------------------------------------------
+// Register map (byte offsets within the peripheral):
+//   0x00..0x0C  A[0][0] A[0][1] A[1][0] A[1][1]   (write operands)
+//   0x10..0x1C  B[0][0] B[0][1] B[1][0] B[1][1]   (write operands)
+//   0x20        CONTROL : write bit0=1 -> start a multiply
+//   0x24        STATUS  : read  bit0   -> done
+//   0x30..0x3C  C[0][0] C[0][1] C[1][0] C[1][1]   (read results)
+//
+// On start it clears the array, streams the stored operands in with the correct
+// systolic skew, then raises `done`. The CPU polls STATUS and reads the result.
+// Fixed for a 2x2 array (the register map is size-specific).
+// =============================================================================
+`default_nettype none
+
+module npu_periph #(parameter int N = 2, parameter int DATA_W = 8, parameter int ACC_W = 32) (
+    input  wire        clk, rst_n,
+    input  wire [31:0] addr,
+    input  wire [31:0] wdata,
+    input  wire        we,
+    output reg  [31:0] rdata
+);
+    logic [DATA_W-1:0] A_reg [0:1][0:1];
+    logic [DATA_W-1:0] B_reg [0:1][0:1];
+
+    typedef enum logic [1:0] {IDLE, CLR, RUN, DONE} st_t;
+    st_t  state;
+    logic [5:0] t;
+    logic done, arr_clr;
+
+    // operands fed to the array this cycle (skewed)
+    logic [DATA_W-1:0] a0, a1, b0, b1;
+    wire  [N*DATA_W-1:0] a_left = {a1, a0};
+    wire  [N*DATA_W-1:0] b_top  = {b1, b0};
+    wire  [N*N*ACC_W-1:0] c_flat;
+
+    systolic_mm #(.N(N), .DATA_W(DATA_W), .ACC_W(ACC_W)) u_arr (
+        .clk, .rst_n, .clr(arr_clr), .a_left, .b_top, .c_flat);
+
+    // helper nets (avoid procedural part-selects of wdata)
+    wire [DATA_W-1:0] wbyte = wdata[DATA_W-1:0];
+    wire              wd0   = wdata[0];
+    wire [7:0]        off   = addr[7:0];
+
+    // result slices as nets
+    wire [ACC_W-1:0] c00 = c_flat[0*ACC_W +: ACC_W];
+    wire [ACC_W-1:0] c01 = c_flat[1*ACC_W +: ACC_W];
+    wire [ACC_W-1:0] c10 = c_flat[2*ACC_W +: ACC_W];
+    wire [ACC_W-1:0] c11 = c_flat[3*ACC_W +: ACC_W];
+
+    // ---- skewed operand feed (combinational, active during RUN) ----
+    always_comb begin
+        a0 = '0; a1 = '0; b0 = '0; b1 = '0;
+        if (state == RUN) begin
+            if (t == 0) a0 = A_reg[0][0]; else if (t == 1) a0 = A_reg[0][1];
+            if (t == 1) a1 = A_reg[1][0]; else if (t == 2) a1 = A_reg[1][1];
+            if (t == 0) b0 = B_reg[0][0]; else if (t == 1) b0 = B_reg[1][0];
+            if (t == 1) b1 = B_reg[0][1]; else if (t == 2) b1 = B_reg[1][1];
+        end
+    end
+
+    // ---- control FSM + operand register writes ----
+    always_ff @(posedge clk or negedge rst_n) begin
+        if (!rst_n) begin
+            state <= IDLE; t <= 0; done <= 0; arr_clr <= 0;
+        end else begin
+            arr_clr <= 1'b0;
+            case (state)
+                IDLE: begin
+                    if (we) begin
+                        case (off)
+                            8'h00: A_reg[0][0] <= wbyte;
+                            8'h04: A_reg[0][1] <= wbyte;
+                            8'h08: A_reg[1][0] <= wbyte;
+                            8'h0C: A_reg[1][1] <= wbyte;
+                            8'h10: B_reg[0][0] <= wbyte;
+                            8'h14: B_reg[0][1] <= wbyte;
+                            8'h18: B_reg[1][0] <= wbyte;
+                            8'h1C: B_reg[1][1] <= wbyte;
+                            8'h20: if (wd0) begin state <= CLR; arr_clr <= 1'b1; done <= 1'b0; t <= 0; end
+                            default: ;
+                        endcase
+                    end
+                end
+                CLR:  begin state <= RUN; t <= 0; end
+                RUN:  begin
+                    t <= t + 1'b1;
+                    if (t >= 6) begin state <= DONE; done <= 1'b1; end
+                end
+                DONE: begin
+                    done <= 1'b1;
+                    if (we && off == 8'h20 && wd0) begin state <= CLR; arr_clr <= 1'b1; done <= 1'b0; t <= 0; end
+                end
+            endcase
+        end
+    end
+
+    // ---- read mux (combinational) ----
+    always_comb begin
+        case (off)
+            8'h24: rdata = {31'b0, done};
+            8'h30: rdata = c00;
+            8'h34: rdata = c01;
+            8'h38: rdata = c10;
+            8'h3C: rdata = c11;
+            default: rdata = 32'h0;
+        endcase
+    end
+endmodule
+
+`default_nettype wire