Vitis HLS FFT IP Test Suite

A comprehensive test suite for validating AMD/Xilinx Vitis HLS FFT IP configurations with streaming interfaces and dataflow optimization.

---

📋 Overview

This project provides reference implementations and validation tests for the AMD/Xilinx Vitis HLS FFT IP library, specifically targeting:

• Pipelined Streaming I/O Architecture (pipelined_streaming_io)
• Dataflow-Optimized Designs for high-throughput FFT processing
• Float and Fixed-Point Configurations (16-bit, 1024/512-point FFTs)
• RTL Co-Simulation Validation with canonical dataflow patterns

🎯 Purpose

This test suite addresses common challenges when integrating the Vitis HLS FFT IP:

• ✅ Proper configuration for streaming interfaces (hls::stream)
• ✅ Correct dataflow pragma usage for concurrent operation
• ✅ Fixed-point scaling schedule configuration (scaled vs unscaled modes)
• ✅ RTL co-simulation compatibility patterns
• ✅ Config/status stream handling in separate functions

---

🚀 Features

Test Configurations

Test Name	Data Type	FFT Size	Architecture	Scaling Mode
test_fft_float_1024_loop	Float (32-bit)	1024-point	Pipelined Streaming	Unscaled
test_fft_float_512_loop	Float (32-bit)	512-point	Pipelined Streaming	Unscaled
test_fft_fixed_1024_loop	Fixed (ap_fixed<16,1>)	1024-point	Pipelined Streaming	Scaled (0x2AB)
test_fft_fixed_512_loop	Fixed (ap_fixed<16,1>)	512-point	Pipelined Streaming	Scaled (0x1AA)

Key Validation Targets

• C Simulation: Functional accuracy validation with reference DFT
• C Synthesis: Resource utilization and timing closure
• RTL Co-Simulation: Bit-accurate RTL verification with Vivado simulator

---

🛠️ Requirements

Hardware

• Target FPGA: Zynq UltraScale+ (xczu28dr-ffvg1517-2-e)
  • Configurable for other Xilinx/AMD FPGAs via Makefile

Software

Required (Must Have)

• AMD Vitis HLS: 2024.2 or later
  • License: Vitis Unified License (commercial)
  • Download: AMD Adaptive Computing Downloads
• GCC: 8.3.0 or later (for C simulation)
• GNU Make: 4.0 or later

Optional (For GUI/Advanced Features)

• Vivado: 2024.2 (for waveform viewing)
• Vitis Unified IDE: 2024.2 (for project management)

---

📦 Installation

1. Clone Repository

git clone https://github.com/rockyco/vitis-hls-fft-ip-test.git
cd vitis-hls-fft-ip-test

2. Set Vitis HLS Path

Edit Makefile to point to your Vitis installation:

VITIS_PATH ?= /opt/Xilinx/Vitis/2024.2

Or set environment variable:

export VITIS_PATH=/path/to/your/Vitis/2024.2

3. Verify Installation

make help

---

🎮 Usage

Quick Start (C Simulation Only)

Test all configurations with C simulation:

make csim_all

Expected Output:

=========================================
Running C Simulation for All FFT Tests
=========================================
Testing Float 1024-point FFT (10 iterations)...
✓ Max error: 2.34e-05 (PASS)

Testing Float 512-point FFT (10 iterations)...
✓ Max error: 1.87e-05 (PASS)

Testing Fixed 1024-point FFT (10 iterations)...
✓ Max error: 4.12e-04 (PASS)

Testing Fixed 512-point FFT (10 iterations)...
✓ Max error: 3.95e-04 (PASS)

---

Individual Test Workflows

Test 1: Float 1024-point FFT

C Simulation:

make test_float_1024

C Simulation + Synthesis:

make test_float_1024 CSYNTH=1

Full Flow (C-Sim + Synthesis + RTL Co-Sim):

make test_float_1024 CSYNTH=1 COSIM=1

