From fa61c9c4a5210f89e4409b0f046b3ce33ed3a26b Mon Sep 17 00:00:00 2001
From: David Harris <david_harris@hmc.edu>
Date: Sat, 14 Jan 2023 18:56:46 -0800
Subject: [PATCH] generic cleanup

---
 pipelined/src/generic/adder.sv         |  3 ++-
 pipelined/src/generic/aplusbeq0.sv     |  3 ++-
 pipelined/src/generic/arrs.sv          | 16 ++++++++--------
 pipelined/src/generic/binencoder.sv    | 11 ++++++++---
 pipelined/src/generic/clockgater.sv    | 24 +++++++++---------------
 pipelined/src/generic/counter.sv       |  3 ++-
 pipelined/src/generic/csa.sv           |  3 +--
 pipelined/src/generic/decoder.sv       |  2 +-
 pipelined/src/generic/lzc.sv           | 24 ++++++++++--------------
 pipelined/src/generic/onehotdecoder.sv |  9 ++++-----
 pipelined/src/generic/or_rows.sv       | 14 ++++++++------
 pipelined/src/hazard/hazard.sv         | 19 +++++++++++--------
 12 files changed, 66 insertions(+), 65 deletions(-)

diff --git a/pipelined/src/generic/adder.sv b/pipelined/src/generic/adder.sv
index b9b2b2af5..7acd20df0 100644
--- a/pipelined/src/generic/adder.sv
+++ b/pipelined/src/generic/adder.sv
@@ -28,7 +28,8 @@
 
 module adder #(parameter WIDTH=8) (
   input  logic [WIDTH-1:0] a, b,
-  output logic [WIDTH-1:0] y);
+  output logic [WIDTH-1:0] y
+);
 
   assign y = a + b;
 endmodule 
diff --git a/pipelined/src/generic/aplusbeq0.sv b/pipelined/src/generic/aplusbeq0.sv
index 4b3c4439d..d322216b3 100644
--- a/pipelined/src/generic/aplusbeq0.sv
+++ b/pipelined/src/generic/aplusbeq0.sv
@@ -28,7 +28,8 @@
 
 module aplusbeq0 #(parameter WIDTH = 8) (
   input  logic [WIDTH-1:0] a, b,
-  output logic             zero);
+  output logic             zero
+);
 
   logic [WIDTH-1:0] x;
   logic [WIDTH-1:0] orshift;
diff --git a/pipelined/src/generic/arrs.sv b/pipelined/src/generic/arrs.sv
index 8256d9d3e..0bb30c96a 100644
--- a/pipelined/src/generic/arrs.sv
+++ b/pipelined/src/generic/arrs.sv
@@ -29,16 +29,17 @@
 
 `include "wally-config.vh"
 
-module arrs
-  (input logic 	clk,
-   input logic 	areset,
-   output logic reset);
+module arrs(
+  input  logic 	clk,
+  input  logic 	areset,
+  output logic  reset
+);
 
-  logic 	metaStable;
-  logic 	resetB;
+  logic 	      metaStable;
+  logic 	      resetB;
   
   always_ff @(posedge clk , posedge areset) begin
-    if(areset) begin
+    if (areset) begin
       metaStable <= 1'b0;
       resetB <= 1'b0;
     end else begin
@@ -48,5 +49,4 @@ module arrs
   end
 
   assign reset = ~resetB;
-  
 endmodule
diff --git a/pipelined/src/generic/binencoder.sv b/pipelined/src/generic/binencoder.sv
index a7e8061fe..89093ea5b 100644
--- a/pipelined/src/generic/binencoder.sv
+++ b/pipelined/src/generic/binencoder.sv
@@ -1,5 +1,5 @@
 ///////////////////////////////////////////
-// prioritythermometer.sv
+// binencoder.sv
 //
 // Written: ross1728@gmail.com November 14, 2022
 //
@@ -23,10 +23,15 @@
 ///////////////////////////////////////////
 
 module binencoder #(parameter N = 8) (
-  input logic [N-1:0] A,
-  output logic [$clog2(N)-1:0] Y);
+  input  logic [N-1:0]         A,   // one-hot input
+  output logic [$clog2(N)-1:0] Y    // binary-encoded output
+);
 
   integer                      index;
+
+  // behavioral description
+  // this is coded as a priority encoder
+  // consider redesigning to take advanteage of one-hot nature of input
   always_comb  begin
     Y = 0;
     for(index = 0; index < N; index++) 
diff --git a/pipelined/src/generic/clockgater.sv b/pipelined/src/generic/clockgater.sv
index 486ea4564..55f02cff5 100644
--- a/pipelined/src/generic/clockgater.sv
+++ b/pipelined/src/generic/clockgater.sv
@@ -26,21 +26,15 @@
 
 `include "wally-config.vh"
 
-module clockgater
-  (input logic 	E,
-   input logic 	SE,
-   input logic 	CLK,
-   output logic ECLK);
+module clockgater (
+  input logic 	E,
+  input logic 	SE,
+  input logic 	CLK,
+  output logic ECLK
+);
 
