Intel® FPGA SDK for OpenCL™ Pro Edition: Programming Guide

ID 683846
Date 10/04/2021

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

Document Table of Contents

8.4. Emulating Your OpenCL Kernel

To emulate your OpenCL™ kernel, run the emulation .aocx file on the platform on which you built your kernel. The OpenCL Emulator uses a different OpenCL platform than when targeting FPGA hardware.

To emulate your kernel, perform the following steps:

  1. Required: Modify your host program to select the emulator OpenCL platform.
    Select the emulation OpenCL platform in your host program by selecting platform with the following name:
    Intel(R) FPGA Emulation Platform for OpenCL(TM)
  2. Required: Build a host application and link your host application to the Khronos ICD Loader Library. For more information, see Linking Your Host Application to the Khronos ICD Loader Library.
  3. If necessary, move the <your_kernel_filename>.aocx file to a location where the host can find it easily, preferably the current working directory.
  4. To run the host application for emulation:
    • For Windows:
      1. Define the number of emulated devices by invoking the set CL_CONFIG_CPU_EMULATE_DEVICES=<number_of_devices> command.
      2. Run the host application.
      3. Invoke set CL_CONFIG_CPU_EMULATE_DEVICES= to unset the variable.
    • For Linux, invoke the env CL_CONFIG_CPU_EMULATE_DEVICES=<number_of_devices> <host_application_filename> command.
    This command specifies the number of identical emulation devices that the Emulator needs to provide.
    Remember: The emulation OpenCL platform (Intel(R) FPGA Emulation Platform for OpenCL(TM)) does not provide access to physical boards. Only the emulated devices are available.
    Tip: If you want to use only one emulator device, you do not need to set the CL_CONFIG_CPU_EMULATE_DEVICES environment variable.
  5. If you change your host or kernel program and you want to test it, only recompile the modified host or kernel program and then rerun emulation.
  • The emulator in Intel® FPGA SDK for OpenCL™ Pro Edition is built with GCC 7.2.0 as part of the offline compiler. When executing the host program for an emulated OpenCL device, the version of must be at least that of GCC 7.2.0. In other words, the LD_LIBRARY_PATH environment variable must ensure that the correct version of is found.

    If the correct version of is not found, the call to clGetPlatformIDs function fails to load the FPGA emulator platform and returns CL_PLATFORM_NOT_FOUND_KHR (error code -1001). Depending on which version of is found, the call to clGetPlatformIDs may succeed, but a later call to the clCreateContext function may fail with CL_DEVICE_NOT_AVAILABLE (error code -2).

    If LD_LIBRARY_PATH does not point to a sufficiently new, use the following syntax to invoke the host program:

    env LD_LIBRARY_PATH=<path to sufficiently new>:$LD_LIBRARY_PATH <host> [host arguments]
  • To enable debugging of kernel code, optimizations are disabled by default for the FPGA emulator. This can lead to sub-optimal execution speed when emulating kernel code.

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