With Waveform Debugging:

make test_float_1024 CSYNTH=1 COSIM=1 COSIM_WAVE_DEBUG=1

---

Test 2: Fixed 1024-point FFT (Recommended)

Why Fixed-Point?

• Better RTL co-simulation reliability
• Deterministic behavior
• Real-world FPGA deployment scenario

Quick Test:

make test_fixed_1024

Full Validation:

make test_fixed_1024 CSYNTH=1 COSIM=1

---

Makefile Targets Reference

Target	Description
make csim_all	Run C simulation for all tests (fast, no HLS tools)
make test_float_1024	Float 1024-point FFT (C-sim + synthesis if CSYNTH=1)
make test_float_512	Float 512-point FFT
make test_fixed_1024	Fixed-point 1024-point FFT (recommended)
make test_fixed_512	Fixed-point 512-point FFT
make clean	Remove build artifacts
make help	Display all available targets

---

Build Variables

Variable	Default	Description
CSYNTH	0	Set to 1 to run C synthesis
COSIM	0	Set to 1 to run RTL co-simulation
COSIM_WAVE_DEBUG	0	Set to 1 to enable waveform capture
VITIS_PATH	/opt/Xilinx/Vitis/2024.2	Path to Vitis installation

Example:

make test_fixed_1024 CSYNTH=1 COSIM=1 COSIM_WAVE_DEBUG=1

---

📊 Expected Results

C Simulation

• Float FFT: Max error < 1e-4 (floating-point precision)
• Fixed FFT: Max error < 5e-4 (16-bit fixed-point quantization)

C Synthesis (Typical Results for Zynq UltraScale+)

Configuration	Latency (cycles)	BRAM	DSP	FF	LUT	Fmax (MHz)
Float 1024	~8,200	24	24	18,500	22,000	300+
Fixed 1024	~8,200	18	18	14,200	18,500	350+
Float 512	~4,100	18	18	15,200	18,000	300+
Fixed 512	~4,100	14	14	11,800	14,500	350+

Values are approximate and vary based on target device and synthesis settings.

RTL Co-Simulation

• Status: PASS (bit-accurate match with C simulation)
• Duration: 2-10 minutes per test (depending on FFT size)

---

📐 Technical Details

FFT IP Configuration

Float Configuration (Unscaled)

struct fft_config_float_1024 : hls::ip_fft::params_t {
    static const unsigned max_nfft = 10;          // 1024-point
    static const unsigned arch_opt = pipelined_streaming_io;
    static const unsigned scaling_opt = unscaled; // Float mode
    static const unsigned input_width = 32;       // Float
    static const unsigned output_width = 32;
};

Fixed-Point Configuration (Scaled)

struct fft_config_fixed_1024 : hls::ip_fft::params_t {
    static const unsigned max_nfft = 10;          // 1024-point
    static const unsigned arch_opt = pipelined_streaming_io;
    static const unsigned scaling_opt = scaled;   // Fixed-point
    static const unsigned input_width = 16;       // ap_fixed<16,1>
    static const unsigned output_width = 16;
};

Scaling Schedule

1024-point FFT (Radix-2): 0x2AB (binary: 0b10_1010_1011)

• Scales by 2 at stages: 0, 1, 3, 5, 7, 9
• Total cumulative scaling: 1/64

512-point FFT (Radix-4): 0x1AA (binary: 0b01_1010_1010)

• Scales for odd-length FFT (radix-4 compatibility)

---

Dataflow Architecture

Critical Pattern for RTL Co-Simulation:

// CORRECT: Config/status handling in separate functions
void write_fft_config(...) {
    config.setDir(1);
    config.setSch(0x2AB);  // For scaled mode
    config_stream.write(config);
}

void read_fft_status(...) {
    status = status_stream.read();
}

