2D Fast Fourier Transform OpenCL Design Example README file
===========================================================
===========================================================

This readme file for the 2D Fast Fourier Transform OpenCL 
Design Example contains information about the design example 
package. For more examples, please visit the page:
http://www.altera.com/support/examples/opencl/opencl.html

This file contains the following information:

- Example Description
- Software and Board Requirements
- Usage Instructions
- Package Contents and Directory Structure
- Release History
- Disclaimer & Licenses
- Contacting Altera(R)


Example Description
===================

This benchmark demonstrates an OpenCL implementation of a 2D Fast Fourier 
Transform (2D FFT) on Altera FPGAs. The benchmark processes a 2D matrix of 
1k x 1k complex single-precision floating-point data. The 2D transform
is decomposed as a 1D FFT applied to each row followed by a 1D FFT 
applied to each column.

The device portion of the code applies a 1D transform to each row and 
transposes the matrix. This computation is enqueued twice from the host 
code. The second iteration applies a 1D transform to each transposed row, 
producing the column-wise FFT. The second transposition restores the 
original matrix layout. 

The 1D FFT engine is written as a single work-item kernel. To achieve
efficient memory access two additional ND range kernels are used to 
read / write data from / to global memory. All three kernels run 
concurrently and exchange data through channels, an Altera specific 
extension. See device/fft2d.cl for more implementation details.

Example output of running this benchmark is shown below:

Launching FFT transform (ordered data layout)
Kernel initialization is complete.
        Processing time = 3.4020ms
        Throughput = 0.3082 Gpoints / sec (30.8224 Gflops)
        Signal to noise ratio on output sample: 124.236435 --> PASSED

Launching inverse FFT transform (ordered data layout)
Kernel initialization is complete.
        Processing time = 3.3848ms
        Throughput = 0.3098 Gpoints / sec (30.9787 Gflops)
        Signal to noise ratio on output sample: 124.227971 --> PASSED

Launching FFT transform (alternative data layout)
Kernel initialization is complete.
        Processing time = 2.1122ms
        Throughput = 0.4964 Gpoints / sec (49.6450 Gflops)
        Signal to noise ratio on output sample: 124.236876 --> PASSED

Launching inverse FFT transform (alternative data layout)
Kernel initialization is complete.
        Processing time = 2.1369ms
        Throughput = 0.4907 Gpoints / sec (49.0689 Gflops)
        Signal to noise ratio on output sample: 124.231472 --> PASSED


Software and Board Requirements
===============================

This design example is for use with the following versions of the 
Altera Complete Design Suite and Quartus(R) II software and
Altera SDK for OpenCL software:
    - 14.0 or later

For host program compilation, the requirements are:
    - Linux: GNU Make and gcc
    - Windows: Microsoft Visual Studio 2010

The supported operating systems for this release:
    - All operating systems supported by the Altera SDK for OpenCL


Usage Instructions
==================

Linux:
  1. make
  2. ./bin/fft2d

Windows:
  1. Build the project in Visual Studio 2010.
  2. Run (Ctrl+F5).

AOCX selection
--------------

The host program will use an AOCX file in the bin directory. If fft2d.aocx
exists, then that will be used. Otherwise, the host program will examine the device
name to extract the board name (which was passed as the --board argument to aoc)
and check for a fft2d_<board>_140.aocx file.


Package Contents and Directory Structure
========================================

/fft2d
  /device
     Contains OpenCL kernel source files (.cl)
  /host
    /inc
      Contains host include (.h) files
    /src
      Contains host source (.cpp) files
  /bin
    Contains host binary and OpenCL binaries (.aocx)


Generating Kernel
=================

To compile the kernel, run:

  aoc device/fft2d.cl -o bin/fft2d.aocx --fpc --no-interleaving default --board <board>

where <board> matches the board you have in your system. If you are unsure
of the board name, use the following command to list available boards:

  aoc --list-boards

This compilation command can also be used to target the emulator by adding 
the -march=emulator flag.

If the board already has a AOCX file (see AOCX selection section above),
be sure to either replace or relocate that AOCX file.


Release History
===============

SDK Version   Example Version   Comments
-------------------------------------------------------------------------------
14.0          1.2               Update documentation for 14.0 release.
13.1          1.1               On Linux, fix possible compilation issues in 
                                AOCL_Utils by including <unistd.h>.
13.1          1.0               First release of example


Disclaimer & Licenses
=====================

Copyright (C) 2013-2014 Altera Corporation, San Jose, California, USA. All rights reserved. 
Permission is hereby granted, free of charge, to any person obtaining a copy of this 
software and associated documentation files (the "Software"), to deal in the Software 
without restriction, including without limitation the rights to use, copy, modify, merge, 
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to 
whom the Software is furnished to do so, subject to the following conditions: 
The above copyright notice and this permission notice shall be included in all copies or 
substantial portions of the Software. 
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
OTHER DEALINGS IN THE SOFTWARE. 
 
This agreement shall be governed in all respects by the laws of the State of California and 
by the laws of the United States of America. 


Contacting Altera
=================

Although we have made every effort to ensure that this design example works
correctly, there might be problems that we have not encountered. If you have
a question or problem that is not answered by the information provided in 
this readme file or the example's documentation, please contact Altera(R) 
support.

http://www.altera.com/mysupport/