-
-
-  if (`FPGA) begin
-    BUFGCE bufgce_i0 (   
-   .I(CLK),
-   .CE(E | SE),
-   .O(ECLK)    
-   );
-  end else begin
+  if (`FPGA) BUFGCE bufgce_i0 (.I(CLK), .CE(E | SE), .O(ECLK));
+  else begin
     // *** BUG 
     // VERY IMPORTANT.
     // This part functionally models a clock gater, but does not necessarily meet the timing constrains a real standard cell would.
@@ -48,7 +42,7 @@ module clockgater
     logic 	enable_q;
     always_latch begin
       if(~CLK) begin
-	enable_q <= E | SE;
+	      enable_q <= E | SE;
       end
     end
     assign ECLK = enable_q & CLK;
diff --git a/pipelined/src/generic/counter.sv b/pipelined/src/generic/counter.sv
index 06df8be63..1480dc929 100644
--- a/pipelined/src/generic/counter.sv
+++ b/pipelined/src/generic/counter.sv
@@ -28,7 +28,8 @@
 
 module counter #(parameter WIDTH=8) (
   input  logic             clk, reset, en,
-  output logic [WIDTH-1:0] q);
+  output logic [WIDTH-1:0] q
+);
 
   logic [WIDTH-1:0] qnext;
 
diff --git a/pipelined/src/generic/csa.sv b/pipelined/src/generic/csa.sv
index ecb0f3762..91aef44dd 100644
--- a/pipelined/src/generic/csa.sv
+++ b/pipelined/src/generic/csa.sv
@@ -36,6 +36,5 @@ module csa #(parameter N=16) (
   // s + c = x + y + z + cin
  
   assign s = x ^ y ^ z;
-  assign c = {x[N-2:0] & (y[N-2:0] | z[N-2:0]) | 
-		    (y[N-2:0] & z[N-2:0]), cin};
+  assign c = {x[N-2:0] & (y[N-2:0] | z[N-2:0]) | (y[N-2:0] & z[N-2:0]), cin};
 endmodule
diff --git a/pipelined/src/generic/decoder.sv b/pipelined/src/generic/decoder.sv
index bfc9d3b55..807a6d6ca 100644
--- a/pipelined/src/generic/decoder.sv
+++ b/pipelined/src/generic/decoder.sv
@@ -26,7 +26,7 @@
 `include "wally-config.vh"
 
 module decoder #(parameter BINARY_BITS = 3) (
-  input  logic [BINARY_BITS-1:0] binary,
+  input  logic [BINARY_BITS-1:0]      binary,
   output logic [(2**BINARY_BITS)-1:0] onehot
 );
 
diff --git a/pipelined/src/generic/lzc.sv b/pipelined/src/generic/lzc.sv
index e3c8e7548..60719c494 100644
--- a/pipelined/src/generic/lzc.sv
+++ b/pipelined/src/generic/lzc.sv
@@ -23,20 +23,16 @@
 // and limitations under the License.
 ////////////////////////////////////////////////////////////////////////////////////////////////
 
-//leading zero counter i.e. priority encoder
 module lzc #(parameter WIDTH = 1) (
-    input logic  [WIDTH-1:0]            num,    // number to count the leading zeroes of
-    output logic [$clog2(WIDTH+1)-1:0]  ZeroCnt // the number of leading zeroes
+  input logic  [WIDTH-1:0]            num,    // number to count the leading zeroes of
+  output logic [$clog2(WIDTH+1)-1:0]  ZeroCnt // the number of leading zeroes
 );
-/* verilator lint_off CMPCONST */
-/* verilator lint_off WIDTH */
-    
-    logic [31:0] i;
-    always_comb begin
-        i = 0;
-        while (~num[WIDTH-1-i] & (i < WIDTH)) i = i+1;  // search for leading one
-        ZeroCnt = i;
-    end
-/* verilator lint_on WIDTH */
-/* verilator lint_on CMPCONST */
+
+  integer i;
+  
+  always_comb begin
+    i = 0;
+    while (~num[WIDTH-1-i] & (i < WIDTH)) i = i+1;  // search for leading one
+    ZeroCnt = i[$clog2(WIDTH)-1:0];
+  end
 endmodule
diff --git a/pipelined/src/generic/onehotdecoder.sv b/pipelined/src/generic/onehotdecoder.sv
index 3c45a7622..6334e91f8 100644
--- a/pipelined/src/generic/onehotdecoder.sv
+++ b/pipelined/src/generic/onehotdecoder.sv
@@ -26,11 +26,10 @@
 
 `include "wally-config.vh"
 
-module onehotdecoder
-  #(parameter WIDTH = 2)
-  (input logic [WIDTH-1:0] bin,
-   output logic [2**WIDTH-1:0] decoded
-   );
+module onehotdecoder #(parameter WIDTH = 2) (
+  input  logic [WIDTH-1:0]    bin,
+  output logic [2**WIDTH-1:0] decoded
+);
 
   always_comb begin
     decoded = '0;
