1-Dimensional(Line) SSR FFT L1 FPGA Module

Overview

Vitis DSP Library offers a fully synthesizable Super Sample data Rate (SSR) FFT with a systolic architecture to process multiple input samples every clock cycle. The number of samples processed in parallel per cycle is denoted by the SSR factor. The SSR FFT is implemented as a C++ template function that synthesizes into a streaming architecture. The SSR FFT architecture used for implementation can be parameterized through template parameters, which are grouped in a C++ struct of type ssr_fft_default_params. A new structure can be defined by extending the default structure and re-defining required member constants as follows:

struct ssr_fft_fix_params:ssr_fft_default_params
{
        static const int N = 1024;
        static const int R = 4;
        static const scaling_mode_enum scaling_mode = SSR_FFT_NO_SCALING;
        static const fft_output_order_enum output_data_order = SSR_FFT_NATURAL;
        static const int twiddle_table_word_length = 18;
        static const int twiddle_table_integer_part_length = 2;
        static const transform_direction_enum transform_direction = FORWARD_TRANSFORM;
        static const butterfly_rnd_mode_enum butterfly_rnd_mode = TRN;
};

The structure above defines:

  • N: Size or length of transform
  • R: The number of samples to be processed in parallel SSR Factor and radix of SSR FFT algorithm used
  • scaling_mode: The scaling mode as enumeration type (SSR FFT has three different scaling modes)
  • output_data_order: Which will decided if data will be in natural order or digit reversed transposed order
  • twiddle_table_word_length: Defines total number of bits to be used for storing twiddle table factors
  • twiddle_table_integer_part_length: The number of integer bits used for storing integer part of twiddles
  • transform_direction : Defines the direction of transform, inverse transform (SSR IFFT) or forward transform (SSR FFT)
  • butterfly_rnd_mode : Defines the rounding mode used by butterflies in SSR FFT stages

Multi-Instance Support

Single-instance example:

xf::dsp::fft::fft<fftParams><ssr_fft_fix_params>(...);

The current release of Vitis SSR FFT supports the use of multiple instances of 1-D SSR FFT in a single design. To enable the use of multiple instances, the fft function takes as an input a new template parameter besides the parameter structure. This parameter gets a default value if no value is provided for it. But if multiple instance support is required, all the instances used should be provided with the unique integer template parameter, like:

xf::dsp::fft::fft<fftParams,1><ssr_fft_fix_params>(...);
xf::dsp::fft::fft<fftParams,2><ssr_fft_fix_params>(...);

Data Type Support for Synthesis

Currently 1-D SSR FFT supports fixed point and floating point complex inputs for synthesis.

Fixed Point

The fixed point SSR FFT implementation is based on fixed point data types std::complex<ap_fixed<>> which are used for synthesis and implementation. It is possible to use floating point types std::complex<float> and std::complex<double> for simulation but these floating point complex models will consume massive resources if synthesized to hardware. For the best results with fixed point type, limit the data bit width to 27 bits (integer + fraction) as it helps to map multiplication and addition within SSR FFT butterflies directly onto a single DSP block. Larger inputs can be used but may lead to slower Fmax and more resource utilization. Finally, note that the complex exponential/twiddle factor storage is on 18 bits (16F+2I bits). The selection of 18-bit is made keeping in view the 18x27 multipliers available within DSP blocks on Xilinx FPGAs.

Floating Point

1-D SSR FFT also supports synthesis for single or double precision floating point type. For synthesizing a complex floating point type, it is required that std::complex type not to be used as a complex wrapper. Since this wrapper has some issues and it is required that a wrapper class provided with the Vitis DSP library called complex_wrapper<…> is used for wrapping complex float numbers. Also while synthesizing floating point 1-D SSR FFT the parameters in the structure which carry information such as scaling mode, twiddle factor storage bits, butterfly rounding mode etc. which are only related to fixed point data-path, carry no meaning. Instead SSR FFT parameter structure can simply define relevant parameters as shown below:

struct ssr_fft_fix_params:ssr_fft_default_params
{
        static const int N = 1024;
        static const int R = 4;
        static const fft_output_order_enum output_data_order = SSR_FFT_NATURAL;
        static const transform_direction_enum transform_direction = FORWARD_TRANSFORM;
};

Managing Bit Growth in SSR FFT Stages

The bit growth management is required for fixed point implementation only. The SSR FFT supports three different modes to manage bit growth between SSR FFT stages. These three modes can be used to allow bit growth in every stage, or use scaling in every stage without any bit growth, or allow bit growth until 27 bits and then start using scaling. The detailed description for the different modes are as follows:

SSR_FFT_GROW_TO_MAX_WIDTH

When the scaling_mode constant in the parameter structure is set to SSR_FFT_GROW_TO_MAX_WIDTH, it specifies growth from stage to stage, starting from the first stage to a specified max bit width. The output bit width grows until 27 bits and then saturates. The output bit width grows by log2(R) bits in every stage, and then maxes outs at 27 bits to keep the butterfly operation mapping to DSPs. This option is useful when the initial input bit width is less than 27 bits.

SSR_FFT_SCALE

When the scaling_mode constant in the parameter structure is set to SSR_FFT_SCALE, it enables scaling of outputs in every stage. The output is scaled in every stage and loses precision. An FFT with size L and Radix=SSR=R has logR(L) stages. This option is useful when the input bit width is already close to 27 bits and it is required that the output does not grow beyond 27 bits so that multiplication can be mapped to DSPs.

SSR_FFT_NO_SCALE

When the scaling_mode constant in the parameter structure is set to SSR_FFT_NO_SCALE, the bit growth is allowed in every stage and the output grows unbounded by log2(R) in every stage. This setting can be useful when high precision is required. However, if the output bit width grows beyond 27 bits, the multiplication may not map to only DSPs, but also start using FPGA fabric logic in combination. This may reduce the clock speed and increase resource utilization.

1-D SSR FFT Library Usage

Following sections describe how to use SSR FFT from Vitis DSP Library.

Fixed Point 1-D SSR FFT Usage

The Vitis 1-D SSR FFT L1 module can be used in a C++ HLS design by: 1- cloning the Vitis DSP Library git repository and add the following path to compiler include path:

REPO_PATH/dsp/L1/include/hw/vitis_fft/fixed/

2- Include vt_fft.hpp

3- Use namespace xf::dsp::fft

4- Define fft parameter structure say call it params_fix by extending ssr_fft_default_params like Defining 1-D SSR FFT Parameter Structure

5- call fft<params_fix>(input_array,output_array)

The following section gives usage examples and explains some other interface level details for use in C++ based HLS design. To use the 1-D SSR FFT L1 module:

  1. Include the vt_fft.hpp header:
#include "vt_fft.hpp"
  1. Use namespace xf::dsp::fft
using namespace xf::dsp::fft;
  1. Define a C++ structure that extends ssr_fft_default_params:
struct params_fix:ssr_fft_default_params
{
        static const int N-SSR_FFT_L;
        static const int R=SSR_FFT_R;
        static const scaling_mode_enum
        scaling_mode=SSR_FFT_GROW_TO_MAX_WIDTH;
        static const fft_output_order_enum
        output_data_order=SSR_FFT_NATURAL;
        static const int twiddle_table_word_length=18;
        static const int twiddle_table_intger_part_length=2;
};
  1. Call 1-D SSR FFT as follows:
fft<params_fix>(inD,outD);
//OR
fft<params_fix,IID>(inD,outD);
// IID: is a constant giving instance ID

where inD and outD are 2-dimensional complex arrays of ap_fixed, float or double type, synthesis and simulation use is already explained in the previous table. The I/O arrays can be declared as follows:

Fixed Point Type First define input type, then using type traits calculate output type based on ssr_fft_params struct (output type calculation takes in consideration scaling mode based bit-growth and input bit-widths).

