Ram handler

docs/DMA_controller.md

@@ -0,0 +1,80 @@
+# GamingCPU — DMA Controller
+
+**Owner:** Evan Eichholz | **RTL Target:** rtl/dma/dma_controller.sv | **Version:** v0.
+
+## Purpose & Role
+
+High-performance Direct Memory Access controller for autonomous data transfers between
+memory and peripherals. Offloads bulk data movement from CPU, enabling concurrent
+computation during video/audio/storage operations.
+
+## Design Specifications
+
+**AXI4 Master** - Full bus master for memory access **Multi-Channel** - 4 independent channels
+with priority arbitration
+**Scatter-Gather** - Linked list descriptor support **Burst Optimization** - Maximum bus
+efficiency **Interrupt Driven** - Completion/error signaling
+
+## Implementation Tasks
+
+```
+Task Decision Deliverable
+```
+```
+Channel Arbitration Fixed priority Bandwidth allocation
+```
+```
+Descriptor Fetch Hardware managed Automatic chain loading
+```
+```
+Burst Control Adaptive sizing Optimal bus utilization
+```
+```
+Error Handling Abort + interrupt Transfer recovery
+```
+```
+Register Interface AXI-Lite Control/status access
+```
+## Channel Configuration
+
+```
+Channel Priority Use Case Burst Size
+```
+```
+0 Highest Video Frame Buffer 16 beats
+```
+```
+1 High Audio Sample Stream 8 beats
+```
+```
+2 Medium SD Card Storage 4 beats
+```
+```
+3 Low General Purpose Configurable
+```
+# INTERFACE DEFINITION
+
+**Module:** dma_controller **Parameters:** CHANNELS = 4, DATA_W = 32
+
+**Ports:**
+
+```
+clk_i, rst_ni - Clock and active-low reset
+m_axi_awaddr[31:0] - AXI write address
+m_axi_awlen[7:0] - AXI write burst length
+m_axi_awvalid - AXI write address valid
+```
+
+m_axi_awready - AXI write address ready
+m_axi_araddr[31:0] - AXI read address
+m_axi_arlen[7:0] - AXI read burst length
+m_axi_arvalid - AXI read address valid
+m_axi_arready - AXI read address ready
+s_axi_araddr[31:0] - Control read address
+s_axi_arvalid - Control read valid
+s_axi_arready - Control read ready
+s_axi_awaddr[31:0] - Control write address
+s_axi_awvalid - Control write valid
+s_axi_awready - Control write ready
+irq_done_o[CHANNELS-1:0] - Transfer complete interrupts
+irq_error_o[CHANNELS-1:0] - Error interrupts

docs/SRAM_dualport.md

@@ -0,0 +1,70 @@
+# GamingCPU — SRAM Dualport
+
+**Owner:** Evan Eichholz **RTL Target:** rtl/mem/sram_dualport.sv
+**Version:** v0.
+
+## Purpose & Role
+
+GamingCPU will implement true dual-port SRAM macro using FPGA block RAM (BRAM)
+primitives. This block will serve as the fundamental building block for all shared,
+concurrent-access memory structures in the SoC by creating a reliable, area-efficient
+memory block that two independent clients can use simultaneously
+
+## Design
+
+**True Dual-Port** - Both ports operate simultaneously, no arbitration
+**FPGA BRAM Mapping** - Use dedicated memory blocks, not flip-flops
+**Byte-Level Writes** - Modify individual bytes without read-modify-write penalty
+**Timing Closure** - Add output registers for better timing
+
+## Implementation Tools
+
+Creating a resource, area-efficient memory block that two independent clients can use
+simultaneously
+
+## Design Specifications
+
+**True Dual-Port** - Both ports operate simultaneously, no arbitration
+**FPGA BRAM Mapping** - Use dedicated memory blocks, not flip-flops
+**Byte-Level Writes** - Modify individual bytes without read-modify-write penalty
+**Timing Closure** - Add output registers for better timing
+
+# Implementation Tasks
+
+| **BRAM Instantiation** | Inference vs Direct | Vendor-agnostic RTL | **Port Wiring** |
+Independent access | No coordination logic | **Byte Enables** | Native BRAM support | Per-
+byte write capability | **Output Registers** | OUT_REG=0 vs 1 | Timing vs latency
+trade-off | **Collision Handling** | Read-old-data vs read-new-data | Documented behavior
+
+# Integration
+
+| **RAM Handler** | Bus interface wrapper | AXI/TL-UL conversion | **Video Pipeline** | Line
+buffers, framebuffers | Direct memory access | **Audio System** | Sample buffers |
+Streaming data | **CPU/Coprocessors** | Shared data structures | Concurrent access
+
+# Interface
+
+```
+module sram_dualport #(
+parameter int DATA_W = 32,
+parameter int ADDR_W = 10,
+parameter bit OUT_REG = 0
+
+
+ )(
+
+input logic clk_i,
+// Port A
+input logic [ADDR_W-1:0] port_a_addr_i,
+input logic [DATA_W-1:0] port_a_wdata_i,
+input logic port_a_we_i,
+input logic [(DATA_W/8)-1:0] port_a_be_i,
+output logic [DATA_W-1:0] port_a_rdata_o,
+// Port B
+input logic [ADDR_W-1:0] port_b_addr_i,
+input logic [DATA_W-1:0] port_b_wdata_i,
+input logic port_b_we_i,
+input logic [(DATA_W/8)-1:0] port_b_be_i,
+output logic [DATA_W-1:0] port_b_rdata_o
+);
+```

