55
Intel ® FPGA SDK for OpenCL Pro Edition Getting Started Guide Updated for Intel ® Quartus ® Prime Design Suite: 21.2 Subscribe Send Feedback UG-OCL001 | 2021.06.21 Latest document on the web: PDF | HTML

Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

  • Upload
    others

  • View
    42

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Intelreg FPGA SDK for OpenCLtrade ProEditionGetting Started Guide

Updated for Intelreg Quartusreg Prime Design Suite 212

SubscribeSend Feedback

UG-OCL001 | 20210621Latest document on the web PDF | HTML

Contents

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide 411 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition5

111 GCC Requirement 712 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility 1013 Contents of the Intel FPGA SDK for OpenCL Pro Edition1114 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process12

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows1521 Downloading the Intel FPGA SDK for OpenCL Pro Edition 1522 Installing the Intel FPGA SDK for OpenCL Pro Edition 1623 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables1724 Verifying Software Installation 1825 Installing an FPGA Board 19

251 Enabling Backwards Compatibility for an FPGA Board2026 Verifying Host Runtime Functionality via Emulation21

261 Accessing an OpenCL Design Example 22262 Compiling a Kernel for Emulation 22263 Building the Host Application 22264 Emulating Your OpenCL Kernel24

27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel2428 Updating the Hardware Image on the FPGA 27

281 Querying the Device Name of Your FPGA Board27282 Programming the Flash Memory of an FPGA28

29 Executing an OpenCL Kernel on an FPGA29291 Running the Host Application29292 Output from Successful Kernel Execution29

210 Uninstalling an FPGA Board 30211 Uninstalling the Software 30

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux 3231 Downloading the Intel FPGA SDK for OpenCL Pro Edition3232 Installing the Intel FPGA SDK for OpenCL Pro Edition3333 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables3434 Verifying Software Installation 3535 Installing an FPGA Board 35

351 Enabling Backwards Compatibility for an FPGA Board3736 Verifying Host Runtime Functionality via Emulation37

361 Accessing an OpenCL Design Example 38362 Compiling a Kernel for Emulation 38363 Building the Host Application 38364 Emulating Your OpenCL Kernel39

37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel4038 Updating the Hardware Image on the FPGA 42

381 Querying the Device Name of Your FPGA Board43382 Programming the Flash Memory of an FPGA43

39 Executing an OpenCL Kernel on an FPGA44391 Running the Host Application44392 Output from Successful Kernel Execution45

Contents

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

2

310 Uninstalling an FPGA Board 46311 Uninstalling the Software 46

A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives47

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition GettingStarted Guide 48

Contents

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

3

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition GettingStarted Guide

The Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide describes theprocedures to install the Intel FPGA Software Development Kit (SDK) for OpenCL(1)Pro Edition This document also contains instructions on how to compile an exampleOpenCL(2) application with the Intel FPGA SDK for OpenCL Pro Edition

OpenCL is a C-based open standard for the parallel programming of heterogeneousdevices For more information about the OpenCL Specification version 10 refer to the OpenCL 10 Reference Pages For detailed information on the OpenCL applicationprogramming interface (API) and programming language refer to the OpenCLSpecification version 10

The Intel FPGA SDK for OpenCL Pro Edition provides a compiler and tools for you tobuild and run OpenCL applications that target Intel FPGA products The Intel FPGASDK for OpenCL Pro Edition supports the embedded profile of the OpenCLSpecification version 10

Tip If you are looking for instructions to get started with oneAPI toolkits use the followinglinks

bull Intel oneAPI Base Toolkit Includes the Intel oneAPI DPC++C++ Compiler andprovides tools and libraries for developing high-performance data-centricapplications across diverse architectures

bull Intel FPGA Add-on for oneAPI Base Toolkit Specialized toolkit for programmingFPGAs

bull Intel DevCloud A cloud-based sandbox to actively prototype and experiment withworkloads on Intel hardware

bull Intel oneAPI Toolkits Installation Guides Provides instructions for installing thetoolkits

bull Get Started with Intel oneAPI Base Toolkit on the DevCloud Provides instructionsto get started with the Intel DevCloud development sandbox

bull Get Started with the Intel oneAPI Base Toolkit for Linux Provides Linux-specificgetting started instructions

bull Get Started with the Intel oneAPI Base Toolkit for Windows Provides Windows-specific getting started instructions

(1) The Intel FPGA SDK for OpenCL is based on a published Khronos Specification and has passedthe Khronos Conformance Testing Process Current conformance status can be found at wwwkhronosorgconformance

(2) OpenCL and the OpenCL logo are trademarks of Apple Inc used by permission of the KhronosGrouptrade

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Attention bull If you only require the Intel FPGA SDK for OpenCLs kernel deploymentfunctionality download and install the Intel FPGA Runtime Environment (RTE) forOpenCL Refer to the Intel FPGA RTE for OpenCL Pro Edition Getting Started Guidefor more information

Do not install the SDK and the RTE on the same host system The SDK alreadycontains the RTE

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the Intel Arriareg

10 GX FPGA Development Kit refer to the Application Note Configuring the IntelArria 10 GX FPGA Development Kit for the Intel FPGA SDK for OpenCL for moreinformation

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the IntelStratixreg 10 GX Development Kit refer to Intel Stratix 10 Development KitInitialization guide (bringup guide included in the ltpath_to_BSPgts10_refbringup directory) and Intel Stratix 10 GX FPGA Development Kit User Guide formore information

Related Information

bull OpenCL Reference Pages

bull OpenCL Specification version 10

bull Intel FPGA RTE for OpenCL Pro Edition Getting Started Guide

bull Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDKfor OpenCL

bull Intel Stratix 10 GX FPGA Development Kit User Guide

11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition

To install the Intel FPGA SDK for OpenCL Pro Edition and create an OpenCL applicationfor an Intel FPGA Preferred Board for OpenCL your system must meet certainhardware target platform and software requirements

Hardware Requirements

Accelerator boards requirements

bull Acquire a Reference Platform from Intel or a Custom Platform from an Intelpreferred board vendor

For more information refer to the Intel FPGA SDK for OpenCL FPGA Platformspage on the Intel FPGA website

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

5

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 2: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Contents

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide 411 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition5

111 GCC Requirement 712 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility 1013 Contents of the Intel FPGA SDK for OpenCL Pro Edition1114 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process12

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows1521 Downloading the Intel FPGA SDK for OpenCL Pro Edition 1522 Installing the Intel FPGA SDK for OpenCL Pro Edition 1623 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables1724 Verifying Software Installation 1825 Installing an FPGA Board 19

251 Enabling Backwards Compatibility for an FPGA Board2026 Verifying Host Runtime Functionality via Emulation21

261 Accessing an OpenCL Design Example 22262 Compiling a Kernel for Emulation 22263 Building the Host Application 22264 Emulating Your OpenCL Kernel24

27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel2428 Updating the Hardware Image on the FPGA 27

281 Querying the Device Name of Your FPGA Board27282 Programming the Flash Memory of an FPGA28

29 Executing an OpenCL Kernel on an FPGA29291 Running the Host Application29292 Output from Successful Kernel Execution29

210 Uninstalling an FPGA Board 30211 Uninstalling the Software 30

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux 3231 Downloading the Intel FPGA SDK for OpenCL Pro Edition3232 Installing the Intel FPGA SDK for OpenCL Pro Edition3333 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables3434 Verifying Software Installation 3535 Installing an FPGA Board 35

351 Enabling Backwards Compatibility for an FPGA Board3736 Verifying Host Runtime Functionality via Emulation37

361 Accessing an OpenCL Design Example 38362 Compiling a Kernel for Emulation 38363 Building the Host Application 38364 Emulating Your OpenCL Kernel39

37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel4038 Updating the Hardware Image on the FPGA 42

381 Querying the Device Name of Your FPGA Board43382 Programming the Flash Memory of an FPGA43

39 Executing an OpenCL Kernel on an FPGA44391 Running the Host Application44392 Output from Successful Kernel Execution45

Contents

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

2

310 Uninstalling an FPGA Board 46311 Uninstalling the Software 46

A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives47

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition GettingStarted Guide 48

Contents

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

3

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition GettingStarted Guide

The Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide describes theprocedures to install the Intel FPGA Software Development Kit (SDK) for OpenCL(1)Pro Edition This document also contains instructions on how to compile an exampleOpenCL(2) application with the Intel FPGA SDK for OpenCL Pro Edition

OpenCL is a C-based open standard for the parallel programming of heterogeneousdevices For more information about the OpenCL Specification version 10 refer to the OpenCL 10 Reference Pages For detailed information on the OpenCL applicationprogramming interface (API) and programming language refer to the OpenCLSpecification version 10

The Intel FPGA SDK for OpenCL Pro Edition provides a compiler and tools for you tobuild and run OpenCL applications that target Intel FPGA products The Intel FPGASDK for OpenCL Pro Edition supports the embedded profile of the OpenCLSpecification version 10

Tip If you are looking for instructions to get started with oneAPI toolkits use the followinglinks

bull Intel oneAPI Base Toolkit Includes the Intel oneAPI DPC++C++ Compiler andprovides tools and libraries for developing high-performance data-centricapplications across diverse architectures

bull Intel FPGA Add-on for oneAPI Base Toolkit Specialized toolkit for programmingFPGAs

bull Intel DevCloud A cloud-based sandbox to actively prototype and experiment withworkloads on Intel hardware

bull Intel oneAPI Toolkits Installation Guides Provides instructions for installing thetoolkits

bull Get Started with Intel oneAPI Base Toolkit on the DevCloud Provides instructionsto get started with the Intel DevCloud development sandbox

bull Get Started with the Intel oneAPI Base Toolkit for Linux Provides Linux-specificgetting started instructions

bull Get Started with the Intel oneAPI Base Toolkit for Windows Provides Windows-specific getting started instructions

(1) The Intel FPGA SDK for OpenCL is based on a published Khronos Specification and has passedthe Khronos Conformance Testing Process Current conformance status can be found at wwwkhronosorgconformance

(2) OpenCL and the OpenCL logo are trademarks of Apple Inc used by permission of the KhronosGrouptrade

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Attention bull If you only require the Intel FPGA SDK for OpenCLs kernel deploymentfunctionality download and install the Intel FPGA Runtime Environment (RTE) forOpenCL Refer to the Intel FPGA RTE for OpenCL Pro Edition Getting Started Guidefor more information

Do not install the SDK and the RTE on the same host system The SDK alreadycontains the RTE

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the Intel Arriareg

10 GX FPGA Development Kit refer to the Application Note Configuring the IntelArria 10 GX FPGA Development Kit for the Intel FPGA SDK for OpenCL for moreinformation

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the IntelStratixreg 10 GX Development Kit refer to Intel Stratix 10 Development KitInitialization guide (bringup guide included in the ltpath_to_BSPgts10_refbringup directory) and Intel Stratix 10 GX FPGA Development Kit User Guide formore information

Related Information

bull OpenCL Reference Pages

bull OpenCL Specification version 10

bull Intel FPGA RTE for OpenCL Pro Edition Getting Started Guide

bull Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDKfor OpenCL

bull Intel Stratix 10 GX FPGA Development Kit User Guide

11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition

To install the Intel FPGA SDK for OpenCL Pro Edition and create an OpenCL applicationfor an Intel FPGA Preferred Board for OpenCL your system must meet certainhardware target platform and software requirements

Hardware Requirements

Accelerator boards requirements

bull Acquire a Reference Platform from Intel or a Custom Platform from an Intelpreferred board vendor

For more information refer to the Intel FPGA SDK for OpenCL FPGA Platformspage on the Intel FPGA website

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

5

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 3: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

310 Uninstalling an FPGA Board 46311 Uninstalling the Software 46

A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives47

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition GettingStarted Guide 48

Contents

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

3

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition GettingStarted Guide

The Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide describes theprocedures to install the Intel FPGA Software Development Kit (SDK) for OpenCL(1)Pro Edition This document also contains instructions on how to compile an exampleOpenCL(2) application with the Intel FPGA SDK for OpenCL Pro Edition

OpenCL is a C-based open standard for the parallel programming of heterogeneousdevices For more information about the OpenCL Specification version 10 refer to the OpenCL 10 Reference Pages For detailed information on the OpenCL applicationprogramming interface (API) and programming language refer to the OpenCLSpecification version 10

The Intel FPGA SDK for OpenCL Pro Edition provides a compiler and tools for you tobuild and run OpenCL applications that target Intel FPGA products The Intel FPGASDK for OpenCL Pro Edition supports the embedded profile of the OpenCLSpecification version 10

