Altera SDK for OpenCL
                                                                                  Programming Guide
                               Last updated for Quartus Prime Design Suite: 15.1
                Subscribe                                 UG-OCL002    101 Innovation Drive
                                                           2015.11.02  San Jose, CA 95134
                Send Feedback                                          www.altera.com
     TOC-2
      Contents
           Altera SDK for OpenCL Programming Guide...................................................1-1
              Altera SDK for OpenCL Programming Guide Prerequisites.................................................................1-1
              Altera SDK for OpenCL FPGA Programming Flow...............................................................................1-2
              Altera Offline Compiler Kernel Compilation Flows...............................................................................1-4
                 One-Step Compilation for Simple Kernels...................................................................................1-4
                 Multistep Altera SDK for OpenCL Design Flow.........................................................................1-5
              Obtaining General Information on Software, Compiler, and Custom Platform................................1-7
                 Displaying the Software Version (version)...................................................................................1-8
                 Displaying the Compiler Version (--version)..............................................................................1-8
                 Listing the Altera SDK for OpenCL Utility Command Options (help)...................................1-8
                 Listing the Altera Offline Compiler Command Options (no argument, --help, or -h).........1-8
                 Listing the Available FPGA Boards in Your Custom Platform (--list-boards).......................1-9
              Managing an FPGA Board..........................................................................................................................1-9
                 Installing an FPGA Board (install)..............................................................................................1-10
                 Uninstalling the FPGA Board (uninstall)...................................................................................1-11
                 Querying the Device Name of Your FPGA Board (diagnose).................................................1-11
                 Running a Board Diagnostic Test (diagnose )...............................................1-12
                 Programming the FPGA Offline or without a Host (program ).................1-12
                 Programming the Flash Memory (flash )....................................................... 1-13
              Structuring Your OpenCL Kernel........................................................................................................... 1-13
                 Guidelines for Naming the Kernel.............................................................................................. 1-14
                 Programming Strategies for Optimizing Data Processing Efficiency.................................... 1-15
                 Programming Strategies for Optimizing Memory Access Efficiency.....................................1-17
                 Implementing the Altera SDK for OpenCL Channels Extension...........................................1-18
                 Implementing OpenCL Pipes.......................................................................................................1-35
                 Using Predefined Preprocessor Macros in Conditional Compilation................................... 1-49
                 Declaring __constant Address Space Qualifiers........................................................................1-50
                 Including Structure Data Types as Arguments in OpenCL Kernels...................................... 1-51
                 Inferring a Register........................................................................................................................ 1-54
                 Enabling Double Precision Floating-Point Operations............................................................1-56
              Designing Your Host Application...........................................................................................................1-56
                 Host Programming Requirements.............................................................................................. 1-57
                 Allocating OpenCL Buffer for Manual Partitioning of Global Memory............................... 1-57
                 Creating a Pipe Object in Your Host Application.....................................................................1-59
                 Collecting Profile Data During Kernel Execution.....................................................................1-60
                 Accessing Custom Platform-Specific Functions....................................................................... 1-62
                 Modifying Host Program for Structure Parameter Conversion............................................. 1-62
                 Allocating Shared Memory for OpenCL Kernels Targeting SoCs..........................................1-63
                 Managing Host Application.........................................................................................................1-65
              Compiling Your OpenCL Kernel............................................................................................................ 1-75
                 Compiling Your Kernel to Create Hardware Configuration File...........................................1-76
                 Compiling a Kernel for a Big-Endian System (--big-endian)..................................................1-76
    Altera Corporation
                                                           TOC-3
                 Compiling Your Kernel without Building Hardware (-c)........................................................1-76
                 Specifying the Location of Header Files (-I )........................................................ 1-77
                 Specifying the Name of an AOC Output File (-o )................................................1-77
                 Compiling a Kernel for a Specific FPGA Board (--board )...........................1-78
                 Resolving Hardware Generation Fitting Errors during Kernel Compilation (--high-
                   effort)..........................................................................................................................................1-79
                 Defining Preprocessor Macros to Specify Kernel Parameters (-D )...........1-79
                 Generating Compilation Progress Report (-v).......................................................................... 1-81
                 Displaying the Estimated Resource Usage Summary On-Screen (--report).........................1-81
                 Suppressing AOC Warning Messages (-W)...............................................................................1-82
                 Converting AOC Warning Messages into Error Messages (-Werror)...................................1-82
                 Adding Source References to Optimization Reports (-g)........................................................ 1-82
                 Disabling Burst-Interleaving of Global Memory (--no-interleaving
                   ).........................................................................................................1-82
                 Configuring Constant Memory Cache Size (--const-cache-bytes )................................1-83
                 Relaxing the Order of Floating-Point Operations (--fp-relaxed)............................................1-83
                 Reducing Floating-Point Rounding Operations (--fpc)...........................................................1-84
              Emulating and Debugging Your OpenCL Kernel.................................................................................1-84
                 Modifying Channels Kernel Code for Emulation..................................................................... 1-84
                 Compiling a Kernel for Emulation (-march=emulator).......................................................... 1-86
                 Emulating Your OpenCL Kernel.................................................................................................1-87
                 Debugging Your OpenCL Kernel on Linux...............................................................................1-87
                 Limitations of the AOCL Emulator.............................................................................................1-89
              Profiling Your OpenCL Kernel................................................................................................................1-89
                 Instrumenting the Kernel Pipeline with Performance Counters (--profile).........................1-90
                 Launching the AOCL Profiler GUI (report)..............................................................................1-90
              Conclusion..................................................................................................................................................1-90
              Document Revision History.....................................................................................................................1-91
           Support Statuses of OpenCL Features .............................................................. A-1
              Support Statuses of OpenCL 1.0 Features............................................................................................... A-1
                 OpenCL1.0 C Programming Language Implementation..........................................................A-1
                 OpenCL C Programming Language Restrictions.......................................................................A-4
                 Argument Types for Built-in Geometric Functions...................................................................A-5
                 Numerical Compliance Implementation.....................................................................................A-6
                 Image Addressing and Filtering Implementation...................................................................... A-7
                 Atomic Functions............................................................................................................................A-7
                 Embedded Profile Implementation..............................................................................................A-7
              Support Statuses of OpenCL 1.2 Features............................................................................................... A-8
                 OpenCL 1.2 Runtime Implementation........................................................................................A-8
                 OpenCL 1.2 C Programming Language Implementation.........................................................A-8
              Support Statuses of OpenCL 2.0 Features............................................................................................... A-9
                 OpenCL 2.0 Runtime Implementation........................................................................................A-9
                 OpenCL 2.0 C Programming Language Restrictions for Pipes..............................................A-10
              Altera SDK for OpenCL Allocation Limits........................................................................................... A-11
              Document Revision History....................................................................................................................A-12
                                                       Altera Corporation
                                                               Altera SDK for OpenCL Programming Guide                                                                                                1
                        2015.11.02
                        UG-OCL002                           Subscribe                  Send Feedback
                                 The Altera SDK for OpenCL Programming Guide provides descriptions, recommendations and usage
                                                                           ®                                                                             ™
                                 information on the Altera  Software Development Kit (SDK) for OpenCL  (AOCL) compiler and tools.
                                                   (1)                       (2)
                                 The AOCL  is an OpenCL -based heterogeneous parallel programming environment for Altera FPGAs.
                    Altera SDK for OpenCL Programming Guide Prerequisites
                                 The Altera SDK for OpenCL Programming Guide assumes that you are knowledgeable in OpenCL
                                 concepts and application programming interfaces (APIs). It also assumes that you have experience
                                 creating OpenCL applications and are familiar with the OpenCL Specification version 1.0.
                                 Before using the Altera SDK for OpenCL or the Altera Runtime Environment (RTE) for OpenCL to
                                 program your device, familiarize yourself with the respective getting started guides. This document
                                 assumes that you have performed the following tasks:
                                 •     For developing and deploying OpenCL kernels, download the tar file and run the installers to install
                                                                            ®
                                       the AOCL, the Quartus  Prime software, and device support.
                                 •     For deployment of OpenCL kernels, download and install the RTE.
                                 •     If you want to use the AOCL or the RTE to program a Cyclone V SoC Development Kit, you also have
                                       to download and install the SoC Embedded Design Suite (EDS).
                                 •     Install and set up your FPGA board.
                                 •     Program your device with the device-compatible version of the hello_world example OpenCL applica‐
                                       tion
                                 If you have not performed the tasks described above, refer to the AOCL getting starting guides for more
                                 information.
                                 Related Information
                                 •     OpenCL References Pages
                                 •     OpenCL Specification version 1.0
                                 •     Altera SDK for OpenCL Getting Started Guide
                                 •     Altera RTE for OpenCL Getting Started Guide
                       (1)   The Altera SDK for OpenCL is based on a published Khronos Specification, and has passed the Khronos
                             Conformance Testing Process. Current conformance status can be found at www.khronos.org/
                             conformance.
                       (2)                                                                                                                                                                        ™
                             OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission of the Khronos Group .
                     ©
                        2015 Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, ENPIRION, MAX, MEGACORE, NIOS, QUARTUS and STRATIX words and logos are
                     trademarks of Altera Corporation and registered in the U.S. Patent and Trademark Office and in other countries. All other words and logos identified as                        ISO
                     trademarks or service marks are the property of their respective holders as described at www.altera.com/common/legal.html. Altera warrants performance                     9001:2008
                     of its semiconductor products to current specifications in accordance with Altera's standard warranty, but reserves the right to make changes to any                      Registered
                     products and services at any time without notice. Altera assumes no responsibility or liability arising out of the application or use of any information,
                     product, or service described herein except as expressly agreed to in writing by Altera. Altera customers are advised to obtain the latest version of device
                     specifications before relying on any published information and before placing orders for products or services.
                www.altera.com
                101 Innovation Drive, San Jose, CA 95134