Merge pull request #1343 from Xilinx/tpreusse.thresholding

Allow thresholding into a range whose size is not a full power of two.

Author: auphelia

finn-rtllib/thresholding/hdl/axilite_if.v

@@ -29,7 +29,7 @@
  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *****************************************************************************/
 
-module axi4lite_if
+module axilite_if
 #(
     parameter ADDR_WIDTH = 32,
     parameter DATA_WIDTH = 32,//AXI4 spec requires this to be strictly 32 or 64

finn-rtllib/thresholding/hdl/thresholding.sv

@@ -32,34 +32,34 @@
  * @author	Thomas B. Preußer <thomas.preusser@amd.com>
  *
  * @description
- *  Produces the N-bit count of those among 2^N-1 thresholds that are not
+ *  Produces the count of those among N thresholds that are not
  *  larger than the corresponding input:
  *     y = Σ(T_i <= x)
  *  The result is computed by binary search. The runtime-configurable
- *  thresholds must be written in ascending order:
+ *  thresholds must be sorted in ascending order:
  *     i < j => T_i < T_j
  *  The design supports channel folding allowing each input to be processed
  *  with respect to a selectable set of thresholds. The corresponding
  *  threshold configuration relies on a channel address prefix. Inputs are
  *  accompanied by a channel selector.
  *
  *  Parameter Layout as seen on AXI-Lite (row by row):
- *            | Base                \    Offs  |   0    1    2  ...   2^N-2   2^N-1
- *   ---------+--------------------------------+------------------------------------
- *    Chnl #0 |   0                            |  T_0  T_1  T_2 ... T_{2^N-2}  'x
- *    Chnl #1 |   2^N                          |  T_0  T_1  T_2 ... T_{2^N-2}  'x
- *    Chnl #c | ((c/PE)*$clog2(PE) + c%PE)*2^N |  T_0  T_1  T_2 ... T_{2^N-2}  'x
+ *            | Base                \    Offs          |   0    1    2  ...   N-1   ...
+ *   ---------+----------------------------------------+---------------------------------
+ *    Chnl #0 |   0                                    |  T_0  T_1  T_2 ... T_{N-1}  'x
+ *    Chnl #1 |   2^$clog2(N)                          |  T_0  T_1  T_2 ... T_{N-1}  'x
+ *    Chnl #c | ((c/PE)*$clog2(PE) + c%PE)*2^$clog2(N) |  T_0  T_1  T_2 ... T_{N-1}  'x
  *
  *****************************************************************************/
 module thresholding #(
-	int unsigned  N,  // output precision
 	int unsigned  K,  // input/threshold precision
+	int unsigned  N,  // number of thresholds
 	int unsigned  C,  // number of channels
 	int unsigned  PE, // parallel processing elements
 
 	bit  SIGNED = 1,  // signed inputs
 	bit  FPARG  = 0,  // floating-point inputs: [sign] | exponent | mantissa
-	int  BIAS   = 0,  // offsetting the output [0, 2^N-1] -> [BIAS, 2^N-1 + BIAS]
+	int  BIAS   = 0,  // offsetting the output [0, N] -> [BIAS, N+BIAS]
 
 	// Initial Thresholds
 	parameter  THRESHOLDS_PATH = "",
@@ -72,8 +72,8 @@ module thresholding #(
 
 	localparam int unsigned  CF = C/PE,  // Channel fold
 	localparam int unsigned  O_BITS = BIAS >= 0?
-		/* unsigned */ $clog2(2**N+BIAS) :
-		/* signed */ 1+$clog2(-BIAS >= 2**(N-1)? -BIAS : 2**N+BIAS)
+		/* unsigned */ $clog2(N+BIAS+1) :
+		/* signed */ 1+$clog2(-BIAS >= N+BIAS+1? -BIAS : N+BIAS+1)
 )(
 	// Global Control
 	input	logic  clk,
@@ -82,7 +82,7 @@ module thresholding #(
 	// Threshold Configuration
 	input	logic  cfg_en,
 	input	logic  cfg_we,
-	input	logic [$clog2(CF)+$clog2(PE)+N-1:0]  cfg_a,
+	input	logic [$clog2(CF)+$clog2(PE)+$clog2(N)-1:0]  cfg_a,
 	input	logic [K-1:0]  cfg_d,
 	output	logic  cfg_rack,
 	output	logic [K-1:0]  cfg_q,
@@ -115,22 +115,25 @@ module thresholding #(
 		CFG = 2'b1x  // Config op (pointer-preserving)
 	} op_e;
 
