Vitis IDE Debug Flow - 2022.1 English

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

Document ID
Release Date
2022.1 English

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.

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