Merge branch 'dev' into custom/transformer

Author: auphelia

.readthedocs.yaml

@@ -36,7 +36,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.10"
 
 sphinx:
    configuration: docs/finn/conf.py

docker/finn_entrypoint.sh

@@ -155,7 +155,7 @@ else
   echo "See https://docs.xilinx.com/r/en-US/ug835-vivado-tcl-commands/Tcl-Initialization-Scripts"
 fi
 
-export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$VITIS_PATH/lnx64/tools/fpo_v7_1"
+export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$VITIS_PATH/lnx64/tools/fpo_v7_1:$HLS_PATH/lnx64/tools/fpo_v7_1"
 
 export PATH=$PATH:$HOME/.local/bin
 

docker/jenkins/Jenkinsfile

@@ -6,6 +6,17 @@ pipeline {
     booleanParam(name: 'end2end', defaultValue: false, description: 'Run end2end tests')
   }
   stages {
+    stage('Prune docker') {
+      agent {
+        label 'finn-build'
+      }
+      steps {
+        script {
+          // Prune old docker containers
+          sh "docker system prune -a -f"
+        }
+      }
+    }
     stage('Run Tests') {
       parallel {
         stage('Sanity - Build Hardware') {

fetch-repos.sh

@@ -32,7 +32,7 @@ QONNX_COMMIT="9036148104d9a5f731dfd7abc794184bd1671d9f"
 FINN_EXP_COMMIT="0724be21111a21f0d81a072fccc1c446e053f851"
 BREVITAS_COMMIT="9421f5670f990a0250128cc6285b3901b4f9ef94"
 CNPY_COMMIT="8c82362372ce600bbd1cf11d64661ab69d38d7de"
-HLSLIB_COMMIT="a19482ba6886f6f26aff11b10126a82ce0dd7ab1"
+HLSLIB_COMMIT="bf7b6ce54b0cf8a521c526ae81ddbd2bb64dbd3e"
 OMX_COMMIT="a5d48f93309b235fdd21556d16e86e6ef5db6e2e"
 AVNET_BDF_COMMIT="2d49cfc25766f07792c0b314489f21fe916b639b"
 XIL_BDF_COMMIT="8cf4bb674a919ac34e3d99d8d71a9e60af93d14e"

finn-rtllib/inner_shuffle/elasticmem.sv

@@ -0,0 +1,135 @@
+/****************************************************************************
+ * Copyright (C) 2025, Advanced Micro Devices, Inc.
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * @brief	BRAM with two output registers and streaming interface with backpressure.
+ * @author	Shane T. Fleming
+ *
+ * @description
+ *  This module implements a simple BRAM/URAM wrapper with two output
+ *  registers to allow Vivado to fuse them into the BRAM for better timing.
+ *  The read side features streaming interfaces with proper backpressure
+ *  handling via an integrated skid buffer.
+ *
+ *  The pipeline consists of:
+ *    Address -> BRAM -> Dout1 -> Dout2 -> skid buffer -> output
+ *
+ *  Backpressure is handled by the skid buffer, which can absorb data
+ *  during temporary downstream stalls while maintaining data ordering.
+ ***************************************************************************/
+
+module elasticmem #(
+	int unsigned  WIDTH,
+	int unsigned  DEPTH,
+	int unsigned  FEED_STAGES = 0,
+	parameter     RAM_STYLE = "auto"
+)(
+	input	logic  clk,
+	input	logic  rst,
+
+	// Write port (simple, no handshake)
+	input	logic [WIDTH-1:0]                wr_data,
+	input	logic [$clog2(DEPTH)-1:0]        wr_addr,
+	input	logic                            wr_en,
+
+	// Read request channel (address)
+	input	logic [$clog2(DEPTH)-1:0]        rd_addr,
+	input	logic                            rd_req_vld,
+	output	logic                            rd_req_rdy,
+
+	// Read data channel (downstream)
+	output	logic [WIDTH-1:0]                rd_dat,
+	output	logic                            rd_dat_vld,
+	input	logic                            rd_dat_rdy
+);
+
+	//-----------------------------------------------------------------------
+	// BRAM and Pipeline Stages
+	(* ram_style = RAM_STYLE *)
+	logic [WIDTH-1:0]  Mem [DEPTH-1:0];
+
+	// Pipeline registers
+	logic [$clog2(DEPTH)-1:0]  AddrReg  = 'x;
+	logic                      AddrVld  =  0;
+	logic [WIDTH-1:0]          Dout1    = 'x;
+	logic                      Dout1Vld =  0;
+	logic [WIDTH-1:0]          Dout2    = 'x;
+	logic                      Dout2Vld =  0;
+
+	//-----------------------------------------------------------------------
+	// Write Port
+	always_ff @(posedge clk) begin
+		if(wr_en) begin
+			Mem[wr_addr] <= wr_data;
+		end
+	end
+
+	//-----------------------------------------------------------------------
+	// Pipeline Control Logic
+	logic  skid_irdy;
+
+	uwire stage2_advance = !Dout2Vld || skid_irdy;
+	uwire stage1_advance = !Dout1Vld || stage2_advance;
+	uwire stage0_advance = !AddrVld  || stage1_advance;
+	assign rd_req_rdy = stage0_advance;
+
+	//-----------------------------------------------------------------------
+	// Stage 0: Address Register
+	always_ff @(posedge clk) begin
+		if(rst) begin
+			AddrReg <= 'x;
+			AddrVld <= 0;
+		end
+		else if(stage0_advance) begin
+			AddrReg <= rd_addr;
+			AddrVld <= rd_req_vld;
+		end
+	end
+
+	//-----------------------------------------------------------------------
+	// Stage 1: First Memory Output Register (BRAM output)
+	always_ff @(posedge clk) begin
+		if(rst) begin
+			Dout1    <= 'x;
+			Dout1Vld <= 0;
+		end
+		else if(stage1_advance) begin
+			Dout1Vld <= AddrVld;
+			Dout1    <= Mem[AddrReg];
+		end
+	end
+
+	//-----------------------------------------------------------------------
+	// Stage 2: Second Output Register (candidate for BRAM fusion)
+	always_ff @(posedge clk) begin
+		if(rst) begin
+			Dout2    <= 'x;
+			Dout2Vld <= 0;
+		end
+		else if(stage2_advance) begin
+			Dout2Vld <= Dout1Vld;
+			Dout2    <= Dout1;
+		end
+	end
+
+	//-----------------------------------------------------------------------
+	// Skid Buffer for Backpressure Handling
+	skid #(
+		.DATA_WIDTH (WIDTH),
+		.FEED_STAGES(FEED_STAGES)
+	) u_skid (
+		.clk  (clk),
+		.rst  (rst),
+
+		.idat (Dout2),
+		.ivld (Dout2Vld),
+		.irdy (skid_irdy),
+
+		.odat (rd_dat),
+		.ovld (rd_dat_vld),
+		.ordy (rd_dat_rdy)
+	);
+
+endmodule : elasticmem

finn-rtllib/inner_shuffle/inner_shuffle.sv

@@ -56,34 +56,6 @@
  * enabling both the write path and the read path to be active simultaneously.
 ****************************************************************************/
 
-// A memory bank in the inner_shuffle design. Pattern was kept as simple
-// as possible to help with Vivado BRAM inference.
-module mem_bank #(
-	int unsigned WIDTH,
-	int unsigned DEPTH,
-	parameter RAM_STYLE = "auto"
-)(
-	input logic clk,
-
-	input logic [WIDTH-1:0] d_in,
-	input logic [$clog2(DEPTH)-1:0] wr_addr,
-	input logic wr_en,
-
-	output logic [WIDTH-1:0] d_out,
-	input  logic [$clog2(DEPTH)-1:0] rd_addr,
-	input  logic rd_en
-);
-
-	(* ram_style=RAM_STYLE *)
-	logic [WIDTH-1:0] Mem [DEPTH-1:0]; // The Mem for this bank
-	always_ff @(posedge clk) begin
-		if(wr_en)  Mem[wr_addr] <= d_in;
-		if(rd_en)  d_out <= Mem[rd_addr];
-	end
-
-endmodule : mem_bank
-
-
 // ----------------------------------------
 // Parallel Transpose Unit (InnerShuffle)
 // ----------------------------------------
@@ -124,23 +96,37 @@ module inner_shuffle #(
 	localparam int unsigned  PAGE_OFFSET =    I*J / SIMD;
 	uwire  wr_en = irdy && ivld;
 	uwire [$clog2(BANK_DEPTH)-1:0]  wr_addr;
-	uwire  rd_en;
 	uwire [BITS-1:0]                d_in      [SIMD-1:0];
 	uwire [BITS-1:0]                d_out     [SIMD-1:0];
+	uwire  rd_req_en;
+	uwire [SIMD-1:0] rd_req_rdy;
+	uwire  rd_req_rdy_all = &rd_req_rdy;
 	logic [$clog2(BANK_DEPTH)-1:0]  raddr     [SIMD-1:0];
+	uwire rd_dat_vld [SIMD-1:0];
+	uwire rd_dat_rdy;
+	assign rd_dat_rdy = osb_rdy && rd_pattern_sb_ovld;
+	uwire rd_pattern_sb_irdy;
+	uwire rd_pattern_sb_ovld;
 	for(genvar i = 0; i<SIMD; i++) begin : gen_mem_banks
-		mem_bank #(
+		elasticmem #(
 			.WIDTH(BITS),
 			.DEPTH(BANK_DEPTH),
 			.RAM_STYLE(RAM_STYLE)
-		) mem_bank_inst (
-			.clk,
-			.wr_en,
-			.wr_addr,
-			.d_in(d_in[i]),
-			.rd_en,
+		) mem_banks_inst (
+			.clk(clk),
+			.rst(rst),
+
+			.wr_data(d_in[i]),
+			.wr_addr(wr_addr),
+			.wr_en(wr_en),
+
 			.rd_addr(raddr[i]),
-			.d_out(d_out[i])
+			.rd_req_vld(rd_req_en),
+			.rd_req_rdy(rd_req_rdy[i]),
+
+			.rd_dat(d_out[i]),
+			.rd_dat_vld(rd_dat_vld[i]),
+			.rd_dat_rdy(rd_dat_rdy)
 		);
 	end : gen_mem_banks
 