diff --git a/pipelined/src/generic/or_rows.sv b/pipelined/src/generic/or_rows.sv
index f281cde59..160bc7447 100644
--- a/pipelined/src/generic/or_rows.sv
+++ b/pipelined/src/generic/or_rows.sv
@@ -4,7 +4,7 @@
 // Written: David_Harris@hmc.edu 13 July 2021
 // Modified: 
 //
-// Purpose: Various flavors of multiplexers
+// Purpose: Perform OR across a 2-dimensional array of inputs to produce a 1-D array of outputs
 // 
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -25,26 +25,28 @@
 ////////////////////////////////////////////////////////////////////////////////////////////////
 
 `include "wally-config.vh"
-/* verilator lint_off DECLFILENAME */
-/* verilator lint_off UNOPTFLAT */
 
 // perform an OR of all the rows in an array, producing one output for each column
 // equivalent to assign y = a.or
 module or_rows #(parameter ROWS = 8, COLS=2) (
   input  var logic [COLS-1:0] a[ROWS-1:0],
-  output logic [COLS-1:0] y); 
+  output     logic [COLS-1:0] y
+  ); 
 
   genvar row;
+
   if(ROWS == 1)
     assign y = a[0];
   else begin
+    /* verilator lint_off UNOPTFLAT */
     logic [COLS-1:0] mid[ROWS-1:1];
+
     assign mid[1] = a[0] | a[1];
     for (row=2; row < ROWS; row++)
       assign mid[row] = mid[row-1] | a[row];
     assign y = mid[ROWS-1];
+    /* verilator lint_on UNOPTFLAT */
   end
 endmodule
 
-/* verilator lint_on UNOPTFLAT */
-/* verilator lint_on DECLFILENAME */
+
diff --git a/pipelined/src/hazard/hazard.sv b/pipelined/src/hazard/hazard.sv
index 7d4aa9d20..ba9e7e21f 100644
--- a/pipelined/src/hazard/hazard.sv
+++ b/pipelined/src/hazard/hazard.sv
@@ -4,8 +4,10 @@
 // Written: David_Harris@hmc.edu 9 January 2021
 // Modified: 
 //
-// Purpose: Determine forwarding, stalls and flushes
+// Purpose: Determine stalls and flushes
 // 
+// Documentation: RISC-V System on Chip Design Chapter 4, Figure 13.54
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University
@@ -28,21 +30,21 @@
 
 module hazard(
   // Detect hazards
-(* mark_debug = "true" *)	      input logic  BPPredWrongE, CSRWriteFenceM, RetM, TrapM,
+(* mark_debug = "true" *)	      input logic  BPPredWrongE, CSRWriteFenceM, RetM, TrapM,   
 (* mark_debug = "true" *)	      input logic  LoadStallD, StoreStallD, MDUStallD, CSRRdStallD,
 (* mark_debug = "true" *)	      input logic  LSUStallM, IFUStallF,
-(* mark_debug = "true" *)         input logic  FCvtIntStallD, FPUStallD,
-(* mark_debug = "true" *)	      input logic  DivBusyE,FDivBusyE,
+(* mark_debug = "true" *)       input logic  FCvtIntStallD, FPUStallD,
+(* mark_debug = "true" *)	      input logic  DivBusyE, FDivBusyE,
 (* mark_debug = "true" *)	      input logic  EcallFaultM, BreakpointFaultM,
-(* mark_debug = "true" *)         input logic  WFIStallM,
+(* mark_debug = "true" *)       input logic  WFIStallM,
   // Stall & flush outputs
 (* mark_debug = "true" *)	      output logic StallF, StallD, StallE, StallM, StallW,
 (* mark_debug = "true" *)	      output logic FlushD, FlushE, FlushM, FlushW
 );
 
-  logic StallFCause, StallDCause, StallECause, StallMCause, StallWCause;
-  logic FirstUnstalledD, FirstUnstalledE, FirstUnstalledM, FirstUnstalledW;
-  logic FlushDCause, FlushECause, FlushMCause, FlushWCause;
+  logic                                       StallFCause, StallDCause, StallECause, StallMCause, StallWCause;
+  logic                                       FirstUnstalledD, FirstUnstalledE, FirstUnstalledM, FirstUnstalledW;
+  logic                                       FlushDCause, FlushECause, FlushMCause, FlushWCause;
   
   // stalls and flushes
   // loads: stall for one cycle if the subsequent instruction depends on the load
@@ -92,6 +94,7 @@ module hazard(
   assign #1 StallM = StallMCause | StallW;
   assign #1 StallW = StallWCause;
 
+  // detect the first stage that is not stalled
   assign FirstUnstalledD = ~StallD & StallF;
   assign FirstUnstalledE = ~StallE & StallD;
   assign FirstUnstalledM = ~StallM & StallE;