Floating Point 1-D SSR FFT Usage

The Vitis 1-D SSR FFT L1 module can be used in a C++ HLS design by:

1- Cloning the Vitis DSP Library git repository and add the following path to compiler include path:

REPO_PATH/dsp/L1/include/hw/vitis_fft/float/

2- Include vt_fft.hpp

3- Use namespace xf::dsp::fft

4- Define fft parameter structure lets say call it params_float by extending ssr_fft_default_params like Defining 1-D SSR FFT Parameter Structure

5- call fft<params_float>(input_array,output_array)

The following section gives usage examples and explains some other interface level details for use in C++ based HLS design. To use the 1-D SSR FFT L1 module:

  1. Include the vt_fft.hpp header:
#include "vt_fft.hpp"
  1. Use namespace xf::dsp::fft
using namespace xf::dsp::fft;
  1. Define a C++ structure that extends ssr_fft_default_params:
struct params_float:ssr_fft_default_params
{
   static const int N = 1024;
   static const int R = 4;
   static const fft_output_order_enum output_data_order = SSR_FFT_NATURAL;
   static const transform_direction_enum transform_direction = FORWARD_TRANSFORM;
};
  1. Call 1-D SSR FFT as follows:
fft<params_float>(inD,outD);
//OR
fft<ssr_fft_params,IID>(inD,outD);
// IID: is a constant giving instance ID

where inD and outD are 2-dimensional complex arrays of ap_fixed, float or double type, synthesis and simulation use is already explained in the previous table. The I/O arrays can be declared as follows:

Fixed Point Type: First define input type, then using type traits calculate output type based on ssr_fft_params struct (output type calculation takes into consideration scaling mode based bit-growth and input bit-widths not relevant for type float).

typedef std::complex< float > I_TYPE;
typedef xf::dsp::fft::ssr_fft_output_type<ssr_fft_params,I_TYPE>::t_ssr_fft_out O_TYPE;
I_TYPE inD[SSR_FFT_R][SSR_FFT_L/SSR_FFT_R];
O_TYPE outD [R][L/R];

Here SSR_FFT_R defines SSR factor and SSR_FFT_L defines the size of the FFT transform.

Float/Double Type: First define the double/float input type, then using type traits calculate output type based on ssr_fft_params struct. For float types the output type calculation will return the same type as input.

typedef std::complex< float/double > I_TYPE;
typedef hls::ssr_fft::ssr_fft_output_type<ssr_fft_params,I_TYPE>::t_ssr_fft_out O_TYPE;
I_TYPE inD[SSR_FFT_R][SSR_FFT_L/SSR_FFT_R];
O_TYPE outD[SSR_FFT_R][SSR_FFT_L/SSR_FFT_R];

1-D SSR FFT Input Array Reading and Writing Considerations

After synthesis, 1-D SSR FFT HLS IP maps to a processing block with buffer interface at both the input and output.

If user requires a streaming 1-D SSR FFT block with FIFO interface at both the input and output, as shown in the following figure:

doc tool flow

They should skip the wrapper fft with the buffer-to-stream transformation blocks named array2Stream and stream2Array, and directly call the innerFFT function in FFTWrapper struct. If input and output arrays are declared as the following:

I_TYPE inD[R][L/R];
O_TYPE outD[R][L/R];

The dimensions with size L/R will be mapped to time and dimension with size R mapped to one stream which is R-wide. This mapping places some constraints on how these arrays can be read and written to by consumers and producers while writing C++ design using 1-D SSR FFT. These constraints stem from the physical mapping of array dimensions to time and parallel wide-accesses.

All of these constraints will be well handled by array2Stream and stream2Array blocks, user could ignore those details by calling the wrapper with buffer interface instead of the internal streaming block innerFFT. If the streaming block is required, the read and write on innerFFT can be performed as follows:

  1. Declares the input and output streams explicitly with corresponding stream depth:
