Intel® FPGA SDK for OpenCL™ Pro Edition: Getting Started Guide

Download PDF
ID 683188
Date 3/28/2022
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. Intel® FPGA SDK for OpenCL™ Pro Edition Getting Started Guide 2. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Windows 3. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Linux 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
1. Intel® FPGA SDK for OpenCL™ Pro Edition Getting Started Guide x
1.1. Prerequisites for the Intel® FPGA SDK for OpenCL™ Pro Edition 1.2. Intel® FPGA SDK for OpenCL™ Pro Edition and OpenCL BSP Backwards Compatibility 1.3. Contents of the Intel® FPGA SDK for OpenCL™ Pro Edition 1.4. Overview of the Intel® FPGA SDK for OpenCL™ Pro Edition Setup Process
1.1. Prerequisites for the Intel® FPGA SDK for OpenCL™ Pro Edition x
1.1.1. GCC Requirement Installing GCC 7 Verifying Your GCC Installation
2. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Windows x
2.1. Downloading the Intel® FPGA SDK for OpenCL™ Pro Edition 2.2. Installing the Intel® FPGA SDK for OpenCL™ Pro Edition 2.3. Setting the Intel® FPGA SDK for OpenCL™ Pro Edition User Environment Variables 2.4. Verifying Software Installation 2.5. Installing an FPGA Board 2.6. Verifying Host Runtime Functionality via Emulation 2.7. Creating the FPGA Hardware Configuration File of an OpenCL Kernel 2.8. Updating the Hardware Image on the FPGA 2.9. Executing an OpenCL Kernel on an FPGA 2.10. Uninstalling an FPGA Board 2.11. Uninstalling the Software
2.5. Installing an FPGA Board x
2.5.1. Enabling Backwards Compatibility for an FPGA Board
2.6. Verifying Host Runtime Functionality via Emulation x
2.6.1. Accessing an OpenCL Design Example 2.6.2. Compiling a Kernel for Emulation 2.6.3. Building the Host Application 2.6.4. Emulating Your OpenCL Kernel
2.8. Updating the Hardware Image on the FPGA x
2.8.1. Querying the Device Name of Your FPGA Board 2.8.2. Programming the Flash Memory of an FPGA
2.9. Executing an OpenCL Kernel on an FPGA x
2.9.1. Running the Host Application 2.9.2. Output from Successful Kernel Execution
3. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Linux x
3.1. Downloading the Intel® FPGA SDK for OpenCL™ Pro Edition 3.2. Installing the Intel® FPGA SDK for OpenCL™ Pro Edition 3.3. Setting the Intel® FPGA SDK for OpenCL™ Pro Edition User Environment Variables 3.4. Verifying Software Installation 3.5. Installing an FPGA Board 3.6. Verifying Host Runtime Functionality via Emulation 3.7. Creating the FPGA Hardware Configuration File of an OpenCL Kernel 3.8. Updating the Hardware Image on the FPGA 3.9. Executing an OpenCL Kernel on an FPGA 3.10. Uninstalling an FPGA Board 3.11. Uninstalling the Software
3.5. Installing an FPGA Board x
3.5.1. Enabling Backwards Compatibility for an FPGA Board
3.6. Verifying Host Runtime Functionality via Emulation x
3.6.1. Accessing an OpenCL Design Example 3.6.2. Compiling a Kernel for Emulation 3.6.3. Building the Host Application 3.6.4. Emulating Your OpenCL Kernel
3.8. Updating the Hardware Image on the FPGA x
3.8.1. Querying the Device Name of Your FPGA Board 3.8.2. Programming the Flash Memory of an FPGA
3.9. Executing an OpenCL Kernel on an FPGA x
3.9.1. Running the Host Application 3.9.2. Output from Successful Kernel Execution
1. Intel® FPGA SDK for OpenCL™ Pro Edition Getting Started Guide
2. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Windows
3. Getting Started with the Intel® FPGA SDK for OpenCL™ Pro Edition for Linux
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

1.1.1. GCC Requirement

For Linux host systems, the Intel® FPGA Emulation Platform for OpenCL™ software requires that you have at least GCC 7.2.0 on your system. GCC 7.2.0 provides the libstdc++.so.6 shared library. Newer versions may work as well. Specifically, libstdc++.so.6.0.24 library or later is required that defines GLIBCXX_3.4.24 and CXXABI_1.3.11 symbol versions.

If you do not have a sufficiently new GCC and libstdc++.so.6 library installed, you may encounter issues when trying to run OpenCL host programs that target the Intel® FPGA 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 to load the emulation platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code -1001). Depending on the version of libstdc++.so library found, the call to clGetPlatformIDs function may succeed, but a later call to the clCreateContext function 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 7.2.0 or greater. If you do not have a sufficiently recent GCC, use the following instructions to install a newer GCC on your system.

Installing GCC 7

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

Ubuntu*

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

