Debugging the AI Engine Application

This launches the emulator and then waits until Linux is booted within the QEMU. The Emulation console shows a transcript of the QEMU launch and Linux boot process. You can tell when the process has completed when the progress dialog closes and the qemu% prompt is black. You can examine the transcript for details of this process.

When launching hardware emulation, you can specify options for the AI Engine simulator that runs the graph application, as described in Simulator Options for Hardware Emulation, The options can be specified in the Emulator Arguments field shown in the prior figure by specifying the following command:

-aie-sim-options ../aiesim_options.txt

This opens the Debug perspective in the Vitis IDE, and 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.

cd /mnt/mmcblk0p1
source init.sh
cat /etc/xocl.txt

The cat command will display the platform name xilinx_vck190_base_202110_1. You can confirm it is the same as your specified platform and that your setup is correct.

This opens the Debug Configurations dialog box to let you set up the tool. For the Hardware builds, you will need to create two launch configurations: one for the top-level system project, and a second for the PS application.

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

• Remote Working Directory: Specify the remote mount location from the accelerator card as determined in an earlier step.
• Linux TCF Agent: Select the new agent you built with the specified IP address for the accelerator card.
• Disable build before launch: This is necessary because without this step, the tool will try to build your system before running the application.

This opens the Debug perspective in the Vitis IDE, and 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.

This opens the Debug Configurations dialog box to let you set up the tool.

Notice the following fields on the Debug Configurations dialog box:

• Project: Reflects the name of the top-level system project which includes the AI Engine graph application, the PL kernels, and the HW-Link projects.
• Hardware Server: Specifies a local connection to the board. You can configure this differently for a remotely connected board.
• Linux TCF Agent: Is disabled for bare-metal systems.
• Disable build before launch: Enable this to prevent the tool from building your system before launching the application.

Click on Launch Group, and provide a Name for the new group. Click Add the top-level project and PS application Debug configurations to the group as shown in the previous image. Click OK to create the launch group.

./emulation/launch_hw_emu.sh -pid-file emulation.pid -no-reboot \
-add-env ENABLE_RDWR_DEBUG=true -add-env RDWR_DEBUG_PORT=10100 -forward-port 1440 1534

Where:

• ./emulation is the output directory of the package process as described in Packaging, and is where the launch_hw_emu.sh script can be found.
• -add-env RDWR_DEBUG_PORT=${aie_mem_sock_port} defines the port for communicating with the AI Engine domain. In the previous example, it is 10100.
• -forward-port ${linux_tcf_agent_port} 1534 defines the port for the Linux TCF agent. In the previous example, it is 1440, which is the default.

This command launches the emulator and then waits until Linux is booted within the QEMU. The QEMU shell shows a transcript of the QEMU launch and Linux boot process. You can tell when the process has completed when the qemu% prompt is displayed. At that time you are ready to proceed.

source /mnt/sd-mmcblk0p1/init.sh

xrt_server -I300 -S -s tcp::4352

where:

• -I300 defines an idle timeout, in which the server quits if there is no response.
• -S specifies print server properties in JSON format to stdout.
• -s tcp::${xrt_server_port} defines the agent listening protocol and port. In the previous example, it is 4352, but can be any free port.

#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 aie_mem_sock_port "10100"
set xrt_server_port "4352"
set app_name "aie_graph"

#Echo the environment setup
puts "Vitis install: $XILINX_VITIS"
puts "Application: $app_name, Work Directory: $aie_work_dir"
puts "XRT Server Port: $xrt_server_port, AIE Port: $aie_mem_sock_port"

#Set up AIE Debug environment
set source_tcl_cmd "source $XILINX_VITIS/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::$xrt_server_port \
-memsock-url localhost:$aie_mem_sock_port -sim-type memserver -name $app_name -full-program"
puts "$aie_debug_cmd"
eval $aie_debug_cmd

vitis -debug -flow embedded_accel -target hw_emu -exe ./ps_app \
-program-args ${xcl_bin_dir}/binary_container_1.xclbin -port 1440

where:

vitis -debug

Launches the Vitis IDE in stand-alone debug mode.

-flow embedded_accel

Specifies the embedded processor application acceleration flow.

-target hw_emu

Indicates the target build 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.

-port 1440

Specifies the ${linux_tcf_agent_port} as discussed previously.

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

Debug Type

Attach to running target

Connection

aie_xrt_server

Execute Script

Specify the path to aie_app_debug.tcl defined in Step 5.

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.

#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

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.

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.

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.