+	//-----------------------------------------------------------------------
+	// Pipeline Feed
+	//	- M := $clog2(N+1) pipeline stages
+	//	- configuration always takes precedence
+	//	- number of pending thresholding ops capped to M+3
+	//	  across pipeline and output FIFO: pipe:M + A:1 + B:1 + 1
+	localparam int unsigned  M = $clog2(N+1);
+	localparam int unsigned  MAX_PENDING = (DEEP_PIPELINE+1)*M + 3;
+
 	// Pipeline Link Type
-	typedef logic [$clog2(CF)+N-1:0]  ptr_t;
+	typedef logic [$clog2(CF)+M-1:0]  ptr_t;
 	typedef logic [K           -1:0]  val_t;
 	typedef struct packed {
 		op_e   op;
 		ptr_t  ptr;	// WR/RB: address;         TH: result
 		val_t  val;	// WR/RB: threshold value; TH: input value
 	} pipe_t;
 
-	//-----------------------------------------------------------------------
-	// Pipeline Feed
-	//	- configuration always takes precedence
-	//	- number of pending thresholding ops capped to N+3
-	//	  across pipeline and output FIFO: pipe:N + A:1 + B:1 + 1
-	localparam int unsigned  MAX_PENDING = (DEEP_PIPELINE+1)*N + 3;
-	pipe_t  pipe[PE][N+1];
+	pipe_t  pipe[PE][M+1];
 	if(1) begin : blkFeed
 
 		// Thresholding Input Guard ensuring Output FIFO is never overrun
@@ -148,20 +151,20 @@ module thresholding #(
 		// PE Configuration Address Decoding
 		logic  cfg_sel[PE];
 		logic  cfg_oob;
-		logic [N-1:0]  cfg_ofs;
+		logic [$clog2(N)-1:0]  cfg_ofs;
 		if(PE == 1) begin
 			assign	cfg_sel[0] = 1;
 			assign	cfg_oob = 0;
-			assign	cfg_ofs = cfg_a[0+:N];
+			assign	cfg_ofs = cfg_a[0+:$clog2(N)];
 		end
 		else begin
-			uwire [$clog2(PE)-1:0]  cfg_pe = cfg_a[N+:$clog2(PE)];
+			uwire [$clog2(PE)-1:0]  cfg_pe = cfg_a[$clog2(N)+:$clog2(PE)];
 			always_comb begin
 				foreach(cfg_sel[pe]) begin
 					cfg_sel[pe] = USE_CONFIG && cfg_en && (cfg_pe == pe);
 				end
 				cfg_oob = (cfg_pe >= PE);
-				cfg_ofs = cfg_a[0+:N];
+				cfg_ofs = cfg_a[0+:$clog2(N)];
 				if(cfg_oob && !cfg_we) begin
 					// Map readbacks from padded rows (non-existent PEs) to padded highest threshold index of first PE
 					cfg_sel[0] = 1;
@@ -171,7 +174,7 @@ module thresholding #(
 		end
 
 		uwire ptr_t  iptr;
-		assign	iptr[0+:N] = cfg_ofs;
+		assign	iptr[0+:M] = cfg_ofs;	// Zero-extend Expand for N = 2^k
 		if(CF > 1) begin
 			// Channel Fold Rotation
 			logic [$clog2(CF)-1:0]  CnlCnt = 0;
@@ -187,7 +190,7 @@ module thresholding #(
 				end
 			end
 