Tip If you are looking for instructions to get started with oneAPI toolkits use the followinglinks

bull Intel oneAPI Base Toolkit Includes the Intel oneAPI DPC++C++ Compiler andprovides tools and libraries for developing high-performance data-centricapplications across diverse architectures

bull Intel FPGA Add-on for oneAPI Base Toolkit Specialized toolkit for programmingFPGAs

bull Intel DevCloud A cloud-based sandbox to actively prototype and experiment withworkloads on Intel hardware

bull Intel oneAPI Toolkits Installation Guides Provides instructions for installing thetoolkits

bull Get Started with Intel oneAPI Base Toolkit on the DevCloud Provides instructionsto get started with the Intel DevCloud development sandbox

bull Get Started with the Intel oneAPI Base Toolkit for Linux Provides Linux-specificgetting started instructions

bull Get Started with the Intel oneAPI Base Toolkit for Windows Provides Windows-specific getting started instructions

(1) The Intel FPGA SDK for OpenCL is based on a published Khronos Specification and has passedthe Khronos Conformance Testing Process Current conformance status can be found at wwwkhronosorgconformance

(2) OpenCL and the OpenCL logo are trademarks of Apple Inc used by permission of the KhronosGrouptrade

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Attention bull If you only require the Intel FPGA SDK for OpenCLs kernel deploymentfunctionality download and install the Intel FPGA Runtime Environment (RTE) forOpenCL Refer to the Intel FPGA RTE for OpenCL Pro Edition Getting Started Guidefor more information

Do not install the SDK and the RTE on the same host system The SDK alreadycontains the RTE

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the Intel Arriareg

10 GX FPGA Development Kit refer to the Application Note Configuring the IntelArria 10 GX FPGA Development Kit for the Intel FPGA SDK for OpenCL for moreinformation

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the IntelStratixreg 10 GX Development Kit refer to Intel Stratix 10 Development KitInitialization guide (bringup guide included in the ltpath_to_BSPgts10_refbringup directory) and Intel Stratix 10 GX FPGA Development Kit User Guide formore information

Related Information

bull OpenCL Reference Pages

bull OpenCL Specification version 10

bull Intel FPGA RTE for OpenCL Pro Edition Getting Started Guide

bull Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDKfor OpenCL

bull Intel Stratix 10 GX FPGA Development Kit User Guide

11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition

To install the Intel FPGA SDK for OpenCL Pro Edition and create an OpenCL applicationfor an Intel FPGA Preferred Board for OpenCL your system must meet certainhardware target platform and software requirements

Hardware Requirements

Accelerator boards requirements

bull Acquire a Reference Platform from Intel or a Custom Platform from an Intelpreferred board vendor

For more information refer to the Intel FPGA SDK for OpenCL FPGA Platformspage on the Intel FPGA website

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

5

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 4: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition GettingStarted Guide

The Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide describes theprocedures to install the Intel FPGA Software Development Kit (SDK) for OpenCL(1)Pro Edition This document also contains instructions on how to compile an exampleOpenCL(2) application with the Intel FPGA SDK for OpenCL Pro Edition

OpenCL is a C-based open standard for the parallel programming of heterogeneousdevices For more information about the OpenCL Specification version 10 refer to the OpenCL 10 Reference Pages For detailed information on the OpenCL applicationprogramming interface (API) and programming language refer to the OpenCLSpecification version 10

The Intel FPGA SDK for OpenCL Pro Edition provides a compiler and tools for you tobuild and run OpenCL applications that target Intel FPGA products The Intel FPGASDK for OpenCL Pro Edition supports the embedded profile of the OpenCLSpecification version 10

Tip If you are looking for instructions to get started with oneAPI toolkits use the followinglinks

bull Intel oneAPI Base Toolkit Includes the Intel oneAPI DPC++C++ Compiler andprovides tools and libraries for developing high-performance data-centricapplications across diverse architectures

bull Intel FPGA Add-on for oneAPI Base Toolkit Specialized toolkit for programmingFPGAs

bull Intel DevCloud A cloud-based sandbox to actively prototype and experiment withworkloads on Intel hardware

bull Intel oneAPI Toolkits Installation Guides Provides instructions for installing thetoolkits

bull Get Started with Intel oneAPI Base Toolkit on the DevCloud Provides instructionsto get started with the Intel DevCloud development sandbox

bull Get Started with the Intel oneAPI Base Toolkit for Linux Provides Linux-specificgetting started instructions

bull Get Started with the Intel oneAPI Base Toolkit for Windows Provides Windows-specific getting started instructions

(1) The Intel FPGA SDK for OpenCL is based on a published Khronos Specification and has passedthe Khronos Conformance Testing Process Current conformance status can be found at wwwkhronosorgconformance

(2) OpenCL and the OpenCL logo are trademarks of Apple Inc used by permission of the KhronosGrouptrade

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Attention bull If you only require the Intel FPGA SDK for OpenCLs kernel deploymentfunctionality download and install the Intel FPGA Runtime Environment (RTE) forOpenCL Refer to the Intel FPGA RTE for OpenCL Pro Edition Getting Started Guidefor more information

Do not install the SDK and the RTE on the same host system The SDK alreadycontains the RTE

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the Intel Arriareg

10 GX FPGA Development Kit refer to the Application Note Configuring the IntelArria 10 GX FPGA Development Kit for the Intel FPGA SDK for OpenCL for moreinformation

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the IntelStratixreg 10 GX Development Kit refer to Intel Stratix 10 Development KitInitialization guide (bringup guide included in the ltpath_to_BSPgts10_refbringup directory) and Intel Stratix 10 GX FPGA Development Kit User Guide formore information

Related Information

bull OpenCL Reference Pages

bull OpenCL Specification version 10

bull Intel FPGA RTE for OpenCL Pro Edition Getting Started Guide

bull Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDKfor OpenCL

bull Intel Stratix 10 GX FPGA Development Kit User Guide

11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition

To install the Intel FPGA SDK for OpenCL Pro Edition and create an OpenCL applicationfor an Intel FPGA Preferred Board for OpenCL your system must meet certainhardware target platform and software requirements

Hardware Requirements

Accelerator boards requirements

bull Acquire a Reference Platform from Intel or a Custom Platform from an Intelpreferred board vendor

For more information refer to the Intel FPGA SDK for OpenCL FPGA Platformspage on the Intel FPGA website

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

5

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 5: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Attention bull If you only require the Intel FPGA SDK for OpenCLs kernel deploymentfunctionality download and install the Intel FPGA Runtime Environment (RTE) forOpenCL Refer to the Intel FPGA RTE for OpenCL Pro Edition Getting Started Guidefor more information

Do not install the SDK and the RTE on the same host system The SDK alreadycontains the RTE

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the Intel Arriareg

10 GX FPGA Development Kit refer to the Application Note Configuring the IntelArria 10 GX FPGA Development Kit for the Intel FPGA SDK for OpenCL for moreinformation

bull If you want to use the Intel FPGA SDK for OpenCL Pro Edition with the IntelStratixreg 10 GX Development Kit refer to Intel Stratix 10 Development KitInitialization guide (bringup guide included in the ltpath_to_BSPgts10_refbringup directory) and Intel Stratix 10 GX FPGA Development Kit User Guide formore information

Related Information

bull OpenCL Reference Pages

bull OpenCL Specification version 10

bull Intel FPGA RTE for OpenCL Pro Edition Getting Started Guide

bull Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDKfor OpenCL

bull Intel Stratix 10 GX FPGA Development Kit User Guide

11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition

To install the Intel FPGA SDK for OpenCL Pro Edition and create an OpenCL applicationfor an Intel FPGA Preferred Board for OpenCL your system must meet certainhardware target platform and software requirements

Hardware Requirements

Accelerator boards requirements

bull Acquire a Reference Platform from Intel or a Custom Platform from an Intelpreferred board vendor

For more information refer to the Intel FPGA SDK for OpenCL FPGA Platformspage on the Intel FPGA website

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

5

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 6: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Development system requirements

bull You must have administrator root or sudo privileges on the development systemto install the necessary packages and drivers

bull The development system has at least 85 gigabytes (GB) of free disk space forsoftware installation

bull For RAM requirements on the deployment system refer to the Download Centerfor FPGAs

Tip Refer to board vendors documentation on the recommended system storagesize

bull For PCI Express (PCIe) accelerator boards the host machine motherboard musthave an available PCIe port slot that is at least the same width (that is the samenumber of PCIe lanes) as the board

The host system must be running one of the following supported operating systems

bull For a list of supported Windows and Linux operating systems refer to the Operating System Support page on the Intel FPGA website

Software Prerequisites

Develop your host application using one of the following Intel FPGA SDK for OpenCL-and Intel Quartusreg Prime software-compatible C compiler or software developmentenvironment

bull For Windows systems use Microsoft Visual Studio Professional and MicrosoftVisual C++ versions 2015 or later

Note Intel FPGA SDK for OpenCL plug-ins support Windows 10 and WindowsServer 2016 systems with installed Microsoft Visual Studio 2017 or 2019version For correct working of Visual Studio plug-ins you should haveinstalled extensions for CC++ Development for example Desktopdevelopment with C++ and Microsoft Net Framework 45 or higher Formore information about the IDE workflow on Microsoft Visual Studio referto FPGA Workflows in Microsoft Visual Studio

bull For Linux systems use Eclipse 2019-12 or later and GCC 720 For moreinformation about GCC refer to GCC Requirement on page 7

Note For correct working of Eclipse extensions you should have installed CC++Development Tools and Java SE 11 or higher For more information aboutthe IDE workflow on Eclipse refer to FPGA Workflows in Eclipse

Linux systems require the Perl command version 5 or later Include the path to thePerl command in your PATH system environment variable setting

For Intel FPGA SDK for OpenCL packages that include Intel Code Builder Intel CodeBuilder requires Java SE version 1871 or later to run

Related Information

Intel FPGA SDK for OpenCL FPGA Platforms

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

6

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 7: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

111 GCC Requirement

For Linux host systems the Intel FPGA Emulation Platform for OpenCL softwarerequires that you have at least GCC 720 on your system GCC 720 provides thelibstdc++so6 shared library Newer versions may work as well Specificallylibstdc++so6024 library or later is required that defines GLIBCXX_3424and CXXABI_1311 symbol versions

If you do not have a sufficiently new GCC and libstdc++so6 library installed youmay encounter issues when trying to run OpenCL host programs that target the IntelFPGA Emulation Platform for OpenCL software If the correct version of libstdc++so library is not found at run time the call to clGetPlatformIDs function fails toload the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code-1001) Depending on the version of libstdc++so library found the call toclGetPlatformIDs function may succeed but a later call to the clCreateContextfunction might fail with CL_DEVICE_NOT_AVAILABLE (error code -2)

To verify the GCC version you are using run the following command

$ gcc -dumpversion

Ensure that the command reports version 720 or greater If you do not have asufficiently recent GCC use the following instructions to install a newer GCC on yoursystem

Installing GCC 7

The process for installing the required GCC differs depending on the host operatingsystem as described in the following sections

Ubuntu

If your Ubuntu version does not include GCC 7x or later by default you can obtainGCC 7x by using the following commands

$ sudo add-apt-repository ppaubuntu-toolchain-rtest $ sudo apt-get update $ sudo apt-get install gcc-7 g++-7$ sudo update-alternatives --install usrbingcc gcc usrbingcc-7 60 --slave usrbing++ g++ usrbing++-7 $ sudo update-alternatives --config gcc

Note Ensure that you select gcc-7 for the sudo update-alternatives command Theupdate-alternatives utility can be used to swap between GCC versions asrequired

CentOS and Red Hat Enterprise Linux Version 7

Note Unfortunately installing the Developer Toolset (for example devtoolset-7) does notprovide the desired result because it does not include a newer libstdc++so6library The Developer Toolset provides a custom version of the GCC that uses theolder libstdc++so6 library originally installed on the system

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

7

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 8: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

For CentOS and Red Hat Enterprise Linux version 7 Intel recommends that youcompile GCC from source and install it using the following instructions

1 Download the tarball of the GCC version you want to install

wget httpwwwnetgullcomgccreleasesgcc-720gcc-720targz

2 Unpack the tar archive and change the current working directory

tar zxf gcc-720targzcd gcc-720

3 Install the bzip2 package

yum -y install bzip2

4 Run the download_prerequisites script to download some prerequisitesrequired by the GCC

Note You must run the script from the top-level of the GCC source tree

contribdownload_prerequisites

5 Once the prerequisites are downloaded execute the following command to startconfiguring the GCC build environment