// input stream of innerFFT
hls::stream<I_TYPE, FIFO_DEPTH> inStrm[R];
// output stream of innerFFT
hls::stream<O_TYPE, FIFO_DEPTH> outStrm[R];
  1. Feeds data to the input FIFO, or eats from the output one:
for (int t = 0; t < L / R; t++)
{
        for (int r = 0; r < R; r++)
        {
    inStrm[r].write(inD[r][t]);
        }
}

for (int t = 0; t < L / R; t++)
{
        for (int r = 0; r < R; r++)
        {
    outD[r][t] = outStrm[r].read();
        }
}

3. If the 1-D SSR FFT IP is facing another HLS IP in the input chain or output chain, the inner loop doing reading and writing should be unrolled.

1-D SSR FFT Usage in Dataflow Region, Streaming/Non-Streaming Connections

1-D SSR FFT internally relies heavily on HLS dataflow optimization. The potential use case for 1-D SSR FFT could interconnect with an SSR FFT input or output in two ways:

  • Streaming Connection
  • Non-Streaming Connections

Streaming Connection

In the case of a streaming connection at the input, the scenario should look as follows:

#pragma HLS DATAFLOW
in_dummy_proc (..., fft_in);
innerFFT<template_param_needed>(fft_in, fft_out);
out_dummy_proc(fft_out, ....)
...
...
...

The constraint for input producer is that it should produce an array of stream. The constraint for output consumers is that it should consume an array of stream. These constraints are also described in previous sections.

Non-Streaming Connection

The current version of the 1-D SSR FFT naturally support non-streaming connection at the output and input.

// just call it
fft<params_float>(inD, outD);
//OR
fft<ssr_fft_params, IID>(inD, outD);
// IID: is a constant giving instance ID

1-D FFT Examples

The following sections provides brief details of examples provided for 1-D SSR FFT.

1-D Fixed Point SSR FFT Example

The example below follows the sequence of steps described in previous sections to do a transform on impulse signal. The listing give below data_path.hpp describes the datapath, by defining size, SSR, data-path bit-widths, scaling mode, out order etc. It also includes top level library interface header vt_fft.hpp which gives to fft function defined in namespace xf::dsp::fft

#ifndef _DATA_PATH_H_
#define _DATA_PATH_H_
#include <ap_fixed.h>
#include <complex>
#include "vt_fft.hpp"
using namespace xf::dsp::fft;

// Define FFT Size and Super Sample Rate
#define FFT_LEN 16
#define SSR 4
// Define fixed point input/output bit-widths
#define IN_WL 16
#define IN_IL 2
#define TW_WL 16
#define TW_IL 2

//Define FFT instane ID, every instance created should have unique ID
#define IID 0

typedef std::complex<ap_fixed<IN_WL, IN_IL> > T_in;

/* Define parameter structure for SSR FFT that defines
 * holds , size, SSR, scaling mode, output order sin/cos
 * bit resoulation for storage*/
struct fftParams : ssr_fft_default_params {
    static const int N = FFT_LEN;
    static const int R = SSR;
    static const scaling_mode_enum scaling_mode = SSR_FFT_NO_SCALING;
    static const fft_output_order_enum output_data_order = SSR_FFT_NATURAL;
    static const int twiddle_table_word_length = TW_WL;
    static const int twiddle_table_intger_part_length = TW_IL;
};
// Using type traits calculate the output type given FFT param struct
// and the input type
typedef ssr_fft_output_type<fftParams, T_in>::t_ssr_fft_out T_out;

#endif // _DATA_PATH_H_

The listing top_module.hpp and top_module.cpp declare and define top level module. The top level function here is very simple it only wraps the core SSR FFT function call in a top level wrapper called fft_top

#include "data_path.hpp"
#include <hls_stream.h>

void fft_top(T_in p_inData[SSR][FFT_LEN / SSR], T_out p_outData[SSR][FFT_LEN / SSR]);

