Hardware Emulation Debug from the Command Line

Hardware Emulation Debug from the Command Line - 2023.1 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID

UG1076

Release Date

2023-06-23

Version

2023.1 English

With the Hardware Emulation 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 QEMU emulator environment using the launch_hw_emu.sh script, that is generated during the --package process.
Launch the Vitis IDE in standalone debug mode using the vitis -debug option.
Configure the debug environment to connect to the PS and AI Engine domains within the system.

For AI Engine platforms, the files required for emulation of the system are defined by the --package command, including the emulation script. To launch the emulation environment use the following command from your build directory:
```
./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.
Tip: Any free ports can be used for aie_mem_sock_port and linux_tcf_agent_port in the above command template. However, these port are mandatory for enabling the AI Engine application and Linux application debug respectively.

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.
In a second terminal window, launch the XRT server application using the following command:
```
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.

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 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

Note: This script requires the $XILINX_VITIS environment variable to be set up.

After the QEMU environment and xrt_server are up and running, you can launch the Vitis IDE in stand-alone debug mode in a third terminal window:
```
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.
In the Debug perspective of the Vitis IDE, create a new target connection of type Hardware Server with the name aie_xrt_server. Specify localhost as host, and xrt_server_port, 4352 in the previous example, as the port.
Create a new Debug configuration of type Single Application Debug as shown.

Debug Type

Attach to running target

Connection

aie_xrt_server

Execute Script

Specify the path to aie_app_debug.tcl defined in Step 4.
Press 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 like step in/step over/viewing variables/plant break points in the emulation environment. Refer to Using the Debug Environment for more information.