Feature/generalized-data-width-converter

streamtools.h

@@ -36,6 +36,7 @@
  *           Thomas B. Preusser <[email protected]>
  *             Marie-Curie Fellow, Xilinx Ireland, Grant Agreement No. 751339
  *           Christoph Doehring <[email protected]>
+ *           Lukas Stasytis <[email protected]>
  *
  *  @file stream-tools.h
  *
@@ -48,8 +49,9 @@
 #ifndef STREAMTOOLS_H
 #define STREAMTOOLS_H
 
-#include <ap_axi_sdata.h>
+#include "ap_axi_sdata.h"
 #include "mmv.hpp"
+#include "utils.hpp"
 
 /**
  * \brief   Stream limiter - limits the number of stream packets
@@ -572,6 +574,146 @@ void StreamingDataWidthConverter_Batch(hls::stream<ap_uint<InWidth> > & in,
   }
 }
 
+/**
+ * \brief   Generalized Stream Data Width Converter - 
+ *			Converts the width of the input stream in the output stream
+ *
+ * Used to upscale or downscale a stream, without any loss of data in the procedure. 
+ * Additionally performs padding or cropping of the streams if
+ * InWidth*NumInWords != OutWidth*NumOutWords
+ *
+ * \tparam     InWidth      Width, in number of bits, of the input stream
+ * \tparam     OutWidth     Width, in number of bits, of the output stream 
+ * \tparam     NumInWords   Number of input words to process
+ * \tparam     NumOutWords  Number of output words to process
+ *
+ * \param      in           Input stream
+ * \param      out          Output stream
+ * \param      numReps      Number of times the function has to be called
+ *
+ */
+template<
+	unsigned  InWidth,		
+	unsigned  OutWidth,		
+	unsigned  NumInWords,
+	unsigned  NumOutWords
+>
+void StreamingDataWidthConverterGeneralized_Batch(
+	hls::stream<ap_uint<InWidth>>  &in,
+	hls::stream<ap_uint<OutWidth>> &out,
+	unsigned const  numReps
+) {
+  constexpr unsigned  BufferLength = InWidth+OutWidth;
+  constexpr unsigned  NumInWordsLog = clog2(NumInWords)+1;
+  constexpr unsigned  NumOutWordsLog = clog2(NumOutWords)+1;
+  constexpr unsigned  BufferWidthLog = clog2(BufferLength)+1;
+  constexpr unsigned totalIters = (NumInWords > NumOutWords ? NumInWords : NumOutWords);
+  // we need one additional cycle per transaction for potential padding
+  unsigned const totalItersReps = totalIters*numReps+numReps;
+
+  ap_uint<NumOutWordsLog> words_written = 0;
+  ap_uint<NumInWordsLog> words_read = 0;
+  ap_uint<BufferWidthLog> els_in_buffer = 0;
+  // we allocate OutWidth extra space for cases where we have leftover from
+  // a previous word due to our els_in_buffer tracking scheme for when to 
+  // read in input (potentially introducing padding or cropping)
+  ap_uint<InWidth+OutWidth> eo = 0;
+  if (InWidth > OutWidth) {
+    // emit multiple output words per input word read
+    for (unsigned int t = 0; t < totalItersReps; t++) {
+#pragma HLS pipeline style=flp II=1
+
+	  // we reached the end of the transaction for this numReps superiteration
+	  // reset all trackers to allow further stream IO and stop padding/cropping
+
+	  // write each cycle and shift
+	  if ((words_written < NumOutWords) && (els_in_buffer >= OutWidth)) {
+	    out.write(eo(OutWidth-1,0));
+	    els_in_buffer -= OutWidth;
+	    eo = eo >> OutWidth;
+	    words_written++;
+	  }
+	  // conditionally read in
+	  if (els_in_buffer < OutWidth) {
+		if (words_read < NumInWords) {
+		  ap_uint<InWidth> const  ei = in.read();
+		  words_read++;
+		  eo(InWidth + els_in_buffer - 1, els_in_buffer) = ei;
+		}
+		// always introducing elements to provide padding functionality
+		els_in_buffer += InWidth;
+	  }
+	  if ((words_written == NumOutWords) && (words_read == NumInWords)) {
+		words_read = 0;
+		words_written = 0;
+		els_in_buffer = 0;
+	  }
+    }
+  } else if (InWidth == OutWidth) {
+	// straight-through copy
+	// NumOutWords != NumInWords if padding or cropping happened
+	// So we use one of two versions where we control how many times
+	// the streams are read/written.
+	if (NumOutWords > NumInWords) {
+		for (unsigned int j = 0; j < numReps; j++) {
+			for (unsigned int i = 0; i < totalIters; i++) {
+#pragma HLS pipeline style=flp II=1
+				ap_uint<InWidth> e = 0;
+				if(i < NumInWords) {
+					e = in.read();
+				}  
+				out.write(e);
+			}
+		}	
+	} else if (NumOutWords == NumInWords) {
+		for (unsigned int j = 0; j < numReps; j++) {
+			for (unsigned int i = 0; i < totalIters; i++) {
+#pragma HLS pipeline style=flp II=1
+				ap_uint<InWidth> const  e = in.read();
+				out.write(e);
+			}	
+		}
+	} else {
+		for (unsigned int j = 0; j < numReps; j++) {
+			for (unsigned int i = 0; i < totalIters; i++) {
+#pragma HLS pipeline style=flp II=1
+				ap_uint<InWidth> const  e = in.read();
+				if(i < NumOutWords)  out.write(e);
+			}	
+		}
+	}
+  } else { // InWidth < OutWidth
+    // read multiple input words per output word emitted
+    for (unsigned int t = 0; t < totalItersReps; t++) {
+#pragma HLS pipeline style=flp II=1
+	  // we reached the end of the transaction for this numReps superiteration
+	  // reset all trackers to allow further stream IO and stop padding/cropping
+
+	  // conditionally write out
+	  if (((els_in_buffer >= OutWidth) || (words_read >= NumInWords)) && (words_written < NumOutWords)) {
+		out.write(eo(OutWidth-1,0));
+		els_in_buffer -= OutWidth;
+		eo = eo >> OutWidth;
+		words_written++;
+	  }
+	  // read input each cycle and shift into output buffer
+	  // padding if we ran out of input words
+	  if (words_read < NumInWords) {
+		ap_uint<InWidth> const  ei = in.read();
+		eo(InWidth + els_in_buffer - 1, els_in_buffer) = ei;
+		words_read++;
+		els_in_buffer += InWidth;
+	  }
+	  if ((words_written == NumOutWords) && (words_read == NumInWords)) {
+		words_read = 0;
+		words_written = 0;
+		els_in_buffer = 0;
+	  }
+
+    }
+  }
+}
+
 /**
  * \brief   Stream Data Width Converter No Multiple - 
  *          Converts the width of the input stream in the output stream for no multiple dimensions
@@ -1082,4 +1224,4 @@ void Stream2Qdma_Batch(hls::stream<ap_uint<DataWidth> > & in, hls::stream<qdma_a
 	}
 }
 
-#endif
+#endif

tb/data/dwc_config.h

@@ -31,4 +31,5 @@
  ******************************************************************************/
 #define INPUT_WIDTH 8
 #define OUT_WIDTH 4