-			assign  iptr[N+:$clog2(CF)] = USE_CONFIG && cfg_en? cfg_a[N+$clog2(PE)+:$clog2(CF)] : CnlCnt;
+			assign  iptr[M+:$clog2(CF)] = USE_CONFIG && cfg_en? cfg_a[$clog2(N)+$clog2(PE)+:$clog2(CF)] : CnlCnt;
 		end
 
 		for(genvar  pe = 0; pe < PE; pe++) begin
@@ -205,9 +208,9 @@ module thresholding #(
 
 	//-----------------------------------------------------------------------
 	// Free-Running Thresholding Pipeline
-	for(genvar  stage = 0; stage < N; stage++) begin : genStages
+	for(genvar  stage = 0; stage < M; stage++) begin : genStages
 
-		localparam int unsigned  SN = N-1-stage;
+		localparam int unsigned  SN = M-1-stage;
 		for(genvar  pe = 0; pe < PE; pe++) begin : genPE
 			uwire pipe_t  p = pipe[pe][stage];
 			uwire  cs = (p.ptr[SN:0] == 2**SN-1);
@@ -222,7 +225,7 @@ module thresholding #(
 					// If BRAM trigger defined, force distributed memory below if Vivado may be tempted to use BRAM nonetheless.
 					DEPTH_TRIGGER_BRAM && (DEPTH >= 64)? "distributed" : "auto";
 
-				(* DONT_TOUCH = "true", RAM_STYLE = RAM_STYLE *)
+                                (* DONT_TOUCH = "true", RAM_STYLE = RAM_STYLE *)
 				val_t  Threshs[DEPTH];
 				if(THRESHOLDS_PATH != "") begin
 					initial  $readmemh($sformatf("%sthreshs_%0d_%0d.dat", THRESHOLDS_PATH, pe, stage), Threshs);
@@ -236,7 +239,7 @@ module thresholding #(
 						end
 					end
 					else begin
-						uwire [$clog2(CF)+stage-1:0]  addr = p.ptr[$clog2(CF)+N-1:SN+1];
+						uwire [$clog2(CF)+stage-1:0]  addr = p.ptr[$clog2(CF)+M-1:SN+1];
 						always @(posedge clk) begin
 							if(we)  Threshs[addr] <= p.val;
 						end
@@ -247,7 +250,7 @@ module thresholding #(
 					assign	Thresh = Threshs[0];
 				end
 				else begin
-					uwire [$clog2(CF)+stage-1:0]  addr = p.ptr[$clog2(CF)+N-1:SN+1];
+					uwire [$clog2(CF)+stage-1:0]  addr = p.ptr[$clog2(CF)+M-1:SN+1];
 					always_ff @(posedge clk) begin
 						Thresh <= Threshs[addr];
 					end
@@ -256,19 +259,30 @@ module thresholding #(
 			end : blkThresh
 
 			// Pipeline State
+			localparam int unsigned  SCOPE_REDUCE = (2**(M-stage-1) + 2**M-1-N) >> (M-stage);
 			pipe_t  P = '{ op: NOP, default: 'x };
-			logic   Reval = 0;
+			logic  Reval = 'x;	// Replace value by readback
+			logic  Scope = 'x;	// Comparison in scope of specified threshold count
 			always_ff @(posedge clk) begin
 				if(rst) begin
 					P <= '{ op: NOP, default: 'x };
-					Reval <= 0;
+					Reval <= 'x;
+					Scope <= 'x;
 				end
 				else begin
 					P <= p;
 					Reval <= (p.op ==? RB) && cs;
+					Scope <= (SCOPE_REDUCE == 0)? 1 : p.ptr[M-1:SN+1] < 2**stage - SCOPE_REDUCE;
 				end
 			end
 
