Using the Standalone Debug Flow - 2021.2 English

Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400)

Document ID
Release Date
2021.2 English

The Vitis IDE lets you open the debug tool for projects that have been built using the command line flow.

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 or the 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 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. -pid-file -no-reboot -forward-port 1440 1534 \


Opens two different command shells to launch QEMU and XSIM, and enables the GDB connection to the QEMU shell.
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, -forward-port 1440 1534 -forward-port 9455 1560.
Exit the QEMU environment when done.
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


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, and these options might need to be specified 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.