®                                                        ™
                Intel  FPGA SDK for OpenCL
                Programming Guide
                               ®        ®
                Updated for Intel  Quartus  Prime Design Suite: 17.1
                     Subscribe
                                                                                  UG-OCL002 | 2017.12.08
                     Send Feedback                                  Latest document on the web: PDF | HTML
                                                                                                                              Contents
                   Contents
                           ®                              ™
                   1 Intel  FPGA SDK for OpenCL  Overview.......................................................................... 6
                          1.1 Intel FPGA SDK for OpenCL Programming Guide Prerequisites...................................... 6
                          1.2 Intel FPGA SDK for OpenCL FPGA Programming Flow...................................................7
                   2 Intel FPGA SDK for OpenCL Offline Compiler Kernel Compilation Flows...........................9
                          2.1 One-Step Compilation for Simple Kernels................................................................. 10
                          2.2 Multistep Intel FPGA SDK for OpenCL Design Flow.....................................................11
                   3 Obtaining General Information on Software, Compiler, and Custom Platform................14
                          3.1 Displaying the Software Version (version)................................................................ 14
                          3.2 Displaying the Compiler Version (-version)............................................................... 14
                          3.3 Listing the Intel FPGA SDK for OpenCL Utility Command Options (help)........................15
                                  3.3.1 Displaying Information on an Intel FPGA SDK for OpenCL Utility Command
                                          Option (help )............................................................. 15
                          3.4 Listing the Intel FPGA SDK for OpenCL Offline Compiler Command Options (no
                                  argument, -help, or -h)......................................................................................15
                          3.5 Listing the Available FPGA Boards in Your Custom Platform (-list-boards)......................16
                          3.6 Displaying the Compilation Environment of an OpenCL Binary (env)............................ 16
                   4 Managing an FPGA Board...............................................................................................17
                          4.1 Installing an FPGA Board (install)............................................................................17
                          4.2 Uninstalling the FPGA Board (uninstall)....................................................................19
                          4.3 Querying the Device Name of Your FPGA Board (diagnose).........................................19
                          4.4 Running a Board Diagnostic Test (diagnose )......................................20
                          4.5 Programming the FPGA Offline or without a Host (program )................20
                          4.6 Programming the Flash Memory (flash )............................................21
                   5 Structuring Your OpenCL Kernel.................................................................................... 22
                          5.1 Guidelines for Naming the Kernel............................................................................22
                          5.2 Programming Strategies for Optimizing Data Processing Efficiency...............................23
                                  5.2.1 Unrolling a Loop........................................................................................23
                                  5.2.2 Coalescing Nested Loops............................................................................24
                                  5.2.3 Specifying a Loop Initiation interval (II)....................................................... 25
                                  5.2.4 Specifying Work-Group Sizes......................................................................26
                                  5.2.5 Specifying Number of Compute Units...........................................................27
                                  5.2.6 Specifying Number of SIMD Work-Items.......................................................28
                          5.3 Programming Strategies for Optimizing Local Memory Efficiency..................................29
                          5.4 Implementing the Intel FPGA SDK for OpenCL Channels Extension.............................. 29
                                  5.4.1 Overview of the Intel FPGA SDK for OpenCL Channels Extension..................... 29
                                  5.4.2 Channel Data Behavior.............................................................................. 30
                                  5.4.3 Multiple Work-Item Ordering for Channels.................................................... 31
                                  5.4.4 Restrictions in the Implementation of Intel FPGA SDK for OpenCL Channels
                                          Extension ...............................................................................................32
                                  5.4.5 Enabling the Intel FPGA SDK for OpenCL Channels for OpenCL Kernel..............34
                          5.5 Implementing OpenCL Pipes...................................................................................48
                                  5.5.1 Overview of the OpenCL Pipe Functions........................................................48
                                  5.5.2 Pipe Data Behavior....................................................................................49
                                  5.5.3 Multiple Work-Item Ordering for Pipes..........................................................50
                                  5.5.4 Restrictions in OpenCL Pipes Implementation................................................52
                       ®                     ™
                   Intel  FPGA SDK for OpenCL  Programming Guide
                   2
                     Contents
                                    5.5.5 Enabling OpenCL Pipes for Kernels.............................................................. 53
                                    5.5.6 Direct Communication with Kernels via Host Pipes.........................................64
                             5.6 Implementing Arbitrary Precision Integers................................................................68
                             5.7 Using Predefined Preprocessor Macros in Conditional Compilation................................69
                             5.8 Declaring __constant Address Space Qualifiers......................................................... 70
                             5.9 Including Structure Data Types as Arguments in OpenCL Kernels.................................71
                                    5.9.1 Matching Data Layouts of Host and Kernel Structure Data Types......................71
                                    5.9.2 Disabling Insertion of Data Structure Padding .............................................. 73
                                    5.9.3 Specifying the Alignment of a Struct............................................................73
                             5.10 Inferring a Register............................................................................................. 74
                                    5.10.1 Inferring a Shift Register..........................................................................75
                             5.11 Enabling Double Precision Floating-Point Operations.................................................76
                             5.12 Single-Cycle Floating-Point Accumulator for Single Work-Item Kernels........................76
                                    5.12.1 Programming Strategies for Inferring the Accumulator................................. 77
                     6 Designing Your Host Application....................................................................................79
                             6.1 Host Programming Requirements............................................................................79
                                    6.1.1 Host Machine Memory Requirements........................................................... 79
                                    6.1.2 Host Binary Requirement........................................................................... 79
                                    6.1.3 Multiple Host Threads................................................................................80
                                    6.1.4 Out-of-Order Command Queues..................................................................80
                                    6.1.5 Requirement for Multiple Command Queues in Channels or Pipes
                                            Implementation.......................................................................................80
                             6.2 Allocating OpenCL Buffers for Manual Partitioning of Global Memory............................ 80
                                    6.2.1 Partitioning Buffers Across Multiple Interfaces of the Same Memory Type..........80
                                    6.2.2 Partitioning Buffers Across Different Memory Types (Heterogeneous Memory)... 82
                                    6.2.3 Creating a Pipe Object in Your Host Application............................................. 83
                             6.3 Collecting Profile Data During Kernel Execution.........................................................84
                                    6.3.1 Profiling Enqueued and Autorun Kernels ......................................................86
                                    6.3.2 Profile Data Acquisition..............................................................................87
                                    6.3.3 Multiple Autorun Profiling Calls....................................................................87
                             6.4 Accessing Custom Platform-Specific Functions.......................................................... 88
                             6.5 Modifying Host Program for Structure Parameter Conversion.......................................89
                             6.6 Managing Host Application..................................................................................... 90
                                    6.6.1 Displaying Example Makefile Fragments (example-makefile or makefile)...........90
                                    6.6.2 Compiling and Linking Your Host Application.................................................91
                                    6.6.3 Linking Your Host Application to the Khronos ICD Loader Library..................... 94
                                    6.6.4 Programming an FPGA via the Host............................................................. 96
                                    6.6.5 Termination of the Runtime Environment and Error Recovery........................ 100
                             6.7 Allocating Shared Memory for OpenCL Kernels Targeting SoCs...................................101
                             6.8 Debugging Your OpenCL System That is Gradually Slowing Down.............................. 103
                     7 Compiling Your OpenCL Kernel.....................................................................................104
                             7.1 Compiling Your Kernel to Create Hardware Configuration File.................................... 104
                             7.2 Compiling Your Kernel without Building Hardware (-c)..............................................105
                             7.3 Specifying the Location of Header Files (-I=)..........................................105
                             7.4 Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File
                                    (-o=)............................................................................................ 106
                             7.5 Compiling a Kernel for a Specific FPGA Board (-board=).....................106
                             7.6 Resolving Hardware Generation Fitting Errors during Kernel Compilation (-high-effort). 108
                             7.7 Defining Preprocessor Macros to Specify Kernel Parameters (-D).........108
                             7.8 Generating Compilation Progress Report (-v).......................................................... 110
                                                                                                 ®                    ™
                                                                                            Intel  FPGA SDK for OpenCL  Programming Guide
                                                                                                                                         3
                                                                                                                              Contents
                          7.9 Displaying the Estimated Resource Usage Summary On-Screen (-report)....................111
                          7.10 Suppressing Warning Messages from the Intel FPGA SDK for OpenCL Offline
                                  Compiler (-W).................................................................................................111
                          7.11 Converting Warning Messages from the Intel FPGA SDK for OpenCL Offline
                                  Compiler into Error Messages (-Werror)..............................................................111
                          7.12 Removing Debug Data from Compiler Reports and Source Code from the .aocx File
                                  (-g0)............................................................................................................. 112
                          7.13 Disabling Burst-Interleaving of Global Memory (-no-
                                  interleaving=)...............................................................112
                          7.14 Configuring Constant Memory Cache Size (-const-cache-bytes=)...................... 113
                          7.15 Relaxing the Order of Floating-Point Operations (-fp-relaxed)..................................113
                          7.16 Reducing Floating-Point Rounding Operations (-fpc)............................................... 113
                          7.17 Speeding Up Your OpenCL Compilation (-fast-compile)...........................................114
                   8 Emulating and Debugging Your OpenCL Kernel............................................................115
                          8.1 Modifying Channels Kernel Code for Emulation........................................................ 115
                                  8.1.1 Emulating a Kernel that Passes Pipes or Channels by Reference.....................116
                                  8.1.2 Emulating Channel Depth.........................................................................117
                          8.2 Compiling a Kernel for Emulation (-march=emulator)...............................................117
                          8.3 Emulating Your OpenCL Kernel..............................................................................118
                          8.4 Debugging Your OpenCL Kernel on Linux................................................................120
                          8.5 Limitations of the Intel FPGA SDK for OpenCL Emulator............................................121
                          8.6 Discrepancies in Hardware and Emulator Results.....................................................122
                   9 Reviewing Your Kernel's report.html File.....................................................................124
                   10 Profiling Your OpenCL Kernel.....................................................................................125
                          10.1 Instrumenting the Kernel Pipeline with Performance Counters (-profile)....................125
                          10.2 Launching the Intel FPGA Dynamic Profiler for OpenCL GUI (report).........................126
                          10.3 Profiling Autorun Kernels....................................................................................126
                   11 Developing OpenCL Applications Using Intel Code Builder for OpenCL.......................128
                          11.1 Configuring the Intel Code Builder for OpenCL Offline Compiler Plug-in for
                                  Microsoft Visual Studio.....................................................................................128
                          11.2 Configuring the Intel Code Builder for OpenCL Offline Compiler Plug-in for Eclipse......128
                          11.3 Creating a Session in the Intel Code Builder for OpenCL ........................................ 129
                          11.4 Configuring a Session........................................................................................ 130
                   12 Intel FPGA SDK for OpenCL Advanced Features......................................................... 132
                          12.1 OpenCL Library................................................................................................. 132
                                  12.1.1 Understanding RTL Modules and the OpenCL Pipeline................................. 134
                                  12.1.2 Packaging an OpenCL Helper Function File for an OpenCL Library.................145
                                  12.1.3 Packaging an RTL Component for an OpenCL Library .................................146
                                  12.1.4 Verifying the RTL Modules.......................................................................148
                                  12.1.5 Packaging Multiple Object Files into a Library File.......................................149
                                  12.1.6 Specifying an OpenCL Library when Compiling an OpenCL Kernel.................149
                                  12.1.7 Using an OpenCL Library that Works with Simple Functions (Example 1).......150
                                  12.1.8 Using an OpenCL Library that Works with External Memory (Example 2).......151
                                  12.1.9 OpenCL Library Command-Line Options....................................................152
                          12.2 Kernel Attributes for Configuring Local Memory System.......................................... 153
                                  12.2.1 Restrictions on the Usage of Local Variable-Specific Kernel Attributes............154
                          12.3 Kernel Attributes for Reducing the Overhead on Hardware Usage.............................155
                                  12.3.1 Hardware for Kernel Interface................................................................. 155
                       ®                    ™
                   Intel  FPGA SDK for OpenCL  Programming Guide
                   4