From c75a164f460c13be05bf890c666876a91eed5f19 Mon Sep 17 00:00:00 2001
From: Ross Thompson <ross1728@gmail.com>
Date: Tue, 17 Jan 2023 21:54:40 -0600
Subject: [PATCH] Added comments to dtim and ahbcacheinterface.

---
 pipelined/src/ebu/ahbcacheinterface.sv | 57 +++++++++++++-------------
 pipelined/src/lsu/dtim.sv              | 19 +++++----
 pipelined/src/lsu/lsu.sv               |  2 +-
 3 files changed, 40 insertions(+), 38 deletions(-)

diff --git a/pipelined/src/ebu/ahbcacheinterface.sv b/pipelined/src/ebu/ahbcacheinterface.sv
index 6a41b115..c39cce55 100644
--- a/pipelined/src/ebu/ahbcacheinterface.sv
+++ b/pipelined/src/ebu/ahbcacheinterface.sv
@@ -33,37 +33,38 @@
 module ahbcacheinterface #(parameter BEATSPERLINE, LINELEN, LOGWPL, CACHE_ENABLED) (
   input  logic                 HCLK, HRESETn,
   // bus interface
-  input  logic                 HREADY,
-  input  logic [`AHBW-1:0]     HRDATA,
-  output logic [2:0]           HSIZE,
-  output logic [2:0]           HBURST,
-  output logic [1:0]           HTRANS,
-  output logic                 HWRITE,
-  output logic [`PA_BITS-1:0]  HADDR,
-  output logic [`AHBW-1:0]     HWDATA,
-  output logic [`AHBW/8-1:0]   HWSTRB,
-  output logic [LOGWPL-1:0]    BeatCount,
+  input logic                 HREADY,                  // AHB peripheral ready
+  input logic [`AHBW-1:0]     HRDATA,                  // AHB read data
+  output logic [2:0]          HSIZE,                   // AHB transaction width
+  output logic [2:0]          HBURST,                  // AHB burst length
+  output logic [1:0]          HTRANS,                  // AHB transaction type, 00: IDLE, 10 NON_SEQ, 11 SEQ
+  output logic                HWRITE,                  // AHB 0: Read operation 1: Write operation 
+  output logic [`PA_BITS-1:0] HADDR,                   // AHB address
+  output logic [`AHBW-1:0]    HWDATA,                  // AHB write data
+  output logic [`AHBW/8-1:0]  HWSTRB,                  // AHB byte mask
   
   // cache interface
-  input  logic [`PA_BITS-1:0]  CacheBusAdr,
-  input  logic [`LLEN-1:0]     CacheReadDataWordM,
-  input  logic [`LLEN-1:0]     WriteDataM,
-  input  logic                 CacheableOrFlushCacheM,
-  input  logic [1:0]           CacheBusRW,
-  output logic                 CacheBusAck,
-  output logic [LINELEN-1:0]   FetchBuffer, 
-  input  logic                 Cacheable,
- 
+  input logic [`PA_BITS-1:0]  CacheBusAdr,             // Address of cache line
+  input logic [`LLEN-1:0]     CacheReadDataWordM,      // one word of cache line during a writeback
+  input logic                 CacheableOrFlushCacheM,  // Memory operation is cacheable or flushing D$
+  input logic [1:0]           CacheBusRW,              // Cache bus operation, 01: writeback, 10: fetch
+  output logic                CacheBusAck,             // Handshack to $ indicating bus transaction completed
+  output logic [LINELEN-1:0]  FetchBuffer,             // Register to hold beats of cache line as the arrive from bus
+  output logic [LOGWPL-1:0]   BeatCount,               // Beat position within the cache line
+  input logic                 Cacheable,               // Memory operation is cachable
+
+  // uncached interface 
+  input logic [`LLEN-1:0]     WriteDataM,              // IEU write data for uncached store
+
   // lsu/ifu interface