configure --disable-multilib --enable-languages=cc++

6 Run the following command to compile the source code Compilation may take afew hours to complete

make -j 4make install

7 Refer to Verifying Your GCC Installation on page 8 section for instructions toverify if your GCC installation was successful

SUSE Enterprise Linux 12

For SUSE Intel recommends that you compile GCC from source and install it byfollowing the instructions provided for CentOS and Red Hat Enterprise Linux

Verifying Your GCC Installation

To verify your GCC installation ensure the following

bull Shell can find the correct GCC binaries

bull The newer GCC is using correct shared libraries (in particular libstdc++so6)

This depends on how you installed the GCC and set the $PATH and$LD_LIBRARY_PATH environment variables You might have installed the GCCbinaries and libraries to the default locations for your operating system

Verifying the Correct GCC Binaries are Used

Perform these steps

1 Verify if your newly-installed GCC binaries are being used

$ which gcc

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

8

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 9: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

2 Ensure the output points to the correct GCC

$ gcc ndashdumpversion

3 Ensure GCC reports a version of 720 or higher

If the above commands do not report the correct GCC version modify your $PATHenvironment variable to point to the location of the newly installed GCC binaries

For Ubuntu the default install location for GCC binaries is usrbin and librariesis usrlib64 However binaries are versioned (for example gcc-7) Use theupdate-alternatives utility to ensure gcc is a symbolic link to the desired GCCversion On Ubuntu systems the $PATH and $LD_LIBRARY_PATH environmentvariables need not be updated because the shell and dynamic linker shouldautomatically search in the correct places for the binaries and libraries respectively

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export PATH=ltpathtonewgccgtbin$PATH

To verify that your $PATH environment variable has been modified appropriately usethe following command

$ echo $PATH

Check the output to ensure that the path to your newly installed GCC is part of your$PATH Repeat these steps to ensure the correct GCC binaries are being used

Verifying the Use of Correct Shared Libraries

To verify that the new GCC libraries are being used check that a test compile linksagainst the correct libstdc++so6 library version by using the following steps

$ echo int main() return 0 gt testcpp $ g++ -Wl--no-as-needed testcpp -o test $ ldd test linux-vdsoso1 =gt (0x00007fff6df35000) libstdc++so6 =gt usrlib64libstdc++so6 (0x0000003451600000) libmso6 =gt lib64libmso6 (0x0000003446a00000) libgcc_sso1 =gt lib64libgcc_sso1 (0x000000344d600000) libcso6 =gt lib64libcso6 (0x0000003446600000) lib64ld-linux-x86-64so2 (0x000055ff56398000) $ strings usrlib64libstdc++so6 | grep GLIBCXX_3424 GLIBCXX_3424

Use the output from the ldd command to determine the path to the libstdc++so6 library that you need to use with the strings command (see highlightedstrings your output may be different) Ensure that the strings command returnsGLIBCXX_3424

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

9

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 10: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Alternatively the libstdc++so6 file is often a symbolic link to the actual librarywhich has the version number appended Therefore instead of calling the stringscommand on libstdc++so6 library you can use the following readlinkcommand to verify libstdc++so6 points to a sufficiently new version of libstdc++

$ readlink usrlib64libstdc++so6 libstdc++so6024

Use the output from the ldd command (executed earlier) to determine the path tolibstdc++so6 that you need to use with the readlink command Ensure thatreadlink command reports that your libstdc++so6 is a symbolic link tolibstdc++so6024 Versions newer than 6024 may also work

If the above commands do not report the correct shared libraries are being used youmight need to modify your $LD_LIBRARY_PATH environment variable to point to thelocation of the newly installed GCC libraries

Tip You can place the following command in your shell startup script or an environmentsetup script so that the development environment is automatically set up when youenter it

$ export LD_LIBRARY_PATH=ltpathtonewgccgtlib64$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modifiedappropriately run the following command

$ echo $LD_LIBRARY_PATH

Check the output to ensure the path to your newly installed GCC libraries are includedin $LD_LIBRARY_PATH Repeat the above steps to ensure the correct GCC libraries(in particular libstdc++so6) are being used

12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSPBackwards Compatibility

The Intel FPGA SDK for OpenCL Pro Edition Version 212 compiler is compatible withOpenCL board support package (BSP) Version 202 and Intel Acceleration StackVersion 201 and Version 121 This backwards compatibility allows you to use olderOpenCL BSPs with newer compilers However some newer OpenCL compiler featuresmight not be available to use with older OpenCL BSPs

Note Starting from the 203 release support for Windows and Linux OpenCL BSPs isremoved Use version 202 or older OpenCL BSPs available at Download Center forFPGAs as a reference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform Porting Guidesavailable under Intel FPGA SDK for OpenCL documentation

To use an older OpenCL BSP with the Intel FPGA SDK for OpenCL you must have aversion of Intel Quartus Prime Pro Edition with the same version number as yourOpenCL BSP For example to use a Version 202 BSP with Intel FPGA SDK for OpenCLPro Edition Version 212 you need Intel Quartus Prime Pro Edition Version 202

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

10

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 11: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Related Information

bull Enabling Backwards Compatibility for an FPGA Board on Windows on page 20

bull Enabling Backwards Compatibility for an FPGA Board on Linux on page 37

13 Contents of the Intel FPGA SDK for OpenCL Pro Edition

The Intel FPGA SDK for OpenCL Pro Edition provides programs and SDK-specificlibraries and files

Logic Components

bull The Intel FPGA SDK for OpenCL Offline Compiler translates your OpenCL devicecode into a hardware configuration file that the system loads onto an Intel FPGAproduct

bull The Intel FPGA SDK for OpenCL Pro Edition utility includes a set of commands youcan invoke to perform high-level tasks such as running diagnostic tests

bull The host runtime provides the OpenCL host and runtime API for your OpenCL hostapplication

The host runtime consists of libraries that provide OpenCL APIs hardwareabstractions and helper libraries

Drivers Libraries and Files

The software installation process installs the Intel FPGA SDK for OpenCL Pro Editioninto a directory that you own The INTELFPGAOCLSDKROOT environment variablereferences the path to the SDKs installation directory

Table 1 Select Contents of the Intel FPGA SDK for OpenCL Pro Edition InstallationDirectory

Windows Folder Linux Directory Description

bin bin User commands in the SDK Include this directory in your PATH environmentvariable setting

boardcustom_platform_toolkittests

board custom_platform_toolkittests

The path to the Intel FPGA SDK for OpenCL Pro Edition kernel code files to testplatformsNote Starting from the 203 release support for Windows and Linux OpenCL

BSPs is removed Use version 202 or older OpenCL BSPs available at Download Center for FPGAs as a reference If you want to migrate yourOpenCL BSP to a newer version follow the recommended steps providedin the Reference Platform Porting Guides available under Intel FPGA SDKfor OpenCL documentation

ip ip Intellectual property (IP) cores used to compile device kernels

host host Files necessary for compiling and running your host application

hostinclude hostinclude OpenCL Specification version 10 header files and software interface filesnecessary for compiling and linking your host applicationThe hostincludeCL subdirectory also includes the C++ header file clhppThe file contains an OpenCL version 11 C++ wrapper API These C++ bindingsenable a C++ host program to access the OpenCL runtime APIs using native C++ classes and methodsImportant The OpenCL version 11 C++ bindings are compatible with OpenCL

Specification versions 10 and 11

Add this path to the include file search path in your development environment

continued

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

11

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 12: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Windows Folder Linux Directory Description

hostwindows64lib

hostlinux64lib

OpenCL host runtime libraries that provide the OpenCL platform and runtimeAPIs These libraries are necessary for linking your host applicationTo run an OpenCL application on Linux include this directory in theLD_LIBRARY_PATH environment variable setting

hostwindows64bin

hostlinux64bin

Runtime commands and libraries necessary for running your host applicationwherever applicable For 64-bit Windows system include this directory in yourPATH environment variable settingbull For Windows system this folder contains runtime librariesbull For Linux system this directory contains platform-specific binary for the aocl

utility command

share share Architecture-independent support files

Example OpenCL Applications

You can refer to example OpenCL applications from the examples_aoc OpenCLdesign examples directory under INTELFPGAOCLSDKROOT

14 Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess

The Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide outlines theprocedures for installing the Intel FPGA SDK for OpenCL Pro Edition and programmingyour FPGA

The following figure summarizes the steps for setting up the necessary software andinstalling the FPGA board

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

12

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 13: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

Figure 1 Intel FPGA SDK for OpenCL Pro Edition Installation Process Overview

Review prerequisites

Download the tar file from intelcom(Tar file includes SDK Intel Quartus Prime

software and device support)

1 Unpack tar file2 Run setup_probat|sh files

Download and installIntel Reference and Custom Platforms

HW SW OS prereq satisfied

Acquire prerequisiteHW SW OS

aocl versionruns

aocldiagnose

ltdevice_namegt

= PASSED

NO

YES

NO YES

NO

YES Obtain the hello_world example from

Legend

Action

Decision

Install FPGA boardaocl install ltpath_to_customplatformgt

Note Resolve errors if any observed

$INTELFPGAOCLSDKROOTexamples_aoc

Attention For possible errors after implementing aocl diagnose utility refer to Possible ErrorsAfter Running the diagnose Utility section

After you complete the initial software and hardware setup successfully you cancreate a hardware image from the hello_world OpenCL design example

Attention Before you program your FPGA with the hardware image ensure that your FPGAcontains an image created using a current version of the Intel FPGA SDK for OpenCLRefer to Updating the Hardware Image on the FPGA for more information

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

13

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 14: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

The following figure summarizes the steps you perform to program your FPGA

Figure 2 FPGA Programming Overview

Extract hello_world OpenCL example

Run hello_world host executable to execute

hello_worldaocx on board

Check settings of QUARTUS_ROOTDIR_OVERRIDE

Select target FPGA board aoc -list-boards

Compile kernel for target board

hello_worldaoco hello_worldaocx

Build successful NOYES

Legend

Action

Decision

File

Attention Adding the -rtl optionin your aoc command (aoc -rtl-v -board-package=ltboard_package_pathgt

devicehello_worldcl-o binhello_worldaocr

)

instructs the offline compiler togenerate only hello_worldaocr

Compile kernel for emulation

aoc -v -board= ltboard_namegt -board-package=ltboard_package_pathgt devicehello_worldcl -o binhello_worldaocx

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

hello_worldaocx Build host application Verify the following1 Host application is built correctly2 Check the link paths to libraries

Debug and correct as neededRun hello_world executable for emulation

hello_worldaocr

-board=ltboard_namegt

Related Information

Updating the Hardware Image on the FPGA on page 27

1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

14

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 15: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

2 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Windows

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Windowsrefer to the following links

bull Intel oneAPI Toolkits Installation Guide for Windows

bull Get Started with the Intel oneAPI Base Toolkit for Windows

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 16

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

4 Verifying Software Installation on page 18

5 Installing an FPGA Board on page 19

6 Verifying Host Runtime Functionality via Emulation on page 21

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 24

8 Updating the Hardware Image on the FPGA on page 27

9 Executing an OpenCL Kernel on an FPGA on page 29

10 Uninstalling an FPGA Board on page 30

11 Uninstalling the Software on page 30

21 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Windows from the Intel FPGA SDK for OpenCLDownload Center

The Intel FPGA SDK for OpenCL Download Center provides a tar file that includes all ofthe following software and files

