Hardware Debug from the Vitis IDE - Hardware Debug from the Vitis IDE - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English
With the top-level system project built, you can use the following steps to debug the system running in the Hardware platform.
  1. Burn <project>/Hardware/package/sd_card.img to a physical SD card. This creates a boot-able medium for your target platform.
  2. Insert the SD card into the card reader of the VCK190 evaluation kit.
  3. Change the boot-mode settings of the card to SD boot mode, and power up the board.
  4. After booting VCK190, enter the mount command at the command prompt to retrieve a list of mount points. As shown in the following figure, the mount command displays mounting information for the system.
    Tip: Be sure to capture the proper path for the cd command in the next step, and subsequent commands, based on the results of the mount command.


  5. Execute the following commands: 
    cd /run/media/mmcblk0p1
  6. Run ifconfig to get the IP address of the target card. Vitis uses the IP address to set up a TCF agent connection in the Vitis Unified IDE. The target need to connect to the network assigned IP address.
  7. From within the IDE, select or create a target connection to the remote accelerator card as follows.
    1. Select the Vitis > Target Connections command from the main menu to open the Target Connections dialog box.
    2. Select an existing Linux TCF Agent connection. Alternatively, right-click Linux TCF Agent and select the New Target command to open the New Target Connection dialog box.

    3. Specify the Target Name and enable the Set as default target check box. Specify the Host IP address of the accelerator card from the ifconfig command.
    4. Click OK to close the dialog box and continue.

  8. Select the Open Settings command in the Flow Navigator next to the Debug command, or open the launch.json from the System project in the Vitis Components Explorer. Validate the launch configurations for the Hardware build, or select the Add Configuration (+) command to create a new configuration as shown in the following figure:

    Be sure to set the following fields on the dialog box as shown in the preceding figure.

    • Target Connection: Select the new Linux TCF agent you built with the specified IP address for the accelerator card
    • Host Executable: Specify the PS application to run from the SD card
    • Cmd Line Args: Specify any command line arguments required for the software application, such as the xclbin file to load
    • Work Directory: Specify the remote mount location for the SD card
    • Stop At Main and Stop At Program Entry: To stop the application and AI Engine from running before starting the Debug process
  9. Click Debug from the Flow Navigator under the HARDWARE heading.
    Tip: The tool will prompt you to create two launch configurations if you haven't already done so. One for the top-level system project, and a second for the PS application.

    This opens the Debug view and connects to the PS application and AI Engine graph running on their respective cores. The application automatically breaks at the main() function for all the ELF files.

You ca now step in, step over, view variables, and apply break points in the emulation environment. See Using the Debug Environment for more information.