SDSoC Debug Features

Xilinx System Debugger (XSDB) uses the Xilinx hw_server as the underlying debug engine.

The Xilinx Software Development Kit (SDK) translates each user interface action into a sequence of Target Communication Frameworks (TCF) commands. It then processes the output from System Debugger to display the current state of the program being debugged. It communicates to the processor on the hardware using Xilinx hw_server. You can debug multiple processors simultaneously with a single System Debugger debug configuration. This is the recommended debug engine for SDxenvironment designs. The System Debugger can either be launched on the hardware or the QEMU engine.

Graphical development environments such as the SDx environment are useful for improving development for a new processor architecture. It helps to abstract away and group most of the common functions into logical wizards that even a novice can use. However, the scriptability of a tool is also essential for providing the flexibility to extend what is done with that tool. It is particularly useful when developing regression tests that are run nightly, or for running a set of commands that are used often by the developer.

Xilinx Software Command-line Tool (XSCT) is an interactive and scriptable command line interface to the SDx environment. As with other Xilinx tools, the scripting language for XSCT is based on Tool Command Language (Tcl). You can run XSCT commands interactively or script the commands for automation. XSCT supports the following actions:

• Create hardware, board support packages (BSPs), and application projects.
• Manage repositories.
• Set toolchain preferences.
• Configure and build BSPs/applications.
• Download and run applications on hardware targets.
• Create and flash boot images by running Bootgen and program_flash tools.

For information on XSCT commands, see the Xilinx Software Command-Line Tool (XSCT) Reference Guide (UG1208).

System emulation provides the same level of accuracy as the final implementation without the need to compile the system into a bitstream and program the device on the board. System emulation can be used for debugging applications without involving the actual hardware. It can also be used for identifying any bottlenecks in performance.

# FPGA Board Platform (Default ~ zcu102)
PLATFORM := zcu102

# Run Target:
#   hw  - Compile for hardware
#   emu - Compile for emulation (Default)
TARGET := emu

# Target OS:
#     linux (Default), standalone
TARGET_OS := linux

# Emulation Mode:
#     debug     - Include debug data
#     optimized - Exclude debug data (Default)
EMU_MODE := optimized

Type make to build the program at the command prompt. If you want to view the waveform in the simulator, change directory to the level where you have the _sds directory, then type sdsoc_emulator -graphic-xsim. This starts the Vivado Simulator, as shown below.

After the final system image is generated and executed in the SDx environment, the entire system (including the embedded processor OS, the application code, and the accelerated hardware functions) can be validated to be executing correctly on the actual hardware, and any necessary debug activity can be performed. The ChipScope™ feature is used to debug designs in hardware using the Vivado IDE. Cross-probing hardware and software requires an advanced understanding of the SDx environment and the Vivado tool suite.

This debugging step can reveal issues relating to connecting to the target platform, booting the processor, and programming the hardware with the system image. It might also highlight problems with interactions between the application code and the hardware functions in the form of protocol violations, and with validating multiple hardware functions with the application code.

This step could also reveal system performance metrics that could shift your focus from debug to performance tuning. In the SDx environment, you can instrument the hardware to analyze transactions on the interfaces of the hardware accelerators and adapters. You can also debug the hardware portion of the design.

The system compiler implements hardware functions either by cross-compiling them into IP using the Vivado High-Level Synthesis (HLS) tool, or by linking them as C-callable IP, as described in the SDSoC Environment Platform Development Guide.

Each hardware function call site is rewritten to call a stub function that manages the execution of the hardware accelerator. The figure below shows an example of hardware function rewriting. The original user code is shown on the left. The code section on the right shows the hardware function calls rewritten with new function names.

Figure: Hardware Function Call Site Rewriting

The stub function initializes the hardware accelerator, initiates any required data transfers for the function arguments, and then synchronizes hardware and software by waiting at an appropriate point in the program for the accelerator and all associated data transfers to complete. For example, if the hardware function foo() is defined in foo.cpp, you can view the generated rewritten code in _sds/swstubs/foo.cpp for the project build configuration. As an example, the stub code shown below replaces a user function marked for hardware. This function starts the accelerator, starts data transfers to and from the accelerator, and waits for those transfers to complete.

