template class xf::dsp::aie::fir::resampler::fir_resampler_graph

#include "fir_resampler_graph.hpp"

Overview

fir_resampler is a generic asymmetric FIR filter that can do fractional and integer interpolation and decimation.

These are the templates to configure the generic FIR class.

Parameters:

TT_DATA

describes the type of individual data samples input to and output from 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.
  • 32 bit types are only supported when TT_DATA is also a 32 bit type,
  • 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_INTERPOLATE_FACTOR is an unsigned integer which describes the interpolation factor of the filter. TP_INTERPOLATE_FACTOR must be in the range 3 to 16.
TP_DECIMATE_FACTOR is an unsigned integer which describes the decimation factor of the filter. TP_DECIMATE_FACTOR must be in the range 2 to 16. The decimation factor should be less that the interpolation factor and should not be divisible factor of the interpolation factor.
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 61.

TP_RND

describes the selection of rounding to be applied during the shift down stage of processing. TP_RND must be in the range 0 to 7 where

  • 0 = floor (truncate) eg. 3.8 Would become 3.

  • 1 = ceiling e.g. 3.2 would become 4.

  • 2 = round to positive infinity.

  • 3 = round to negative infinity.

  • 4 = round symmetrical to infinity.

  • 5 = round symmetrical to zero.

  • 6 = round convergent to even.

  • 7 = round convergent to odd.

    Modes 2 to 7 round to the nearest integer. They differ only in how they round for values of 0.5.

TP_INPUT_WINDOW_VSIZE

describes the number of samples in the window API used for input to the filter function.

The number of values in the output window will be TP_INPUT_WINDOW_VSIZE multipled by TP_INTERPOLATE_FACTOR and divided by TP_DECIMATE_FACTOR.

In the instance this would lead to a fraction number of output samples, this would be rounded down.

Note: Margin size should not be included in TP_INPUT_WINDOW_VSIZE.

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 9.

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, optional port: port<input> coeff; will be added to the FIR.

TP_NUM_OUTPUTS

sets the number of ports over which the output is sent.

This can be 1 or 2. It is set to 1 by default.

Depending on TP_API, additional output ports functionality differs. For Windows API, additional output provides flexibility in connecting FIR output with multiple destinations. Additional output out2 is an exact copy of the data of the output port out .

With Stream API, the additional output port increases the FIR’s throughput.

Data is sent in a 128-bit interleaved pattern, e.g. :

  • samples 0-3 is sent over stream0 for cint16 data type,

  • samples 4-7 is sent over stream1 for cint16 data type.

    Note: when used, optional port: port<output> out2; will be added to the FIR.

TP_DUAL_IP

allows 2 stream inputs to be connected to FIR, increasing available throughput.

When set to 0, single stream will be connected as FIRs input.

When set to 1, two stream inputs will be connected.

In such case data should be organized in 128-bit interleaved pattern, e.g.:

  • samples 0-3 to be sent over stream0 for cint16 data type,
  • samples 4-7 to be sent over stream1 for cint16 data type.
TP_API

specifies if the input/output interface should be window-based or stream-based.

The values supported are 0 (window API) or 1 (stream API).

template <
    typename TT_DATA,
    typename TT_COEFF,
    unsigned int TP_FIR_LEN,
    unsigned int TP_INTERPOLATE_FACTOR,
    unsigned int TP_DECIMATE_FACTOR,
    unsigned int TP_SHIFT,
    unsigned int TP_RND,
    unsigned int TP_INPUT_WINDOW_VSIZE,
    unsigned int TP_CASC_LEN = 1,
    unsigned int TP_USE_COEFF_RELOAD = 0,
    unsigned int TP_NUM_OUTPUTS = 1,
    unsigned int TP_DUAL_IP = 0,
    unsigned int TP_API = 0
    >
class fir_resampler_graph: public graph

// fields

port_array <input, 1> in
port_array <output, 1> out
port_conditional_array <input, (TP_DUAL_IP==1), 1> in2
port_conditional_array <input, (TP_USE_COEFF_RELOAD==1), 1> coeff
port_conditional_array <output, (TP_NUM_OUTPUTS==2), 1> out2

Fields

port_array <input, 1> in

The input data to the function. This input 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, 1> out

The output data 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).

port_conditional_array <input, (TP_DUAL_IP==1), 1> in2

The conditional input data to the function. This input is (generated when TP_DUAL_IP == 1) either a window API of samples of TT_DATA type or stream API (depending on TP_API).

port_conditional_array <input, (TP_USE_COEFF_RELOAD==1), 1> coeff

The conditional coefficient data to the function. This port is (generated when TP_USE_COEFF_RELOAD == 1) an array of coefficients of TT_COEFF type.

port_conditional_array <output, (TP_NUM_OUTPUTS==2), 1> out2

The output data from the function. This output is (generated when TP_NUM_OUTPUTS == 2) 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).

Methods

getKernels

getKernels overload (1)

kernel* getKernels ()

Access function to get pointer to kernel (or first kernel in a chained configuration).

getKernels overload (2)

kernel* getKernels (int cascadePosition)

Access function to get pointer to an indexed kernel.

Parameters:

cascadePosition an index to the kernel’s position in the cascade.

getInNet

connect <stream, stream>* getInNet (int cascadePosition)

Access function to get pointer to net of the in port. Nets only get assigned when streaming interface is being broadcast, i.e. nets only get used when TP_API == 1 and TP_CASC_LEN > 1

Parameters:

cascadePosition an index to the kernel’s position in the cascade.

getIn2Net

connect <stream, stream>* getIn2Net (int cascadePosition)

Access function to get pointer to net of the in2 port, when port is being generated, i.e. when TP_DUAL_IP == 1. Nets only get assigned when streaming interface is being broadcast, i.e. nets only get used when TP_API == 1 and TP_CASC_LEN > 1

Parameters:

cascadePosition an index to the kernel’s position in the cascade.

getKernelArchs

unsigned int getKernelArchs ()

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

getPolyphaseLaneAlias

unsigned int getPolyphaseLaneAlias ()

Access function to get kernels PoliphaseLaneAlias.

fir_resampler_graph

fir_resampler_graph overload (1)

fir_resampler_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.

fir_resampler_graph overload (2)

fir_resampler_graph ()

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