Generalised Transpose and Reshape support

custom_hls/bs_utils.hpp

@@ -0,0 +1,134 @@
+/****************************************************************************
+ * Copyright (C) 2025, Advanced Micro Devices, Inc.
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * @author	Shane T. Fleming <[email protected]>
+ ****************************************************************************/
+
+#ifndef SM_UTIL_HPP
+#define SM_UTIL_HPP
+#include "hls_vector.h"
+
+//- Compile-Time Functions --------------------------------------------------
+
+// ceil(log2(x))
+//template<typename T>
+//constexpr unsigned clog2(T  x) {
+//  return  x<2? 0 : 1+clog2((x+1)/2);
+//}
+
+//- Streaming Flit with `last` Marking --------------------------------------
+template<typename T>
+struct flit_t {
+	bool  last;
+	T     data;
+
+public:
+	flit_t(bool  last_, T const &data_) : last(last_), data(data_) {}
+	~flit_t() {}
+};
+
+//- Streaming Copy ----------------------------------------------------------
+template<typename T>
+void move(hls::stream<T> &src, hls::stream<T> &dst) {
+#pragma HLS pipeline II=1 style=flp
+	if(!src.empty())  dst.write(src.read());
+}
+
+//- Tree Reduce -------------------------------------------------------------
+template< unsigned long  N, typename  TA, typename  TR = TA, typename  F >
+TR tree_reduce(hls::stream<TA> &v, F f) {
+#pragma HLS inline
+#pragma HLS function_instantiate variable=f
+        TR  tree[2*N-1];
+#pragma HLS array_partition complete dim=1 variable=tree
+        for(unsigned  i = N; i-- > 0;) {
+#pragma HLS unroll
+                tree[N-1 + i] = v.read();
+        }
+        for(unsigned  i = N-1; i-- > 0;) {
+#pragma HLS unroll
+                tree[i] = f(tree[2*i+1], tree[2*i+2]);
+        }
+        return  tree[0];
+}
+
+// Recursive comparison and count (of max)
+// Builds a tree to compute the max of a vector
+template<unsigned N, typename T>
+struct MaxReduction {
+
+    static T max(const hls::vector<T, N>& input) {
+#pragma HLS INLINE
+        constexpr unsigned M = (N + 1) / 2;
+        hls::vector<T, M> res;
+
+        for(unsigned i = 0; i < M; ++i) {
+#pragma HLS unroll
+            if (2*i + 1 < N)
+                res[i] = input[2*i] > input[2*i + 1] ? input[2*i] : input[2*i + 1];
+            else
+                res[i] = input[2*i]; // Handle the case where the input size is odd
+        }
+
+        return MaxReduction<M, T>::max(res);
+    }
+
+};
+
+template<typename T>
+struct MaxReduction<2, T> {
+    static T max(const hls::vector<T, 2>& input) {
+#pragma HLS INLINE
+        return (input[0] > input[1]) ? input[0] : input[1];
+    }
+};
+
+template<typename T>
+struct MaxReduction<1, T> {
+    static T max(const hls::vector<T, 1>& input) {
+#pragma HLS INLINE
+        return input[0];
+    }
+};
+
+// Recursive reduction tree for the total summation
+// Code for the Nth stage
+template<typename T, unsigned N>
+struct TreeReduction {
+    static T reduce(const hls::vector<T, N>& input) {
+#pragma HLS INLINE
+        constexpr unsigned M = (N + 1) / 2;
+        hls::vector<T, M> sum;
+
+        for(unsigned i = 0; i < M; ++i) {
+#pragma HLS unroll
+            if (2*i + 1 < N)
+                sum[i] = input[2*i] + input[2*i + 1];
+            else
+                sum[i] = input[2*i]; // Handle the case where the input size is odd
+        }
+
+        return TreeReduction<T, M>::reduce(sum);
+    }
+};
+
+template<typename T>
+struct TreeReduction<T, 2> {
+    static T reduce(const hls::vector<T, 2>& input) {
+#pragma HLS INLINE
+        return input[0] + input[1];
+    }
+};
+
+template<typename T>
+struct TreeReduction<T, 1> {
+    static T reduce(const hls::vector<T, 1>& input) {
+#pragma HLS INLINE
+        return input[0];
+    }
+};
+
+#endif

custom_hls/input_gen.hpp

