FIFO management

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Description
+Describe the changes made and why they were made.
+
+## Related Issue(s)
+Link or list the issue(s) this PR addresses (e.g., #123).
+
+## Type
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Enhancement
+- [ ] Documentation update

FIFO_MANAGEMENT.txt

@@ -0,0 +1,34 @@
+
+/***FIFO MANAGEMENT**/
+// Internal FIFO memory, pointers, and counter
+localparam ADDR_WIDTH = $clog2(FIFO_DEPTH);
+reg [7:0] fifo_mem [0:FIFO_DEPTH-1];
+reg [ADDR_WIDTH-1:0] waddr_ptr;
+reg [ADDR_WIDTH-1:0] raddr_ptr;
+reg [ADDR_WIDTH:0] count;
+wire fifo_full  = (count == FIFO_DEPTH);
+wire fifo_empty = (count == 0);
+
+// FIFO Push (write) and Pop (read) logic
+always @(posedge clk or posedge rst) begin
+    if (rst) begin
+        waddr_ptr <= 0;
+        raddr_ptr <= 0;
+        count <= 0;
+    end
+    else begin
+        // Push data to FIFO (CPU write)
+        if (wvalid && awvalid && !fifo_full) begin
+            fifo_mem[waddr_ptr] <= wdata;   // Write CPU data into FIFO
+            waddr_ptr <= waddr_ptr + 1;     // Increment write pointer
+            count <= count + 1;             // Increment FIFO count
+        end
+
+        // Pop data from FIFO (CPU read)
+        if (rready && arvalid && !fifo_empty) begin
+            RBR <= fifo_mem[raddr_ptr];     // Load data to read register
+            raddr_ptr <= raddr_ptr + 1;     // Increment read pointer
+            count <= count - 1;             // Decrement FIFO count
+        end
+    end
+end

docs/ip-briefs/CPU_Core_Brief_(v1.0).md

@@ -0,0 +1,85 @@
+**Author:** Sebastian Candelaria
+**RTL:** *rtl/cpu/core/rv32_core.sv*
+
+---
+#### **Purpose & Role**
+- The CPU Core is the main processing unit of the SoC, in charge of running all instructions from a given program and storing/loading memory data as needed
+	- 5-stage pipeline in RV32IMA (ISA-format) with M/S-mode (privilege levels)
+	- Built for a single-core system
+---
+#### **Parameters**
+- Parameters in Verilog/SystemVerilog are similar to constants and #define directives seen in C/C++ that are reused many times across a module to avoid magic numbers and promote reusability
+
+| Name       | Default         | Description                                                                                            |
+| ---------  | --------------- | ------------------------------------------------------------------------------------------------------ |
+| HAS_M      | 1               | Enable RV32M mul/div instructions                                                                      |
+| HAS_A      | 1               | Enable LR/SC atomic instructions                                                                       |
+
+---
+#### **Interfaces (Ports)**
+- Any external input or output signal that will be used by the IF stage
+- AXI, IRQ, and debug signal sizes must be defined
+- Subject to change
+
+| Signal Name              | Direction | Width | Description                                                            |
+| ------------------------ | --------- | ----- | ---------------------------------------------------------------------- |
+| **Global Signals**       |           |       |                                                                        |
+| clk_i                    | In        | 1     | Main clock input                                                       |
+| rst_ni                   | In        | 1     | Active-low reset                                                       |
+|                          |           |       |                                                                        |
+| **PLIC/CLINT Interface** |           |       |                                                                        |
+| irq_ext_i                | In        | 1     | Interrupt request from external device(s) (controller, keyboard, etc.) |
+| irq_timer_i              | In        | 1     | Interrupt request from timer                                           |
+| irq_soft_i               | In        | N/A   |                                                                        |
+|                          |           |       |                                                                        |
+| **AXI Interface**        |           |       |                                                                        |
+| i_axi_*                  | I/O       | N/A   | Instruction AXI: Communicates with instruction cache                   |
+| d_axi_*                  | I/O       | N/A   | Data AXI: Communicates with data cache                                 |
+|                          |           |       |                                                                        |
+| **Debug Interface**      |           |       |                                                                        |
+| dbg_*                    | I/O       | N/A   | JTAG Signals for checking CPU behavior (Test Clock, Test Data, etc.)   |
+|                          |           |       |                                                                        |
+
+---
+#### **Reset/Init**
+- When performing a reset, the signal rst_ni becomes LOW (0), the CPU enters its default program ready state
+	- The program counter (PC) is set to the BootROM's beginning instruction
+	- The control-status registers (CSRs) are set to initial values, such as # of cycles elapsed = 0
+	- All data in the pipeline, including intermediate registers and the register file, is flushed (cleared)
+---
+#### **Behavior & Timing**
+- Instruction Execution Order: The pipeline executes the instructions in-order, or in the sequence given by the program
+	- Data forwarding, consisting of signals backtracking to Decode (ID) stage, is used to handle dependencies between instructions (EX: Instruction 2 needs data provided by Instruction 1)
+	- Hazard/flush control is needed for when hazards become issues, such as an instruction 
+- Control Components: The core needs to minimize cycle losses from control flow changes (i.e. jumping instructions)
+	- Branch Target Buffer (BTB, optional): Table of instruction addresses recently visited, indicating whether they are more likely to be visited again upon a branch (if condition is true, jump to instruction) instruction
+	- Trap Vector Exception: Upon encountering a trap/error (EX: Division by zero), the CPU should immediately execute a subroutine at a vector (function's address) given by a table
+---
+#### **Programming Model**
+- CLINT: *specs/registers/clint.yaml*
+- PLIC: *specs/registers/plic.yaml*
+---
+#### **Errors/IRQs**
+- Trap Vector Handling
+- Exception Causes
+- MCAUSE/MEPC Behavior
+---
+#### **Performance Targets**
+- CPI: Average number of clock cycles taken to execute an instruction (>= 1)
+	- Goal: <= 2 cycles per instruction
+- MIPS: # of millions of instructions per second
+	- Dependent on CPI and clock frequency
+	- Goal: >= 126.5 MIPS
+---
+#### **Dependencies**
+- AXI: *rtl/bus/axi/axi_crossbar.sv*
+	- AXI connection to fetch instructions and data from memory hierarchy (ideally cache, main memory upon miss)
+- PLIC/CLINT: *rtl/irq/clint.sv*, *rtl/irq/plic.sv*
+	- PLIC/CLINT send interrupts, signals for CPU to temporarily switch to execution of a function's instructions in the program, based on controller inputs, timer values, etc.
+- MMU: *rtl/cpu/mmu/sv32_mmu.sv*
+	- Controls where/how instructions and data are loaded and stored
+- RV32 Package: *rtl/cpu/pkg/rv32_pkg.sv*
+---
+#### **Verification Links**
+- *sim/uvm/test_core.sv*
+	- SystemVerilog simulation environment to verify CPU core

docs/ip-briefs/Decode_Stage_Brief_(v1.0).md

@@ -0,0 +1,67 @@
+**Author:** Sebastian Candelaria
+**RTL:** *rtl/cpu/core/decode.sv*
+
+---
+#### **Purpose & Role**
+- The Instruction Decode (ID) stage is the 2nd stage in a standard 5-stage RISC-V pipeline. At each clock cycle, the decode stage translates an instruction into data values and control signals to direct the rest of the pipeline
+	- For any instructions involving register-reading, the decode stage will retrieve the data from the register file (RF) 
+	- Any instruction operation codes (opcodes) or encoded immediate/constant values (imm values) are translated into control signals and real, usable values
+
+---
+#### **Parameters**
+- Parameters in Verilog/SystemVerilog are similar to constants and #define directives seen in C/C++ that are reused many times across a module to avoid magic numbers and promote reusability
+- Note: Inherited from `rv32_pkg.sv` and `rv32_core` top-level. See CPU Core Brief for HAS_M/HAS_A configuration.
+
+| Name        | Default | Description                                          |
+|-------------|---------|------------------------------------------------------|
+| HAS_M       | 1       | Enable RV32M instruction decoding                    |
+| HAS_A       | 1       | Enable RV32A instruction decoding                    |
+| DATA_WIDTH  | 32      | Operand width                                        |
+
+---
+#### **Interfaces (Ports)**
+- Any external input or output signal that will be used by the ID stage
+- Subject to change
+
+| Signal Name              | Direction | Width | Description                                                            |
+| ------------------------ | --------- | ----- | ---------------------------------------------------------------------- |
+| **Global Signals**       |           |       |                                                                        |
+| clk_i                    | In        | 1     | Main clock input                                                       |
+| rst_ni                   | In        | 1     | Active-low asynchronous reset                                          |
+|                          |           |       |                                                                        |
+| **Semi-Global Signals**  |           |       |                                                                        |
+| inst_i                   | In        | 32    | Fetched instruction                                                    |
+| rf_a_i                   | In        | 32    | Register A operand (data) from RF                                      |
+| rf_b_i                   | In        | 32    | Register B operand (data) from RF                                      |
+| rf_a_o                   | Out       | 32    | Register A operand to execute (EX) stage                               |
+| rf_b_o                   | Out       | 32    | Register B operand to execute (EX) stage                               |
+| ctrl_*_o                 | Out       | N/A   | Control signals to execute                                             |
+|                          |           |       |                                                                        |
+
+---
+#### **Reset/Init**
+- When performing a reset, the signal rst_ni becomes LOW (0), the CPU enters its default state
+	- All registers are flushed
+	- Control signals enter default values
+---
+#### **Behavior & Timing**
+- One-Cycle Decode: Entire decode process should occur within one cycle
+	- Control Signals: Decode stage must produce control signals for following stages based on given instruction, likely through a control unit (CU) or FSM if needed
+- Hazard/Flush: Upon encountering a pipeline hazard, such as branch calculation, decode should flush execute/memory stage
+	- Illegal instructions should raise a trap(error) cause, leading into trap subroutine execution
+	- Data Forwarding: Read output values from execute (EX) and memory (MM) stages and, if meant for register needed to read from, substitute values for next instruction's register data output. If data cannot be forwarded yet (EX: waiting on memory cache), stall until it can
+---
+#### **Errors/IRQs**
+- Illegal Instruction Trap
+---
+#### **Performance Targets**
+- 1-cycle execution
+---
+#### **Dependencies**
+- Execute (EX): *rtl/bus/core/execute.sv*
+- Memory (MM): *rtl/bus/core/mem_stage.sv*
+- RV32 Package: *rtl/cpu/pkg/rv32_pkg.sv*
+---
+#### **Verification Links**
+- *sim/uvm/test_decode.sv*
+	- SystemVerilog simulation environment to verify decode stage

docs/ip-briefs/Execute_Stage_Brief_(v1.0).md

@@ -0,0 +1,71 @@
+**Author:** Sebastian Candelaria
+**RTL:** *rtl/cpu/core/execute.sv*
+
+---
+#### **Purpose & Role**
+- The Execute (EX) stage is the 3rd stage in a standard 5-stage RISC-V pipeline. At each clock cycle, the execute stage performs arithmetic and logic operations on operand values. 
+	- Conditional statement evaluation (thus redirects) occurs here
+	- Contains Arithmetic & Logic Unit (ALU) for basic operations (add, sub, shift, etc.) + multiplier and divider
+
+---
+#### **Parameters**
+- Parameters in Verilog/SystemVerilog are similar to constants and #define directives seen in C/C++ that are reused many times across a module to avoid magic numbers and promote reusability
+- Note: Inherited from `rv32_pkg.sv` and `rv32_core` top-level. See CPU Core Brief for HAS_M/HAS_A configuration.
+
+| Name        | Default | Description                                          |
+|-------------|---------|------------------------------------------------------|
+| MUL_CYCLES  | 3       | Multiplier latency in cycles                         |
+| DIV_CYCLES  | 5       | Divider latency in cycles                            |
+| HAS_M       | 1       | Enable mul/div hardware                              |
+
+---
+#### **Interfaces (Ports)**
+- Any external input or output signal that will be used by the EX stage
+- Subject to change
+
+| Signal Name              | Direction | Width | Description                                                            |
+| ------------------------ | --------- | ----- | ---------------------------------------------------------------------- |
+| **Global Signals**       |           |       |                                                                        |
+| clk_i                    | In        | 1     | Main clock input                                                       |
+| rst_ni                   | In        | 1     | Active-low asynchronous reset                                          |
+|                          |           |       |                                                                        |
+| **Local Signals**        |           |       |                                                                        |
+| ctrl_*_i                 | In        | N/A   | Control signals to execute                                             |
+| op_a_i                   | In        | 32    | Register A operand (data) from RF                                      |
+| op_b_i                   | In        | 32    | Register B operand (data) from RF                                      |
+| alu_res_o                | Out       | 32    | ALU result from processing operands                                    |
+| branch_taken_o           | Out       | 1     | Control signal for whether branch should be taken                      |
+| branch_target_o          | Out       | N/A   | Address for branch to redirect program counter (PC) to                 |
+|                          |           |       |                                                                        |
+
+---
+#### **Reset/Init**
+- When performing a reset, the signal rst_ni becomes LOW (0), the CPU enters its default state
+	- All registers are flushed
+	- Control signals enter default values
+---
+#### **Behavior & Timing**
+- One-Cycle ALU: All ALU outputs should be available within one cycle of processing request
+- Multi-Cycle Mul/Div: Multiplier and divider should take multiple cycles, requiring stalls until processing is finished
+	- Stalls should occur under busy/ready internal handshake signals (aka while working on operation, stall)
+- Unique-Case FSM: A finite state machine (FSM), a sequential logic model for paths of outputs depending on inputs, should control output signals depending on specific operationctrl_*_os, such as initiating stalls upon multiply/divide and releasing at operation finish
+- Redirect Signal: Upon determining branch output in one cycle, EX should send the result directly back to the fetch stage (IF) for the redirect to occur on the next cycle
+- Memory Operations: All memory control signals and operations, unless needing execute, should bypass to MM stage on next cycle
+	- FENCE.I Side-Effects: Since FENCE.I replaces old instructions with new ones, this instruction should bypass to MM stage
+---
+#### **Errors/IRQs**
+- Division By Zero
+- Overflow Handling
+---
+#### **Performance Targets**
+- CPU should stall for at most five cycles due to EX
+	- 1-cycle ALU, <= 5-cycle Mul/Div
+---
+#### **Dependencies**
+- Memory (MM): *rtl/bus/core/mem_stage.sv*
+- Writeback (WB): *rtl/bus/core/writeback.sv*
+- RV32 Package: *rtl/cpu/pkg/rv32_pkg.sv*
+---
+#### **Verification Links**
+- *sim/uvm/test_execute.sv*
+	- SystemVerilog simulation environment to verify execute stage