Vitis: Debugging During Hardware Execution (How to chipscope)

If you are experiencing issues, which are only happening during hardware execution, and not during simulation, looking into the hardware may be the only option to find out what is going wrong.

For using chipscope to look into your hardware designs, you first have to integrate the logic analyzers. Keep in mind that they are consuming resources and can affect timing.
The most common is to look at the interfaces of compute units, which can be configured in the link script of an HLS design. If you have an RTL design, you can also add an IP core, which probes specific signals.

More details on integrating the logic analyzer into your design can be found here:

Enabling Kernels for Debugging with Chipscope

For all full example using a SUS kernel with XRT take a look here:

Using Xilinx' Integrated Logic Analyzer for SUS Designs

You need to modify your host code, so that it waits after loading the bitstream, because only then you can start the debugging server. This can be accomplished with a wait for a specific keypress like in the following example suggested by AMD:

void wait_for_enter(const std::string &msg) {
    std::cout << msg << std::endl;
    std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
}

After loading the bitstream, you need to ssh to the fpga node and start the debug server there. For this the following command is used.

debug_hw --xvc_pcie /dev/xfpga/xvc_pub.<driver_id> --hw_server

The driver ids for the cards on the U280 nodes of noctua2 are the following:

u257.0
u33025.0
u41217.0

The files are only available, when a bitstream is loaded, so when in doubt reset all cards and check which files are there.

For using chipscope, it is highly recommended to use the remote desktop enviroment on the running FPGA node. Follow the VNC guide to achieve this.

vnc

When the debug server is launched and you are you are running a desktop on the FPGA node, use the following command, to start chipscope and connect with the debug server.

debug_hw --vivado --host localhost --ltx_file ./_x/link/vivado/vpl/prj/prj.runs/impl_1/debug_nets.ltx

Just copying the debug_nets.ltx is not enough, because vivado needs more files and also writes some during execution. Because of this, you should work in the original synthesis folder.

A detailed documentation on using chipscope and setting the triggers can be found here:

Connecting to the Hardware Target and Programming the Device