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

ID 683846
Date 9/26/2022

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

Document Table of Contents

8.5. Debugging Your OpenCL Kernel on Linux

For Linux systems, you can direct the Intel® FPGA SDK for OpenCL™ Emulator to run your OpenCL kernel in the debugger and debug it functionally as part of the host application. The debugging feature allows you to debug the host and the kernel seamlessly. You can step through your code, set breakpoints, and examine and set variables.

To compile your OpenCL kernel for debugging, perform the following steps:

  1. To generate an emulator .aocx file for debugging, invoke the aoc -march=emulator <your_kernel_filename>.cl command.
  2. Build the host application and link your host application to the Khronos ICD Loader Library. For details, see Linking Your Host Application to the Khronos ICD Loader Library.
  3. Ensure that the <your_kernel_filename>.aocx file is in a location where the host expects to find it.
  4. To run the application, invoke the command env CL_CONFIG_CPU_EMULATE_DEVICES=<number_of_devices> gdb --args <your_host_program_name> [<host_program_arguments>], where <number_of_devices> is the number of identical emulation devices that the Emulator needs to provide.
    Note: You can omit the CL_CONFIG_CPU_EMULATE_DEVICES environment variable if you only want to emulate a single device.
  5. If you make changes to only your host application, recompile only the host before restarting the debugger. Similarly, if you make changes to only your kernel code, recompile only the kernel code before restarting the debugger.
To run your kernel in the debugger:
  1. During program execution, the debugger cannot step from the host code to the kernel code. You must set a breakpoint before the actual kernel invocation by adding these lines:
    1. break <your_kernel>

      This line sets a breakpoint before the kernel.

    2. continue

      If you have not begun debugging your host, then type start instead.

  2. The debugger does not recognize kernel names until the host actually loads the kernel functions. As a result, the debugger generates the following warning for the breakpoint you set before the execution of the first kernel:

    Function "<your_kernel>" not defined.

    Make breakpoint pending on future shared library load? (y or [n])

    Answer y. After initial program execution, the debugger recognizes the function and variable names, and line number references for the duration of the session.

Note: When debugging kernel code with the FPGA emulator, the debugger may display some source lines out of order for certain code patterns. Currently, there is no known workaround for this issue.