// Top-level function with DATAFLOW
void test_fft_loop(...) {
    #pragma HLS DATAFLOW

    write_fft_config(config_stream);
    hls::fft<CONFIG>(input, output, status_stream, config_stream);
    read_fft_status(status_stream);
}

Why? Vitis HLS requires config/status streams to be accessed in separate functions for proper DATAFLOW synthesis and RTL co-simulation.

---

🐛 Troubleshooting

Issue 1: Co-Simulation Timeout

Symptom: RTL simulation hangs or times out.

Solution:

• Use fixed-point FFT (more reliable for co-sim)
• Increase timeout in TCL script: config_rtl -reset_async
• Check FIFO depths: config_dataflow -fifo_depth 2 (default)

---

Issue 2: Float FFT Co-Simulation Errors

Symptom: ERROR: add_1 must be in range [-1,DEPTH-1]

Root Cause: Float FFT IP has RTL compatibility issues with scaling schedule handling.

Solution: Use fixed-point FFT for co-simulation validation.

---

Issue 3: Type Mismatch in Fixed-Point

Symptom: no matching function for call to 'fft'

Solution: Ensure fixed-point type matches FFT IP requirement:

// CORRECT: ap_fixed<((input_width + 7) / 8) * 8, 1>
typedef ap_fixed<16, 1> fixed_t;  // For input_width=16

---

Issue 4: Accuracy Errors

Symptom: Max error exceeds tolerance in C simulation.

Solution:

• Float FFT: Check tolerance < 1e-4
• Fixed FFT: Check tolerance < 5e-4 (quantization noise)
• Verify scaling schedule is correct

---

📚 References

AMD/Xilinx Documentation

• Vitis HLS User Guide (UG1399)
• Fast Fourier Transform v9.1 LogiCORE IP Product Guide (PG109)
• Vitis HLS FFT Library Documentation

Key Concepts

• Pipelined Streaming I/O: High-throughput architecture with continuous data flow
• Dataflow Optimization: Task-level parallelism with concurrent function execution
• Scaling Schedule: Fixed-point overflow prevention through stage-wise scaling

---

🤝 Contributing

Contributions welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Test your changes: make csim_all must pass
4. Commit with clear messages: git commit -m 'Add amazing feature'
5. Submit a Pull Request

Coding Standards

• Follow AMD/Xilinx HLS coding guidelines
• Use #pragma HLS directives for optimization
• Include testbenches for new features
• Document complex configurations

---

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

Third-Party Licenses

AMD/Xilinx Vitis HLS Tools:

• License: Vitis Unified License (commercial)
• Requirement: Users must have valid AMD/Xilinx tool licenses
• Note: This repository contains test code only - no proprietary AMD/Xilinx IP is included

AMD/Xilinx FFT IP Library:

• Part of Vitis HLS standard library
• Requires valid Vitis HLS license for use
• This project demonstrates proper usage only

---

⚠️ Disclaimer

This is an independent educational project demonstrating proper usage of AMD/Xilinx Vitis HLS FFT IP. It is:

• ✅ NOT officially endorsed by AMD or Xilinx
• ✅ NOT a replacement for official AMD/Xilinx documentation
• ✅ NOT guaranteed for production use
• ✅ Provided "AS IS" without warranty

For production deployments, consult official AMD/Xilinx support and documentation.

---

👥 Authors

Jie Lei - Initial work - rockyco

---

🙏 Acknowledgments

• AMD/Xilinx for Vitis HLS tools and FFT IP library
• FPGA development community for best practices and debugging insights
• Contributors to open-source HLS design patterns

---

🗺️ Roadmap

• Add 256-point FFT configurations
• Add inverse FFT (IFFT) test cases
• Add multi-channel FFT support
• Add Verilog RTL export examples
• Add Python golden model validation
• Add performance benchmarking suite
• Add Vivado IP integrator examples

---

⭐ Star this repository if it helped you!

📢 Share with others working on Vitis HLS FFT designs!

---

Last Updated: October 2025