@@ -221,6 +207,7 @@ module inner_shuffle #(
 
 	localparam int unsigned  RD_ROT_PERIOD = I / SIMD; // (I % SIMD == 0) is a constraint
 	typedef logic [$clog2(SIMD)-1:0]  rotidx_vec_t[SIMD-1:0];
+	typedef logic [SIMD*$clog2(SIMD)-1:0] packed_rotidx_vec_t;
 	typedef logic [$clog2(BANK_DEPTH)-1:0]  bank_addr_t [SIMD-1:0];
 
 	// --------------------------------------------------------------------------
@@ -279,7 +266,7 @@ module inner_shuffle #(
 	uwire [$clog2(BANK_DEPTH)-1:0] page_rd_offset;
 	uwire osb_rdy; // output skid buffer ready signal
 	uwire rd_guard = !CurrentPageRd && !WrJobsDone[0] && !WrJobsDone[1];
-	uwire rd_inc = osb_rdy & !rd_guard;
+	uwire rd_inc = rd_req_en && rd_req_rdy_all;
 
 	// Counts reads across the columns
 	logic[$clog2(I)-1 : 0] RdICnt = 0; // 0, ..., I - 1
@@ -349,9 +336,7 @@ module inner_shuffle #(
 	// --------------------------------------------------------------------------
 	//   Page management
 