@@ -0,0 +1,237 @@
+/****************************************************************************
+ * Copyright (C) 2025, Advanced Micro Devices, Inc.
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * @author	Thomas B. Preußer <[email protected]>
+ ****************************************************************************/
+
+#ifndef INPUT_GEN_HPP
+#define INPUT_GEN_HPP
+
+#include <ap_int.h>
+#include <hls_stream.h>
+#include "bs_utils.hpp"
+
+#include <algorithm>
+#include <tuple>
+#include <type_traits>
+
+/**
+ * Computes the updates of the read and free pointers for a buffer read out by
+ * the specified loop nest.
+ *
+ * @param  R	also responsible for the update of the free pointer
+ * @param  V	loop nest specifiction, odd length, see specializations
+ *
+ * A given perfect loop nest:
+ *
+ *	for(unsigned  i0 = 0; i0 < N0; i0++) {
+ *		for(unsigned  i1 = 0; i1 < N1; i1++) {
+ *			...
+ *			for(unsigned  in = 0; in < Nn; in++) {
+ *				emit(ifm[C0*i0 + C1*i1 + ... + Cn*in]);
+ *			}
+ *			...
+ *		}
+ *	}
+ *
+ * encodes as:
+ *
+ *	Nest<true, IFM_SIZE, N0, C0, N1, C1, ..., Nn, Cn>
+ *
+ * As this class computes relative updates by each invocation of `tick()`,
+ * an absolute offset must be reflected in the original pointer initialization.
+ * The contract for a directly enclosed loop is:
+ *	- For the total of an entire period of increments, the cumulative read pointer
+ *	  updates amount to the number immediately preceding its execution count.
+ *	- The free pointer is incremented in lockstep if R is true and if this loops
+ *	  own increments are positive and would fit entirely into a period of the
+ *	  enclosing loop.
+ * Currently, all coefficients Ci must be positive. The implication is that
+ * every completed loop induces a net non-negative read-pointer increment.
+ * Negative read pointer updates are only possible by loop termination leaving
+ * a net positive update for the enclosing loop but possibly retracting the read
+ * pointer back to the expected enclosing increment after overshooting
+ * internally.
+ * As each completed loop guarantees a net positive increment, negative pointer
+ * retractions never add up. Thus, the biggest retraction can be used to
+ * dimension provided buffer storage.
+ */
+template<bool R, unsigned... V>
+class Nest {};
+
+/**
+ * Terminal innermost loop.
+ *
+ * @param  R	also responsible for the update of the free pointer
+ * @param  W	represented increment of read pointer
+ */
+template<
+	bool      R,
+	unsigned  W
+>
+class Nest<R, W> {
+public:
+	static constexpr unsigned  rp_rewind = 0;
+	static constexpr unsigned  fp_rewind = 0;
+
+	static constexpr int  max_rp_retract = 0;
+
+public:
+	std::tuple<int, unsigned, ap_int<1>> tick() {
+#pragma HLS inline
+		return  { W, R? W : 0, -1 };
+	}
+};
+
+/**
+ * Non-terminal loop.
+ *
+ * @param  R	also responsible for the update of the free pointer
+ * @param  W	represented increment of read pointer
+ * @param  N	iteration count of directly enclosed loop
+ * @param  C	increment of read pointer by directly enclosed loop
+ * @param  V	further nested loops
+ *
+ *	- Each non-terminal loop will slice off two values, W & N, from the
+ *	  specification vector V.
+ *	- The directly enclosed loop will inherit responsibility for the
+ *	  free pointer update only if it represents a strictly monotonic increase
+ *	  contained entirely within the pointer update of this loop.
+ */
+template<
+	bool      R,
+	unsigned  W,
+	unsigned  N,
+	unsigned  C,
+	unsigned... V
+>
+class Nest<R, W, N, C, V...> {
+
+	static constexpr bool  R_INNER = R && (0 < C) && (C*N <= W);
+	using  Inner = Nest<R_INNER, C, V...>;
+
+public:
+	static constexpr unsigned  rp_rewind = (N-1)*C + Inner::rp_rewind;
+	static constexpr unsigned  fp_rewind = R_INNER? (N-1)*C + Inner::fp_rewind : 0;
+
+private:
+	static constexpr int  terminal_rp_inc = W - rp_rewind;
+public:
+	static constexpr int  max_rp_retract = std::max(-terminal_rp_inc, Inner::max_rp_retract);
+
+private:
+	static_assert(N > 0, "Must have positive iteration count.");
+	ap_int<1+clog2(std::max(1u, N-1))>  cnt = N-2;	// N-2, N-1, ..., 1, 0, -1
+	Inner  inner;
+
+public:
+	std::tuple<int, unsigned, ap_int<2+sizeof...(V)/2>> tick() {
+#pragma HLS inline
+		auto const  t = inner.tick();
+		int       rp_inc = std::get<0>(t);
+		unsigned  fp_inc = std::get<1>(t);
+		ap_int<2+sizeof...(V)/2>  term = std::get<2>(t);
+
+		if(term < 0) {
+			if(cnt < 0) {
+				rp_inc = terminal_rp_inc;
+				if(R)  fp_inc = W - fp_rewind;
+				cnt = N-2;
+			}
+			else {
+				term[decltype(term)::width-1] = 0;
+				cnt--;
+			}
+		}
+		return { rp_inc, fp_inc, term };
+	}
+};
+
+/**
+ * Input generator:
+ *	- over a feature map of pixels of type T
+ *	- iterated over by the loop nest specified by V
+ *	- optionally identifying the completion of a kernel produced by the M innermost loops.
+ *
+ * @param	M	innermost loop count constituting a kernel
+ *		M <  0 - no `last` indicator on destination stream
+ *		M >= 0 - `last` indicator on destination stream:
+ *			0 - always asserted
+ *			1 - upon completion of innermost loop
+ *			M - upon completion of M innermost loops
+ * @param	V	loop nest descriptor, see above for Nest<>
+ * @param	T	(inferred) pixel type
+ */
+template<int  M, unsigned... V, typename  T>
+void input_gen(
+	hls::stream<T> &src,
+	hls::stream<typename std::conditional<M < 0, T, flit_t<T>>::type> &dst
+) {
+#pragma HLS pipeline II=1 style=flp
+
+	// Write Pointer update delay needed to accommodate memory read-out latency.
+	constexpr unsigned  WP_DELAY = 4;
+
+	using  MyNest = Nest<true, V...>;
+	constexpr unsigned  ADDR_BITS = clog2(2*MyNest::max_rp_retract + WP_DELAY);
+	constexpr unsigned  BUF_SIZE  = 1 << ADDR_BITS;
+	using  ptr_t = ap_int<1 + ADDR_BITS>;
+
+	static MyNest  nest;
+	static T  buf[BUF_SIZE];
+	static ptr_t  wp[WP_DELAY] = { 0, };
+	static ptr_t  rp = 0;
+	static ptr_t  fp = 0;
+#pragma HLS reset variable=nest
+#pragma HLS reset variable=buf off
+#pragma HLS reset variable=wp
+#pragma HLS reset variable=rp
+#pragma HLS reset variable=fp
+#pragma HLS dependence variable=buf inter false
+#pragma HLS dependence variable=buf intra false
+#pragma HLS array_partition variable=wp complete
+
+	static bool  ovld = false;
+	static struct OBuf {
+		bool  lst;
+		T     dat;
+
+	public:
+		operator T const&()  const { return  dat; }
+		operator flit_t<T>() const { return { lst, dat }; }
+	} obuf;
+#pragma HLS reset variable=ovld
+#pragma HLS reset variable=obuf off
+
+	// Update delay pipeline for wp
+	for(unsigned  i = WP_DELAY-1; i > 0; i--)  wp[i] = wp[i-1];
+
+	// Read into buffer memory if capacity is available
+	if(/* wp <= fp' */ ptr_t(wp[0]-fp) >= 0) {
+		T  x;
+		if(src.read_nb(x))  buf[ap_uint<ADDR_BITS>(wp[0]++)] = x;
+	}
+
+	// Try to clear output buffer
+	if(ovld)  ovld = !dst.write_nb(obuf);
+
+	// Try to refill output buffer
+	if(!ovld) {
+		obuf.dat = buf[ap_uint<ADDR_BITS>(rp)];
+
+		if(/* rp < wp */ ptr_t(rp-wp[WP_DELAY-1]) < 0) {
+			auto const  t = nest.tick();
+			rp += std::get<0>(t);
+			fp += std::get<1>(t);
+
+			if(M >= 0)  obuf.lst = std::get<2>(t)[M];
+			ovld = true;
+		}
+	}
+
+} // input_gen()
+
+#endif