Vitis IDE Debug Flow

The Vitis™ IDE provides easy access to the debug capabilities. When performed manually, setting up an executable for debugging requires many steps. When you use the debug flow, these steps are handled automatically by the Vitis IDE.

Note: The debug flow in the Vitis IDE relies on shell scripts during debugging. This requires that the setup files, such as .bashrc or .cshrc, do not interfere with the environment setup, such as the LD_LIBRARY_PATH.

To prepare the executable for debugging, you must change the build configurations to enable Host debug and Kernel debug. Set these options in the Project Editor view in the Vitis IDE, as shown in the following figure. There are two check boxes provided in the Options section for the Active build configuration:

Host debug enables debugging constructs in the host compilation, and is available for all build types.
Kernel debug enables debugging of the kernels, but is only available in software and hardware emulation builds. To enable debug in hardware builds, use the Chipscope Debug settings as described in Vitis Hardware Function Settings.

These check boxes enable the -g, or --debug options in the g++ and Vitis compilers.

Figure 1: Project Editor View Debug Options

You can also enable the debug features from the Build Configuration Settings dialog box, as shown in Vitis Build Configuration Settings, by selecting the build configuration in the Assistant view and clicking the Settings button. Alternatively, you can double-click the build configuration. The same two check boxes are presented. While you can enable host debug on all targets, kernel debug is only supported for software emulation and hardware emulation build targets.

Running a GDB session from the Vitis IDE takes care of all the required setup. It automatically manages the environment setup for software emulation. It configures XRT to ensure debug support when the application is running, as described in xrt.ini File, and manages the different consoles required for the execution of the host code, the kernel code, and the debug server.

When running on an embedded platform, the Vitis IDE also configures and launches the QEMU system mode, the logic simulator for the PL kernel, and manages synchronization between them. For more information, refer to launch_emulator Utility.

After setting up the build configuration for debug, clean the build directory, and rebuild the application to ensure that the project is ready to run in the GDB debug environment.

To launch a debug session, select the build configuration in the Assistant view, and click Debug (). When launching the debug session in the Vitis IDE, the perspective switches to the Debug perspective, which is configured to present additional windows to manage the different debug views and source code windows. The following figure shows the Debug perspective.

After launching the debug environment, by default, the application is stopped at the beginning of the main function body in the host code. As with any GDB graphical front end, you can now set breakpoints and inspect variables in the host code. The Vitis IDE enables the same capabilities for the accelerated kernel implementation in a transparent way. For more information, refer to Debugging Applications and Kernels.

Using the Standalone Debug Flow

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.

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

vitis -debug Command Line

Command Line Usage

The Vitis software platform standalone debug feature lets you launch the Vitis IDE for debugging an existing command line project. In the following sections, an explanation of each of the command line options is described with examples of launching the standalone debug environment for different platforms and target builds.

-debug

vitis -debug

Launches the Vitis IDE in standalone debug mode.

-flow

-flow [ data_center | embedded_accel | embedded ]

Specifies the type of application project being debugged. This configures the Vitis IDE for debugging Data Center applications running on Alveo cards; for example, application acceleration projects running on embedded platforms, such as the zcu104_base platform, or embedded software projects.

IMPORTANT: For embedded and embedded_accel flows, you must launch the QEMU system emulator using the launch_hw_emu.sh or launch_sw_emu.sh script generated during the --package step as described in Packaging for Embedded Platforms, or using the launch_emulator.py command.

-workspace

-workspace <workspace>

Specifies the Vitis IDE workspace to use when opening the application project in debug mode. If this option is not specified, the tool will create a directory named workspace in the current working directory. If a directory named workspace already exists, the tool will use that as the workspace.

-exe

-exe <path_to_executable>

Specifies the file name and path to the application (host) executable.

For example:

vitis -debug -exe ./host.elf

-target

-target [ sw_emu | hw_emu | hw ]

Specifies the build target to use for debugging.

TIP: This only applies for data_center and embedded_accel flows.

For example:

vitis -debug -target hw_emu

-program-args

-program-args <program arguments>

Specifies the command line arguments to be passed to the host application at runtime. If not specified, the tool will pass the .xclbin as a program argument when the data_center or embedded_accel flows are selected.

For example:

vitis -debug -program-args ./xclbin in.dat

-kernels

-kernels <list of kernels>

Specifies the list of kernels to debug. Multiple kernel names can be specified, separated by commas. Listed kernels are defined as function-level breakpoints, so the debugger stops when kernel execution starts. If a kernel is not specified, no function-level debugging is provided.

This is valid only for data_center flows and is not supported for embedded or embedded_accel flows.

For example:

vitis -debug -kernels mmult madd

-work-dir

-work-dir <path_to_working_directory>

Specifies the working directory to save generated output files and reports. This is valid for data_center and embedded_accel flows.

For the data_center flow, this is the directory where the specified .exe will be launched. For embedded_accel flow, the launch directory will be defined by -target-work-dir.

TIP: If not specified, the current working directory is used as the working directory.

-target-work-dir

-target-work-dir <Target working directory>

This is the directory on the target board OS, and the QEMU environment, where the executable will be launched. This is valid for embedded_accel and also for embedded flows using a Linux OS.

TIP: If not specified, the target working directory is /mnt.

-xrt-ini

-xrt-ini <path_to_xrt.ini>

Specifies the location of the xrt.ini file. Valid for data_center and embedded_accel flows.

If the location is specified, it will be looked for in the same directory as the application .exe or in the working directory.

-os

-os [ linux | baremetal ]

Specifies the OS running on the target board. This is valid for the embedded flows.

-host

-host <host_name or ip_address>

Specifies the name or IP address of the host system where the TCF agent or hw_server is running. Valid for embedded_accel and embedded flows. If not specified, it the default host name is localhost for bare metal, and the default IP address is 192.168.0.1 for Linux target OS.

-port

-port <port number>

Port for TCF agent running on target Linux, or the port for hw_server running on local host for bare metal target. If not specified, the port is 1534 for tcf-agent and 3121 for hw_server.

-launch-script

-launch-script <path_to_tcl_script>

Specify a Tcl script to be sourced before attaching the application to the debugger. This is valid only for embedded flow with bare metal OS. The Tcl script can contain commands to initialize the board, download the application, add breakpoints and make the target ready for the debugger to attach.