#include "top_module.hpp"
#include "data_path.hpp"

void fft_top(T_in p_inData[SSR][FFT_LEN / SSR], T_out p_outData[SSR][FFT_LEN / SSR]) {
    xf::dsp::fft::fft<fftParams, IID>(p_inData, p_outData);
}

The listing below gives main funtion that generates impulse data for SSR FFT input in a 2-dimensional array which is SSRx(Size/SRR) and feeds it to top level which produces a 2-dimensional output array of same dimensions. The impulse input produces a step which is verified and test declared as passed.

#include "top_module.hpp"
#include <iostream>

int main(int argc, char** argv) {
    T_in inData[SSR][FFT_LEN / SSR];
    T_out outData[SSR][FFT_LEN / SSR];
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            if (r == 0 && t == 0)
                inData[r][t] = 1;
            else
                inData[r][t] = 0;
        }
    }
    for (int t = 0; t < 4; ++t) {
        // Added Dummy loop iterations
        // to make II measurable in cosim
        fft_top(inData, outData);
    }
    int errs = 0;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            if (outData[r][t].real() != 1 || outData[r][t].imag() != 0) errs++;
        }
    }
    std::cout << "===============================================================" << std::endl;
    std::cout << "--Input Impulse:" << std::endl;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            std::cout << inData[r][t] << std::endl;
        }
    }
    std::cout << "===============================================================" << std::endl;

    std::cout << "===============================================================" << std::endl;
    std::cout << "--Output Step fuction:" << std::endl;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            std::cout << outData[r][t] << std::endl;
        }
    }
    std::cout << "===============================================================" << std::endl;

    return errs;
}

Compiling and Building Example HLS Project

Before compiling and running the example it is required to setup the path to HLS compiler which can be done as follows: change the setting of environment variable TA_PATH to point to the installation path of your Vitis, and run following command to set up the environment.

export XILINX_VITIS=${TA_PATH}/Vitis/2021.1
export XILINX_VIVADO=${TA_PATH}/Vivado/2021.1
source ${XILINX_VIVADO}/settings64.sh

The example discussed above is also provided as an example and available at the following path : REPO_PATH/dsp/L1/examples/1Dfix_impluse it can be simulated, synthesized or co-simulated as follows: Simply go to the directory REPO_PATH/dsp/L1/examples/1Dfix_impluse and simulate, build and co-simulate project using : make run XPART='xcu200-fsgd2104-2-e' CSIM=1 CSYNTH=1 COSIM=1 you can choose the part number as required and by settting CSIM/CSYNTH/COSIM=0 choose what to build and run with make target.

1-D Floating Point SSR FFT Example

The use of floating point SSR FFT is very similar to fixed point SSR FFT the following listing data_path.hpp gives parameter struct which is simple as compared to fixed point since data-path constants scaling type, input bit-widths etc are not required for floatig point case. It essentially requires declaration of Size and SSR factor and output data order by default is set to natural order, if required it can be changed to digital reversed transposed.

#ifndef _DATA_PATH_H_
#define _DATA_PATH_H_

#include <ap_fixed.h>
#include <complex>
#include "vt_fft.hpp"
using namespace xf::dsp::fft;

// Define FFT Size and Super Sample Rate
#define FFT_LEN 16
#define SSR 4

typedef complex_wrapper<float> T_in;
#define IID 0

// Define parameter structure for SSR FFT
struct fftParams : ssr_fft_default_params {
    static const int N = FFT_LEN;
    static const int R = SSR;
};

// typedef ssr_fft_output_type<fftParams,T_in>::t_ssr_fft_out T_out;
typedef T_in T_out;

#endif // _DATA_PATH_H_

The following two listings top_moduel.hpp and top_module.cpp give top level module decleration and definition only.

#include "data_path.hpp"
#include <hls_stream.h>