-  input  logic                 Flush,
-  input  logic [`PA_BITS-1:0]  PAdr,
-  input  logic [1:0]           BusRW,
-  input  logic                 Stall,
-  input  logic [2:0]           Funct3,
-  output logic                 SelBusBeat,
-  output logic                 BusStall,
-  output logic                 BusCommitted
-);
+  input logic                 Flush,                   // Pipeline stage flush. Prevents bus transaction from starting
+  input logic [`PA_BITS-1:0]  PAdr,                    // Physical address of uncached memory operation
+  input logic [1:0]           BusRW,                   // 
+  input logic                 Stall,
+  input logic [2:0]           Funct3,
+  output logic                SelBusBeat,
+  output logic                BusStall,
+  output logic                BusCommitted);
   
   localparam integer           LLENPOVERAHBW = `LLEN / `AHBW; // *** fix me duplciated in lsu.
 
diff --git a/pipelined/src/lsu/dtim.sv b/pipelined/src/lsu/dtim.sv
index d4fe7a08..a5f74e91 100644
--- a/pipelined/src/lsu/dtim.sv
+++ b/pipelined/src/lsu/dtim.sv
@@ -26,14 +26,15 @@
 `include "wally-config.vh"
 
 module dtim(
-  input logic                clk, ce,
-  input logic [1:0]          MemRWM,
-  input logic [`PA_BITS-1:0] Adr,
-  input logic                FlushW, 
-  input logic [`LLEN-1:0]    WriteDataM,
-  input logic [`LLEN/8-1:0]  ByteMaskM,
-  output logic [`LLEN-1:0]   ReadDataWordM
-);
+  input logic 				 clk, 
+  input logic 				 ce,            // Chip Enable
+  input logic [1:0] 		 MemRWM,        // Read/Write control
+  input logic [`PA_BITS-1:0] AdrM,          // Execution stage memory address
+  input logic 				 FlushW, 
+  input logic [`LLEN-1:0] 	 WriteDataM,    // Write data from IEU
+  input logic [`LLEN/8-1:0]  ByteMaskM,     // Selects which bytes within a word to write
+  output logic [`LLEN-1:0] 	 ReadDataWordM  // Read data before subword selection
+  );
 
   logic                      we;
  
@@ -43,6 +44,6 @@ module dtim(
   assign we = MemRWM[0]  & ~FlushW;  // have to ignore write if Trap.
 
   ram1p1rwbe #(.DEPTH(`DTIM_RANGE/8), .WIDTH(`LLEN)) 
-    ram(.clk, .ce, .we, .bwe(ByteMaskM), .addr(Adr[ADDR_WDITH+OFFSET-1:OFFSET]), .dout(ReadDataWordM), .din(WriteDataM));
+    ram(.clk, .ce, .we, .bwe(ByteMaskM), .addr(AdrM[ADDR_WDITH+OFFSET-1:OFFSET]), .dout(ReadDataWordM), .din(WriteDataM));
 endmodule  
   
diff --git a/pipelined/src/lsu/lsu.sv b/pipelined/src/lsu/lsu.sv
index e69fbcb8..c7d57723 100644
--- a/pipelined/src/lsu/lsu.sv
+++ b/pipelined/src/lsu/lsu.sv
@@ -232,7 +232,7 @@ module lsu (
     // **** fix ReadDataWordM to be LLEN. ByteMask is wrong length.
     // **** create config to support DTIM with floating point.
     dtim dtim(.clk, .ce(~GatedStallW), .MemRWM(DTIMMemRWM),
-              .Adr(DTIMAdr), .FlushW, .WriteDataM(LSUWriteDataM), 
+              .AdrM(DTIMAdr), .FlushW, .WriteDataM(LSUWriteDataM), 
               .ReadDataWordM(DTIMReadDataWordM[`XLEN-1:0]), .ByteMaskM(ByteMaskM[`XLEN/8-1:0]));
   end else begin
   end