bull Intel FPGA SDK for OpenCL Pro Edition

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 16: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Windows SDK tab select the Intel FPGA SDK for OpenCL (includesIntel Quartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL offline compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

22 Installing the Intel FPGA SDK for OpenCL Pro Edition

In this section you learn how to unpack the downloaded tar archive and run theinstallation files to install all the software and filesInstall the Windows version of the Intel FPGA SDK for OpenCL Pro Edition in a folderthat you own

You must have administrator privileges to execute these instructions

To install the SDK Intel Quartus Prime software and device support files perform thefollowing tasks

1 Unpack the downloaded AOCL-ltversiongt-ltbuildgt-windowstar archive intoa temporary folder

2 Run the setup_probat file to install the SDK with the Intel Quartus Prime ProEdition software

3 Note The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a Windows command window and then type echoINTELFPGAOCLSDKROOT at the command prompt

If the returned path does not point to the location of the SDK installation edit theINTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Microsoft Visual Studio Plug-in

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

16

After installing the Intel FPGA SDK for OpenCL perform these steps to install theMicrosoft Visual Studio plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installbat script

3 Follow the prompts to indicate which version of the Microsoft Visual Studio plug-in you want to install

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

23 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Windows userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variables permanently you apply the settings once duringinstallation If you set the environment variables transiently you must apply thesettings during installation and during every subsequent session you run

Table 2 Intel FPGA SDK for OpenCL Windows User Environment Variable Settings

Environment Variable Path to Include

PATH 1 INTELFPGAOCLSDKROOTbin

2 INTELFPGAOCLSDKROOTwindows64bin

3 INTELFPGAOCLSDKROOThostwindows64bin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

17

bull To apply permanent environment variable settings perform the following tasks

a Click Windows Start menu Control Panel (or search for and then openthe Control Panel application in Windows 81 and Windows 10)

b Click System

c In the System window click Advanced system settings

d Click the Advanced tab in the System Properties dialog box

e Click Environment VariablesThe Environment Variables dialog box appears

f To modify an existing environment variable setting select the variable underUser variables for ltuser_namegt and then click Edit In the Edit UserVariable dialog box type the environment variable setting in the Variablevalue field

g If you add a new environment variable click New under User variables forltuser_namegt In the New User Variable dialog box type the environmentvariable name and setting in the Variable name and Variable value fieldsrespectively

For an environment variable with multiple settings add semicolons to separate thesettings

bull To apply transient environment variable settings open a command window andrun the INTELFPGAOCLSDKROOTinit_openclbat script

Example script output

Adding INTELFPGAOCLSDKROOTbin to PATHAdding INTELFPGAOCLSDKROOThostwindows64bin to PATH

Running the init_openclbat script only affects the current command windowThe script performs the following tasks

mdash Finds the Intel Quartus Prime Pro Edition software installation

mdash Finds the Microsoft Visual Studio installation

mdash Imports the Microsoft Visual Studio environment to properly set the LIBenvironment variable

mdash Ensures that the PATH environment variable includes the path to the MicrosoftLINKEXE file and the aocexe file

24 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

18

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

25 Installing an FPGA Board

Before creating an OpenCL application for an FPGA accelerator board or SoC deviceyou must first download and install the Intel Reference Platform or the CustomPlatform from your board vendor Most Custom Platform installers requireadministrator privileges

To install your board into a Windows host system invoke the aocl installltpath_to_customplatformgt utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

Note Starting from 203 release support for Windows OpenCL BSPs is removedUse 202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a folder that you own (that is not a system folder)

You can install multiple Custom Platforms simultaneously on the same systemusing the SDK utilities such as aocl diagnose with multiple Custom PlatformsThe Custom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Driver (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory

5 Add the paths to the Custom Platform libraries (for example path to the MMDlibrary of the board support package resembles ltpath_to_customplatformgtwindows64bin) to the PATH environment variable setting

For information on setting user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

19

Remember bull You need administrative rights to install a board To run aWindows command prompt as an administrator click Start AllPrograms Accessories Under Accessories right clickCommand Prompt In the right-click menu click Run asAdministrator

On Windows 81 or Windows 10 systems you might also need todisable signed driver verification For details see the followingarticles

mdash Windows 8 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-basesolutionsfb321729html

mdash Windows 10 httpswwwintelcomcontentaltera-wwwglobalen_usindexsupportsupport-resourcesknowledge-baseembedded2017Why-does-aocl-diagnose-fail-while-using-Windows-10html

bull If the system already has the driver installed and you need toinstall FCD without the administrative rights you can invoke theaocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 Query a list of FPGA devices installed in your machine by invoking the aocldiagnose commandThe software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility section inthe Intel Arria 10 GX FPGA Development Kit Reference PlatformPorting Guide For more information on querying the ltdevice_namegtof your accelerator board refer to the Querying the Device Name ofYour FPGA Board section

8 Verify the successful installation of the FPGA board by invoking the commandaocl diagnose ltdevice_namegt to run any board vendor-recommendeddiagnostic test

Related Information

bull Querying the Device Name of Your FPGA Board on page 27

bull Intel FPGA SDK for OpenCL FPGA Platforms

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

251 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version

For example you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

20

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 19

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

set QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board with the followingcommand

aocl install ltYOUR_PATH_TO_V202_OpenCL_BSPgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your backlevel OpenCL BSP

26 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Pro Edition Emulator

1 Add the path to the LINKexe file in Microsoft Visual Studio to the PATH userenvironment variable setting

2 Add the path to the Microsoft compilation time libraries in Microsoft Visual Studioto the LIB user environment variable setting

1 Accessing an OpenCL Design Example on page 22

2 Compiling a Kernel for Emulation on page 22

3 Building the Host Application on page 22

4 Emulating Your OpenCL Kernel on page 24

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

21

261 Accessing an OpenCL Design Example

The INTELFPGAOCLSDKROOTexamples_aoc directory contains sample applicationsof varying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world folder

2 Copy it to a folder that you have write access for

Important Ensure that the folder name does not contain spaces

262 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The Intel FPGA SDK for OpenCL Offline Compiler compiles the hello_worldclkernel source file and creates the hello_worldaocx emulation-specificexecutable file in the bin subdirectory

263 Building the Host Application

The ltlocal_path_to exm_opencl_hello_worldgthello_worldhello_worldsln file contains the host solution After you open this sln file inMicrosoft Visual Studio you can build the OpenCL host application in the maincppfile

If you are using Microsoft Visual Studio you need the FCD and the Installable ClientDriver (ICD) from Khronos The ICD driver links the host against the OpenCLdllwhich requires the FPGA Client Driver (FCD) installed For installing FCD refer to Installing an FPGA Board on page 19

To set up Microsoft Visual Studio with FCD and ICD perform the following tasks priorto building the host application

1 Verify that FCD and ICD are set up correctly using the aocl diagnose -icd-only command If both FCD and ICD are installed correctly you should see thefollowing output

ICD System Diagnostics -------------------------------------------------------------------- Using the following location for ICD installation HKEY_LOCAL_MACHINESoftwareKhronosOpenCLVendors

Found 1 icd entry at that location ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0

Checking validity of found icd entries ltINTELFPGAOCLSDKROOTgtwindows64binalteracl_icddll REG_DWORD 0x0 is correctly registered on the system

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

22

Using the following location for fcd installations HKEY_LOCAL_MACHINESoftwareIntelOpenCLBoards

Found 1 fcd entry at that location ltpath_to_OpenCL_BSPgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0

Checking validity of found fcd entries ltpath_to_OpenCL_bspgta10_refwindows64binaltera_a10_ref_mmddll REG_DWORD 0x0 is correctly registered on the system

Number of Platforms = 1 1 Intel(R) FPGA SDK for OpenCL(TM) | Intel(R) Corporation | OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) Version ltversion_numbergt-------------------------------------------------------------------- ICD diagnostics PASSED --------------------------------------------------------------------

2 If neither the FCD nor ICD is setup correctly refer to the Installing an FPGA Boardfor FCD setup and refer to the Accessing Custom Platform-Specific Functions andLinking Your Host Application to the Khronos ICD Loader Library sections of theIntel FPGA SDK for OpenCL Pro Edition Programming Guide for more information

3 Link the host application to the OpenCLlib library

a Under the Solution right-click the host application name and selectProperties and then select Configuration Properties Linker Input

b In the Additional Dependencies field enter OpenCLlib

Attention Because you are using FCD and ICD do not link the host program toalteracllib or to your Custom Platforms MMD libraries directly

To build the hello_world host application perform the following tasks

1 Open the ltlocal_path_to_exm_opencl_hello_worldgthello_worldhello_worldsln file in Microsoft Visual Studio

2 Verify that the build configuration is correct The default build configuration isDebug but you can use Release You must select the appropriate option as thesolution platform (for example for x64 architecture select x64)

3 Build the solution by selecting the Build Build Solution menu option or bypressing the F7 keyThe hello_worldexe executable is in theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

4 Verify that the build is correct An output ending with a message similar to the oneshown below notifies you of a successful build

1gt Build succeeded1gt1gt Time Elapsed 00000329========== Build 1 succeeded 0 failed 0 up-to-date 0 skipped ==========

Attention You can ignore the LNK4009 PDB vc90pdb was not foundwith warnings because they have no effect on the build Thecompiler might issue this type of warning messages if you have builtyour Windows libraries using a previous version of Microsoft VisualStudio

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

23

Related Information

bull Accessing Custom Platform-Specific Functions

bull Linking Your Host Application to the Khronos ICD Loader Library

264 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you build your kernel

To emulate your kernel perform the following steps

1 To run the host application for emulation first define the number of emulateddevices by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgt command andthen run the host applicationThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variableThe host application for the hello_world design example only requires a singledevice so you may skip setting this environment variable

Remember When the host is compiled and running for the emulator platformonly the emulated devices are available that is access to all physicalboards is disabled

2 After you run the host application unset theCL_CONFIG_CPU_EMULATE_DEVICES variable by invoking the setCL_CONFIG_CPU_EMULATE_DEVICES= command

Upon successful emulation of your kernel you should see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

Related Information

Running the Host Application on page 29

27 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Access the hello_world OpenCL design example from the INTELFPGAOCLSDKROOTexamples_aoc folder Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

24

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If no board package is installed use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails To install an FPGA board refer to Installing an FPGA Board for moreinstructions

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to theIntel Quartus Prime Pro Edition software Open a Windows command window andthen type echo QUARTUS_ROOTDIR_OVERRIDE at the command prompt

If the path to the installation folder of the Intel Quartus Prime Pro Edition softwareis not returned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt ltkernelclgt

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

3 At a command prompt navigate to the hello_world design folder containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

25

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world folder containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK forOpenCL Pro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

26

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

bull Installing an FPGA Board on page 19

28 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

Related Information

Configuring the Intel Arria 10 GX FPGA Development Kit for the Intel FPGA SDK forOpenCL

281 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

27

diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

282 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

For example some Custom Platforms require you to install the Intel FPGADownload Cable driver to load your hardware configuration file into the flashmemory For installation instructions refer to the Intel FPGA Download Cable IIUser Guide

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the design example package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL kernel in the Intel FPGA SDK forOpenCL Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

28

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

bull Intel FPGA Download Cable II User Guide

bull Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 17

29 Executing an OpenCL Kernel on an FPGA

Build your OpenCL host application in Microsoft Visual Studio and run the applicationby invoking the hello_worldexe executable The Intel FPGA SDK for OpenCL iscompatible with 64-bit host binaries only

Related Information

Building the Host Application on page 22

291 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Windows host application that youbuilt from the sln file

1 Add the path INTELFPGAOCLSDKROOThostwindows64bin to the PATHenvironment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin folder

3 Invoke the hello_worldexe executableThe hello_world executable executes the kernel code on the FPGA

292 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = true

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

29

CL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

210 Uninstalling an FPGA Board

To uninstall an FPGA board for Windows invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables Youmust uninstall the existing FPGA board if you migrate your OpenCL application toanother FPGA board that belongs to a different Custom Platform

To uninstall your FPGA board perform the following tasks

1 Follow your board vendors instructions to disconnect the board from yourmachine

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember You need administrative rights to uninstall the Custom Platform Ifyou want to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only asshown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

3 Uninstall the Custom Platform

4 Modify PATH environment variable to remove paths that have theINTELFPGAOCLSDKROOT environment variable

211 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL Pro Edition for Windows run theuninstaller and restore all modified environment variables to their previous settings

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

30

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Windows you mustfirst uninstall the FPGA board Refer to Uninstalling an FPGA Board on page 30 formore information

1 From the Windows Start Menu shortcut navigate to the intelFPGA_proltversiongt lteditiongt installation folder

2 Select Uninstall Intel Quartus Prime Pro EditionThe uninstallation wizard appears

3 In the uninstallation wizard perform the following tasks

a Select Individual components and then click Next

b Select the SDK and then click NextThe uninstaller uninstalls the Intel FPGA SDK for OpenCL

4 Remove the following paths from the PATH environment variable

a INTELFPGAOCLSDKROOTbin

b INTELFPGAOCLSDKROOThostwindows64bin

5 Remove the INTELFPGAOCLSDKROOT environment variable

6 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

31

3 Getting Started with the Intel FPGA SDK for OpenCLPro Edition for Linux

The Intel FPGA SDK for OpenCL Pro Edition setup process includes downloading andinstalling the software installing the FPGA board and then executing an OpenCLkernel on the FPGA

Tip If you are looking for instructions to get started with oneAPI toolkits on Linux refer tothe following guides

bull Intel oneAPI Toolkits Installation Guide for Linux

bull Get Started with the Intel oneAPI Base Toolkit for Linux

1 Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

2 Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

3 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

4 Verifying Software Installation on page 35

5 Installing an FPGA Board on page 35

6 Verifying Host Runtime Functionality via Emulation on page 37

7 Creating the FPGA Hardware Configuration File of an OpenCL Kernel on page 40

8 Updating the Hardware Image on the FPGA on page 42

9 Executing an OpenCL Kernel on an FPGA on page 44

10 Uninstalling an FPGA Board on page 46

11 Uninstalling the Software on page 46

31 Downloading the Intel FPGA SDK for OpenCL Pro Edition

Download the installation package that contains the Intel FPGA SDK for OpenCL ProEdition and all related software for Linux from the Download Center

The Download Center provides a tar file that includes all of the following software andfiles

bull Intel FPGA SDK for OpenCL

bull Intel Quartus Prime Pro Edition software

bull Device support

1 Go to the Intel FPGA SDK for OpenCL Download Center at the following URL

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

httpsfpgasoftwareintelcomopencl

2 Select the Pro edition

3 Select the software version The default selection is the current version

4 On the Linux SDK tab select the Intel FPGA SDK for OpenCL (includes IntelQuartus Prime Pro Edition software and devices) package

This package provides core functions of the Intel FPGA SDK for OpenCL includingthe Intel FPGA SDK for OpenCL Offline Compiler and the Intel FPGA SDK forOpenCL utility

Click More beside Download and install instructions if you want to see thedownload and installation instructions

5 Perform the steps outlined in the download and installation instructions on thedownload page

Related Information

Intel FPGA website

32 Installing the Intel FPGA SDK for OpenCL Pro Edition

Unpack the downloaded tar file and run the installation files to install all the softwareand filesInstall the Linux version of the Intel FPGA SDK for OpenCL Pro Edition in a directorythat you own

bull You must have sudo or root privileges

bull You must install the Linux OS kernel source and headers (for example kernel-develx86_64 and kernel-headersx86_64) and the GNU CompilerCollection (GCC) (gccx86_64)

bull If you are installing a package that includes Intel Code Builder you must haveJava SE 1871 or later installed to run Intel Code Builder If you have an earlierversion of Java SE installed you can still complete the installation of Intel CodeBuilder However you must meet the Java version prerequisite to run Intel CodeBuilder

Attention If you install the software on a system that does not contain any C Shell RunCommands file (cshrc) or Bash Run Commands file (bashrc) in your directoryyou must set the environment variables INTELFPGAOCLSDKROOT and PATH manuallyAlternatively you may create the cshrc and bashrc files and then append theenvironment variables to them To ensure that the updates take effect restart yourterminal after you set the environment variables

To install the Intel FPGA SDK for OpenCL Intel Quartus Prime software and devicesupport files simultaneously perform the following tasks

1 Unpack the downloaded tar file into a temporary directory

2 Run the setup_prosh file to install the SDK with the Intel Quartus Prime ProEdition software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

33

Important Run this script with sudo privileges to ensure the Installable ClientDriver (ICD) is setup successfully

3 Verify that INTELFPGAOCLSDKROOT points to the current version of the softwareOpen a shell and then type echo $INTELFPGAOCLSDKROOT at the commandprompt

Note bull The installer sets the environment variable INTELFPGAOCLSDKROOT topoint to the path of the software installation

bull If there are dependency issues use the ndashnodeps option

If the returned path does not point to the location of the Intel FPGA SDK forOpenCL installation edit the INTELFPGAOCLSDKROOT setting

For instructions on modifying environment variable settings refer to Setting theIntel FPGA SDK for OpenCL Pro Edition User Environment Variables

Installing the Eclipse Plug-in

After installing the Intel FPGA SDK for OpenCL perform these steps to install theEclipse plug-in

1 Navigate to the $INTELFPGAOCLSDKROOTide_plugins directory

2 Execute the plugins_installsh script

3 Follow the prompts to indicate where your installation of Eclipse is

Note If the installation indicates that it finished successfully but you do not see the plug-insin the IDE ensure the Java Runtime version you have installed is supported by theEclipse IDE version and that you have all of the prerequisites described in Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

33 Setting the Intel FPGA SDK for OpenCL Pro Edition UserEnvironment Variables

You have the option to set the Intel FPGA SDK for OpenCL Pro Edition Linux userenvironment variables permanently or transiently The environment variable settingsdescribe the FPGA board and the host runtime to the software

Attention If you set the environment variable in your bashrc or cshrc file the settings areapplied to all subsequent sessions If you set the environment variables transientlyyou must apply the settings during installation and during every subsequent sessionyou run

Table 3 Intel FPGA SDK for OpenCL Linux User Environment Variable Settings

Environment Variable Path to Include

PATH $INTELFPGAOCLSDKROOTbin

where INTELFPGAOCLSDKROOT points to the path of the softwareinstallation

LD_LIBRARY_PATH $INTELFPGAOCLSDKROOThostlinux64lib

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

34

bull To automatically initialize the environment at the beginning of each session addthe following export statements to your bashrc or cshrc file

export ltvariable_namegt=ltvariable_settinggt$ltvariable_namegtcommand

For example the command export PATH=$INTELFPGAOCLSDKROOTbin$PATH adds $INTELFPGAOCLSDKROOTbin to the list of PATH settings

bull To apply transient environment variable settings open a bash-shell command-lineterminal and run the source $INTELFPGAOCLSDKROOTinit_openclshcommand This command does not work in other shells

Example script output

Adding $INTELFPGAOCLSDKROOTbin to PATHAdding $INTELFPGAOCLSDKROOThostlinux64lib to LD_LIBRARY_PATH

34 Verifying Software Installation

Invoke the version utility command and verify that the correct version of theOpenCL software is installed

bull At a command prompt invoke the aocl version utility commandAn output similar to the one below notifies you of a successful installation

aocl ltversiongtltbuildgt (Intel(R) FPGA SDK for OpenCL(TM) Version ltversiongt Build ltbuildgt Copyright (C) ltyeargt Intel(R) Corporation)

bull If installation was unsuccessful reinstall the software You can also refer to theIntel FPGA Software Installation and Licensing manual and the Intel FPGAKnowledge Base for more information

Related Information

bull Intel FPGA Software Installation and Licensing

bull Intel FPGA Knowledge Base

35 Installing an FPGA Board

Before creating an OpenCL application for an FPGA board on Linux you must firstdownload and install the Intel Reference Platform or the Custom Platform from yourboard vendor Most Custom Platform installers require administrator privileges Visitthe Download Center for FPGAs site for downloading the Intel Reference Platform Toinstall your board into a Linux host system invoke the install utility command

The steps below outline the board installation procedure Some Custom Platformsrequire additional installation tasks Consult your board vendors documentation forfurther information on board installation

1 Follow your board vendors instructions to connect the FPGA board to your system

2 Download the Custom Platform for your FPGA board from your board vendorswebsite

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

35

Note Starting from 203 release support for Linux OpenCL BSPs is removed Use202 or older OpenCL BSPs available at Download Center for FPGAs as areference If you want to migrate your OpenCL BSP to a newer versionfollow the recommended steps provided in the Reference Platform PortingGuides available under Intel FPGA SDK for OpenCL documentation

3 Install the Custom Platform in a directory that you own (that is not a systemdirectory)

You can install multiple Custom Platforms simultaneously on the same system Usethe RTE utilities such as aocl diagnose with multiple Custom Platforms TheCustom Platform subdirectory contains the board_envxml file

In a system with multiple Custom Platforms ensure that the host program usesthe FPGA Client Drivers (FCD) to discover the boards rather than linking to theCustom Platforms memory-mapped device (MMD) libraries directly If FCD iscorrectly set up for Custom Platform FCD finds all the installed boards at runtime

4 Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to theIntel Quartus Prime Pro Edition software installation directory Open a shell andthen type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt

5 Add the paths to the Custom Platform libraries (for example the path to the MMDlibrary resembles ltpath_to_customplatformgtlinux64lib) to theLD_LIBRARY_PATH environment variable setting

For information on setting Linux user environment variables and running theinit_opencl script refer to the Setting the Intel FPGA SDK for OpenCL ProEdition User Environment Variables section

6 Invoke the command aocl install ltpath_to_customplatformgt at acommand prompt

Remember You need sudo or root privileges to install a board

Invoking aocl install ltpath_to_customplatformgt installs both the FCDand a board driver that allows communication between host applications andhardware kernel programs

If the system already has the drivers installed and you need to install FCDwithout the root privilege you can perform the following

a Export the ACL_BOARD_VENDOR_PATH=ltpath_to_install_fcdgtenvironment variable to specify the installation directory of FCD other than thedefault location

Note If you set the ACL_BOARD_VENDOR_PATH environmental variable set itevery time after you enter the OpenCL development environment viathe source init_openclsh file

b Invoke the aocl install command with the flag -fcd-only as shownbelow and follow the prompt for FCD installation

aocl install ltpath_to_customplatformgt -fcd-only

7 To query a list of FPGA devices installed in your machine invoke the aocldiagnose command

The software generates an output that includes the ltdevice_namegt which is anacl number that ranges from acl0 to acl127

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

36

Attention For possible errors after implementing the aocl diagnose utilityrefer to Possible Errors After Running the diagnose Utility sectionFor more information on querying the ltdevice_namegt of youraccelerator board refer to the Querying the Device Name of YourFPGA Board section

8 To verify the successful installation of the FPGA board invoke the command aocldiagnose ltdevice_namegt to run any board vendor-recommended diagnostictest

351 Enabling Backwards Compatibility for an FPGA Board

To enable a board with a downlevel OpenCL BSP you need a version of Intel QuartusPrime Pro Edition with the same version number as the OpenCL BSP version Forexample you can use Version 202 OpenCL BSP with Intel FPGA SDK for OpenCLVersion 212 and Intel Acceleration Stack Version 201 and Version 121

After you have installed and configured the required version or versions of IntelQuartus Prime Pro Edition you enable your backwards compatible boards by settingthe QUARTUS_ROOTDIR_OVERRIDE environment variable and running the aoclinstall command so that your Intel Quartus Prime Pro Edition version matches yourOpenCL BSP version number

Before you set the QUARTUS_ROOTDIR_OVERRIDE environment variable and run theaocl install command install and configure the version of Intel Quartus Prime ProEdition that your OpenCL BSP needs

Also install your FPGA board or boards following the instructions in Installing an FPGABoard on page 35

To enable a board with a backwards compatible OpenCL BSP

1 Set the QUARTUS_ROOTDIR_OVERRIDE to point to the version of Intel QuartusPrime Pro Edition that your OpenCL BSP needs

For example if you have Version 202 OpenCL BSPQUARTUS_ROOTDIR_OVERRIDE must point at Intel Quartus Prime Pro EditionVersion 202

export QUARTUS_ROOTDIR_OVERRIDE=ltpath_to_quartus_installgtquartus

2 Run the aocl install ltpath_to_customplatformgt command with the pathto your backward compatible OpenCL BSP as the value forltpath_to_customplatformgt

For example to point to a Version 202 OpenCL BSP for the Intel Arria 10 GXFPGA Development Kit Reference Platform install the board as follows

aocl install ltYOUR_PATH_TO_V202_OPENCL_BSPsgta10_ref

After you complete these steps Intel SDK for OpenCL commands like aocldiagnose should work correctly with your back-level OpenCL BSP

36 Verifying Host Runtime Functionality via Emulation

Test the functionality of the host runtime by emulating an OpenCL design exampleusing the Intel FPGA SDK for OpenCL Emulator

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

37

Important Before you proceed review Emulating and Debugging Your OpenCL Kernel topic of theIntel FPGA SDK OpenCL Pro Edition Programming Guide

1 Verify that the LD_LIBRARY_PATH environment variable setting includes the pathsidentified in Setting the Intel FPGA SDK for OpenCL User Environment VariablesOpen a shell and then type echo $LD_LIBRARY_PATH at the command prompt

If the returned path do not include $INTELFPGAOCLSDKROOThostlinux64lib add it to the LD_LIBRARY_PATH setting

1 Accessing an OpenCL Design Example on page 38

2 Compiling a Kernel for Emulation on page 38

3 Building the Host Application on page 38

4 Emulating Your OpenCL Kernel on page 39

361 Accessing an OpenCL Design Example

The $INTELFPGAOCLSDKROOTexamples_aoc contains sample applications ofvarying complexities that you can copy to your local and run on your FPGA

The following instructions are for accessing the Hello World design

1 Access the hello_world directory

2 Copy it to a directory to which you have write access

Important Ensure that the directory path does not contain spaces

362 Compiling a Kernel for Emulation

To compile an OpenCL kernel for emulation include the -march=emulator option inyour aoc command

bull To compile the kernel for your target FPGA board at a command prompt navigateto the hello_world design and then invoke the following command

aoc -march=emulator -v devicehello_worldcl -o binhello_worldaocx

The compiles the hello_worldcl kernel source file and creates thehello_worldaocx emulation-specific executable file in the bin subdirectory

363 Building the Host Application

Build the host executable with the ltlocal_path_to_exm_opencl_hello_worldgthello_worldMakefile file

To build the host application perform the following tasks

1 If you did not run the aocl install command when performing the steps from Installing an FPGA Board on page 35 you must execute the following command

aocl install -fcd-only ltboard_package_pathgta10_ref

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

38

The ICD driver links the host against the libOpenCLso which requires the FPGAClient Driver (FCD) installed For installing FCD refer to Installing an FPGA Boardon page 35

Note If you do not have the root privilege refer to Installing an FPGA Board onpage 35

2 Navigate to the hello_world directory

3 Invoke the make commandThe hello_world executable is generated in the bin sub-directory

4 If you performed the step 1 then you must execute the following command

aocl uninstall -fcd-only ltboard_package_pathgta10_ref

364 Emulating Your OpenCL Kernel

To emulate your OpenCL kernel run the emulation aocx file on the platform onwhich you built your kernel The OpenCL Emulator uses a different OpenCL platformthan when targeting FPGA hardware

To emulate your kernel perform the following steps

1 To run the host application for emulation invoke the envCL_CONFIG_CPU_EMULATE_DEVICES=ltnumber_of_devicesgtlthost_application_filenamegt commandThis command specifies the number of identical emulation devices that theEmulator needs to provide By default the emulator platform provides a singleemulator device Therefore if your host code requires only a single device you donot need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable

For the hello_world design example run binhost -emulator The -emulator argument informs the host program to select the Intel FPGA EmulationPlatform for OpenCL

Upon successful emulation of your kernel you see the following output

Using AOCX hello_worldaocx

Kernel initialization is complete

Launching the kernel

Thread 2 Hello from Intel FPGA OpenCL Compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

39

Note bull The emulator in Pro Edition is built with GCC 720 as part of the offline compilerWhen executing the host program for an emulated OpenCL device the version oflibstdc++so must be at least that of GCC 720 In other words theLD_LIBRARY_PATH environment variable must ensure that the correct version oflibstdc++so is found

If the correct version of libstdc++so is not found the call toclGetPlatformIDs function fails to load the FPGA emulator platform and returnsCL_PLATFORM_NOT_FOUND_KHR (error code -1001) Depending on whichversion of libstdc++so is found the call to clGetPlatformIDs may succeedbut a later call to the clCreateContext function may fail withCL_DEVICE_NOT_AVAILABLE (error code -2)

If LD_LIBRARY_PATH does not point to a sufficiently new libstdc++so usethe following syntax to invoke the host program

env LD_LIBRARY_PATH=ltpath to sufficiently new libstdc++sogt$LD_LIBRARY_PATH lthostgt [host arguments]

bull To enable debugging of kernel code optimizations are disabled by default for theFPGA emulator This can lead to sub-optimal execution speed when emulatingkernel code

You can pass the -g0 flag to the aoc compile command to disable debugging andenable optimizations This enables faster emulator execution

Related Information

Running the Host Application on page 44

37 Creating the FPGA Hardware Configuration File of an OpenCLKernel

Copy the hello_world OpenCL design example from the $INTELFPGAOCLSDKROOTexamples_aoc directory Compile the hello_world kernel program using the IntelFPGA SDK for OpenCL Offline Compiler to create the hello_worldaocx executablefile The aocx file is the FPGA hardware configuration file

After you successfully install your FPGA board and emulate your kernel you cancreate a aocx file that executes on the device The steps below describe the processof creating a aocx file from the hello_world example design

Note The Intel FPGA SDK for OpenCL Offline Compiler compiles an OpenCL kernel for atarget FPGA board The Intel FPGA SDK for OpenCL compiles for the installed boardpackage If you have not installed the FPGA board refer to Installing an FPGA Boardfor more instructions If you do not install the board package use the -board-package=ltboard_package_pathgt option to point to the OpenCL BSP otherwisethe Intel FPGA SDK for OpenCL throws an error Refer to the following steps for moredetails

1 Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points toyour Intel Quartus Prime software Open a shell and then type echo$QUARTUS_ROOTDIR_OVERRIDE at the command prompt

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

40

If the path to the installation directory of the Intel Quartus Prime software is notreturned add it to the QUARTUS_ROOTDIR_OVERRIDE setting

2 Select your target FPGA board To list the FPGA boards available in your CustomPlatform invoke the command aoc -list-boards at a command prompt Ifno OpenCL BSP is installed No board support packages installedmessage is displayed Use the -board-package=ltboard_package_pathgtoption to point to the OpenCL BSP

If you have multiple OpenCL BSPs installed you can compile your kernel with theboard variant from a specific Custom Platform by including -board-package=ltcustom_platform_pathgt option with -board=ltboard_namegt Atthe command prompt invoke the following command

aoc -board-package=ltboard_package_pathgt -board=ltboard_namegt kernelcl

The Intel FPGA SDK for OpenCL Offline Compiler compiles the kernel with theboard specified in the ltboard_package_pathgt To list Custom Platformsavailable in the system include the -list-board-packages option in the aoccommand

For more information about -list-boards -board-package and -list-board-packages options of the aoc command refer to the Listing the AvailableFPGA Boards in Your Custom Platform (-list-boards and -list-board-packages)section of the Intel FPGA SDK for OpenCL Pro Edition Programming Guide

3 At a command prompt navigate to the hello_world design directory containing thehello_worldcl file that you used for emulation

4 To compile the kernel for your target FPGA board invoke the following command

aoc -v -board-package=ltboard_package_pathgt -board=ltboard_namegt devicehello_worldcl -o binhello_worldaocx

This command performs the following tasks

bull Generates the Intel Quartus Prime design project files from the OpenCL sourcecode

bull Checks for initial syntax errors

bull Performs basic optimizations

bull Creates a hello_world directory containing necessary intermediate files

bull Creates the aocx file

Tip bull If you have only one FPGA board installed -board=ltboard_namegt isoptional

bull If you have only one OpenCL BSP installed -board-package=ltboard_package_pathgt is optional

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

41

Attention The aocx file might take hours to build depending on the complexityof the kernel To view the progress of the compilation on-screeninclude the -v flag in your aoc command An example output isshown below

aoc Environment checks are completed successfullyYou are now compiling the full flowaoc Selected target board ltboard_namegtaoc Running OpenCL parseraoc OpenCL parser completed successfullyaoc Compilingaoc Linking with IP library aoc First stage compilation completed successfullyaoc Setting up project for CvP revision flowaoc Hardware generation completed successfully

The offline compiler displays the line aoc Hardware generationcompleted successfully to signify the completion of thecompilation process

For more information about the -board=ltboard_namegt option of the aoccommand refer to the Compiling a Kernel for a Specific FPGA Board and CustomPlatform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt) section of the Intel FPGA SDK for OpenCL ProEdition Programming Guide

