Using the Standalone Debug Flow - 2023.1 English

Launching Standalone Debug for Embedded Platforms

The standalone debug flow supports both the embedded processor application acceleration flow (embedded_accel) or the embedded processor software development flow (embedded). For embedded platforms, the application is running on the Arm processor of the device, the files that are required to boot the system, and load the application and kernel, are on a remote system, but the debug tools are running on the local system, and the data and reports generated need to be moved from the embedded system to the local system. The process for debugging in that environment requires more setup and configuration.

Running standalone debug in the Vitis IDE for the embedded_accel flow is a two-step process.

1. You must first launch the QEMU emulator environment using the launch_sw_emu.sh or the launch_hw_emu.sh script, that is generated during the --package process.
2. Then you must launch the Vitis IDE in standalone debug mode using the -debug option.

To run standalone debug in the Vitis IDE for the embedded flow, you must first launch the QEMU emulator environment using the launch_hw_emu.sh script, that is generated during the --package process.

The files required for emulation of the system are also defined by the --package command. This means that launching the standalone debug process for embedded platforms is reliant on the output of the package process, including the emulation script. An example command to launch the emulation environment would include the following.

launch_hw_emu.sh -pid-file emulation.pid -no-reboot -forward-port 1440 1534 \
-enable-debug

Where:

-enable-debug

Opens two different command shells to launch QEMU and XSIM, and enables the GDB connection to the QEMU shell.

-forward-port

Forwards the TCP port from target to host for connecting to the QEMU shell. The QEMU port default is 1440. You can change it if necessary, for example, to 1446, but you must specify it for both the launch_emulation command or script and in the vitis -debug command line. Also, there is support for multiple forward ports enabled. For example, launch_sw_emu.sh -forward-port 1440 1534 -forward-port 9455 1560.

-no-reboot

Exit the QEMU environment when done.

-pid-file

Write the process ID to the specified file, used to kill the process, if necessary.

For hardware emulation, this launches two terminal windows running the QEMU system mode, and the Vivado simulator for simulating the PL kernel.

After the terminals and emulation are up and running, you can launch the Vitis IDE in standalone debug mode in a separate command shell:

vitis -debug -flow embedded_accel -target hw_emu -exe vadd.elf \
-program-args vadd.xclbin -kernels vadd

Where:

vitis -debug

Launches the Vitis IDE in standalone debug mode.

-flow embedded_accel

Specifies the application acceleration flow on an embedded processor platform.

-target hw_emu

Indicates the target build being debugged.

-exe vadd.elf

Indicates the executable application to run and debug.

-program-args vadd.xclbin

Specifies the .xclbin file to be loaded as an argument to the executable.

There are more options that can be specified as described in vitis -debug Command Line , and these options might be needed depending on the configuration of your application and build environment.

The default for embedded systems searches for the executable and the .xclbin file, and any other required input files, on the /mnt folder of the emulation environment, or the embedded system. You can change this by specifying the -target-work-dir when launching the tool. This launches the Vitis IDE with the Debug perspective enabled, running a debug configuration for the specified executable application and kernel code. From this point you can do all the debug activities like step in/step over/viewing variables/adding break points within the GUI-based debug environment.

Launching Standalone Debug for Data Center Platforms

Launching standalone debug for Data Center applications is a bit simpler. In this case, you need to identify the build target and the executable to run and debug. The Data Center platforms do not require an emulation environment.

The following example launches the Vitis standalone debug for the data_center flow targeting the software emulation build. It specifies the executable, host.exe, which is looked for in the current directory, and specifies the kernel to debug.

vitis -debug -flow data_center -target sw_emu -exe host.exe -kernels krnl_vadd

By default, the standalone debug flow looks in the current directory for specified files and to write results. You can specify the -work-dir option to indicate a different working directory from the default. This might be necessary when the .xclbin file is built in a different directory.

This launches the Vitis IDE with the Debug perspective enabled, letting you perform debug activities like step in/step over/viewing variables/adding break points within the GUI-based debug environment.