Debugging Applications and Kernels

TheSDAccel™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 bothPCIe®usingXilinx®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 theSDAccel 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
  1. dmesg is a Linux command.
  2. GDB is the GNU Debugger.
  3. xbutil is aXilinxprovided 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
Xilinxutilityxbutil Integrated Logic Analyzer (ILA)
Linuxdmesg 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)hwto 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++ orOpenCL™). 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; thusXilinxrecommends 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 theSDAccel Environment Profiling and Optimization Guidefor 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.SDAccelprovides 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.SDAccelalso provides special GDB extensions to examine the content of theOpenCLruntime environment from the application host. These can be used to debug protocol synchronization issues between the host and the kernel.

TheSDAccelenvironment 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-goption to thexocccommand 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 theSDAccel Environment Debugging Guide.

Linux “dmesg”

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

When the software or hardware appears to lock up, you can use thedmesgcommand 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

SDAccelprovides waveform-based HDL debugging through the GUI flow in hardware emulation mode. The waveform is opened in theVivado®waveform viewer which should be familiar toVivadousers. 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 theSDAccel Environment Profiling and Optimization Guide.

ILA

SDAccelprovides 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 toVivadousers. See theVivado 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 usingxocccommand with-–dkoptions.

For example, 
$ xocc --dk chipscope::

Captured data can be accessed through theXilinxVirtual Cable (XVC) using theVivadotools.