-	logic OsbVld  = 0; // output skidbuffer valid signal
-	logic OsbVld_D = 0; // output skidbuffer valid signal
-	assign rd_en  = osb_rdy;
+	assign rd_req_en  = !rd_guard && rd_pattern_sb_irdy; // We can read once the guard is not up
 
 	always_ff @(posedge clk) begin
 		if (rst) begin
@@ -363,37 +348,26 @@ module inner_shuffle #(
 			if (wr_addr == 2*PAGE_OFFSET - 1) WrJobsDone[1] <= 1;
 
 			// Clear the relevant job once it is read
-			if (page_boundary && (osb_rdy && OsbVld)) begin
+			if (page_boundary && (rd_req_en && rd_req_rdy_all)) begin
 				WrJobsDone[CurrentPageRd] <= 0;
 		       		CurrentPageRd <= !CurrentPageRd;
 			end
 		end
 	end
 
-	assign page_rd_offset = CurrentPageRd ? 0: PAGE_OFFSET;
+	assign page_rd_offset = CurrentPageRd ? 0 : PAGE_OFFSET;
 	assign irdy = !WrJobsDone[0] || !WrJobsDone[1];
 
 	// Forward the current RD_PATTERN row onto the next pipeline stage
 	rotidx_vec_t RdPat = RD_INIT_PAT;
