Intel FPGA SDK for OpenCL Standard Edition: Getting Started Guide
Intel FPGA SDK for OpenCL Standard Edition Getting Started Guide
OpenCL* is a C-based open standard for the parallel programming of heterogeneous devices. For more information about the OpenCL* Specification version 1.0, refer to the OpenCL* 1.0 Reference Pages. For detailed information on the OpenCL* application programming interface (API) and programming language, refer to the OpenCL Specification version 1.0.
The Intel® FPGA SDK for OpenCL™ Standard Edition provides a compiler and tools for you to build and run OpenCL* applications that target Intel® FPGA products. The Intel® FPGA SDK for OpenCL™ Standard Edition supports the embedded profile of the OpenCL* Specification version 1.0.
- If you only require the
Intel® FPGA SDK for OpenCL™
's kernel deployment functionality, download
and install the
Intel®
FPGA Runtime
Environment (RTE) for OpenCL. Refer to the
Intel®
FPGA RTE for OpenCL
Standard
Edition Getting Started Guide for more
information.
Do not install the SDK and the RTE on the same host system. The SDK already contains the RTE.
- If you want to use the Intel® FPGA SDK for OpenCL™ Standard Edition with the Cyclone® V SoC Development Kit, refer to the Intel® FPGA SDK for OpenCL™ Standard Edition Cyclone V SoC Getting Started Guide for more information.
Prerequisites for the Intel FPGA SDK for OpenCL Standard Edition
Hardware Requirements
Accelerator boards requirements:
- Acquire a Reference Platform from
Intel®
, or a Custom Platform from an
Intel®
preferred board vendor.
For more information, refer to the Intel FPGA SDK for OpenCL FPGA Platforms page on the Intel® FPGA website.
Development system requirements:
- You must have administrator, root, or sudo privileges on the development system to install the necessary packages and drivers.
- The development system has at least 85 gigabytes (GB) of free disk space for software installation.
- The development system has at least 24 GB of RAM.Tip: Refer to board vendor's documentation on the recommended system storage size.
- For PCI Express* ( PCIe* ) accelerator boards, the host machine motherboard must have an available PCIe* port slot that is at least the same width (that is, the same number of PCIe* lanes) as the board.
The host system must be running one of the following supported operating systems:
- 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® Quartus® Prime software-compatible C compiler or software development environment:
- For Windows systems, use Microsoft Visual Studio Professional version 2010 or later.
- For Linux systems, use the C compiler included with the GCC.
Linux systems require the Perl command version 5 or later. Include the path to the Perl command in your PATH system environment variable setting.
For Intel® FPGA SDK for OpenCL™ packages that include Intel Code Builder, Intel Code Builder requires Java SE version 1.8.71 or later to run.
Contents of the Intel FPGA SDK for OpenCL Standard Edition
Logic Components
- The Intel® FPGA SDK for OpenCL™ Offline Compiler translates your OpenCL* device code into a hardware configuration file that the system loads onto an Intel® FPGA product.
- The Intel® FPGA SDK for OpenCL™ Standard Edition utility includes a set of commands you can invoke to perform high-level tasks such as running diagnostic tests.
- The host
runtime provides the
OpenCL*
host
and runtime API for your
OpenCL*
host
application.
The host runtime consists of libraries that provide OpenCL* APIs, hardware abstractions, and helper libraries.
Drivers, Libraries and Files
The software installation process installs the Intel® FPGA SDK for OpenCL™ Standard Edition into a directory that you own. The INTELFPGAOCLSDKROOT environment variable references the path to the SDK's installation directory.
Windows Folder | Linux Directory | Description |
---|---|---|
bin | bin | User commands in the SDK. Include this directory in your PATH environment variable setting. |
board | board | The
Intel® FPGA SDK for OpenCL™
Standard
Edition Custom Platform Toolkit and Reference
Platforms available with the software.
|
ip | ip | Intellectual property (IP) cores used to compile device kernels. |
host | host | Files necessary for compiling and running your host application. |
host\include | host/include |
OpenCL*
Specification version 1.0 header files and software interface files
necessary for compiling and linking your host application. The host/include/CL subdirectory also includes the C++ header file cl.hpp. The file contains an OpenCL* version 1.1 C++ wrapper API. These C++ bindings enable a C++ host program to access the OpenCL* runtime APIs using native C++ classes and methods. Important: The
OpenCL*
version 1.1 C++ bindings are compatible
with
OpenCL*
Specification
versions 1.0 and 1.1.
Add this path to the include file search path in your development environment. |
host\windows64\lib | host/linux64/lib |
OpenCL*
host
runtime libraries that provide the
OpenCL*
platform and runtime APIs. These libraries are
necessary for linking your host application. To run an OpenCL* application on Linux, include this directory in the LD_LIBRARY_PATH environment variable setting. |
host\windows64\bin | host/linux64/bin | Runtime commands and libraries necessary for running
your host application, wherever applicable. For 64-bit Windows
system, include this directory in your PATH environment variable setting. For Windows system, this folder contains runtime libraries. 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 download example OpenCL* applications from the OpenCL* Design Examples page.
Overview of the Intel FPGA SDK for OpenCL Standard Edition Setup Process
The figure below summarizes the steps for setting up the necessary software and installing the FPGA board.
After you complete the initial software and hardware setup successfully, you can create a hardware image from the hello_world OpenCL* design example.
The figure below summarizes the steps you perform to program your FPGA.
Getting Started with the Intel FPGA SDK for OpenCL Standard Edition for Windows
- Downloading the Intel FPGA SDK for OpenCL Standard Edition
Download the installation package that contains the Intel® FPGA SDK for OpenCL™ Standard Edition and all related software for Windows from the Intel® FPGA SDK for OpenCL™ Download Center. - Installing the Intel FPGA SDK for OpenCL
Install the Windows version of the Intel® FPGA SDK for OpenCL™ Standard Edition in a folder that you own. - Setting the Intel FPGA SDK for OpenCL Standard Edition User Environment Variables
You have the option to set the Intel® FPGA SDK for OpenCL™ Standard Edition Windows user environment variables permanently or transiently. - Verifying Software Installation
Invoke the version utility command and verify that the correct version of the OpenCL™ software is installed. - Installing an FPGA Board
To install your board into a Windows host system, invoke the install <path_to_customplatform> utility command. - Verifying Host Runtime Functionality via Emulation
Test the functionality of the host runtime by emulating an OpenCL™ design example using the Intel® FPGA SDK for OpenCL™ Standard Edition Emulator. - Creating the FPGA Hardware Configuration File of an OpenCL Kernel
Compile the hello_world kernel program using the Intel® FPGA SDK for OpenCL™ Offline Compiler to create the hello_world.aocx executable file. - Updating the Hardware Image on the FPGA
If applicable, before you execute an OpenCL™ kernel program on the FPGA, ensure that the flash memory of the FPGA contains a hardware image created using a current version of the OpenCL software. - Executing an OpenCL Kernel on an FPGA
Build your OpenCL™ host application in Microsoft Visual Studio, and run the application by invoking the hello_world.exe executable. - Uninstalling the Software
To uninstall the Intel® FPGA SDK for OpenCL™ Standard Edition for Windows, run the uninstaller, and restore all modified environment variables to their previous settings. - Uninstalling the FPGA Board
To uninstall an FPGA board for Windows, invoke the uninstall utility command, uninstall the Custom Platform, and unset the relevant environment variables.
Downloading the Intel FPGA SDK for OpenCL Standard Edition
- Intel® FPGA SDK for OpenCL™ Standard Edition
- Intel® Quartus® Prime Standard Edition software
- Device support
- Go to the Intel® FPGA SDK for OpenCL™ Download Center at the following URL:
- Select the Standard edition.
- Select the software version. The default selection is the current version.
-
Select one of the following download methods:
- Akamai DLM3 Download Manager
- Direct Download
- Click the Windows SDK tab.
- Click More beside Download and install instructions if you want to see the download and installation instructions.
- Click the download button to start the download process.
- Perform the steps outlined in the download and installation instructions on the download page.
Installing the Intel FPGA SDK for OpenCL
In this section, you learn how to unpack the downloaded tar archive and run the installation files to install all the software and files.
To install the Intel® FPGA SDK for OpenCL™ , Intel® Quartus® Prime Standard Edition software, and device support files, perform the following tasks:
- Unpack the downloaded AOCL-<version>-<build>-windows.tar archive into a temporary folder.
- Run the setup.bat file to install the SDK with the Intel® Quartus® Prime Standard Edition software.
-
Note: The installer sets the user environment variable INTELFPGAOCLSDKROOT to point to the path of the software installation.Verify that INTELFPGAOCLSDKROOT points to the current version of the software. Open a Windows command window and then type echo %INTELFPGAOCLSDKROOT% at the command prompt.If the returned path does not point to the location of the Intel® FPGA SDK for OpenCL™ installation, edit the INTELFPGAOCLSDKROOT setting.
Setting the Intel FPGA SDK for OpenCL Standard Edition User Environment Variables
Environment Variable | Path to Include |
---|---|
PATH |
where INTELFPGAOCLSDKROOT points to the path of the software installation |
-
To apply permanent environment variable settings, perform the
following tasks:
- Click Windows Start menu > Control Panel (or search for and then open the Control Panel application in Windows 8.1 and Windows 10).
- Click System and Security > System.
- In the System window, click Advanced system settings.
- Click the Advanced tab in the System Properties dialog box.
-
Click Environment
Variables.
The Environment Variables dialog box appears.
- To modify an existing environment variable setting, select the variable under User variables for <user_name> and then click Edit. In the Edit User Variable dialog box, type the environment variable setting in the Variable value field.
- If you add a new environment variable, click New under User variables for <user_name>. In the New User Variable dialog box, type the environment variable name and setting in the Variable name and Variable value fields, respectively.
For an environment variable with multiple settings, add semicolons to separate the settings.
-
To apply transient environment variable settings, open a
command window and run the %INTELFPGAOCLSDKROOT%\init_opencl.bat script.
Example script output:
Adding %INTELFPGAOCLSDKROOT%\bin to PATH Adding %INTELFPGAOCLSDKROOT%\host\windows64\bin to PATH
Running the init_opencl.bat script only affects the current command window. The script performs the following tasks:- Finds the Intel® Quartus® Prime Standard Edition software installation
- Finds the Microsoft Visual Studio installation
- Imports the Microsoft Visual Studio environment to properly set the LIB environment variable
- Ensures that the PATH environment variable includes the path to the Microsoft LINK.EXE file and the aoc.exe file
Verifying Software Installation
-
At a command prompt, invoke the
aocl
version
utility command.
An output similar to the one below notifies you of a successful installation:
aocl <version>.<build> (Intel(R) FPGA SDK for OpenCL(TM), Version <version> Build <build>, Copyright (C) <year> Intel® Corporation)
- If installation was unsuccessful, reinstall the software. You can also refer to the Intel® FPGA Software Installation and Licensing manual and the Intel FPGA Knowledge Base for more information.
Installing an FPGA Board
- Follow your board vendor's instructions to connect the FPGA board to your system.
- Download the Custom Platform for your FPGA board from your board vendor's website. To download an Intel® FPGA SDK for OpenCL Reference Platform, refer to the Intel® FPGA SDK for OpenCL FPGA Platforms page.
-
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 system using the SDK utilities, such as aocl diagnose with multiple Custom Platforms. The Custom Platform subdirectory contains the board_env.xml file.
In a system with multiple Custom Platforms, ensure that the host program uses the FPGA Client Driver (FCD) to discover the boards rather than linking to the Custom Platforms' memory-mapped device (MMD) libraries directly. As long as FCD is correctly set up for Custom Platform, FCD finds all the installed boards at runtime.
- Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to e installation directory.
-
Add the paths to the Custom Platform libraries (for example,
the memory-mapped (MMD) library) to the PATH
environment variable setting.
For information on setting user environment variables and running the init_opencl script, refer to the Setting the Intel® FPGA SDK for OpenCL™ Standard Edition User Environment Variables section.
-
Invoke the command
aocl
install
<path_to_customplatform>
at a command prompt.
Invoking aocl install <path_to_customplatform> also installs a board driver that allows communication between host applications and hardware kernel programs.Remember: You need administrative rights to install a board. To run a Windows command prompt as an administrator, click Start > All Programs > Accessories. Under Accessories, right click Command Prompt, In the right-click menu, click Run as Administrator.
-
To query a list of FPGA devices installed in your machine,
invoke the
aocl
diagnose
command.
The software generates an output that includes the <device_name>, which is an acl number that ranges from acl0 to acl31.Attention: For more information on querying the <device_name> of your accelerator board, refer to the Querying the Device Name of Your FPGA Board section.
- To verify the successful installation of the FPGA board, invoke the command aocl diagnose <device_name> to run any board vendor-recommended diagnostic test.
Verifying Host Runtime Functionality via Emulation
- Install a Custom or Reference Platform because emulation targets a specific FPGA board.
- Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to the
correct edition of the
Intel®
Quartus® Prime Standard Edition software. Open a Windows
command window and then type echo
%QUARTUS_ROOTDIR_OVERRIDE% at the command
prompt.
If the path to the installation folder of the Intel® Quartus® Prime Standard Edition software is not returned, add it to the QUARTUS_ROOTDIR_OVERRIDE setting.
- Add the path to the LINK.exe file in Microsoft Visual Studio to the PATH user environment variable setting.
- Add the path to the Microsoft compilation time libraries in Microsoft Visual Studio to the LIB user environment variable setting.
- Downloading an OpenCL Design Example
The OpenCL Design Examples page contains sample applications of varying complexities that you can download and run on your FPGA. - Compiling a Kernel for Emulation
To compile an OpenCL™ kernel for emulation, include the -march=emulator option in your aoc command. - Building the Host Application
The <path_to_exm_opencl_hello_world_x64_windows_<version>>\hello_world\hello_world.sln file contains the host solution. After you open this .sln file in Microsoft Visual Studio, you can build the OpenCL™ host application in the main.cpp file. - Emulating Your OpenCL Kernel
To emulate your OpenCL™ kernel, run the emulation .aocx file on the platform on which you build your kernel.
Downloading an OpenCL Design Example
The following instructions are for downloading the Hello World design.
- In the OpenCL Design Examples page, under Basic Examples, click Hello World.
- In the Hello World Design Example page, under Downloads, click <version> x64 Windows package (.zip) to download the compressed file for your platform.
-
Unzip the exm_opencl_hello_world_x64_windows_<version>.zip file and save it in a folder
that you have write access for.
Important: Ensure that the folder name does not contain spaces.
Compiling a Kernel for Emulation
The Intel® FPGA SDK for OpenCL™ Offline Compiler compiles the hello_world.cl kernel source file and creates the hello_world_emulation.aocx emulation-specific executable file in the bin subdirectory.
Building the Host Application
- Verify that FCD and ICD are set up correctly. You must set up FCD and ICD manually if invoking the aocl install <path_to_customplatform> utility command fails to set them up. For instructions, refer to the Accessing Custom Platform-Specific Functions and Linking to the ICD Loader Library on Windows sections of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide for more information.
- Link the host application to the OpenCL.lib library.
- Under the solution properties, select Configuration Properties > Linker > Input.
- In the Additional Dependencies field, enter OpenCL.lib.
Attention: Because you are using FCD and ICD, do not link the host program to alteracl.lib or to your Custom Platform's MMD libraries directly.
- Open the <path_to_exm_opencl_hello_world_x64_windows_<version>>\hello_world\hello_world.sln file in Microsoft Visual Studio.
- Verify that the build configuration is correct. The default build configuration is Debug, but you can use Release. You must select the appropriate option as the solution platform (for example, for x64 architecture, select x64).
-
Build the solution
by selecting the
Build > Build
Solution menu option, or by pressing the F7
key.
The hello_world.exe executable will be in the <path_to_exm_opencl_hello_world_x64_windows_<version>>\hello_world\bin folder.
-
Verify that the
build is correct. An output ending with a message similar to the one shown
below notifies you of a successful build:
1> Build succeeded. 1> 1> Time Elapsed 00:00:03:29 ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
Attention: You can ignore the LNK4009: PDB 'vc90.pdb' was not found with... warnings because they have no effect on the build. The compiler might issue this type of warning messages if you have built your Windows libraries using a previous version of Microsoft Visual Studio.
Emulating Your OpenCL Kernel
To emulate your kernel, perform the following steps:
- Run the utility command aocl linkflags to find out which libraries are necessary for building a host application. The software lists the libraries for both emulation and regular kernel compilation flows.
- Link your host application to the libraries returned by the aocl linkflags utility command.
- Move the hello_world_emulation.aocx file to the current working directory so that the host can locate it easily.
-
To run the host application for emulation, first define the
number of emulated devices by invoking the
set
CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA=<number_of_devices>
command and then run
the host application.
This command specifies the number of identical emulation devices that the Emulator needs to provide.Remember: When the environment variable CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA is set, only the emulated devices are available, that is, access to all physical boards is disabled.
- After you run the host application, unset the CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA variable by invoking the set CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA= command.
Creating the FPGA Hardware Configuration File of an OpenCL Kernel
-
Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to the
Intel®
Quartus® Prime Standard Edition software. Open a
Windows command window and then type echo
%QUARTUS_ROOTDIR_OVERRIDE% at the command prompt.
If the path to the installation folder of the Intel® Quartus® Prime Standard Edition software is not returned, add it to the QUARTUS_ROOTDIR_OVERRIDE setting.
-
Select your target FPGA board. To list the FPGA boards
available in your Custom Platform, invoke the command
aoc
-list-boards
at a command
prompt.
For more information on the -list-boards option of the aoc command, refer to the Listing the Available FPGA Boards in Your Custom Platform (-list-boards) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
- At a command prompt, navigate to the hello_world design folder containing the hello_world.cl file that you used for emulation.
-
To compile the kernel for your target FPGA board, invoke the
following command:
aoc -v -board=<board_name> device/hello_world.cl -o=bin/hello_world.aocx
This command performs the following tasks:
- Generates the Intel® Quartus® Prime design project files from the OpenCL source code.
- Checks for initial syntax errors.
- Performs basic optimizations.
- Creates a hello_world folder containing necessary intermediate files.
- Creates the Intel® FPGA SDK for OpenCL™ Offline Compiler Object File (.aoco).
- Creates the .aocx file.
Attention:The .aocx file might take hours to build, depending on the complexity of the kernel. To view the progress of the compilation on-screen, include the -v flag in your aoc command. An example output is shown below.
aoc: Environment checks are completed successfully. You are now compiling the full flow!! aoc: Selected target board <board_name> aoc: Running OpenCL parser.... aoc: OpenCL parser completed successfully. aoc: Compiling.... aoc: Linking with IP library ... aoc: First stage compilation completed successfully. aoc: Setting up project for CvP revision flow.... aoc: Hardware generation completed successfully.
The offline compiler displays the line aoc: Hardware generation completed successfully. to signify the completion of the compilation process.
For more information about the -board <board_name> option of the aoc command, refer to the Compiling a Kernel for a Specific FPGA Board (-board=<board_name>) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
For more information about the -v option of the aoc command, refer to the Generating Compilation Progress Report (-v) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
For more information about the -o=<filename> option of the aoc command, refer to the Specifying the Name of an Intel® FPGA SDK for OpenCL™ Offline Compiler Output File (-o <filename>) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
Updating the Hardware Image on the FPGA
- If your Custom Platform requires that you preload a valid OpenCL image into the flash memory, for every major release of the Intel Quartus® Prime Design Suite, program the flash memory of the FPGA with a hardware image compatible with the current version of the software.
Querying the Device Name of Your FPGA Board
aocl diagnose: Running diagnostic from INTELFPGAOCLSDKROOT/board/<board_name>/<platform>/libexec Verified that the kernel mode driver is installed on the host machine. Using board package from vendor: <board_vendor_name> Querying information for all supported devices that are installed on the host machine ... device_name Status Information acl0 Passed <descriptive_board_name> PCIe dev_id = <device_ID>, bus:slot.func = 02:00.00, at Gen 2 with 8 lanes. FPGA temperature = 43.0 degrees C. acl1 Passed <descriptive_board_name> PCIe dev_id = <device_ID>, bus:slot.func = 03:00.00, at Gen 2 with 8 lanes. FPGA temperature = 35.0 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 <device_name> DIAGNOSTIC_PASSED
Programming the Flash Memory of an FPGA
Preloading an OpenCL image into the flash memory is necessary for the proper functioning of many Custom Platforms. For example, most PCIe®-based boards require a valid OpenCL image in flash memory so that hardware on the board can use the image to configure the FPGA device when the host system powers up for the first time. If the FPGA is not configured with a valid OpenCL image, the system will fail to enumerate the PCIe endpoint, or the driver will not function.
Before running any designs, ensure that the flash memory of your board has a valid OpenCL image that is compatible with the current OpenCL software version. Consult your board vendor's documentation for board-specific requirements.
To load your hardware configuration file into the flash memory of your FPGA board, perform the following tasks:
-
Install any drivers or utilities that your Custom Platform
requires.
For example, some Custom Platforms require you to install the Intel® FPGA Download Cable driver to load your hardware configuration file into the flash memory. For installation instructions, refer to the Intel® FPGA Download Cable User Guide.
-
Download
a
design
example for your Custom Platform.
Remember: Download design examples from the OpenCL Design Examples page, and extract the example to a location that you have write access for. Ensure that the location name does not contain spaces.
- To load the hardware configuration file into the flash memory, invoke the aocl flash <device_name> <design_example_filename>.aocx command, where <device_name> refers to the acl number (e.g. acl0 to acl31) that corresponds to your FPGA device, and <design_example_filename>.aocx is the hardware configuration file you create from the <design_example_filename>.cl file in the design example package.
-
Power down your device or computer and then power it up
again.
Power cycling ensures that the FPGA configuration device retrieves the hardware configuration file from the flash memory and configures it into the FPGA.Warning: Some Custom Platforms require you to power cycle the entire host system after programming the flash memory. For example, PCIe-based Custom Platforms might require a host system restart to reenumerate the PCIe endpoint. Intel® recommends that you power cycle the complete host system after programming the flash memory.
Executing an OpenCL Kernel on an FPGA
Running the Host Application
- Add the path %INTELFPGAOCLSDKROOT%\host\windows64\bin to the PATH environment variable.
- At a command prompt, navigate to the host executable within the <path_to_exm_opencl_hello_world_x64_windows_<version>>\hello_world\bin folder.
-
Invoke the
hello_world.exe executable.
The hello_world executable executes the kernel code on the FPGA.
Output from Successful Kernel Execution
Example output:
Reprogramming device [0] with handle 1 Querying platform for info: ========================== CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM) CL_PLATFORM_VENDOR = Intel Corporation CL_PLATFORM_VERSION = OpenCL 1.0 Intel(R) FPGA SDK for OpenCL(TM), <version> Querying device for info: ======================== CL_DEVICE_NAME = <board name> : <descriptive board name> CL_DEVICE_VENDOR = <board vendor name> CL_DEVICE_VENDOR_ID = <board vendor ID> CL_DEVICE_VERSION = OpenCL 1.0 Intel(R) FPGA SDK for OpenCL(TM), <version> CL_DRIVER_VERSION = <version> CL_DEVICE_ADDRESS_BITS = 64 CL_DEVICE_AVAILABLE = true CL_DEVICE_ENDIAN_LITTLE = true CL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768 CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0 CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592 CL_DEVICE_IMAGE_SUPPORT = true CL_DEVICE_LOCAL_MEM_SIZE = 16384 CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000 CL_DEVICE_MAX_COMPUTE_UNITS = 1 CL_DEVICE_MAX_CONSTANT_ARGS = 8 CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648 CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3 CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192 CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024 CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4 CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2 CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0 Command queue out of order? = false Command queue profiling enabled? = true Using AOCX: hello_world.aocx Kernel initialization is complete. Launching the kernel... Thread #2: Hello from the Intel(R) FPGA OpenCL(TM) compiler! Kernel execution is complete.
Uninstalling the Software
- From the Windows Start Menu shortcut, navigate to the Altera <version> Standard Edition installation folder.
-
Select Uninstall
Intel®
Quartus® Prime Standard Edition
.
The uninstallation wizard appears.
-
In the uninstallation wizard, perform the following
tasks:
- Select Individual components and then click Next.
-
Select the SDK and then click Next.
The uninstaller uninstalls the Intel® FPGA SDK for OpenCL™ .
-
Remove the following paths from the PATH environment variable:
- %INTELFPGAOCLSDKROOT%\bin
- %INTELFPGAOCLSDKROOT%\host\windows64\bin
- Remove the INTELFPGAOCLSDKROOT environment variable.
- Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable.
Uninstalling the FPGA Board
To uninstall your FPGA board, perform the following tasks:
- Following your board vendor's instructions to disconnect the board from your machine.
- Invoke the aocl uninstall <path_to_customplatform> utility command to remove the current host computer drivers (for example, PCIe® drivers). The Intel® FPGA SDK for OpenCL™ uses these drivers to communicate with the FPGA board.
- Uninstall the Custom Platform.
- Unset the PATH environment variable.
Getting Started with the Intel FPGA SDK for OpenCL Standard Edition for Linux
- Downloading the Intel FPGA SDK for OpenCL Standard Edition
Download the installation package that contains the Intel® FPGA SDK for OpenCL™ Standard Edition and all related software for Linux from the Intel® FPGA SDK for OpenCL™ Download Center. - Installing the Intel FPGA SDK for OpenCL
Install the Linux version of the Intel® FPGA SDK for OpenCL™ Standard Edition in a directory that you own. - Setting the Intel FPGA SDK for OpenCL Standard Edition User Environment Variables
You have the option to set the Intel® FPGA SDK for OpenCL™ Standard Edition Linux user environment variables permanently or transiently. - Verifying Software Installation
Invoke the version utility command and verify that the correct version of the OpenCL™ software is installed. - Installing an FPGA Board
To install your board into a Linux host system, invoke the install utility command. - Verifying Host Runtime Functionality via Emulation
Test the functionality of the host runtime by emulating an OpenCL™ design example using the Intel® FPGA SDK for OpenCL™ Standard Edition Emulator. - Creating the FPGA Hardware Configuration File of an OpenCL Kernel
Compile the hello_world kernel program using the Intel® FPGA SDK for OpenCL™ Offline Compiler to create the hello_world.aocx executable file. - Updating the Hardware Image on the FPGA
If applicable, before you execute an OpenCL™ kernel program on the FPGA, ensure that the flash memory of the FPGA contains a hardware image created using a current version of the OpenCL software. - Executing an OpenCL Kernel on an FPGA
You must build your OpenCL™ host application with the Makefile file, and run the application by invoking the hello_world executable. - Uninstalling the Software
To uninstall the Intel® FPGA SDK for OpenCL™ Standard Edition for Linux, remove the software package via the GUI uninstaller, then delete the software directory and restore all modified environment variables to their previous settings. - Uninstalling the FPGA Board
To uninstall an FPGA board for Linux, invoke the uninstall utility command, uninstall the Custom Platform, and unset the relevant environment variables.
Downloading the Intel FPGA SDK for OpenCL Standard Edition
- Intel® FPGA SDK for OpenCL™ Standard Edition
- Intel® Quartus® Prime Standard Edition software
- Device support
- Go to the Intel® FPGA SDK for OpenCL™ Download Center at the following URL:
- Select the Standard edition.
- Select the software version. The default selection is the current version.
-
Select one of the following download methods:
- Akamai DLM3 Download Manager
- Direct Download
- On the Linux SDK tab.
- Click More beside Download and install instructions if you want to see the download and installation instructions.
- Perform the steps outlined in the download and installation instructions on the download page.
Installing the Intel FPGA SDK for OpenCL
Unpack the downloaded tar file and and run the installation files to install all the software and files.
- You must have sudo or root privileges.
- You must install the Linux OS kernel source and headers (for example, kernel-devel.x86_64 and kernel-headers.x86_64), and the GNU Compiler Collection (GCC) (gcc.x86_64).
- If you are installing a package that includes Intel Code Builder, you must have Java SE 1.8.71 or later installed to run Intel Code Builder. If you have an earlier version of Java SE installed, you can still complete the installation of Intel Code Builder. However, you must meet the Java version prerequisite to run Intel Code Builder.
To install the Intel® FPGA SDK for OpenCL™ , Intel® Quartus® Prime Standard Edition software, and device support files simultaneously, perform the following tasks:
- Unpack the downloaded tar file into a temporary directory.
- Run the setup.sh file to install the SDK with the Intel® Quartus® Prime Standard Edition software.
-
Note: The installer sets the environment variable INTELFPGAOCLSDKROOT to point to the path of the software installation.Verify that INTELFPGAOCLSDKROOT points to the current version of the software. Open a shell and then type echo $INTELFPGAOCLSDKROOT at the command prompt.If the returned path does not point to the location of the Intel® FPGA SDK for OpenCL™ installation , edit the INTELFPGAOCLSDKROOT setting.
Setting the Intel FPGA SDK for OpenCL Standard Edition User Environment Variables
Environment Variable | Path to Include |
---|---|
PATH |
$INTELFPGAOCLSDKROOT/bin
where INTELFPGAOCLSDKROOT points to the path of the software installation |
LD_LIBRARY_PATH | $INTELFPGAOCLSDKROOT/host/linux64/lib |
-
To apply permanent environment variable settings,
open
a shell and then type the export
<variable_name>="<variable_setting>":$<variable_name>
command.
For example, the command export PATH="$INTELFPGAOCLSDKROOT/bin":$PATH adds $INTELFPGAOCLSDKROOT/bin to the list of PATH settings.
-
To apply transient environment variable settings, open a
bash-shell command-line terminal and run the source
$INTELFPGAOCLSDKROOT/init_opencl.sh command. This
command does not work in other shells.
Example script output:
Adding $INTELFPGAOCLSDKROOT/bin to PATH Adding $INTELFPGAOCLSDKROOT/host/linux64/lib to LD_LIBRARY_PATH
where AOCL_BOARD_PACKAGE_ROOT points to the path of the Custom or Reference Platform.
Verifying Software Installation
-
At a command prompt, invoke the
aocl
version
utility command.
An output similar to the one below notifies you of a successful installation:
aocl <version>.<build> (Intel(R) FPGA SDK for OpenCL(TM), Version <version> Build <build>, Copyright (C) <year> Intel® Corporation)
- If installation was unsuccessful, reinstall the software. You can also refer to the Intel® FPGA Software Installation and Licensing manual and the Intel FPGA Knowledge Base for more information.
Installing an FPGA Board
- Follow your board vendor's instructions to connect the FPGA board to your system.
- Download the Custom Platform for your FPGA board from your board vendor's website. To download an Intel® FPGA SDK for OpenCL™ Reference Platform, refer to the Intel® FPGA SDK for OpenCL™ FPGA Platforms page.
-
Install the Custom Platform in a directory that you own (that
is, not a system directory).
You can install multiple Custom Platforms simultaneously on the same system. To use the RTE utilities, such as aocl diagnose with multiple Custom Platforms. The Custom Platform subdirectory contains the board_env.xml file.
In a system with multiple Custom Platforms, ensure that the host program uses the FPGA Client Drivers (FCD) to discover the boards rather than linking to the Custom Platforms' memory-mapped device (MMD) libraries directly. If FCD is correctly set up for Custom Platform, FCD finds all the installed boards at runtime.
- Set the QUARTUS_ROOTDIR_OVERRIDE user environment variable to point to the Intel® Quartus® Prime Standard Edition software installation directory. Open a shell and then type echo $QUARTUS_ROOTDIR_OVERRIDE at the command prompt.
-
Add the
paths to
the Custom Platform
libraries
(for example, memory-mapped (MMD) library) to the LD_LIBRARY_PATH environment
variable
setting.
For information on setting Linux user environment variables and running the init_opencl script, refer to the Setting the Intel® FPGA SDK for OpenCL™ Standard Edition User Environment Variables section.
-
Remember: You need sudo or root privileges to install a board.Invoke the command aocl install <path_to_customplatform> at a command prompt.
Invoking aocl install <path_to_customplatform> also installs a board driver that allows communication between host applications and hardware kernel programs.
-
To query a list of FPGA devices installed in your machine,
invoke the
aocl
diagnose
command.
The software generates an output that includes the <device_name>, which is an acl number that ranges from acl0 to acl31.
Attention: For more information on querying the <device_name> of your accelerator board, refer to the Querying the Device Name of Your FPGA Board section. - To verify the successful installation of the FPGA board, invoke the command aocl diagnose <device_name> to run any board vendor-recommended diagnostic test.
Verifying Host Runtime Functionality via Emulation
- Install a Custom or Reference Platform because emulation targets a specific FPGA board.
- Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to the
Intel®
Quartus® Prime Standard Edition software. Open a shell and
then type echo $QUARTUS_ROOTDIR_OVERRIDE
at the command prompt.
If the path to the installation directory of the Intel® Quartus® Prime Standard Edition software is not returned, add it to the QUARTUS_ROOTDIR_OVERRIDE setting.
- Verify that the LD_LIBRARY_PATH
environment variable setting includes the paths identified in Setting the
Intel® FPGA SDK for OpenCL™
Standard
Edition User Environment Variables. Open a shell
and then type echo $LD_LIBRARY_PATH at
the command prompt.
If the returned path do not include $INTELFPGAOCLSDKROOT/host/linux64/lib, add it to the LD_LIBRARY_PATH setting.
- Downloading an OpenCL Design Example
The OpenCL Design Examples page contains sample applications of varying complexities that you can download and run on your FPGA. - Compiling a Kernel for Emulation
To compile an OpenCL™ kernel for emulation, include the -march=emulator option in your aoc command. - Building the Host Application
Build the host executable with the <path_to_exm_opencl_hello_world_x64_linux_<version>>/hello_world/Makefile file. - Emulating Your OpenCL Kernel
To emulate your OpenCL™ kernel, run the emulation .aocx file on the platform on which you build your kernel.
Downloading an OpenCL Design Example
The following instructions are for downloading the Hello World design.
- In the OpenCL Design Examples page, under Basic Examples, click Hello World.
- In the Hello World Design Example page, under Downloads, click <version> x64 Linux package (.tgz) to download the compressed file for your platform.
-
Unpack the .tgz file and
save it in a directory to which you have write access.
Important: Ensure that the directory name does not contain spaces.
Compiling a Kernel for Emulation
The Intel® FPGA SDK for OpenCL™ Offline Compiler compiles the hello_world.cl kernel source file and creates the hello_world_emulation.aocx emulation-specific executable file in the bin subdirectory.
Building the Host Application
To build the host application, perform the following tasks:
- Navigate to the hello_world directory.
-
Invoke the
$
make
-f Makefile
command. Alternatively, you can simply invoke the
make
command.
The hello_world executable will be in the <path_to_exm_opencl_hello_world_x64_linux_<version>>/hello_world/bin directory.
Emulating Your OpenCL Kernel
To emulate your kernel, perform the following steps:
- Run the utility command aocl linkflags to find out which libraries are necessary for building a host application. The software lists the libraries for both emulation and regular kernel compilation flows.
- Link your host application to the libraries returned by the aocl linkflags utility command.
- Move the hello_world_emulation.aocx file to the current working directory so that the host can locate it easily.
-
To run the host application for emulation, invoke the
env
CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA=<number_of_devices>
<host_application_filename>
command.
This command specifies the number of identical emulation devices that the Emulator needs to provide.
Each invocation of the emulated kernel creates a shared library copy called <process_ID>-libkernel.so in a default temporary directory, where <process_ID> is a unique numerical value assigned to each emulation run. You may override the default directory by setting the TMPDIR environment variable.
Creating the FPGA Hardware Configuration File of an OpenCL Kernel
-
Verify that the QUARTUS_ROOTDIR_OVERRIDE environment variable points to your
Intel®
Quartus® Prime software. Open a shell and then
type echo $QUARTUS_ROOTDIR_OVERRIDE at
the command prompt.
If the path to the installation directory of the Intel® Quartus® Prime Standard Edition software is not returned, add it to the QUARTUS_ROOTDIR_OVERRIDE setting.
-
Select your target FPGA board. To list the FPGA boards
available in your Custom Platform, invoke the command
aoc
-list-boards
at a command
prompt.
For more information on the -list-boards option of the aoc command, refer to the Listing the Available FPGA Boards in Your Custom Platform (-list-boards) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
- At a command prompt, navigate to the hello_world design directory containing the hello_world.cl file that you used for emulation.
-
To compile the kernel for your target FPGA board, invoke the
following command:
aoc -v -board=<board_name> device/hello_world.cl -o=bin/hello_world.aocx
This command performs the following tasks:
- Generates the Intel® Quartus® Prime design project files from the OpenCL source code.
- Checks for initial syntax errors.
- Performs basic optimizations.
- Creates a hello_world directory containing necessary intermediate files.
- Creates the Intel® FPGA SDK for OpenCL™ Offline Compiler Object File (.aoco).
- Creates the .aocx file.
Attention:The .aocx file might take hours to build, depending on the complexity of the kernel. To view the progress of the compilation on-screen, include the -v flag in your aoc command. An example output is shown below.
aoc: Environment checks are completed successfully. You are now compiling the full flow!! aoc: Selected target board <board_name> aoc: Running OpenCL parser.... aoc: OpenCL parser completed successfully. aoc: Compiling.... aoc: Linking with IP library ... aoc: First stage compilation completed successfully. aoc: Setting up project for CvP revision flow.... aoc: Hardware generation completed successfully.
The offline compiler displays the line aoc: Hardware generation completed successfully. to signify the completion of the compilation process.
For more information about the -board=<board_name> option of the aoc command, refer to the Compiling a Kernel for a Specific FPGA Board (-board=<board_name>) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
For more information about the -v option of the aoc command, refer to the Generating Compilation Progress Report (-v) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
For more information about the -o <filename> option of the aoc command, refer to the Specifying the Name of an Intel® FPGA SDK for OpenCL™ Offline Compiler Output File (-o=<filename>) section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
Updating the Hardware Image on the FPGA
- If your Custom Platform requires that you preload a valid OpenCL image into the flash memory, for every major release of the Intel Quartus® Prime Design Suite, program the flash memory of the FPGA with a hardware image compatible with the current version of the software.
Querying the Device Name of Your FPGA Board
aocl diagnose: Running diagnostic from INTELFPGAOCLSDKROOT/board/<board_name>/<platform>/libexec Verified that the kernel mode driver is installed on the host machine. Using board package from vendor: <board_vendor_name> Querying information for all supported devices that are installed on the host machine ... device_name Status Information acl0 Passed <descriptive_board_name> PCIe dev_id = <device_ID>, bus:slot.func = 02:00.00, at Gen 2 with 8 lanes. FPGA temperature = 43.0 degrees C. acl1 Passed <descriptive_board_name> PCIe dev_id = <device_ID>, bus:slot.func = 03:00.00, at Gen 2 with 8 lanes. FPGA temperature = 35.0 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 <device_name> DIAGNOSTIC_PASSED
Programming the Flash Memory of an FPGA
Preloading an OpenCL image into the flash memory is necessary for the proper functioning of many Custom Platforms. For example, most PCIe®-based boards require a valid OpenCL image in flash memory so that hardware on the board can use the image to configure the FPGA device when the host system powers up for the first time. If the FPGA is not configured with a valid OpenCL image, the system will fail to enumerate the PCIe endpoint, or the driver will not function.
Before running any designs, ensure that the flash memory of your board has a valid OpenCL image that is compatible with the current OpenCL software version. Consult your board vendor's documentation for board-specific requirements.
To load your hardware configuration file into the flash memory of your FPGA board, perform the following tasks:
- Install any drivers or utilities that your Custom Platform requires.
-
Download a design example for your Custom Platform.
Remember: Download design examples from the OpenCL Design Examples page, and extract the example to a location to which you have write access. Ensure that the location name does not contain spaces.
- To load the hardware configuration file into the flash memory, invoke the aocl flash <device_name> <design_example_filename>.aocx command, where <device_name> refers to the acl number (e.g. acl0 to acl31) that corresponds to your FPGA device, and <design_example_filename>.aocx is the hardware configuration file you create from the <design_example_filename>.cl file in the example design package.
-
Power down your
device or computer and then power it up again.
Power cycling ensures that the FPGA configuration device retrieves the hardware configuration file from the flash memory and configures it into the FPGA.Warning: Some Custom Platforms require you to power cycle the entire host system after programming the flash memory. For example, PCIe-based Custom Platforms might require a host system restart to reenumerate the PCIe endpoint. Intel® recommends that you power cycle the complete host system after programming the flash memory.
Executing an OpenCL Kernel on an FPGA
Running the Host Application
- Add the path $INTELFPGAOCLSDKROOT/host/linux64/lib to the LD_LIBRARY_PATH environment variable.
- At a command prompt, navigate to the host executable within the <path_to_exm_opencl_hello_world_x64_linux_<version>>/hello_world/bin directory.
-
Invoke the
hello_world
executable.
The hello_world executable executes the kernel code on the FPGA.
Output from Successful Kernel Execution
Example output:
Reprogramming device [0] with handle 1 Querying platform for info: ========================== CL_PLATFORM_NAME = Intel(R) FPGA SDK for OpenCL(TM) CL_PLATFORM_VENDOR = Intel Corporation CL_PLATFORM_VERSION = OpenCL 1.0 Intel(R) FPGA SDK for OpenCL(TM), <version> Querying device for info: ======================== CL_DEVICE_NAME = <board name> : <descriptive board name> CL_DEVICE_VENDOR = <board vendor name> CL_DEVICE_VENDOR_ID = <board vendor ID> CL_DEVICE_VERSION = OpenCL 1.0 Intel(R) FPGA SDK for OpenCL(TM), <version> CL_DRIVER_VERSION = <version> CL_DEVICE_ADDRESS_BITS = 64 CL_DEVICE_AVAILABLE = true CL_DEVICE_ENDIAN_LITTLE = true CL_DEVICE_GLOBAL_MEM_CACHE_SIZE = 32768 CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE = 0 CL_DEVICE_GLOBAL_MEM_SIZE = 8589934592 CL_DEVICE_IMAGE_SUPPORT = true CL_DEVICE_LOCAL_MEM_SIZE = 16384 CL_DEVICE_MAX_CLOCK_FREQUENCY = 1000 CL_DEVICE_MAX_COMPUTE_UNITS = 1 CL_DEVICE_MAX_CONSTANT_ARGS = 8 CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE = 2147483648 CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS = 3 CL_DEVICE_MEM_BASE_ADDR_ALIGN = 8192 CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE = 1024 CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR = 4 CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT = 2 CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT = 1 CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE = 0 Command queue out of order? = false Command queue profiling enabled? = true Using AOCX: hello_world.aocx Kernel initialization is complete. Launching the kernel... Thread #2: Hello from the Intel(R) FPGA OpenCL(TM) compiler! Kernel execution is complete.
Uninstalling the Software
-
Remove the software package by performing one of the following
tasks:
- To uninstall the SDK, run the aocl-<version>-uninstall.run program located in the <install directory>/uninstall directory of the Intel® Quartus® Prime Standard Edition software.
- Remove $INTELFPGAOCLSDKROOT/bin from the PATH environment variable.
- Remove $INTELFPGAOCLSDKROOT/host/linux64/lib from the LD_LIBRARY_PATH environment variable.
- Remove the INTELFPGAOCLSDKROOT environment variable.
- Remove the QUARTUS_ROOTDIR_OVERRIDE environment variable.
Uninstalling the FPGA Board
To uninstall your FPGA board, perform the following tasks:
- Disconnect the board from your machine by following the instructions provided by your board vendor.
- Invoke the aocl uninstall <path_to_customplatform> utility command to remove the current host computer drivers (for example, PCIe® drivers). The Intel® FPGA SDK for OpenCL™ uses these drivers to communicate with the FPGA board.
- Uninstall the Custom Platform.
- Unset the LD_LIBRARY_PATH environment variable.
Document Revision History for Intel FPGA SDK for OpenCL Standard Edition Getting Started Guide
Document Version | Intel® Quartus® Prime Version | Changes |
---|---|---|
2018.09.24 | 18.1 |
|
2018.05.04 | 18.0 |
|
Date | Version | Changes |
---|---|---|
December 2017 | 2017.12.08 |
|
November 2017 | 2017.11.06 |
|
May 2017 | 2017.05.05 |
|
October 2016 | 2016.10.31 |
|
May 2016 | 2016.05.02 |
|
November 2015 | 2015.11.02 |
|
May 2015 | 15.0.0 |
|
December 2014 | 14.1.0 |
|
June 2014 | 14.0.0 |
|
December 2013 | 13.1.1 |
|
November 2013 | 13.1.0 |
|
June 2013 | 13.0 SP1.0 |
|
May 2013 | 13.0.1 |
|
May 2013 | 13.0.0 |
|
November 2012 | 12.1.0 | Initial release. |