template class xf::dsp::aie::fir::tdm::fir_tdm_graph

#include "fir_tdm_graph.hpp"

Overview

fir_tdm is a Time-Division Multiplexing (TDM) FIR filter

These are the templates to configure the TDM FIR class.

Parameters:

TT_DATA	describes the type of individual data samples input to the filter function. This is a typename and must be one of the following: int16, cint16, int32, cint32, float, cfloat.
TT_COEFF	describes the type of individual coefficients of the filter taps. It must be one of the same set of types listed for TT_DATA and must also satisfy the following rules: Complex types are only supported when `TT_DATA` is also complex. `TT_COEFF` must be an integer type if TT_DATA is an integer type `TT_COEFF` must be a float type if TT_DATA is a float type.
TP_FIR_LEN	is an unsigned integer which describes the number of taps in the filter.
TP_SHIFT	describes power of 2 shift down applied to the accumulation of FIR terms before output. `TP_SHIFT` must be in the range 0 to 59 (61 for AIE1).
TP_RND	describes the selection of rounding to be applied during the shift down stage of processing. Although, TP_RND accepts unsigned integer values descriptive macros are recommended where rnd_floor = Truncate LSB, always round down (towards negative infinity). rnd_ceil = Always round up (towards positive infinity). rnd_sym_floor = Truncate LSB, always round towards 0. rnd_sym_ceil = Always round up towards infinity. rnd_pos_inf = Round halfway towards positive infinity. rnd_neg_inf = Round halfway towards negative infinity. rnd_sym_inf = Round halfway towards infinity (away from zero). rnd_sym_zero = Round halfway towards zero (away from infinity). rnd_conv_even = Round halfway towards nearest even number. rnd_conv_odd = Round halfway towards nearest odd number. No rounding is performed on ceil or floor mode variants. Other modes round to the nearest integer. They differ only in how they round for values of 0.5. Note: Rounding modes `rnd_sym_floor` and `rnd_sym_ceil` are only supported on AIE-ML and AIE-MLv2 device.
TP_INPUT_WINDOW_VSIZE	describes the number of samples processed by the graph in a single iteration run. Samples are buffered and stored in a ping-pong window buffer mapped onto Memory Group banks. Note: Margin size should not be included in `TP_INPUT_WINDOW_VSIZE` . Note: `TP_INPUT_WINDOW_VSIZE` must be an integer multiple of number of TDM Channels `TP_TDM_CHANNELS` .
TP_TDM_CHANNELS	describes the number of TDM Channels processed by the FIR. Each kernel requires storage for all taps and all channels it is required to operate on, i.e. requires storage for: `TP_FIR_LEN * TP_TDM_CHANNELS` . Note: For SSR configurations (TP_SSR>1), TDM Channels coefficients will be split over multiple paths, in a round-robin fashion.
TP_NUM_OUTPUTS	sets the number of ports to broadcast the output to. Note: Dual output ports are not supported at this time.
TP_DUAL_IP	allows 2 stream inputs to be connected to FIR, increasing available throughput. Note: Dual input ports are not supported at this time.
TP_SSR	specifies the number of parallel input/output paths where samples are interleaved between paths, giving an overall higher throughput. A `TP_SSR` of 1 means just one output leg and 1 input phase. The number of AIE kernels created is equal to `TP_SSR` . For SSR configurations (TP_SSR>1), the input data must be split over multiple ports, where each successive sample is sent to a different input port in a round-robin fashion. Each path will have a dedicated input buffer of size defined by `TP_INPUT_WINDOW_VSIZE / TP_SSR` . In addition, TDM Channels coefficients will be split over multiple paths, in a round-robin fashion. Finally, computed output samples will also be split over SSR number of output paths. Each path will have a dedicated output buffer of size defined by `TP_INPUT_WINDOW_VSIZE / TP_SSR` .
TP_SAT	describes the selection of saturation to be applied during the shift down stage of processing. TP_SAT accepts unsigned integer values, where: 0: none = No saturation is performed and the value is truncated on the MSB side. 1: saturate = Default. Saturation rounds an n-bit signed value in the range [- ( 2^(n-1) ) : +2^(n-1) - 1 ]. 3: symmetric = Controls symmetric saturation. Symmetric saturation rounds an n-bit signed value in the range [- ( 2^(n-1) -1 ) : +2^(n-1) - 1 ].
TP_CASC_LEN	describes the number of AIE processors to split the operation over. This allows resource to be traded for higher performance. TP_CASC_LEN must be in the range 1 (default) to 40.
TT_OUT_DATA	describes the type of output data samples from the filter function. It must be one of the same set of types listed for `TT_DATA` , i.e. int16, cint16, int32, cint32, float, cfloat. `TT_OUT_DATA` must also satisfy the following rules: Complex types are only supported when `TT_DATA` is also complex. `TT_OUT_DATA` must be same or greater precision, e.g. 32-bit `TT_OUT_DATA` , when `TT_DATA` is 16-bit. `TT_OUT_DATA` must be an integer type if `TT_DATA` is an integer type `TT_OUT_DATA` must be a float type if `TT_DATA` is a float type.
TP_USE_COEFF_RELOAD	allows the user to select if runtime coefficient reloading should be used. When defining the parameter: 0 = static coefficients, defined in filter constructor, 1 = reloadable coefficients, passed as argument to runtime function. Note: when used, async port: `port_conditional_array<input, (TP_USE_COEFF_RELOAD == 1), (TP_SSR * TP_CASC_LEN)> coeff;` will be added to the FIR. Note: the size of the port array is equal to the total number of kernels (TP_SSR TP_CASC_LEN). Note: each port should contain portion of the coefficient array contents. To get the contents for each port, please use a helper method `extractTaps` of the `fir_tdm_graph` class.

