Hardware Emulation Debug from the Command Line

Hardware Emulation Debug from the Command Line - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID

UG1393

Release Date

2023-12-13

Version

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

Launch the QEMU emulator environment using the launch_hw_emu.sh script, that is generated during the --package process.
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 Versal Designs, 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.

From this point you can do all the debug activities like step in/step over/viewing variables/plant break points in the emulation environment.