Hardware Debug from the Command Line - 2022.2 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2022-10-19
Version
2022.2 English
With the Hardware build complete, including the AI Engine graph, the PL region kernels, and the PS application, you can use the following steps to debug the system design. This process makes use of the Vitis IDE to launch the debug environment from the command line.
  • Launch the Vitis IDE in standalone debug mode using the vitis -debug option.
  • Connect to the board using the hardware server (hw_server) command.
  • Configure the debug environment for the AI Engine domain.
  1. Burn <project>/Hardware/package/sd_card.img to a physical SD card. This creates a bootable 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. Run ifconfig to get the IP address of the target card. The IP address is used to set up a the hardware serve connection in Vitis IDE. The target needs to connect to the network assigned IP address.
  5. In a terminal window, launch the hardware server to connect to the board.
  6. Create a Tcl script with the name aie_app_debug.tcl to set up the AI Engine debug environment:
    #Set up the required environment
    # The aie_mem_socket and xrt_server ports must match what was specified in earlier commands. 
    set aie_work_dir "<AIE_Project>/Work"
    set hw_server_host "gandalf"
    set app_name "aie_graph"
    
    #Printing the information
    puts "Install: $$XILINX_VITIS"
    puts "Application: $app_name, Work Directory: $aie_work_dir"
    puts "Hardware Server: $hw_server_host"
     
     
    set source_tcl_cmd "source ${vitis_install}/scripts/vitis/util/aie_debug_init.tcl"
    puts "$source_tcl_cmd"
    eval $source_tcl_cmd
     
    ##run the command to connect and display debug targets
    set aie_debug_cmd "init_aie_debug -work-dir $aie_work_dir -url tcp:$hw_server_host:3121 -jtag -name $app_name"
    puts "$aie_debug_cmd"
    eval $aie_debug_cmd
    Note: This script requires setting up the $XILINX_VITIS environment variable.
  7. After the board system and hw_server are up and running, launch the Vitis IDE in standalone debug mode in a second terminal window:
    vitis -debug -flow embedded_accel -target hw -exe ./ps_app \
    -program-args ${xcl_bin_dir}/binary_container_1.xclbin -host ${linux_tcf_agent_host} \
    -port 1534

    where:

    vitis -debug
    Launches the Vitis IDE in standalone debug mode.
    -flow embedded_accel
    Specifies the embedded processor application acceleration flow.
    -target hw
    Defines the hardware build as being debugged.
    -exe ./ps_app
    Indicates the PS application to run and debug.
    -program-args ${xcl_bin_dir}/binary_container_1.xclbin
    Refers to the location of the XCLBIN file to be loaded as an argument to the executable.
    -host ${linux_tcf_agent_host}
    Specifies the host name or IP address obtained from Linux running on the board, ${linux_tcf_agent_host}.
    -port 1534
    Specifies the port the Linux TCF agent is running on, ${linux_tcf_agent_port}. In this case 1534.

    This opens the Vitis IDE with the Debug perspective displayed, and the debug configuration for the PS application loaded.

    Figure 1. PS Debug Configuration
  8. Create a new debug configuration of type Single Application Debug as shown.

    Debug Type
    Attach to running target
    Connection
    hw_server defined in Step 5.
    Execute Script
    Specify the path to aie_app_debug.tcl defined in Step 6.
  9. Click Debug to proceed.

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



From this point you can do all the debug activities such as step in/step over/viewing variables/plant break points in the debug environment. Refer to Using the Debug Environment for more information.