template <
    typename TT_DATA,
    typename TT_COEFF,
    unsigned int TP_FIR_LEN,
    unsigned int TP_SHIFT,
    unsigned int TP_RND,
    unsigned int TP_INPUT_WINDOW_VSIZE,
    unsigned int TP_TDM_CHANNELS = 1,
    unsigned int TP_NUM_OUTPUTS = 1,
    unsigned int TP_DUAL_IP = 0,
    unsigned int TP_SSR = 1,
    unsigned int TP_SAT = 1,
    unsigned int TP_CASC_LEN = 1,
    typename TT_OUT_DATA = TT_DATA,
    unsigned int TP_USE_COEFF_RELOAD = 0
    >
class fir_tdm_graph: public graph

// typedefs

typedef port_conditional_array <input, (TP_USE_COEFF_RELOAD==1), (TP_SSR*TP_CASC_LEN)> rtp_port_array

// structs

struct first_casc_params

template <
    int dim,
    int tdmChannels = TP_TDM_CHANNELS
    >
struct ssr_params

// fields

kernel m_firKernels[TP_SSR *TP_CASC_LEN]
port_array <input, TP_SSR> in
port_array <output, TP_SSR> out
rtp_port_array coeff

Fields

kernel m_firKernels [TP_SSR *TP_CASC_LEN]

The array of kernels that will be created and mapped onto AIE tiles.

port_array <input, TP_SSR> in

The input data array to the function. This input array is either a window API of samples of TT_DATA type or stream API (depending on TP_API). Note: Margin is added internally to the graph, when connecting input port with kernel port. Therefore, margin should not be added when connecting graph to a higher level design unit. Margin size (in Bytes) equals to TP_FIR_LEN rounded up to a nearest multiple of 32 bytes.

port_array <output, TP_SSR> out

The output data array from the function. This output is either a window API of samples of TT_DATA type or stream API (depending on TP_API). Number of output samples is determined by interpolation & decimation factors (if present).

rtp_port_array coeff

The conditional array of input async ports used to pass run-time programmable (RTP) coefficients. This port_conditional_array is (generated when TP_USE_COEFF_RELOAD == 1) an array of input ports, which size is *defined by TP_SSR. Each port in the array holds a duplicate of the coefficient array, required to connect to each SSR input path.

Methods

getTotalRtpPorts

static constexpr unsigned int getTotalRtpPorts ()

Access function to get total number of RTP ports.

extractTaps

static std::vector <TT_COEFF> extractTaps (
    const std::vector <TT_COEFF>& taps,
    unsigned int kernelNo
    )

Access function to get a vector of taps per RTP port. Number of taps each RTP port handles may differ when TP_SSR > 1 and/or when TP_CASC_LEN > 1 .

Parameters:

taps	an std::vector of coefficients of TT_COEFF type for all channels (i.e. std::vector of `TP_FIR_LEN * TP_TDM_CHANNELS` ).
kernelNo	an index to the kernel position in the array of TDM kernels (i.e. in the array of `TP_SSR * *TP_CASC_LEN` ).

getKernels

getKernels overload (1)

kernel* getKernels ()

Access function to get pointer to kernel (or first kernel in a chained and/or SSR configurations). No arguments required.

getKernels overload (2)

kernel* getKernels (int ssrIndex)

Access function to get pointer to an indexed kernel.

Parameters:

ssrIndex

an index to the SSR data Path.

getKernelArchs

unsigned int getKernelArchs ()

Access function to get kernel’s architecture (or first kernel’s architecture in a chained configuration).

getTapsPerRtpPort

int getTapsPerRtpPort (int kernelNo)

Access function to get number taps per RTP port. Number of taps each RTP port handles may differ when TP_SSR > 1 and/or when TP_CASC_LEN > 1 .

Parameters:

kernelNo an index to the kernel position in the array of TDM kernels (i.e. in the array of TP_SSR * TP_CASC_LEN ).

fir_tdm_graph

fir_tdm_graph overload (1)

fir_tdm_graph (const std::vector <TT_COEFF>& taps)

This is the constructor function for the FIR graph with static coefficients.

Parameters:

taps

a reference to the std::vector array of taps values of type TT_COEFF. Coefficients are expected to be in a form that presents each tap for all TDM channels, followed by next tap for all TDM channels. For example, a 4 tap, 8 TDM channel argument would look like the vector below:

std::vector<int16> taps {
           t00, t01, t02, t03, t04, t05, t06, t07,
           t10, t11, t12, t13, t14, t15, t16, t17,
           t20, t21, t22, t23, t24, t25, t26, t27,
           t30, t31, t32, t33, t34, t35, t36, t37
           }

where each element tnm represents a n-th tap for a m-th TDM channel.

template class xf::dsp::aie::fir::tdm::fir_tdm_graph - 2025.2 English

Vitis IP Libraries

Overview

Fields

Methods

getTotalRtpPorts

extractTaps

getKernels

getKernels overload (1)

getKernels overload (2)

getKernelArchs

getTapsPerRtpPort

fir_tdm_graph

fir_tdm_graph overload (1)