Debugging Applications and Kernels

The SDAccel™ environment provides application-level debug features and techniques that allow the host code, kernel code, and the interactions between them to be debugged. These features and techniques are split between software-centric and more detailed low-level hardware centric flows.

In addition, for hardware-centric debugging, designs running on hardware can be debugged with both PCIe® using Xilinx® virtual cable (XVC) and JTAG using USB-JTAG cables without changing the design.

Debugging Features and Techniques

There are several features and techniques that you can use to debug your design. The following table lists the features or techniques that can be used for debugging in the three build configurations. Each feature and technique is described in more detail in the SDAccel Environment Debugging Guide.

Table 1. Features and Techniques for Debugging Different Build Configurations
Feature/Technique	OS	Host	Kernel	FPGA (Platform)
Software Emulation	dmesg	GDB	GDB	xbutil
Hardware Emulation	dmesg	GDB	GDB Kernel Waveform Viewer	xbutil
System	dmesg	GDB	Kernel Waveform Viewer ILA	xbutil
dmesg is a Linux command. GDB is the GNU Debugger. xbutil is a Xilinx provided utility.

These features and techniques can be divided into software and hardware-centric debugging features as shown in the following table.

Table 2. Software and Hardware Debugging Features and Techniques
Software-centric	Hardware-centric
GNU Debugger (GDB)	Kernel waveform viewer
Xilinx utility `xbutil`	Integrated Logic Analyzer (ILA)
Linux `dmesg`	N/A

Using both software-centric, and hardware-centric debugging features, you can isolate and identify functional issues, protocol problems, as well as troubleshoot board hangs.

Debugging Flows

The recommended application-level debugging flow consists of three levels of debugging:

Perform software emulation (sw_emu) to confirm the algorithm functionality.
Perform hardware emulation (hw_emu) to create custom hardware and confirm the correctness of the logic generated and performance on FPGAs.
Perform a System build (hardware) hw to implement the custom hardware.

Each provides specific insights into the design and makes debugging easier. All flows are supported through an integrated GUI flow as well as through a batch flow using basic compile time and runtime setup options. A brief description of each flow follows.

Software Emulation

Software emulation can be used to validate functional correctness of the host and kernel (written in C/C++ or OpenCL™). The GDB can be used to debug both the host and kernel code. It is recommended to iterate in Software Emulation, which takes little compile time and executes quickly, until the application is functioning correctly in all modes of operation.

Hardware Emulation

Hardware Emulation can be used to validate the host code, profile host and kernel performance, give estimated FPGA resource usage as well as verify the kernel using an accurate model of the hardware (RTL). The execution time for hardware emulation takes more time than software emulation; thus Xilinx recommends that you use small data sets for debug and validation. Again, the GDB can be used to debug the host and kernels. Iterate in Hardware Emulation until the estimated kernel performance is sufficient (see the SDAccel Environment Profiling and Optimization Guide for optimization details).

System

Finally, in hardware execution (System) the complete system is validated on actual hardware to ensure kernels are executing correctly and system performance is met. SDAccel provides specific hardware debug capabilities which include waveform analysis, kernel activity reports, and memory access analysis to isolate these critical hardware issues. Hardware debugging requires additional logic to be incorporated into the overall hardware model and will impact FPGA resources and performance. This additional logic can be removed in the final compilation.

GNU Debugging

For the GNU debugging (GDB), you can add breakpoints, inspect variables, and debug the kernel or host code. This familiar software debug flow allows quick debugging to validate the functionality. SDAccel also provides special GDB extensions to examine the content of the OpenCL runtime environment from the application host. These can be used to debug protocol synchronization issues between the host and the kernel.

The SDAccel environment supports GDB host program debugging in all flows, but kernel debugging is limited to software and hardware emulation flows. Debugging information needs to be generated first in the binary container by passing the -g option to the xocc command line executable or enabled by setting the appropriate box in the GUI options.

In software and hardware emulation flows, there are restrictions with respect to the accelerated kernel code debug interactions. Because this code is preprocessed in the software emulation flow and translated into a hardware description language (HDL) in the hardware emulation flow, it is not always possible to set breakpoints at all locations especially in hardware emulation.

For more details, see the SDAccel Environment Debugging Guide.

Linux “dmesg”

Debugging hangs in the system can be difficult; however, SDAccel provides a method to debug the interaction with Linux and the hardware platform using the dmesg Linux command.

When the software or hardware appears to lock up, you can use the dmesg command to print a record of the transactions and kernel information messages. The detailed report can help to isolate and resolve the issue.

Kernel Waveform Viewer

SDAccel provides waveform-based HDL debugging through the GUI flow in hardware emulation mode. The waveform is opened in the Vivado® waveform viewer which should be familiar to Vivado users. It allows you to display kernel interface and internal signals and includes debug controls such as restart, HDL breakpoints, as well as HDL code lookup and waveform markers. In addition, it provides top-level DDR data transfers (per bank) along with kernel-specific details including compute unit stalls, loop pipeline activity, and data transfers.

For details, see the SDAccel Environment Profiling and Optimization Guide.

ILA

SDAccel provides insertion of the system integrated logic analyzers (ILA) into a design to capture and view AXI transaction level activity using the interface signals between the kernel and global memory. The ILA provides, for example, custom event triggering on one or more signals to allow waveform capture at system speeds. The waveforms can be analyzed in a viewer and used to debug hardware such as protocol violations or performance issues and can be crucial for debugging difficult situation like application hangs. This low-level, hardware-centric debug technique should be familiar to Vivado users. See the Vivado Design Suite User Guide: Programming and Debugging (UG908) for complete details.

Note: The ILA core requires system resources, including logic and local memory to capture and store the signal data.

System ILAs can be inserted into the design using xocc command with -–dk options.

For example,

$ xocc --dk chipscope:<compute_unit_name>:<interface_name>

Captured data can be accessed through the Xilinx Virtual Cable (XVC) using the Vivado tools.