+			always_ff @(posedge clk) begin
+				assert((P.op !=? TH) || (Scope !== 1'bx)) else begin
+					$error("%m: [%0d.%0d] Broken Scope.", pe, stage);
+				end
+			end
+
+			// Mask comparisons beyond specified threshold count
 			logic  cmp;
 			if(!SIGNED)		assign	cmp = $unsigned(Thresh) <= $unsigned(P.val);
 			else if(!FPARG)	assign	cmp =   $signed(Thresh) <=   $signed(P.val);
@@ -290,7 +304,7 @@ module thresholding #(
 			pipe_t  pp;
 			always_comb begin
 				pp = P;
-				if(P.op !=? CFG)  pp.ptr[SN] = cmp;
+				if(P.op !=? CFG)  pp.ptr[SN] = Scope && cmp;
 				if(Reval)         pp.val = Thresh;
 			end
 
@@ -301,7 +315,12 @@ module thresholding #(
 				pipe_t  Pf = '{ op: NOP, default: 'x };
 				always_ff @(posedge clk) begin
 					if(rst)  Pf <= '{ op: NOP, default: 'x };
-					else     Pf <= pp;
+					else begin
+						assert((pp.op !=? TH) || (^pp.ptr[$left(ptr_t):SN] !== 1'bx)) else begin
+							$error("%m: [%0d.%0d] Broken ptr[$left:%0d].", pe, stage, SN);
+						end
+						Pf <= pp;
+					end
 				end
 				assign	pf = Pf;
 			end
@@ -317,34 +336,34 @@ module thresholding #(
 		cfg_rack = 0;
 		cfg_q = 0;
 		foreach(pipe[pe]) begin
-			automatic pipe_t  p = pipe[pe][N];
+			automatic pipe_t  p = pipe[pe][M];
 			cfg_rack |= p.op ==? RB;
 			cfg_q    |= p.val;
 		end
 	end
 
 	//-----------------------------------------------------------------------
 	// Stream Output through FIFO
-	//	- Depth of N + Output Reg to allow pipe to drain entirely under backpressure
+	//	- Depth of M + Output Reg to allow pipe to drain entirely under backpressure
 	//	- Typically mapped to an SRL shift register
 	if(1) begin : blkStreamOutput
 		localparam int unsigned  A_DEPTH = MAX_PENDING - 1;
-		logic        [PE-1 : 0][N-1 : 0]  ADat[A_DEPTH];
+		logic        [PE-1 : 0][M-1 : 0]  ADat[A_DEPTH];
 		logic signed [$clog2(A_DEPTH):0]  APtr = '1;	// -1, 0, 1, ..., A_DEPTH-1
 		uwire  avld = !APtr[$left(APtr)];
 
-		logic [PE-1:0][N-1:0]  BDat = 'x;
+		logic [PE-1:0][M-1:0]  BDat = 'x;
 		logic  BVld =  0;
 
-		uwire  aload = pipe[0][N].op ==? TH;
+		uwire  aload = pipe[0][M].op ==? TH;
 		uwire  bload = !BVld || ordy;
 
 		always_ff @(posedge clk) begin
 			if(aload) begin
 				assert(APtr < $signed(A_DEPTH-1)) else begin
 					$error("Overrun after failing stream guard.");
 				end
-				foreach(pipe[pe])  ADat[0][pe] <= pipe[pe][N].ptr;
+				foreach(pipe[pe])  ADat[0][pe] <= pipe[pe][M].ptr;
 				for(int unsigned  i = 1; i < A_DEPTH; i++)  ADat[i] <= ADat[i-1];
 			end
 		end

finn-rtllib/thresholding/hdl/thresholding_axi.sv

@@ -39,9 +39,9 @@
  *****************************************************************************/
 
 module thresholding_axi #(
-	int unsigned  N,	// output precision
 	int unsigned  WI,	// input precision
 	int unsigned  WT,	// threshold precision
+	int unsigned  N,	// number of thresholds
 	int unsigned  C = 1,	// Channels
 	int unsigned  PE = 1,	// Processing Parallelism, requires C = k*PE
 
@@ -51,7 +51,6 @@ module thresholding_axi #(
 
 	// Initial Thresholds
 	parameter  THRESHOLDS_PATH = "",
-
 	bit  USE_AXILITE,	// Implement AXI-Lite for threshold read/write
 
 	// Force Use of On-Chip Memory Blocks
@@ -60,10 +59,10 @@ module thresholding_axi #(
 	bit  DEEP_PIPELINE = 0,
 
 	localparam int unsigned  CF = C/PE,	// Channel Fold
-	localparam int unsigned  ADDR_BITS = $clog2(CF) + $clog2(PE) + N + 2,
+	localparam int unsigned  ADDR_BITS = $clog2(CF) + $clog2(PE) + $clog2(N) + 2,
 	localparam int unsigned  O_BITS = BIAS >= 0?
-		/* unsigned */ $clog2(2**N+BIAS) :
-		/* signed */ 1+$clog2(-BIAS >= 2**(N-1)? -BIAS : 2**N+BIAS)
+		/* unsigned */ $clog2(N+BIAS+1) :
+		/* signed */ 1+$clog2(-BIAS >= N+BIAS+1? -BIAS : N+BIAS+1)
 )(
 	//- Global Control ------------------
 	input	logic  ap_clk,
@@ -116,7 +115,7 @@ module thresholding_axi #(
 
 	if(USE_AXILITE) begin
 		uwire [ADDR_BITS-1:0]  cfg_a0;
-		axi4lite_if #(.ADDR_WIDTH(ADDR_BITS), .DATA_WIDTH(32), .IP_DATA_WIDTH(WT)) axi (
+		axilite_if #(.ADDR_WIDTH(ADDR_BITS), .DATA_WIDTH(32), .IP_DATA_WIDTH(WT)) axi (
 			.aclk(ap_clk), .aresetn(ap_rst_n),
 
 			.awready(s_axilite_AWREADY), .awvalid(s_axilite_AWVALID), .awaddr(s_axilite_AWADDR), .awprot('x),
@@ -178,7 +177,7 @@ module thresholding_axi #(
 	//-----------------------------------------------------------------------
 	// Kernel Implementation
 	thresholding #(
-		.N(N), .K(WT), .C(C), .PE(PE),
+		.K(WT), .N(N), .C(C), .PE(PE),
 		.SIGNED(SIGNED), .FPARG(FPARG), .BIAS(BIAS),
 		.THRESHOLDS_PATH(THRESHOLDS_PATH), .USE_CONFIG(USE_AXILITE),
 		.DEPTH_TRIGGER_URAM(DEPTH_TRIGGER_URAM), .DEPTH_TRIGGER_BRAM(DEPTH_TRIGGER_BRAM),

finn-rtllib/thresholding/hdl/thresholding_template_wrapper.v

@@ -33,9 +33,9 @@
  */
 
 module $MODULE_NAME_AXI_WRAPPER$ #(
-	parameter  N = $N$,		// output precision
 	parameter  WI = $WI$,	// input precision
 	parameter  WT = $WT$,	// threshold precision
+	parameter  N = $N$,		// number of thresholds
 	parameter  C = $C$,	// Channels
 	parameter  PE = $PE$,	// Processing Parallelism, requires C = k*PE
 
@@ -64,7 +64,7 @@ module $MODULE_NAME_AXI_WRAPPER$ #(
 	// Writing
 	input   s_axilite_AWVALID,
 	output  s_axilite_AWREADY,
-	input [$clog2(C/PE) + $clog2(PE) + N + 1:0]  s_axilite_AWADDR,	// lowest 2 bits (byte selectors) are ignored
+	input [$clog2(C/PE) + $clog2(PE) + $clog2(N) + 1:0]  s_axilite_AWADDR,	// lowest 2 bits (byte selectors) are ignored
 
 	input         s_axilite_WVALID,
 	output        s_axilite_WREADY,
@@ -78,7 +78,7 @@ module $MODULE_NAME_AXI_WRAPPER$ #(
 	// Reading
 	input   s_axilite_ARVALID,
 	output  s_axilite_ARREADY,
-	input [$clog2(C/PE) + $clog2(PE) + N + 1:0]  s_axilite_ARADDR,
+	input [$clog2(C/PE) + $clog2(PE) + $clog2(N) + 1:0]  s_axilite_ARADDR,
 
 	output         s_axilite_RVALID,
 	input          s_axilite_RREADY,