void _p0_mmult0(float *A, float *B, float *C) {
   switch_to_next_partition(0);
   int start_seq[3];
   start_seq[0] = 0x00000f00;
   start_seq[1] = 0x00010100;
   start_seq[2] = 0x00020000;  
   cf_send_i(cmd_addr,start_seq,cmd_handle);
   cf_wait(cmd_handle);
   cf_send_i(A_addr, A, A_handle);
   cf_send_i(B_addr, B, B_handle);
   cf_receive_i(C_addr, C, C_handle);
   cf_wait(A_handle);
   cf_wait(B_handle);
   cf_wait(C_handle);

Event tracing provides visibility into each phase of the hardware function execution, including the software setup for the accelerators and data transfers, as well as the hardware execution of the accelerators and data transfers. For example, the stub code below is instrumented for trace. Each command that starts the accelerator, starts a transfer, or waits for a transfer to complete is instrumented.

void_p0_mmult_0(float *A, float *B, float *C) {
   switch_to_next_partition(0);
   int start_seq[3];
   start_seq[0] = 0x00000f00;
   start_seq[1] = 0x00010100;
   start_seq[2] = 0x00020000;
   sds_trace(EVENT_START);  
   cf_send_i(cmd_addr,start_seq,cmd_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_wait(cmd_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_send_i(A_addr, A, A_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_send_i(B_addr, B, B_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_receive_i(C_addr, C, C_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_wait(A_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_wait(B_handle);
   sds_trace(EVENT_STOP);
   sds_trace(EVENT_START);
   cf_wait(C_handle);
   sds_trace(EVENT_STOP);

Event tracing automatically instruments the stub function to capture software control events associated with the implementation of a hardware function call. The event types include the following:

• Accelerator setup and initiation
• Data transfer setup
• Hardware/software synchronization barriers (“wait for event”)

See SDSoC Environment Programmers Guide (UG1278) for more detail on these topics.

Each of these events is independently traced and results in a single AXI4-Lite write into the programmable logic, where it receives a time stamp from the same global timer as hardware events.

The SDSoC environment supports hardware event tracing of accelerators cross-compiled using Vivado High-Level Synthesis (HLS) tool, and data transfers over AXI4-Stream connections. When sds++ is invoked with the -trace option, it automatically inserts hardware monitor IP cores into the generated system to log the following event types:

• Accelerator start and stop, defined by ap_start and ap_done signals.
• Data transfer start and stop, defined by AXI4-Stream handshake and TLAST signals.

#pragma HLS interface s_axilite port=foo

These debug cores use some hardware resources; less than 0.1% of the hardware resources available on a ZC706 board.

The AXI4-Stream monitor core has two modes: basic and statistics. The basic mode does just the start/stop trace event generation. The statistics mode enables an AXI4-Lite interface to two 32-bit registers. The register at offset 0x0 presents the word count of the current, on-going transfer. The register at offset 0x4 presents the word count of the previous transfer. As soon as a transfer is complete, the current count is moved to the previous register. By default, the AXI4-Stream core is configured in the basic mode.

In addition to the hardware trace monitor cores, the output trace event signals are combined by a single integration core. This core has a parameterizable number of ports (from 1–63), and can thus support up to 63 individual monitor cores (either accelerator or AXI4-Stream). The resource utilization of this core depends on the number of ports enabled, and thus the number of monitor cores inserted.

On a ZC706 platform, this can use between roughly 0.1-1.0 percent of the available hardware resources, and up to approximately 10% of the memories with the integration logic.

During the implementation flow, when tracing is enabled, tracing instrumentation is inserted into the software code and hardware monitors are inserted into the hardware system automatically. The hardware system (including the monitor cores) is then synthesized and implemented, producing the bitstream. The software tracing is compiled into the regular user program.

Hardware and software traces are time-stamped in hardware and collected into a single trace stream that is buffered up in the programmable logic.