-	rotidx_vec_t RdPat_D = RD_INIT_PAT; // The fowarded rotation pattern
-	always_ff @(posedge clk) begin : rd_pattern_col_forwarding
-		if (rst) begin
-			OsbVld <= 0;
-			RdPat_D <= RD_INIT_PAT;
-		end
-		else begin
-			OsbVld <= !rd_guard;
-			OsbVld_D <= OsbVld;
-			if (rd_inc) RdPat_D <= RdPat;
-			if(OsbVld & rd_guard & !osb_rdy) OsbVld <= 1;
-		end
-	end : rd_pattern_col_forwarding
+	packed_rotidx_vec_t rd_pat_forwarded_packed;
+	rotidx_vec_t rd_pat_forwarded;
 
 	// Structural remapping using the output of the memory banks
 	// and the Read rotation from the previous clock cycle that was
 	// used to generate the read addresses.
     	uwire [SIMD-1:0][BITS-1:0] remapped_data; // remapped output
-	for(genvar i=0; i<SIMD; i++) assign remapped_data[i] = d_out[RdPat_D[i]];
+	for(genvar i=0; i<SIMD; i++) assign remapped_data[i] = d_out[rd_pat_forwarded[i]];
 
 	// the next permutation of the rd pattern
 	rotidx_vec_t rd_pat_next;
@@ -433,11 +407,32 @@ module inner_shuffle #(
 			end
 		end
 	end : rd_pattern_assignment
+
+
+	//=======================================================================
+	skid #(
+		.DATA_WIDTH($bits(packed_rotidx_vec_t))
+	)
+	rd_pattern_skid (
+		.clk(clk),
+		.rst(rst),
+
+		.idat(packed_rotidx_vec_t'(RdPat)),
+		.ivld(rd_req_en),
+		.irdy(rd_pattern_sb_irdy),
+
+		.odat(rd_pat_forwarded_packed),
+		.ovld(rd_pattern_sb_ovld),
+		.ordy(osb_rdy && rd_dat_vld[0])
+	);
+
+	assign rd_pat_forwarded = rotidx_vec_t'(rd_pat_forwarded_packed);
 	// --------------------------------------------------------------------------
 
 	//=======================================================================
 	// Output SkidBuffer -- Used to decouple control signals for timing
 	// improvements
+	uwire osb_vld = rd_pattern_sb_ovld && rd_dat_vld[0];
 	skid #(
 		.DATA_WIDTH(SIMD*BITS)
 	)
@@ -446,7 +441,7 @@ module inner_shuffle #(
 		.rst(rst),
 
 		.idat(remapped_data),
-		.ivld(OsbVld),
+		.ivld(osb_vld),
 		.irdy(osb_rdy),
 
 		.odat(odat),