$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test 
$ sudo apt-get update 
$ sudo apt-get install gcc-7 g++-7
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \  
--slave /usr/bin/g++ g++ /usr/bin/g++-7 
$ sudo update-alternatives --config gcc
Note: Ensure that you select gcc-7 for the sudo update-alternatives command. The update-alternatives utility can be used to swap between GCC versions as required.
CentOS and Red Hat Enterprise Linux* Version 7
Note: Unfortunately, installing the Developer Toolset* (for example, devtoolset-7), does not provide the desired result because it does not include a newer libstdc++.so.6 library. The Developer Toolset* provides a custom version of the GCC that uses the older libstdc++.so.6 library originally installed on the system.

For CentOS and Red Hat Enterprise Linux version 7, Intel® recommends that you compile GCC from source and install it using the following instructions:

  1. Download the tarball of the GCC version you want to install. 
    wget http://www.netgull.com/gcc/releases/gcc-7.2.0/gcc-7.2.0.tar.gz
  2. Unpack the tar archive and change the current working directory.
    tar zxf gcc-7.2.0.tar.gz
cd gcc-7.2.0
  3. Install the bzip2 package.
    yum -y install bzip2
  4. Run the download_prerequisites script to download some prerequisites required by the GCC.
    Note: You must run the script from the top-level of the GCC source tree. 
    ./contrib/download_prerequisites
  5. Once the prerequisites are downloaded, execute the following command to start configuring the GCC build environment:
    ./configure --disable-multilib --enable-languages=c,c++
  6. Run the following command to compile the source code. Compilation may take a few hours to complete.
    make -j 4
make install
  7. Refer to Verifying Your GCC Installation section for instructions to verify if your GCC installation was successful.

SUSE Enterprise Linux* 12

For SUSE, Intel® recommends that you compile GCC from source and install it by following the instructions provided for CentOS and Red Hat Enterprise Linux.

Verifying Your GCC Installation

To verify your GCC installation, ensure the following:

  • Shell can find the correct GCC binaries.
  • The newer GCC is using correct shared libraries (in particular, libstdc++.so.6).

This depends on how you installed the GCC and set the $PATH and $LD_LIBRARY_PATH environment variables. You might have installed the GCC binaries 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
  2. Ensure the output points to the correct GCC. 
    $ gcc –dumpversion
  3. Ensure GCC reports a version of 7.2.0 or higher.

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

For Ubuntu, the default install location for GCC binaries is /usr/bin; and libraries is /usr/lib64. However, binaries are versioned (for example, gcc-7). Use the update-alternatives utility to ensure gcc is a symbolic link to the desired GCC version. On Ubuntu systems, the $PATH and $LD_LIBRARY_PATH environment variables need not be updated because the shell and dynamic linker should automatically 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 environment setup script so that the development environment is automatically set up when you enter it. 

$ export PATH=</path/to/new/gcc>/bin:$PATH
To verify that your $PATH environment variable has been modified appropriately, use the 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 links against the correct libstdc++.so.6 library version by using the following steps: 

$ echo "int main() { return 0; }" > test.cpp 
$ g++ -Wl,--no-as-needed test.cpp -o test 
$ ldd test 
        linux-vdso.so.1 =>  (0x00007fff6df35000) 
        libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x0000003451600000) 
        libm.so.6 => /lib64/libm.so.6 (0x0000003446a00000) 
        libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x000000344d600000) 
        libc.so.6 => /lib64/libc.so.6 (0x0000003446600000) 
        /lib64/ld-linux-x86-64.so.2 (0x000055ff56398000) 
$ strings /usr/lib64/libstdc++.so.6 | grep GLIBCXX_3.4.24 
GLIBCXX_3.4.24

Use the output from the ldd command to determine the path to the libstdc++.so.6 library that you need to use with the strings command (see highlighted strings; your output may be different). Ensure that the strings command returns GLIBCXX_3.4.24.

Alternatively, the libstdc++.so.6 file is often a symbolic link to the actual library, which has the version number appended. Therefore, instead of calling the strings command on libstdc++.so.6 library, you can use the following readlink command to verify libstdc++.so.6 points to a sufficiently new version of libstdc++: 

$ readlink /usr/lib64/libstdc++.so.6 
libstdc++.so.6.0.24

Use the output from the ldd command (executed earlier) to determine the path to libstdc++.so.6 that you need to use with the readlink command. Ensure that readlink command reports that your libstdc++.so.6 is a symbolic link to libstdc++.so.6.0.24. Versions newer than 6.0.24 may also work.

If the above commands do not report the correct shared libraries are being used, you might need to modify your $LD_LIBRARY_PATH environment variable to point to the location of the newly installed GCC libraries.

Tip:

You can place the following command in your shell startup script or an environment setup script so that the development environment is automatically set up when you enter it. 

$ export LD_LIBRARY_PATH=</path/to/new/gcc>/lib64:$LD_LIBRARY_PATH

To verify that your $LD_LIBRARY_PATH environment variable has been modified appropriately, run the following command: 

$ echo $LD_LIBRARY_PATH

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

Level Two Title