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

ID 683342
Date 4/22/2019
Public
Document Table of Contents

8.4. 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.
Prior to debugging your kernel, you must perform the following tasks:
  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 kernel is loaded as a shared library immediately before the host loads the kernels. The debugger does not recognize the kernel names until the host actually loads the kernel functions. As a result, the debugger will generate 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 will recognize the function and variable names, and line number references for the duration of the session.

CAUTION:
The Emulator uses the OpenCL runtime to report some error details. For emulation, the runtime uses a default print out callback when you initialize a context via the clCreateContext function.
Note: Kernel debugging is independent of host debugging. Debug your host code in existing tools such as Microsoft Visual Studio Debugger for Windows and GDB for Linux.

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

  1. To generate a .aocx file for debugging that targets a specific accelerator board, invoke the aoc -march=emulator <your_kernel_filename>.cl -board=<board_name> command.
    Attention: Specify the name of your FPGA board when you run your host application. To verify the name of the target board for which you compile your kernel, invoke the aoc -march=emulator -v <your_kernel_filename>.cl command. The Intel® FPGA SDK for OpenCL™ Offline Compiler will display the name of the target FPGA board.
  2. Run the utility command aocl linkflags to find out the additional libraries necessary to build a host application that supports kernel debugging.
  3. Build a host application and link it to the libraries from Step 2.
  4. Ensure that the <your_kernel_filename>.aocx file is in a location where the host can find it, preferably the current working directory.
  5. To run the application, invoke the command env CL_CONTEXT_EMULATOR_DEVICE_INTELFPGA=<number_of_devices> gdb --args <your_host_program_name> , where <number_of_devices> is the number of identical emulation devices that the Emulator needs to provide.
  6. 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 the debugger.