feat: implement programmable fetch/execute logic and BRAM-mapped IMEM

Refactors the Borg module from a single-step arithmetic unit into a
minimal shading processor. Key changes include:

- Instruction Memory: Replaced the single 'instr' register with an
  8-word instruction memory (imem) mapped to 0x20-0x38.
- Execution Control: Added a Program Counter (PC) and a control
  register (0x3C) to handle Start and Reset/Stop logic.
- Status Polling: Implemented a Status Register (0x10) with a 'Halted'
  bit, allowing software to poll for execution completion.
- RISC-V Style Decoding: Updated decoding logic to support a 'rd'
  (destination register) field, enabling flexible register file writes.
- Test Updates: Synchronized Scala and Python test drivers to use
  the new memory-mapped I/O flow and polling-based execution.

Author: gonsolo

borg/src/Borg.scala

@@ -4,12 +4,17 @@
 package borg
 
 import chisel3.*
-import chisel3.util.MuxLookup
+import chisel3.util.*
 
+/** BorgIO defines the interface for the shading processor. It uses
+  * memory-mapped I/O for register and instruction memory access.
+  */
 class BorgIO extends Bundle {
-  val address = Input(UInt(6.W))
+  val address = Input(
+    UInt(6.W)
+  ) // 64-word address space (byte-addressed internally by shifting)
   val data_in = Input(UInt(32.W))
-  val data_write_n = Input(UInt(2.W))
+  val data_write_n = Input(UInt(2.W)) // 0b10 for write
   val data_read_n = Input(UInt(2.W))
   val data_out = Output(UInt(32.W))
   val data_ready = Output(Bool())
@@ -18,71 +23,124 @@ class BorgIO extends Bundle {
   val user_interrupt = Output(Bool())
 }
 
+/** Borg is a minimal shading processor with instruction memory and a program
+  * counter. It executes floating-point addition instructions in a 4-cycle
+  * pipeline.
+  */
 class Borg extends Module {
   val io = IO(new BorgIO)
 
-  val rf = Reg(Vec(3, UInt(32.W)))
-  val instr = RegInit(0.U(32.W))
+  // --- Storage ---
+  // registerFile: 4 general-purpose 32-bit registers for floating-point data
+  val registerFile = Reg(Vec(4, UInt(32.W)))
 
+  // instructionMemory: 8 words of instruction memory to store the shader program
+  val instructionMemory = Reg(Vec(8, UInt(32.W)))
+
+  // programCounter: Points to the current instruction in instructionMemory
+  val programCounter = RegInit(0.U(3.W))
+
+  // currentInstruction: The instruction currently being decoded/executed
+  val currentInstruction = RegInit(0.U(32.W))
+
+  // running: Status flag indicating if the processor is currently executing a program
+  val running = RegInit(false.B)
+
+  // --- Pipeline Control ---
+  // busy_counter: Tracks the 4-cycle execution stage of the current instruction
   val busy_counter = RegInit(0.U(3.W))
   val is_busy = busy_counter > 0.U
 
   val is_writing = io.data_write_n === "b10".U
-  val writing_instr = is_writing && io.address === 60.U
 
-  when(writing_instr) {
-    busy_counter := 4.U // Start 4-cycle countdown
-    instr := io.data_in
+  // --- Memory-Mapped Write Logic ---
+  when(is_writing) {
+    when(io.address < 16.U) {
+      // 0x00 - 0x0C: Register File (rf0, rf1, rf2, rf3)
+      registerFile(io.address(3, 2)) := io.data_in
+    }.elsewhen(io.address >= 32.U && io.address < 64.U) {
+      when(io.address === 60.U) {
+        // 0x3C (60): Control Register
+        // Bit 0 = Start execution
+        // Bit 1 = Reset PC and stop
+        when(io.data_in(0)) { running := true.B }
+        when(io.data_in(1)) { programCounter := 0.U; running := false.B }
+      }.otherwise {
+        // 0x20 - 0x38: Instruction Memory (8 slots)
+        instructionMemory(io.address(4, 2)) := io.data_in
+      }
+    }
+  }
+
+  // --- Fetch & Execute State Machine ---
+  when(running && !is_busy) {
+    // Fetch Stage: Load next instruction from memory
+    currentInstruction := instructionMemory(programCounter)
+    busy_counter := 4.U
   }.elsewhen(is_busy) {
+    // Execution Stages: Counting down 4 cycles
     busy_counter := busy_counter - 1.U
-  }
 
-  val funct7 = instr(31, 25)
-  val rs2_idx = instr(24, 20) % 3.U
-  val rs1_idx = instr(19, 15) % 3.U
+    when(busy_counter === 1.U) {
+      // End of execution: Increment PC
+      programCounter := programCounter + 1.U
 
-  when(is_writing && !writing_instr) {
-    when(io.address === 0.U) { rf(0) := io.data_in }
-      .elsewhen(io.address === 4.U) { rf(1) := io.data_in }
-      .elsewhen(io.address === 16.U) { rf(2) := io.data_in }
+      // Stop execution if the next instruction is all zeros (HALT)
+      // Note: This creates an "Implicit Halt" at the end of the program
+      when(instructionMemory(programCounter + 1.U) === 0.U) {
+        running := false.B
+      }
+    }
   }
 
-  val recA = recFNFromFN(8, 24, rf(rs1_idx))
-  val recB = recFNFromFN(8, 24, rf(rs2_idx))
+  // --- Instruction Decoding (RISC-V inspired) ---
+  val rs2_idx = currentInstruction(24, 20)(1, 0)
+  val rs1_idx = currentInstruction(19, 15)(1, 0)
+  val rd_idx = currentInstruction(11, 7)(1, 0)
 
-  // --- Simplified Math: Adder Only ---
+  // Floating Point Operands
+  val recA = recFNFromFN(8, 24, registerFile(rs1_idx))
+  val recB = recFNFromFN(8, 24, registerFile(rs2_idx))
+
+  // --- Arithmetic Logic Unit: Floating Point Adder ---
   val f_add = Module(new AddRecFN(8, 24))
   f_add.io.subOp := false.B
   f_add.io.a := recA
   f_add.io.b := recB
   f_add.io.roundingMode := 0.U
   f_add.io.detectTininess := 1.U
 
-  // --- Optimization: Multi-Stage Pipeline ---
+  // --- Multi-Stage Pipeline ---
   val stage1_math_rec = Reg(UInt(33.W))
-  val math_result_reg = RegInit(0.U(32.W))
 
   // Stage 1: Capture (Cycle 2 of 4)
   when(busy_counter === 2.U) {
     stage1_math_rec := f_add.io.out
   }
 
-  // Stage 2: Final Conversion (Cycle 1 of 4)
+  // Stage 2: Writeback (Cycle 1 of 4)
   when(busy_counter === 1.U) {
-    math_result_reg := fNFromRecFN(8, 24, stage1_math_rec)
+    registerFile(rd_idx) := fNFromRecFN(8, 24, stage1_math_rec)
   }
 
+  // --- Memory-Mapped Read Logic ---
   io.data_out := MuxLookup(io.address, 0.U)(
     Seq(
-      0.U -> rf(0),
-      4.U -> rf(1),
-      16.U -> rf(2),
-      8.U -> math_result_reg,
-      60.U -> instr
+      0.U -> registerFile(0),
+      4.U -> registerFile(1),
+      8.U -> registerFile(2),
+      12.U -> registerFile(3),
+      16.U -> Cat(
+        0.U(30.W),
+        !running,
+        0.U(1.W)
+      ), // Status Register: [Halted, _]
+      60.U -> currentInstruction
     )
   )
-
-  io.data_ready := !is_busy && !writing_instr
+  // Memory bus reads from peripheral registers take 1 cycle.
+  // We rely on software polling `status[1]` (Halted) to avoid reading `res` while busy.
+  io.data_ready := true.B
 
   io.uo_out := 0.U
   io.user_interrupt := false.B

borg/test/src/BorgTests.scala

@@ -30,31 +30,46 @@ object BorgTests extends TestSuite {
 
   def readAddr(borg: Borg, addr: Int): Float = {
     borg.io.address.poke(addr.U)
-    val res = bitsToFloat(borg.io.data_out.peek().litValue)
-    borg.clock.step(1)
-    res
+    bitsToFloat(borg.io.data_out.peek().litValue)
   }
 
   def runBasicMathTest(borg: Borg, a: Float, b: Float, epsilon: Float): Unit = {
-    // 1. Load operands into registers 0 and 1
+    // 1. Reset PC and stop execution
+    writeAddr(borg, 60, 2) // Bit 1 = Reset PC
+
+    // 2. Load operands into registers 0 and 1
     writeAddr(borg, 0, floatToBits(a))
     writeAddr(borg, 4, floatToBits(b))
 
-    // 2. Setup Addition Instruction
-    // rs1 = reg0, rs2 = reg1, funct7 = 0x00 (Add)
-    val add_instr = (0x00 << 25) | (1 << 20) | (0 << 15)
-    writeAddr(borg, 60, BigInt(add_instr))
+    // 3. Setup Addition Instruction in imem(0)
+    // opcode/funct7 = 0x00 (Add), rs1 = reg0, rs2 = reg1, rd = reg2
+    // RISC-V like format: funct7(7) | rs2(5) | rs1(5) | funct3(3) | rd(5) | opcode(7)
+    // We only use funct7, rs2, rs1, rd.
+    val rd = 2
+    val rs1 = 0
+    val rs2 = 1
+    val add_instr = (0x00 << 25) | (rs2 << 20) | (rs1 << 15) | (rd << 7)
+    writeAddr(borg, 32, BigInt(add_instr)) // imem(0)
+
+    // Halt instruction (zero) in imem(1)
+    writeAddr(borg, 36, 0)
 
-    // 3. Wait for Hardware Pipeline
-    while (!borg.io.data_ready.peek().litToBoolean) {
+    // 4. Start execution
+    writeAddr(borg, 60, 1) // Bit 0 = Start
+
+    // 5. Wait for Halted bit (status address 16, bit 1)
+    var status: BigInt = 0
+    do {
+      borg.io.address.poke(16.U)
+      status = borg.io.data_out.peek().litValue
       borg.clock.step(1)
-    }
-    
-    // 4. Read result from math_result register (addr 8)
+    } while ((status & 2) == 0)
+
+    // 6. Read result from rf(2) (addr 8)
     val addActual = readAddr(borg, 8)
     val expectedSum = a + b
 
-    // 5. Report results to console
+    // 7. Report results to console
     println(
       f"Check: $a%8.2f + $b%8.2f -> Actual: $addActual%8.2f (Exp: $expectedSum%8.2f)"
     )

test/test.py

@@ -28,23 +28,42 @@ def load_test_data():
 class BorgDriver:
     def __init__(self, tqv):
         self.tqv = tqv
-        # Address Map matches the simplified Borg.scala
-        self.ADDR_A = 0
-        self.ADDR_B = 4
-        self.ADDR_RESULT = 8  
-        self.ADDR_INSTR = 60
+        # Address Map matches Borg.scala
+        self.ADDR_STATUS = 16
+        self.ADDR_IMEM = 32
+        self.ADDR_CONTROL = 60
 
     async def write_reg(self, reg_idx, val_float):
+        # Register file at 0x00 - 0x0C
         addr = reg_idx * 4
         bits = float_to_bits(np.float32(val_float))
         await self.tqv.write_word_reg(addr, bits)
 
-    async def write_instr(self, instr_bits):
-        await self.tqv.write_word_reg(self.ADDR_INSTR, instr_bits)
-
-    async def read_result(self):
-        # read_word_reg handles the polling of data_ready internally
-        bits = await self.tqv.read_word_reg(self.ADDR_RESULT)
+    async def write_imem(self, idx, instr_bits):
+        # Instruction memory at 0x20 - 0x38
+        addr = self.ADDR_IMEM + (idx * 4)
+        await self.tqv.write_word_reg(addr, instr_bits)
+
+    async def start_execution(self, reset_pc=False):
+        # Control register at 0x3C (60)
+        # Bit 0 = Start, Bit 1 = Reset PC
+        val = 1
+        if reset_pc:
+            val |= 2
+        await self.tqv.write_word_reg(self.ADDR_CONTROL, val)
+
+    async def wait_for_halt(self):
+        # Status register at 0x10 (16)
+        # Bit 1 = Halted
+        while True:
+            status = await self.tqv.read_word_reg(self.ADDR_STATUS)
+            if status & 2:
+                break
+            await cocotb.triggers.Timer(100, units="ns")
+
+    async def read_register(self, reg_idx):
+        addr = reg_idx * 4
+        bits = await self.tqv.read_word_reg(addr)
         return bits_to_float(bits)
 
     async def reset(self):
@@ -55,25 +74,39 @@ async def run_basic_math_test(dut, driver, a, b, epsilon):
     a_32 = np.float32(a)
     b_32 = np.float32(b)
 
-    # 1. Upload Data
+    # 1. Reset PC and stop execution
+    await driver.start_execution(reset_pc=True)
+
+    # 2. Upload Data to registers 0 and 1
     await driver.write_reg(0, a_32)
     await driver.write_reg(1, b_32)
 
-    # 2. Execute ADD: funct7=0x00, rs2=1, rs1=0
-    # In the current Borg.scala, any instr with busy_counter triggers the adder
-    instr_add = (0x00 << 25) | (1 << 20) | (0 << 15)
-    await driver.write_instr(instr_add)
-    
-    # 3. Read Result (Wait for 4-cycle pipeline)
-    add_res = await driver.read_result()
+    # 3. Setup Addition Instruction in imem(0)
+    # funct7=0x00 (Add), rs2=1, rs1=0, rd=2
+    instr_add = (0x00 << 25) | (1 << 20) | (0 << 15) | (2 << 7)
+    await driver.write_imem(0, instr_add)
+
+    # Halt instruction (zero) in imem(1)
+    await driver.write_imem(1, 0)
+
+    # 4. Start execution
+    await driver.start_execution()
+
+    # 5. Wait for Halted status
+    await driver.wait_for_halt()
+
+    # 6. Read Result from register 2
+    add_res = await driver.read_register(2)
 
-    # 4. Assertions
+    # 7. Assertions
     expected_add = a_32 + b_32
 
-    assert abs(add_res - expected_add) < epsilon, f"Add failed: {a_32}+{b_32}={add_res} (Exp: {expected_add})"
+    assert (
+        abs(add_res - expected_add) < epsilon
+    ), f"Add failed: {a_32}+{b_32}={add_res} (Exp: {expected_add})"
 
     dut._log.info(
-        f"Checked Adder: {a_32:8.2f} + {b_32:8.2f} -> Result: {add_res:8.2f}"
+        f"Checked Shader Adder: {a_32:8.2f} + {b_32:8.2f} -> Result: {add_res:8.2f}"
     )
 
 
@@ -82,7 +115,7 @@ async def run_basic_math_test(dut, driver, a, b, epsilon):
 
 @cocotb.test()
 async def test_borg_vulkan_style_math(dut):
-    dut._log.info("Starting Single-Port Programmable Borg Adder Test")
+    dut._log.info("Starting Programmable Borg Shading Processor Test")
 
     test_data = load_test_data()
     epsilon = test_data["epsilon"]
@@ -97,4 +130,4 @@ async def test_borg_vulkan_style_math(dut):
     for a, b in test_data["pairs"]:
         await run_basic_math_test(dut, driver, a, b, epsilon)
 
-    dut._log.info("All Borg Adder Tests Passed!")
+    dut._log.info("All Borg Shading Processor Tests Passed!")