docs/bootrom.md

@@ -0,0 +1,41 @@
+# GamingCPU — Boot ROM
+
+```
+Owner: [Evan Eichholz] | RTL Target: rtl/mem/boot_rom.sv | Version: v0.
+```
+## Purpose & Role
+
+```
+Initial boot code storage and CPU initialization. Contains the first instructions executed by
+the processor after reset, handling early system setup, peripheral initialization, and FSBL
+(First Stage Boot Loader) loading from storage.
+```
+## Design Specifications
+
+```
+Read-Only Memory - Pre-programmed content, no write capability
+Fixed Address Range - 4KB memory space at hardware-defined base address
+Minimal Latency - Single-cycle read access for immediate execution
+Synchronous Interface - Clocked read operations only
+```
+## Implementation Tasks
+
+```
+Task Decision Deliverable
+Memory Initialization $readmemh from hex file Pre-programmed boot code
+Interface Design Simple read-only port Clean CPU interface
+Address Decoding Full 4KB range No external decoding needed
+Timing Optimization Combinational read Zero-wait-state access
+```
+## INTERFACE DEFINITION
+
+
+
+```
+module boot_rom #( parameter int ADDR_W = 12, // 4KB address space
+parameter int DATA_W = 32 // 32-bit instruction width
+)(
+input logic clk_i, input logic rst_ni,
+input logic [ADDR_W-1:0] addr_i,
+output logic [DATA_W-1:0] data_o, output logic valid_o
+);

rtl/dma/dma_channel_arbiter.sv

@@ -12,21 +12,36 @@ module dma_channel_arbiter import dma_pkg::*; (
 );
 
     logic [CHANNEL_W-1:0] current_channel;
+    logic [N_CHANNELS-1:0] grant_next;
 
+    // fixed priority logic
+    always_comb begin
+        grant_next = '0;
+
+        // Channel 0 has highest priority
+        for (int i = 0; i < N_CHANNELS; i++) begin
+            if (req_i[i]) begin
+                grant_next[i] = 1'b1;
+                break;
+            end
+        end
+    end
+
+    // reg outputs
     always_ff @(posedge clk_i or negedge rst_ni) begin
         if (!rst_ni) begin
             current_channel <= '0;
             grant_o <= '0;
-        end else begin
-            // Fixed priority arbitration (Channel 0 highest priority)
-            grant_o <= '0;
+        end 
+        else begin
+            grant_o <= grant_next;
+
+            // track which channel got granted
             for (int i = 0; i < N_CHANNELS; i++) begin
-                if (req_i[i]) begin
-                    grant_o[i] <= 1'b1;
-                    break;
-                end
+                if (grant_next[i])
+                    current_channel <= i;
             end
         end
     end
 
-endmodule
+endmodule

rtl/dma/dma_controller.sv

@@ -1,45 +1,93 @@
 //======================================================================
 // DMA Controller - Top Level
-// Author: Evan Eichholz  
+// Author: Evan Eichholz
 // Description: Multi-channel DMA with scatter-gather support
 // References: specs/registers/dma.yaml, docs/dma_operation.md
 //======================================================================
 
-module dma_controller import dma_pkg::*; (
-    // Clock and reset
+module dma_controller
+    import dma_pkg::*;
+(
     input  logic                    clk_i,
     input  logic                    rst_ni,
-
-    // AXI4 Memory Interface (Master) - Write address channel
+
     output logic [ADDR_W-1:0]       m_axi_awaddr_o,
     output logic [7:0]              m_axi_awlen_o,
-    // ... (other AXI ports - truncated for brevity)
-
-    // AXI4-Lite Control Interface (Slave)
+    output logic [2:0]              m_axi_awsize_o,
+    output logic [1:0]              m_axi_awburst_o,
+    output logic                    m_axi_awvalid_o,
+    input  logic                    m_axi_awready_i,
+
+    output logic [DATA_W-1:0]       m_axi_wdata_o,
+    output logic [DATA_W/8-1:0]     m_axi_wstrb_o,
+    output logic                    m_axi_wlast_o,
+    output logic                    m_axi_wvalid_o,
+    input  logic                    m_axi_wready_i,
+
+    input  logic [1:0]              m_axi_bresp_i,
+    input  logic                    m_axi_bvalid_i,
+    output logic                    m_axi_bready_o,
+
+    output logic [ADDR_W-1:0]       m_axi_araddr_o,
+    output logic [7:0]              m_axi_arlen_o,
+    output logic [2:0]              m_axi_arsize_o,
+    output logic [1:0]              m_axi_arburst_o,
+    output logic                    m_axi_arvalid_o,
+    input  logic                    m_axi_arready_i,
+
+    input  logic [DATA_W-1:0]       m_axi_rdata_i,
+    input  logic [1:0]              m_axi_rresp_i,
+    input  logic                    m_axi_rlast_i,
+    input  logic                    m_axi_rvalid_i,
+    output logic                    m_axi_rready_o,
+
     input  logic [ADDR_W-1:0]       s_axi_awaddr_i,
-    // ... (other AXI-Lite ports)
-
-    // Interrupt outputs
+    input  logic                    s_axi_awvalid_i,
+    output logic                    s_axi_awready_o,
+
+    input  logic [DATA_W-1:0]       s_axi_wdata_i,
+    input  logic [DATA_W/8-1:0]     s_axi_wstrb_i,
+    input  logic                    s_axi_wvalid_i,
+    output logic                    s_axi_wready_o,
+
+    output logic [1:0]              s_axi_bresp_o,
+    output logic                    s_axi_bvalid_o,
+    input  logic                    s_axi_bready_i,
+
+    input  logic [ADDR_W-1:0]       s_axi_araddr_i,
+    input  logic                    s_axi_arvalid_i,
+    output logic                    s_axi_arready_o,
+
+    output logic [DATA_W-1:0]       s_axi_rdata_o,
+    output logic [1:0]              s_axi_rresp_o,
+    output logic                    s_axi_rvalid_o,
+    input  logic                    s_axi_rready_i,
+
     output logic [N_CHANNELS-1:0]   irq_done_o,
     output logic [N_CHANNELS-1:0]   irq_error_o,
-
-    // Peripheral request interface
+
     input  logic [N_CHANNELS-1:0]   periph_req_i,
     output logic [N_CHANNELS-1:0]   periph_ack_o
 );
 
-    // Internal signals
-    dma_regs_t regs_q, regs_d;
-    channel_state_e [N_CHANNELS-1:0] channel_state;
-    logic [N_CHANNELS-1:0] channel_grant;
+    dma_regs_t                   regs;
+    logic [N_CHANNELS-1:0]       ch_req;
+    logic [N_CHANNELS-1:0]       ch_grant;
+    logic [CHANNEL_W-1:0]        grant_ch;
+    logic                        grant_valid;
+    ch_status_t [N_CHANNELS-1:0] ch_status;
+    xfer_req_t                   xfer_req;
+    xfer_resp_t                  xfer_resp;
+    desc_fetch_req_t             desc_req;
+    desc_fetch_resp_t            desc_resp;
+    irq_type_e [N_CHANNELS-1:0] irq_type;
 
-    // Module instances
+    dma_reg_if       u_reg_if          (.*);
     dma_channel_arbiter u_channel_arbiter (.*);
-    dma_desc_fetch u_desc_fetch (.*);
-    dma_xfer_engine u_xfer_engine (.*);
-    dma_axi_mux u_axi_mux (.*);
-    dma_reg_if u_reg_if (.*);
-    dma_irq_ctrl u_irq_ctrl (.*);
-    dma_status u_status (.*);
-
-endmodule
+    dma_desc_fetch   u_desc_fetch      (.*);
+    dma_xfer_engine  u_xfer_engine     (.*);
+    dma_axi_mux      u_axi_mux         (.*);
+    dma_irq_ctrl     u_irq_ctrl        (.*);
+    dma_status       u_status          (.*);
+
+endmodule