elastic buffers classification

hw/rtl/libs/VX_stream_buffer

@@ -0,0 +1,128 @@
+// Copyright 2024 blaise
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// A stream elastic buffer operates at full-bandwidth where push and pop can happen simultaneously
+// It has the following benefits:
+// + full-bandwidth throughput
+// + ready_in and ready_out are decoupled
+// + data_out can be fully registered
+// It has the following limitations:
+// - requires two registers for storage
+
+`include "VX_platform.vh"
+
+`TRACING_OFF
+module VX_stream_buffer #(
+    parameter DATAW    = 1,
+	parameter OUT_REG  = 0,
+    parameter PASSTHRU = 0
+) ( 
+    input  wire             clk,
+    input  wire             reset,
+    input  wire             valid_in,
+    output wire             ready_in,        
+    input  wire [DATAW-1:0] data_in,
+    output wire [DATAW-1:0] data_out,
+    input  wire             ready_out,
+    output wire             valid_out
+); 
+    if (PASSTHRU != 0) begin
+        `UNUSED_VAR (clk)
+        `UNUSED_VAR (reset)
+        assign ready_in  = ready_out;
+        assign valid_out = valid_in;        
+        assign data_out  = data_in;
+    end else begin
+		if (OUT_REG != 0) begin
+
+			reg [DATAW-1:0] data_out_r;
+			reg [DATAW-1:0] buffer;
+			reg             valid_out_r;
+			reg             use_buffer;
+			
+			wire push = valid_in && ready_in;
+			wire stall_out = valid_out_r && ~ready_out;
+			
+			always @(posedge clk) begin
+				if (reset) begin
+					valid_out_r <= 0; 
+					use_buffer  <= 0;
+				end else begin
+					if (ready_out) begin
+						use_buffer <= 0;
+					end else if (valid_in && valid_out) begin
+						use_buffer <= 1;
+					end
+					if (~stall_out) begin
+						valid_out_r <= valid_in || use_buffer;
+					end
+				end
+			end
+
+			always @(posedge clk) begin
+				if (push) begin
+					buffer <= data_in;
+				end
+				if (~stall_out) begin
+					data_out_r <= use_buffer ? buffer : data_in;
+				end
+			end
+
+			assign ready_in  = ~use_buffer;
+			assign valid_out = valid_out_r;
+			assign data_out  = data_out_r;
+
+		end else begin
+
+			reg [1:0][DATAW-1:0] shift_reg;
+			reg valid_out_r, ready_in_r, rd_ptr_r;
+
+			wire push = valid_in && ready_in;
+			wire pop = valid_out_r && ready_out;
+
+			always @(posedge clk) begin
+				if (reset) begin
+					valid_out_r <= 0;
+					ready_in_r  <= 1;
+					rd_ptr_r    <= 1;
+				end else begin
+					if (push) begin
+						if (!pop) begin                            
+							ready_in_r  <= rd_ptr_r;
+							valid_out_r <= 1;
+						end
+					end else if (pop) begin
+						ready_in_r  <= 1;
+						valid_out_r <= rd_ptr_r;
+					end
+					rd_ptr_r <= rd_ptr_r ^ (push ^ pop);
+				end                   
+			end
+
+			always @(posedge clk) begin
+				if (push) begin
+					shift_reg[1] <= shift_reg[0];
+					shift_reg[0] <= data_in;
+				end
+			end
+
+			assign ready_in  = ready_in_r;
+			assign valid_out = valid_out_r;
+			assign data_out  = shift_reg[rd_ptr_r];
+		end
+    end
+
+endmodule
+`TRACING_ON
+