For more information about the -v option of the aoc command refer to theGenerating Compilation Progress Report (-v) section of the Intel FPGA SDK for OpenCLPro Edition Programming Guide

For more information about the -o ltfilenamegt option of the aoc command refer tothe Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt) section of the Intel FPGA SDK for OpenCL Pro Edition ProgrammingGuide

Related Information

bull Installing an FPGA Board on page 35

bull Listing the Available FPGA Boards and Custom Platforms (-list-boards and -list-board-packages)

bull Compiling a Kernel for a Specific FPGA Board and Custom Platform (-board=ltboard_namegt) and (-board-package=ltboard_package_pathgt)

bull Generating Compilation Progress Report (-v)

bull Specifying the Name of an Intel FPGA SDK for OpenCL Offline Compiler Output File(-o ltfilenamegt)

38 Updating the Hardware Image on the FPGA

If applicable before you execute an OpenCL kernel program on the FPGA ensure thatthe flash memory of the FPGA contains a hardware image created using a currentversion of the OpenCL software

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

42

Remember If your Custom Platform requires that you preload a valid OpenCL image into the flashmemory for every major release of the Intel Quartus Prime Design Suite program theflash memory of the FPGA with a hardware image compatible with the current versionof the software

381 Querying the Device Name of Your FPGA Board

