Installing and Running the MEX Function - 9.1 English - PG109

Fast Fourier Transform LogiCORE IP Product Guide (PG109)
Document ID
PG109
Release Date
2024-11-13
Version
9.1 English

To install the FFT MEX function, place the MEX file in your MATLAB software working directory, or in the MATLAB software, change directory to the directory containing the MEX file.

Note: For Windows platforms, the correct libIp_xfft_v9_1_bitacc_cmodel.dll and libgmp.dll files must be copied to the directory where the FFT MEX function has been installed before running the MEX function.
Note: For Linux platforms, the libIp_xfft_v9_1_bitacc_cmodel.so and libgmp.so.11 files must be copied to the directory where the FFT MEX function has been installed before running the MEX function, or be visible using the $LD_LIBRARY_PATH environment variable. $LD_LIBRARY_PATH must be set correctly before starting MATLAB software.

The FFT MEX function is called xfft_v9_1_bitacc_mex. Enter this function name without arguments at the MATLAB software command line to see usage information. The FFT MEX function syntax is:

[output_data, blk_exp, overflow] = xfft_v9_1_bitacc_mex(generics, nfft, input_data, scaling_sch, direction)

The function inputs are shown in the following table.

Table 1. FFT MEX Function Inputs
Input Description Permitted values
generics Core parameters. Single-element, 9-field structure containing all relevant generics defining the core  
generics.C_NFFT_MAX log2(maximum transform length) 3-16
generics.C_ARCH Architecture

1 = Radix-4, Burst I/O,

2 = Radix-2, Burst I/O,

3 = Pipelined, Streaming I/O,

4 = Radix-2 Lite, Burst I/O

 3 = Pipelined, Streaming I/O
generics.C_HAS_NFFT Runtime configurable transform length 0 = no, 1 = yes 0 = no
generics.C_USE_FLT_PT Core interface 0 = fixed-point 1 = single-precision floating-point (pseudo) 2 = single-precision floating-point (native)
generics.C_INPUT_WIDTH Input data width 8-34 bits 32 bits 32 bits
generics.C_TWIDDLE_WIDTH Phase factor width 8-34 bits 24-25 bits 32 bits
generics.C_HAS_SCALING Type of scaling 0 = unscaled, 1 = other 0 0
generics.C_HAS_BFP Type of scaling if C_HAS_SCALING = 1

0 = scaled,

1 = block floating-point

 0 0
generics.C_HAS_ROUNDING Type of rounding

0 = truncation,

1 = convergent rounding

 0 0
generics.C_SYSTOLICFFT_INV Inverse FFT for Floating Point (native) 0 0

0 = forward FFT,

1 = inverse FFT (IFFT)
nfft log2(transform length) for this transform. Single integer. Maximum value is C_NFFT_MAX. Minimum value is 6 for Radix-4, Burst I/O architecture, or 3 for other architectures. Maximum value is C_NFFT_MAX. Minimum value is 6 for Radix-4, Burst I/O architecture, or 3 for other architectures. Maximum value is C_NFFT_MAX. Minimum value is 6 for SSR=4, or 3 for SSR=2.
input_data Input data. 1D array of complex data with 2nfft elements.

All components must be in the range of

-1.0 ≤ data < +1.0.

 All components must be representable in the MATLAB software single datatype (equivalent to a float in C++). All components must be representable in the MATLAB software single datatype (equivalent to a float in C++).
scaling_sch

Scaling schedule. 1D array of integer values size S = number of stages. For Radix-4 and Streaming architectures,

S = nfft/2, rounded up to the next integer. For Radix-2 and Radix-2 Lite architectures,

S = nfft.

 Each value corresponds to scaling to be performed by the corresponding stage and must be in the range 0 to 3. scaling_sch[1] is the scaling for the first stage. N/A N/A
direction Transform direction. Single integer.

1 = forward FFT,

0 = inverse FFT (IFFT)

1 = forward FFT,

0 = inverse FFT (IFFT)

 N/A

The following notes apply to the MEX function inputs.

  1. nfft input is only used for runtime configurable transform length (that is, generics.C_HAS_NFFT = 1). It is ignored otherwise and generics. C_NFFT_MAX is used instead.
  2. For fixed-point input FFTs (that is, generics.C_USE_FLT_PT = 0), to ensure identical numerical behavior to the hardware, pre-quantize the input_data values to have precision determined by C_INPUT_WIDTH. This is achieved using the MATLAB software built-in quantize function.

  3. scaling_sch input is only used for a fixed-point input, scaled FFT (that is, generics.C_USE_FLT_PT = 0, generics.C_HAS_SCALING = 1, and generics.

    C_HAS_BFP = 0). It is ignored otherwise.

  4. input_data can be in natural or bit/digit-reversed sample index order. The MEX function produces samples in the same ordering format as they were input.

The function outputs are shown in the following table.

Table 2. FFT MEX Function Outputs
Output Description Validity
output_data Output data. 1D array of complex data with 2nfft elements. Always valid.
blk_exp Block exponent. Single integer. Only valid if using block floating-point (if generics.C_HAS_SCALING = 1 and C_HAS_BFP = 1). Zero otherwise.
overflow Overflow. Single integer. 1 indicates overflow occurred, 0 indicates no overflow occurred. Only valid with a scaled FFT (if generics.C_HAS_SCALING = 1 and generics.C_HAS_BFP = 0) or an FFT with floating-point interfaces (that is, generics.C_USE_FLT_PT = 1). Zero otherwise.

The notes under the following headings apply to the MEX function outputs.