Fast Fourier Transform IP Library - Fast Fourier Transform IP Library - 2026.1 English - UG1399

The AMD FFT LogiCORE IP can be called within a C++ design using the library hls_fft.h. This section explains how the FFT can be configured in your C++ code. An example FFT application can be found in Vitis-HLS-Introductory-Examples on GitHub. For the Versal RF dedicated FFT block instantiation, refer to the "Fast Fourier Transform for Versal RF" section.

The FFT library supports floating-point data types when targeting Versal devices. The hls::fft can be called with different parameter lists through C++ function overloading and template specialization. These overloaded versions of the fft function use different parameter function signatures.

Super Sample Rate (SSR) parameters for both fixed-point and floating-point are supported.

To use the FFT in your C++ code:

1. Include the hls_fft.h library
2. Set the default parameters using the library predefined struct hls::ip_fft::params_t, or inherit from it as your own configuration struct (see the code snippet below).
   Tip: The Vivado LogiCORE IP through its dialog wizard detects and prevents incompatibilities in settings. Check your own configuration struct parameters into these Vivado IP dialogs to avoid unsupported or faulty configurations.
3. Define the runtime configuration
4. Call the FFT function
   Tip: Because it uses the DATAFLOW pragma or directive, the pipelined execution of an FFT must be in a dataflow loop and not a pipelined loop.
5. Optionally, check the runtime status

Each of these steps is discussed in more detail below with code snippets:

First, include the FFT library in the source code. This header file resides in the include directory in the Vitis HLS installation area which is automatically searched when Vitis HLS executes.

#include "hls_fft.h"

Define the static parameters of the FFT such as the input width, number of channels, type of architecture which do not change dynamically. The FFT library includes a parameterization struct hls::ip_fft::params_t to initialize all static parameters with default values.

In the C++ code below, a new user-defined struct config1 inherits from the library struct params_t with all its default values. Then specific struct parameter values such as output ordering and the widths of the configuration are overridden.

Next, set the runtime configuration using the following arguments of the hls::fft API:

• fwd_inv: The direction of the FFT (not applicable for native floating point; the static configuration parameter systolicfft_inv must be used instead).
• scale_sch: The scaling schedule (not applicable for native floating point).
• cp_len: The cyclic prefix length (required for cyclic_prefix_insertion==1).

Call the FFT function using the hls namespace.

The function parameters are as follows for various streaming configurations, single channel, with or without runtime configurable transform length:

// streaming 1 channel no run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(hls::stream<std::complex<_DATA_IN_T>>& in,
         hls::stream<std::complex<_DATA_OUT_T>>& out,
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);

// streaming 1 channel run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(unsigned log2_transform_length,
         hls::stream<std::complex<_DATA_IN_T>>& in,
         hls::stream<std::complex<_DATA_OUT_T>>& out,
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);

// streaming SSR>1 1 channel no run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(hls::stream<hls::vector<std::complex<_DATA_IN_T>, _CONFIG_T::super_sample_rate>>&  in,
         hls::stream<hls::vector<std::complex<_DATA_OUT_T>, _CONFIG_T::super_sample_rate>>&  out,
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);

// streaming SSR>1 1 channel run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(unsigned log2_transform_length,
         hls::stream<hls::vector<std::complex<_DATA_IN_T>, _CONFIG_T::super_sample_rate>>&  in,
         hls::stream<hls::vector<std::complex<_DATA_OUT_T>, _CONFIG_T::super_sample_rate>>&  out,
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);
         

The function parameters are as follows for various array configurations, single or multi-channel, with or without runtime configurable transform length:

// array 1 channel no run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(std::complex<_DATA_IN_T>  in[1 << _CONFIG_T::log2_transform_length],
         std::complex<_DATA_OUT_T>  out[1 << _CONFIG_T::log2_transform_length],
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);

// array 1 channel run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(unsigned log2_transform_length,
         std::complex<_DATA_IN_T>  in[1 << _CONFIG_T::log2_transform_length],
         std::complex<_DATA_OUT_T>  out[1 << _CONFIG_T::log2_transform_length],
         bool fwd_inv = false, // direction
         int scale_sch = -1,
         int cp_len = -1,
         bool *ovflo = 0,
         unsigned *blk_exp = 0);