Some OpenCL software utility commands require you to specify the device name(ltdevice_namegt) The ltdevice_namegt refers to the acl number (eg acl0 to acl127)that corresponds to the FPGA device When you query a list of accelerator boards theOpenCL software produces a list of installed devices on your machine in the order oftheir device names

bull To query a list of installed devices on your machine type aocl diagnose at acommand promptThe software generates an output that resembles the example shown below

aocl diagnose Running diagnostic from ltboard_package_pathgtltboard_namegtltplatformgtlibexec

Verified that the kernel mode driver is installed on the host machine

Using board package from vendor ltboard_vendor_namegtQuerying information for all supported devices that are installed on the host machine

device_name Status Information

acl0 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 020000 at Gen 2 with 8 lanes FPGA temperature = 430 degrees C

acl1 Passed ltdescriptive_board_namegt PCIe dev_id = ltdevice_IDgt busslotfunc = 030000 at Gen 2 with 8 lanes FPGA temperature = 350 degrees C

Found 2 active device(s) installed on the host machine to perform a full diagnostic on a specific device please run aocl diagnose ltdevice_namegt

DIAGNOSTIC_PASSED

382 Programming the Flash Memory of an FPGA

Configure the FPGA by loading the hardware image of an Intel FPGA SDK for OpenCLdesign example into the flash memory of the device When there is no power theFPGA retains the hardware configuration file in the flash memory When you power upthe system it configures the FPGA circuitry based on this hardware image in the flashmemory Therefore it is imperative that an OpenCL-compatible hardware configurationfile is loaded into the flash memory of your FPGA

Preloading an OpenCL image into the flash memory is necessary for the properfunctioning of many Custom Platforms For example most PCIe-based boards requirea valid OpenCL image in flash memory so that hardware on the board can use theimage to configure the FPGA device when the host system powers up for the firsttime If the FPGA is not configured with a valid OpenCL image the system fails toenumerate the PCIe endpoint or the driver does not function

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

43

Before running any designs ensure that the flash memory of your board has a validOpenCL image that is compatible with the current OpenCL software version Consultyour board vendors documentation for board-specific requirements

Caution When you load the hardware configuration file into the flash memory of the FPGAmaintain system power for the entire loading process which might take a fewminutes Also do not launch any host code that calls OpenCL kernels or mightotherwise communicate with the FPGA board

To load your hardware configuration file into the flash memory of your FPGA boardperform the following tasks

1 Install any drivers or utilities that your Custom Platform requires

2 To load the hardware configuration file into the flash memory invoke the aoclflash ltdevice_namegt ltdesign_example_filenamegtaocx commandwhere ltdevice_namegt refers to the acl number (eg acl0 to acl127) thatcorresponds to your FPGA device and ltdesign_example_filenamegtaocx isthe hardware configuration file you create from theltdesign_example_filenamegtcl file in the example design package

For more information about compiling an aocx file refer to Creating the FPGAHardware Configuration File of an OpenCL Kernel in the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

3 Power down your device or computer and then power it up again

Power cycling ensures that the FPGA configuration device retrieves the hardwareconfiguration file from the flash memory and configures it into the FPGA

Warning Some Custom Platforms require you to power cycle the entire hostsystem after programming the flash memory For example PCIe-basedCustom Platforms might require a host system restart to re-enumeratethe PCIe endpoint Intel recommends that you power cycle thecomplete host system after programming the flash memory

Related Information

Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables onpage 34

39 Executing an OpenCL Kernel on an FPGA

You must build your OpenCL host application with the Makefile file and run theapplication by invoking the hello_world executable You need GNU developmenttools such as gcc and make to build the OpenCL application

Related Information

Building the Host Application on page 38

391 Running the Host Application

To execute the OpenCL kernel on the FPGA run the Linux host application that youbuilt from the Makefile

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

44

1 Add the path $INTELFPGAOCLSDKROOThostlinux64lib to theLD_LIBRARY_PATH environment variable

2 At a command prompt navigate to the host executable within theltlocal_path_to_exm_opencl_hello_worldgthello_worldbin directory

3 Invoke the hello_world executableThe hello_world executable executes the kernel code on the FPGA

392 Output from Successful Kernel Execution

When you run the host application to execute your OpenCL kernel on the target FPGAthe OpenCL software notifies you of a successful kernel execution

Example output

Reprogramming device [0] with handle 1Querying platform for info==========================CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM)CL_PLATFORM_VENDOR = Intel CorporationCL_PLATFORM_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongt

Querying device for info========================CL_DEVICE_NAME = ltboard namegt ltdescriptive board namegtCL_DEVICE_VENDOR = ltboard vendor namegtCL_DEVICE_VENDOR_ID = ltboard vendor IDgtCL_DEVICE_VERSION = OpenCL 10 Intel(R) FPGA SDK for OpenCL(TM) ltversiongtCL_DRIVER_VERSION = ltversiongtCL_DEVICE_ADDRESS_BITS = 64CL_DEVICE_AVAILABLE = trueCL_DEVICE_ENDIAN_LITTLE = trueCL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592CL_DEVICE_IMAGE_SUPPORT = trueCL_DEVICE_LOCAL_MEM_SIZE = 16384CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000CL_DEVICE_MAX_COMPUTE_UNITS = 1CL_DEVICE_MAX_CONSTANT_ARGS = 8CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0Command queue out of order = falseCommand queue profiling enabled = trueUsing AOCX hello_worldaocx

Kernel initialization is completeLaunching the kernel

Thread 2 Hello from the Intel(R) FPGA OpenCL(TM) compiler

Kernel execution is complete

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

45

310 Uninstalling an FPGA Board

To uninstall an FPGA board for Linux invoke the uninstall utility commanduninstall the Custom Platform and unset the relevant environment variables

To uninstall your FPGA board perform the following tasks

1 Disconnect the board from your machine by following the instructions provided byyour board vendor

2 Invoke the aocl uninstall ltpath_to_customplatformgt utility commandto remove the current host computer drivers (for example PCIe drivers) The IntelFPGA SDK for OpenCL uses these drivers to communicate with the FPGA board

Remember bull You need root privileges to uninstall the Custom Platform If youwant to keep the driver while removing the installed FCD you caninvoke the aocl uninstall command with the flag -fcd-only as shown below and follow the prompt for FCD uninstall

aocl uninstall ltpath_to_customplatformgt -fcd-only

bull For Linux systems if you had installed the FCD to a specificdirectory then prior to uninstalling you need to ensure that youhave set an environment variable ACL_BOARD_VENDOR_PATH thatpoints to that specific FCD installation directory

3 Uninstall the Custom Platform

4 Unset the LD_LIBRARY_PATH environment variable

311 Uninstalling the Software

To uninstall the Intel FPGA SDK for OpenCL for Linux remove the software packagevia the GUI uninstaller then delete the software directory and restore all modifiedenvironment variables to their previous settings

Note Before uninstalling the Intel FPGA SDK for OpenCL Pro Edition for Linux you must firstuninstall the FPGA board Refer to Uninstalling an FPGA Board on page 46 for moreinformation

1 Remove the software package by running the aocl-ltversiongt-uninstallrun program located in the ltinstall directorygtuninstalldirectories for the Intel Quartus Prime Standard Edition software and the IntelQuartus Prime Pro Edition software This uninstalls the SDK

2 Remove $INTELFPGAOCLSDKROOTbin from the PATH environment variable

3 Remove $INTELFPGAOCLSDKROOThostlinux64lib from theLD_LIBRARY_PATH environment variable

4 Remove the INTELFPGAOCLSDKROOT environment variable

5 Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable

3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

46

A Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide Archives

If the table does not list a software version the user guide for the previous software version applies

Intel Quartus PrimeVersion

User Guide

211 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

204 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

203 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

202 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

194 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

193 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

191 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

181 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

180 Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

171 Intel FPGA SDK for OpenCL Getting Started Guide

170 Intel FPGA SDK for OpenCL Getting Started Guide

161 Altera SDK for OpenCL Getting Started Guide

160 Altera SDK for OpenCL Getting Started Guide

151 Altera SDK for OpenCL Getting Started Guide

150 Altera SDK for OpenCL Getting Started Guide

141 Altera SDK for OpenCL Getting Started Guide

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

B Document Revision History of the Intel FPGA SDK forOpenCL Pro Edition Getting Started Guide

Document Version Intel QuartusPrime Version

Changes

20210621 212 bull Maintenance release

20210329 211 bull Added a note about running the script with sudo privileges in step 2 ofInstalling the Intel FPGA SDK for OpenCL Pro Edition

bull Updated the BSP and SDK versions throughout the guidebull Changed all occurrences of BSP to OpenCL BSP for clarity

20201214 204 bull Maintenance release

20200928 203 bull Added instructions for installing GCC from the source for CentOS RedHat Enterprise Linux and SUSE Enterprise Linux

bull Updated the SDK versions throughout the guidebull Added a note about the Microsoft Visual Studio and Eclipse plug-ins in

Prerequisites for the Intel FPGA SDK for OpenCL Pro Editionbull Added Microsoft Visual Studio and Eclipse plug-ins install instructions in

Installing the Intel FPGA SDK for OpenCL Pro Edition topics forWindows and Linux

bull In multiple topics added or updated a note about the lack of supportfor Windows and Linux BSPs

bull Updated the backward compatibility options in Enabling BackwardsCompatibility for an FPGA Board and Intel FPGA SDK for OpenCL ProEdition and BSP Backwards Compatibility topics

20200622 202 bull Updated the SDK versions throughout the guidebull Updated the Intel Acceleration Stack version in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Added reference to the Intel Stratix 10 bring-up guide in the

introductionbull RAM details and GCC version updated in Prerequisites for the Intel

FPGA SDK for OpenCL Pro Editionbull Updated the board directory details in Contents of the Intel FPGA SDK

for OpenCL Pro Editionbull Modified the Intel FPGA SDK for OpenCL Pro Edition Installation Process

Overview figure to include downloading both Intel and CustomPlatforms in Overview of the Intel FPGA SDK for OpenCL Pro EditionSetup Process

bull Modified the FPGA Programming Overview figure to include -board-package=ltboard_package_pathgt in Overview of the Intel FPGASDK for OpenCL Pro Edition Setup Process

bull Since the BSPs are no longer part of the SDK updated all occurrencesof the path to BSP

bull Modified the title and instructions in the Downloading an OpenCLDesign Example topic

bull Removed references to downloading OpenCL design examples fromIntel website and replaced them with instructions to access examplesfrom the SDK

bull Added a new topic GCC Requirement

continued

UG-OCL001 | 20210621

Send Feedback

Intel Corporation All rights reserved Intel the Intel logo and other Intel marks are trademarks of IntelCorporation or its subsidiaries Intel warrants performance of its FPGA and semiconductor products to currentspecifications in accordance with Intels standard warranty but reserves the right to make changes to anyproducts and services at any time without notice Intel assumes no responsibility or liability arising out of theapplication or use of any information product or service described herein except as expressly agreed to inwriting by Intel Intel customers are advised to obtain the latest version of device specifications before relyingon any published information and before placing orders for products or servicesOther names and brands may be claimed as the property of others

ISO90012015Registered

Document Version Intel QuartusPrime Version

Changes

20191216 194 bull Made minor updates in steps 1 and 4 in Building the Host Applicationbull Added more information in step 6 of Installing an FPGA Boardbull Updated the backward compatibility details in Intel FPGA SDK for

OpenCL Pro Edition and BSP Backwards Compatibilitybull Changed the BSP path to INTELFPGAOCLSDKROOTboard in Installing

an FPGA Boardbull Updated the backwards compatibility version details in Enabling

Backwards Compatibility for an FPGA Boardbull Made the following changes in Creating the FPGA Hardware

Configuration File of an OpenCL Kernelmdash Added more information to the descriptionmdash Added more information to Step 2mdash In Step 4 removed a task about aoco file

bull Added more information about ICD and FCD in Building the HostApplication

bull Updated the details about environment variables in Setting the IntelFPGA SDK for OpenCL Pro Edition User Environment Variables

bull Included GCC 630 requirement in Prerequisites for the Intel FPGA SDKfor OpenCL Pro Edition

20190930 193 bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated two commands

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess updated few commands in the FPGA Programming Overviewimage

bull In Verifying Host Runtime Functionality via Emulation removed stepsabout installing a custom or reference platform and verifying theQUARTUS_ROOTDIR_OVERRIDE environment variable

bull In Compiling a Kernel for Emulation removed -fast-emulatoroption

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelupdated the commands

bull In Emulating Your OpenCL Kernel made the following updatesmdash Removed a steps about running aocl linkflags linking host

application and moving the hello_worldaocx filemdash Changed CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA to

CL_CONFIG_CPU_EMULATE_DEVICESmdash Added more information in the step about running the host

application for emulationmdash Removed information about shared library copymdash Only in Emulating Your OpenCL Kernel topic for Linux added a note

about the version of libstdc++so that must be at least that ofGCC 630

bull In Getting Started with the SDK on Windows chapter swapped topicsUninstalling an FPGA Board and Uninstalling the Software

bull In Uninstalling the Software added a note about uninstalling the FPGAboard

bull In Building the Host Application completely updated this topic byadding new steps and modifying existing steps

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

49

Document Version Intel QuartusPrime Version

Changes

20190401 191 bull Following topics were updated with information about -fcd-onlymdash Installing an FPGA Board on page 19mdash Uninstalling an FPGA Board on page 30mdash Installing an FPGA Board on page 35mdash Uninstalling an FPGA Board on page 46

bull Updated the compatibility details in Intel FPGA SDK for OpenCL ProEdition and OpenCL BSP Backwards Compatibility on page 10

bull In Building the Host Application on page 22 steps 1 - 3 were updatedfor setting up the MS Visual Studios showing output when FCD andICD are correctly setup

bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 added support for MS Visual C++ 2015 or later

bull In Compiling a Kernel for Emulation on page 22 Emulating YourOpenCL Kernel on page 24 and Emulating Your OpenCL Kernelchanged hello_world_emulationaocx to hello_worldaocx

bull In Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15and Downloading the Intel FPGA SDK for OpenCL Pro Edition on page32 removed a step about downloading Intel FPGA SDK for OpenCL withIntel Code Builder

bull In Figure 2 on page 14 changed hello_world_emulationaocx tohello_worldaocx

bull In Installing an FPGA Board on page 19 and Installing an FPGA Boardon page 35 added an example for the step about adding the paths tothe Custom Platform libraries

bull In Uninstalling the Software on page 30 updated the path to theinstallation folder

bull In Uninstalling an FPGA Board on page 30 updated the last step aboutthe PATH variable for better clarity

bull In Creating the FPGA Hardware Configuration File of an OpenCL Kernelon page 24 and Creating the FPGA Hardware Configuration File of anOpenCL Kernel on page 40 updated step 2 with more informationabout what you can when you have multiple BSPs

bull In Emulating Your OpenCL Kernel on page 24 and Emulating YourOpenCL Kernel added the output observed upon successful emulationof the kernel

20180114 181 bull In Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page5 updated Microsoft Visual Studio version required to Visual Studio2015 or later

20181224 181 bull Removed references to passing channels by reference since it is nolonger supported

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

50

Document Version Intel QuartusPrime Version

Changes

20181210 181 bull Added information about backwards compatibility for OpenCL boardsupport packages (BSPs) The following topic new topics were addedmdash Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards

Compatibility on page 10mdash Enabling Backwards Compatibility for an FPGA Board on Windowsmdash Enabling Backwards Compatibility for an FPGA Board on Linux

20180924 181 bull In Intel FPGA SDK for OpenCL Pro Edition the Intel FPGA SDK forOpenCL Offline Compiler has a new front end For a summary ofchanges introduced by this new front end see Improved Intel FPGASDK for OpenCL Compiler Front End in the Intel FPGA SDK for OpenCLPro Edition Release Notes

bull Replaced alteracom links with intelcom links For example httpdlalteracomopencl is now httpfpgasoftwareintelcomopencl

20180504 180 bull Removed Intel Quartus Prime Standard Edition software-relatedinformation

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition SetupProcess on page 12 updated the figure FPGA Programming Overview toinclude the aocr file as an output and changed the -c flag to -rtlflag in the Attention note

bull For Windows and Linux updated the maximum number of devices (thatis acl number) from 32 to 128 in the following topicsmdash Querying the Device Name of Your FPGA Boardmdash Programming the Flash Memory of an FPGA

Date Version Changes

December 2017 20171208 bull Updated the following sections to include the availability of Intel FPGASDK for OpenCL installation packages that include Intel Code Buildermdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32

bull Updated the following sections to include the Java SE version prerequisiterequired to run Intel Code Buildermdash Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition on page 5mdash Installing the Intel FPGA SDK for OpenCL Pro Edition on page 33

November 2017 20171106 bull Rebranded the followingmdash ALTERAOCLSDKROOT to INTELFPGAOCLSDKROOTmdash CL_CONTEXT_EMULATOR_DEVICE_ALTERA to

