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 foraie_mem_sock_port
andlinux_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. - Run the following command in the QEMU shell at the
qemu%
prompt:source /mnt/sd-mmcblk0p1/init.sh
Note: The mount drive is reported in your QEMU transcript, or can be found by typing mount at theqemu%
prompt. The drive above should be standard for Xilinx platforms. - 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
. Specifylocalhost
as host, andxrt_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 5.
- 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.