// array N channel no run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(std::complex<_DATA_IN_T>  in[1 << _CONFIG_T::log2_transform_length][_CONFIG_T::channels],
         std::complex<_DATA_OUT_T>  out[1 << _CONFIG_T::log2_transform_length][_CONFIG_T::channels],
         hls::vector<bool, _CONFIG_T::channels> &fwd_inv,
         hls::vector<int, _CONFIG_T::channels> &scale_sch, // used only if enabled in config
         int cp_len = -1,
         hls::vector<bool, _CONFIG_T::channels> *ovflo = 0,
         hls::vector<unsigned, _CONFIG_T::channels> *blk_exp = 0);

// array N channel run_time_configurable_transform_length 
template<typename _CONFIG_T =  hls::ip_fft::params_t,
         typename _DATA_IN_T,
         typename _DATA_OUT_T>
void fft(unsigned log2_transform_length,
         std::complex<_DATA_IN_T>  in[1 << _CONFIG_T::log2_transform_length][_CONFIG_T::channels],
         std::complex<_DATA_OUT_T>  out[1 << _CONFIG_T::log2_transform_length][_CONFIG_T::channels],
         hls::vector<bool, _CONFIG_T::channels> &fwd_inv,
         hls::vector<int, _CONFIG_T::channels> &scale_sch, // used only if enabled in config
         int cp_len = -1,
         hls::vector<bool, _CONFIG_T::channels> *ovflo = 0,
         hls::vector<unsigned, _CONFIG_T::channels> *blk_exp = 0);

For example, this is a call of an FFT with fixed transform length (run_time_configurable_transform_length==0), no cyclic prefix length and no output block exponent.

hls::fft<config1>(xn, xk, dir, scaling, -1, ovflo);

Finally and optionally, check the output statuses, namely the overflow (applicable only for non-native floating point) and the output block exponent (applicable for non-native floating point with block floating point).

The parameters of the FFT struct hls::ip_fft::params_t are listed below with their default values.

Restrictions and Known Issues

The FFTs parametrized with super sample rate larger than one (SSR>1) for both fixed and native floating-point share the same configuration restrictions as the underlying LogiCORE IP, namely:

• The numerical precision of the C model of FFT IP core is affected by the C model of HLS math on Linux. To preserve the accuracy of the C model of FFT, add the -stdmath option for both csim_design and cosim_design to use std::math for the C model of HLS math library.
  • Using this option you get C simulation of floating-point math library functions (that is exp, pow, log, …) called outside the FFT model which is accurate with respect to the std::math function definitions, but not bit accurate with respect to RTL simulation. The reason is that:
  • HLS by default performs C simulation of these standard math functions called within user code outside the FFT with a C model that is bit-accurate with respect to the RTL that it generates.
  • The FFT C simulation model delivered as part of the LogiCORE IP expects to use the standard math functions, not the HLS C math simulation model.
• No support for dynamic configuration (for example, direction, transform length, and scaling schedule). For compatibility the API provide a dynamic config input but the values are ignored, and the API checks that the values, if specified, are the same as the underlying IP defaults.
• The direction of the transform is specified using a new static config parameter called systolicfft_inv.
• No output status (for example, no overflow output). For compatibility the APIs provide a status output argument, which is always set to 0.
• Phase_factor_width is fixed at 32 bits for floating point and 19 bits for fixed point.
• XK_INDEX is not supported.
• Output_ordering is fixed at natural order, meaning that the results can be presented in the sequence they naturally occur, without any additional sorting or rearrangement applied.
• Cyclic_prefix_insertion is not supported.
• Complex_mult_type is fixed at use_mults_performance.
• Butterfly_type is fixed at use_extremedsp_slice.
• The SSR FFTs have a 6-cycle gap in the input TREADY and output TVALID whenever the FFT starts a new data frame.

Fast Fourier Transform for Versal RF

The dedicated FFT block of Versal RF can be instantiated via the hls_vrf_fft.h library.

The new API:

template<typename _CONFIG_T> void hls::vrf_fft::fft(hls::stream<input_t<_CONFIG_T>>& in1, hls::stream<output_t<_CONFIG_T>>& out1)