CL_CONTEXT_EMULATOR_DEVICE_INTELFPGAmdash Quartus Prime to Intel Quartus Primemdash Arria 10 to Intel Arria 10mdash USB Blaster to Intel FPGA Download Cable

bull In Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide onpage 4 changed OpenCL Reference Pages as OpenCL 10 reference pagesto improve clarity and added reference to Intel Arria 10 GX ApplicationNote

bull In Prerequisites for the Intel FPGA SDK for OpenCLmdash Changed Intel preferred accelerator board to Intel FPGA Preferred

Board for OpenCLmdash Changed Microsoft Visual Studio version 2010 Professional as Microsoft

Visual Studio Professional version 2010 or laterbull In Contents of the Intel FPGA SDK for OpenCL

mdash In the sentence The Intel FPGA SDK for OpenCL provides logiccomponents drivers and SDK-specific libraries and files changedlogical components to programs

mdash Under the Logic Components section changed host platform API andruntime API as host and runtime API

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

51

Date Version Changes

bull In Building the Host Application on page 22 updated references toMicrosoft Visual Studio 2015 as Microsoft Visual Studio

bull In Executing an OpenCL Kernel on an FPGA on page 29 updated referenceto Microsoft Visual Studio version 2010 Professional as Microsoft VisualStudio

bull Removed topics on Licensing the Intel FPGA SDK for OpenCL in bothOpenCL for Linux and Windows sections

bull Added support for Intel Stratix 10 devices in the following topicsmdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 15mdash Installing an FPGA Board on page 19mdash Verifying Host Runtime Functionality via Emulation on page 21mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Downloading the Intel FPGA SDK for OpenCL Pro Edition on page 32mdash Installing an FPGA Board on page 35mdash Verifying Host Runtime Functionality via Emulation on page 37mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 40bull Implemented single dash and -option=ltvaluegt conventions in the

following topicsmdash Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process

on page 12mdash Creating the FPGA Hardware Configuration File of an OpenCL Kernel on

page 24mdash Compiling a Kernel for Emulation on page 22

bull Removed references to AOCL_BOARD_PACKAGE_ROOT throughout theguide since it is deprecated

bull Updated instances of aocl install to aocl installltpath_to_customplatformgt

bull Updated instances of aocl uninstall to aocl uninstallltpath_to_customplatformgt

bull In Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Processon page 12 added a note after the Installation Process Overview diagramabout possible errors after implementing aocl diagnose

bull In Updating the Hardware Image on the FPGA on page 27 added a noteand related links to Configuring the Intel Arria 10 GX FPGA DevelopmentKit for the Intel FPGA SDK for OpenCL application note

May 2017 20170505 bull Rebranded the Altera Client Driver (ACD) to the FPGA Client Driver (FCD)bull Updated the download instructions in Downloading the Intel FPGA SDK for

OpenCL for Windows and Linuxbull Added reminders that folder names where you uncompress downloaded

OpenCL design examples must not contain spaces

October 2016 20161031 bull Rebranded the Altera SDK for OpenCL to Intel FPGA SDK for OpenCLbull Rebranded the Altera Offline Compiler to Intel FPGA SDK for OpenCL

Offline Compilerbull In Installing an FPGA Board for Windows and Linux provided the following

updatesmdash Noted that the SDK supports multi-Custom Platform installation To use

the SDK utilities on each board in a multi-Custom Platform installationthe AOCL_BOARD_PACKAGE_ROOT environment variable setting mustcorrespond to the Custom Platform subdirectory of the associatedboard

mdash Noted that in a multi-Custom Platform system the host programshould use ACD to discover the boards instead of directly linking to theMMD libraries

bull In Building the Host Application for Windows outlined the prerequisitetasks for setting up ACD and ICD for use with Microsoft Visual Studio 2015prior to building the host application

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

52

Date Version Changes

May 2016 20160502 bull Replaced the lists of supported Windows and Linux versions to a link tothe Operating System Support page on the Altera website

bull Added the ALTERAOCLSDKROOTwindows64bin setting to the list ofWindows environment variables

bull Corrected the Windows instructions for setting theCL_CONTEXT_EMULATOR_DEVICE_ALTERA variable for emulating multipledevices

November 2015 20151102 bull Changed instances of Quartus II to Quartus Primebull Added Windows 81 to supported Windows versionsbull Modified download and installation instructions for the tar file that includes

the AOCL Quartus Prime software and device supportbull Deprecated and removed AOCL-only installation instructions because they

are invalid for the current versionbull Added instructions to verify host runtime functionality by emulating the

hello_world example designbull Modified the figure FPGA Programming Overview to include emulation in

the programming flowbull Updated uninstallation instructions

May 2015 1500 bull Reorganized instructions into the following sectionsDecember 2014mdash Getting Started with the AOCL on Windowsmdash Getting Started with the AOCL on Linux

1410 bull Reorganized information flowbull Updated Red Hat Enterprise Linux (RHEL) version supportbull Included the Contents of the AOCL sectionbull Updated licensing instructions for the new Altera Software Development

Kit (SDK) for OpenCL (AOCL) single licensebull Updated board uninstallation instructions to include the aocl

uninstall utility commandbull Included information on the init_opencl script for setting environment

variablesbull Grouped software and board uninstallation instructions under Uninstalling

the Software and the FPGA Board

June 2014 1400 bull Updated the Prerequisites sectionbull Updated the figure AOCL Installation Process Overviewbull Updated software download instructionsbull Updated AOCL installation and uninstallation instructions for Windowsbull For Linux systems

mdash Added the sections Installing the AOCL on Linux Using RPM andUninstalling the AOCL on Linux Using RPM

mdash Updated the section Installing the AOCL on Linux Using the GUIInstaller

bull Added the section Licensing the Softwarebull Updated the section Installing an FPGA Board with updated instructions on

querying your devices and running diagnostic testsbull Updated the section Creating the FPGA Hardware Configuration File of an

OpenCL Kernelmdash Updated path that you have to set for AOCL_BOARD_PACKAGE_ROOTmdash Updated example AOC output for compiling hello_worldcl with the

-v optionmdash Updated AOC output

bull Added the section Identifying the Device Name of Your FPGA Boardbull Modified instructions for building and running the host application with

updated hello_world directory and file namesbull Added the section Uninstalling an FPGA Board

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

53

Date Version Changes

December 2013 1311 bull Updated the Prerequisites section to include a reminder to install Linuxkernel source headers and GCC

November 2013 1310 bull Reorganized information flowbull Updated the Prerequisites sectionbull Updated board installation instructionsbull Updated software download instructionsbull Inserted the section Installing the AOCL and the Quartus II Software

Togetherbull Updated software installation and uninstallation instructionsbull Inserted the following figures

mdash AOCL Installation Process Overviewmdash FPGA Programming Overview

bull Removed the Licensing sectionbull Removed all board-specific installation and configuration instructionsbull Changed example OpenCL application used to demonstrate kernel

configuration and FPGA programming from moving_average tohello_world

bull Inserted the section Updating the Hardware Image on the FPGA whichcontained the updated flash programming instructions

bull Removed the section Installing the USB-Blaster Driver on Windowsbull Updated output from successful execution of hello_world kernel on FPGA

for Windows and Linux systemsbull Removed the figure Contents of the Moving Average Examplebull Removed the figure Opening hostsln in Visual Studio

June 2013 130 SP10 bull Updated requisite Quartus II and AOCL software versions from 130 to130 SP1

bull Inserted the figure A Correct Windows Device Manager After CompleteBoard Driver Installation for a BittWare Board

bull Updated the vendor and device IDs in the Verifying the Functionality ofthe BittWare Board section for Windows

bull Updated the AOCL installation instructions for Linux systems that do notcontain a cshrc or a bashrc file in the directory

bull Updated path to the AOCL design examplesbull Updated the figure Contents of the Moving Average Examplebull Updated flash programming instructions

May 2013 1301 bull Renamed the OpenCL_SDK folder or directory to AOCLbull Inserted warning about the AOCL installation dependency on cshrc

and bashrc files for Linux systemsbull Included reminder to BittWare board users about installing the BittWare

development softwarebull Inserted warning about potential Jungo WinDriver installation failure for

systems running on Windows 7 Included reinstallation instructionsbull Inserted warnings about error messages displayed for aocl commands

that have not been implemented for the BittWare FPGA boardbull Inserted caution message about setting the environment variable

AOCL_BOARD_PACKAGE_ROOT

continued

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Send Feedback

54

Date Version Changes

bull Updated board driver installation procedures for Windows and Linuxsystems

bull Modified the path to the default location of the AOCL for Windows andLinux systems

bull Modified the path name added to the PATH environment variable wheninstalling the AOCL on Linux systems The path name should be$QUARTUS_ROOTDIRbin instead of $QUARTUS_ROOTDIRbin64

May 2013 1300 bull Updated installation and compilation proceduresbull Incorporated licensing procedurebull Updated flash programming procedure and moved it to Appendix Abull Updated links to software and documentation download pages

November 2012 1210 Initial release

B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting StartedGuide

UG-OCL001 | 20210621

Send Feedback Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide

55

  • Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
  • Contents
  • 1 Intelreg FPGA SDK for OpenCLtrade Pro Edition Getting Started Guide
    • 11 Prerequisites for the Intel FPGA SDK for OpenCL Pro Edition
      • 111 GCC Requirement
        • 12 Intel FPGA SDK for OpenCL Pro Edition and OpenCL BSP Backwards Compatibility
        • 13 Contents of the Intel FPGA SDK for OpenCL Pro Edition
        • 14 Overview of the Intel FPGA SDK for OpenCL Pro Edition Setup Process
          • 2 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Windows
            • 21 Downloading the Intel FPGA SDK for OpenCL Pro Edition
            • 22 Installing the Intel FPGA SDK for OpenCL Pro Edition
            • 23 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
            • 24 Verifying Software Installation
            • 25 Installing an FPGA Board
              • 251 Enabling Backwards Compatibility for an FPGA Board
                • 26 Verifying Host Runtime Functionality via Emulation
                  • 261 Accessing an OpenCL Design Example
                  • 262 Compiling a Kernel for Emulation
                  • 263 Building the Host Application
                  • 264 Emulating Your OpenCL Kernel
                    • 27 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                    • 28 Updating the Hardware Image on the FPGA
                      • 281 Querying the Device Name of Your FPGA Board
                      • 282 Programming the Flash Memory of an FPGA
                        • 29 Executing an OpenCL Kernel on an FPGA
                          • 291 Running the Host Application
                          • 292 Output from Successful Kernel Execution
                            • 210 Uninstalling an FPGA Board
                            • 211 Uninstalling the Software
                              • 3 Getting Started with the Intel FPGA SDK for OpenCL Pro Edition for Linux
                                • 31 Downloading the Intel FPGA SDK for OpenCL Pro Edition
                                • 32 Installing the Intel FPGA SDK for OpenCL Pro Edition
                                • 33 Setting the Intel FPGA SDK for OpenCL Pro Edition User Environment Variables
                                • 34 Verifying Software Installation
                                • 35 Installing an FPGA Board
                                  • 351 Enabling Backwards Compatibility for an FPGA Board
                                    • 36 Verifying Host Runtime Functionality via Emulation
                                      • 361 Accessing an OpenCL Design Example
                                      • 362 Compiling a Kernel for Emulation
                                      • 363 Building the Host Application
                                      • 364 Emulating Your OpenCL Kernel
                                        • 37 Creating the FPGA Hardware Configuration File of an OpenCL Kernel
                                        • 38 Updating the Hardware Image on the FPGA
                                          • 381 Querying the Device Name of Your FPGA Board
                                          • 382 Programming the Flash Memory of an FPGA
                                            • 39 Executing an OpenCL Kernel on an FPGA
                                              • 391 Running the Host Application
                                              • 392 Output from Successful Kernel Execution
                                                • 310 Uninstalling an FPGA Board
                                                • 311 Uninstalling the Software
                                                  • A Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide Archives
                                                  • B Document Revision History of the Intel FPGA SDK for OpenCL Pro Edition Getting Started Guide
Page 17: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 18: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 19: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 20: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 21: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 22: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 23: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 24: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 25: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 26: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 27: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 28: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 29: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 30: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 31: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 32: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 33: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 34: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 35: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 36: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 37: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 38: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 39: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 40: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 41: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 42: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 43: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 44: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 45: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 46: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 47: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 48: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 49: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 50: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 51: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 52: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 53: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 54: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera
Page 55: Altera SDK for OpenCL Getting Started - FPGA CPLD and ASIC from Altera