-#define NUM_REPEAT 4
+#define NumInWords 4
+#define NUM_REPEAT 1

tb/data/dwcgeneralized_config.h

@@ -0,0 +1,62 @@
+/******************************************************************************
+ *  Copyright (c) 2019, Xilinx, Inc.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *
+ *  1.  Redistributions of source code must retain the above copyright notice,
+ *     this list of conditions and the following disclaimer.
+ *
+ *  2.  Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in the
+ *      documentation and/or other materials provided with the distribution.
+ *
+ *  3.  Neither the name of the copyright holder nor the names of its
+ *      contributors may be used to endorse or promote products derived from
+ *      this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+ *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ *  OR BUSINESS INTERRUPTION). HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ *  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ ******************************************************************************/
+
+// pad larger output width
+#define INPUT_WIDTH 4
+#define OUT_WIDTH 13
+#define NumInWords 6
+#define NumOutWords 2
+#define NUM_REPEAT 4
+
+/* pad words on equal widths
+#define INPUT_WIDTH 4
+#define OUT_WIDTH 4
+#define NumInWords 2
+#define NumOutWords 4
+#define NUM_REPEAT 4
+*/
+
+/* pad smaller output width
+#define INPUT_WIDTH 10
+#define OUT_WIDTH 6
+#define NumInWords 1
+#define NumOutWords 2
+#define NUM_REPEAT 4
+*/
+
+/* crop smaller output width
+#define INPUT_WIDTH 10
+#define OUT_WIDTH 4
+#define NumInWords 1
+#define NumOutWords 2
+#define NUM_REPEAT 4
+*/

tb/dwc_tb.cpp

@@ -57,17 +57,16 @@
 using namespace hls;
 using namespace std;
 
-#define MAX_IMAGES 1
 void Testbench_dwc(stream<ap_uint<INPUT_WIDTH> > & in, stream<ap_uint<OUT_WIDTH> > & out, unsigned int numReps);
 
 int main()
 {
 	stream<ap_uint<INPUT_WIDTH> > input_stream("input_stream");
 	stream<ap_uint<OUT_WIDTH> > output_stream("output_stream");
-	static ap_uint<OUT_WIDTH> expected[NUM_REPEAT*MAX_IMAGES*INPUT_WIDTH/OUT_WIDTH];
+	static ap_uint<OUT_WIDTH> expected[NumInWords*NUM_REPEAT*INPUT_WIDTH/OUT_WIDTH];
 	unsigned int count_out = 0;
 	unsigned int count_in = 0;
-	for (unsigned int counter = 0; counter < NUM_REPEAT*MAX_IMAGES; counter++) {
+	for (unsigned int counter = 0; counter < NumInWords*NUM_REPEAT; counter++) {
 		ap_uint<INPUT_WIDTH> value = (ap_uint<INPUT_WIDTH>) counter;
 		input_stream.write(value);
 		if(INPUT_WIDTH < OUT_WIDTH){
@@ -96,8 +95,8 @@ int main()
 			}
 		}
 	}
-	Testbench_dwc(input_stream, output_stream, MAX_IMAGES);
-	for (unsigned int counter=0 ; counter <  NUM_REPEAT*MAX_IMAGES*INPUT_WIDTH/OUT_WIDTH; counter++)
+	Testbench_dwc(input_stream, output_stream, NUM_REPEAT);
+	for (unsigned int counter=0 ; counter <  NumInWords*INPUT_WIDTH/OUT_WIDTH; counter++)
 	{
 		ap_uint<OUT_WIDTH> value = output_stream.read();
 		if(value!= expected[counter])

tb/dwc_top.cpp

@@ -47,5 +47,5 @@ using namespace hls;
 #include "data/dwc_config.h"
 
 void Testbench_dwc(stream<ap_uint<INPUT_WIDTH> > & in, stream<ap_uint<OUT_WIDTH> > & out, unsigned int numReps){
-	StreamingDataWidthConverter_Batch<INPUT_WIDTH, OUT_WIDTH, NUM_REPEAT>(in, out, numReps);
+	StreamingDataWidthConverter_Batch<INPUT_WIDTH, OUT_WIDTH, NumInWords>(in, out, numReps);
 }