SDAccel Debug Command Line Flow

The Application Debug feature in the SDAccel™ Environment provides tools to debug the OpenCL® application running in all modes: Software Emulation, Hardware Emulation, or Hardware. It is referred to as Application Debug because it mainly deals with debugging on the host side, including the associated OpenCL APIs, and is in contrast to pure Kernel Debug which involves debugging OpenCL kernels (such as the accelerated portion).

There are four steps to application debugging in SDAccel using the command line flow:

  1. General Environment Setup
  2. Prepare the Host Code for Debug
  3. Prepare Kernel Code for Debug
  4. Launch GDB Standalone to Debug
    IMPORTANT!: the SDAccel Environment supports host program debugging in all flows, but kernel debugging is only supported in the emulation flows with gdb. In addition, more hardware centric debugging support such as waveform analysis is provided for the kernels.

General Environment Setup

To run software emulation or hardware emulation from the command line, you must set the following environment variables:

Table 1. Environment Variables and Values
Environment Variable Value
XCL_EMULATION_MODE sw_emu or hw_emu
XILINX_SDX The path to the installed SDx.
XILINX_OPENCL The path to the installed SDx (same as ${XILINX_SDX}).
LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${XILINX_SDX}/lib/lnx64.o:${XILINX_SDX}/ runtime/lib/x86_64:${XILINX_SDX}/lib/lnx64.o/Default
Note: When using DSA 4.x or earlier, Software and Hardware Emulation require that you 4.x DSA libraries be prefixed to the LD_LIBRARY_PATH

Preparing the Host Code

The host program needs to be compiled with debugging information generated in the executable by adding the -g option to the xcpp command line option, as follows:

xcpp -g ...
TIP: Because xcpp is simply a wrapper around the system compiler (gcc), the -g option enables the compiler to generate debug information.

Preparing the Kernel

Kernel code can be debugged together with the host program in either software emulation or hardware emulation. Debugging information needs to be generated first in the binary container by passing the -g option to the xocc command line executable:

xocc -g -t [sw_emu | hw_emu] ...

The –t option is used to specify software emulation (sw_emu) or hardware emulation (hw_emu).

In the software emulation flow, additional runtime checks can be performed for OpenCL based kernels. The runtime checks include:
  • Checking out-of-bound access made by kernel interface buffers (option: address)
  • Checking uninitialized memory access initiated by kernel local to kernel (option: memory)
The options are enabled through the -–xp option and need to be enabled during the link stage (-l) as shown in the following examples:
xocc -l –t sw_emu --xp param:compiler.fsanitize=address -o bin_kernel.xclbin
xocc -l –t sw_emu --xp param:compiler.fsanitize=memory -o bin_kernel.xclbin
xocc -l –t sw_emu --xp param:compiler.fsanitize=address,memory -o bin_kernel.xclbin

Once applied, the software emulation run produces a debug log with emulation diagnostic messages at <project_dir>/Emulation-SW/<proj_name>-Default>/emulation_debug.log .

Launching GDB

You can launch GDB standalone to debug the application if the host program and kernel were built with debug information (built with the -g flag). This flow should also work while using a graphical front-end for GDB, such as ddd.

Below are the instructions for launching GDB:
  1. To set up the environment to run SDx, source the file below so that SDx command settings are in the PATH:
    • C Shell: source <SDX_INSTALL_DIR>/settings64.csh
    • Bash: source <SDX_INSTALL_DIR>/settings64.sh
  2. Ensure that the environment variable XCL_EMULATION_MODE is set.
  3. The application debug feature must be enabled at run time using an attribute in the sdaccel.ini file. Create an sdaccel.ini file in the same directory as your host executable, and include the following lines:
    [Debug]
app_debug=true
profile=true
  4. Start gdb through the Xilinx® wrapper: xgdb – args host.exe test.xclbin
    The xgdb wrapper performs the following setup steps under the hood:
    • Launches GDB on the host program: gdb --args host.exe test.xclbin
    • Setup of the environment variables PYTHONHOME and PYTHONPATH to Python installation. Currently, the gdb in SDx expects Python 2.6 or Python 2.7. For example, if the Python available on the machine is Python 2.6 then set the environment as shown (Bash shell shown): 
      export PYTHONHOME=/usr 
export PYTHONPATH=/usr/lib64/python2.6/:/usr/lib64/python2.6/lib-dynload/
    • Sources the python script in the GDB console to enable the Xilinx GDB extensions:
      gdb> source ${XILINX_SDX}/scripts/appdebug.py