void fft_top(T_in p_inData[SSR][FFT_LEN / SSR], T_out p_outData[SSR][FFT_LEN / SSR]);

    #include "top_module.hpp"
    #include "data_path.hpp"

    void fft_top(T_in p_inData[SSR][FFT_LEN / SSR], T_out p_outData[SSR][FFT_LEN / SSR]) {
        xf::dsp::fft::fft<fftParams, IID>(p_inData, p_outData);
}

The listing below main.cpp gives main function which creates an impulse input and verfies if the correct output is produced. The only significant change w.r.t to fixed point is the data type declaration and the param struct otherwise this example is very the same like the use of fixed point SSR FFT.

#include "top_module.hpp"
#include <iostream>
int main(int argc, char** argv) {
    T_in inData[SSR][FFT_LEN / SSR];
    T_out outData[SSR][FFT_LEN / SSR];
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            if (r == 0 && t == 0)
                inData[r][t] = 1;
            else
                inData[r][t] = 0;
        }
    }
    for (int t = 0; t < 4; ++t) {
        // Added Dummy loop iterations
        // to make II measurable in cosim
        fft_top(inData, outData);
    }
    int errs = 0;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            if (outData[r][t].real() != 1 || outData[r][t].imag() != 0) errs++;
        }
    }
    std::cout << "===============================================================" << std::endl;
    std::cout << "--Input Impulse:" << std::endl;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            std::cout << inData[r][t] << std::endl;
        }
    }
    std::cout << "===============================================================" << std::endl;

    std::cout << "===============================================================" << std::endl;
    std::cout << "--Output Step fuction:" << std::endl;
    for (int r = 0; r < SSR; ++r) {
        for (int t = 0; t < FFT_LEN / SSR; ++t) {
            std::cout << outData[r][t] << std::endl;
        }
    }
    std::cout << "===============================================================" << std::endl;

    return errs;
}

Compiling and Building Example HLS Project

Before compiling and running the example it is required to setup the path to HLS compiler which can be done as follows: change the setting of environment variable TA_PATH to point to the installation path of your Vitis, and run following command to set up the environment.

export XILINX_VITIS=${TA_PATH}/Vitis/2021.1
export XILINX_VIVADO=${TA_PATH}/Vivado/2021.1
source ${XILINX_VIVADO}/settings64.sh

The example discussed above is also provided as an example and available at the following path : REPO_PATH/dsp/L1/examples/1Dfloat_impluse it can be simulated, synthesized or co-simulated as follows: Simply go to the directory REPO_PATH/dsp/L1/examples/1Dfloat_impluse and simulate, build and co-simulate project using : make run XPART='xcu200-fsgd2104-2-e' CSIM=1 CSYNTH=1 COSIM=1 you can choose the part number as required and by settting CSIM/CSYNTH/COSIM=0 choose what to build and run with make target

1-D SSR FFT Tests

Different tests are provided for fixed point and floating point 1-D SSR FFT. These tests can be ran individually using the makefile or they can all be lauched at the same time by using a provided script. All the 1-D SSR FFT tests are in folder REPO_PATH/dsp/L1/tests/hw/1dfft

Launching an Individual Test

To launch an individual test first it is required to setup environment for lanching Vitis HLS Compiler which can be done as follows:
setup of environment variable TA_PATH to point to the installation path of your Vitis, and run following commands to set up the environment.
export XILINX_VITIS=${TA_PATH}/Vitis/2021.1
export XILINX_VIVADO=${TA_PATH}/Vivado/2021.1
source ${XILINX_VIVADO}/settings64.sh

Once the environment settings are done an individual test can be launched by going to test folder (any folder inside sub-directory at any level of REPO_PATH/dsp/L1/test/hw/1dfft that has a Makefile is a test) and running the make command :

make run XPART='xcu200-fsgd2104-2-e' CSIM=1 CSYNTH=1 COSIM=1 you can choose the part number as required and by settting CSIM/CSYNTH/COSIM=0 choose what to build and run with make target