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 the application of debug flags. Set these options in the Project Editor view in the Vitis IDE. There are two check boxes provided in the Options section for the Active build configuration. Host debug enables debugging constructs in the host compilation. Kernel debug enables debugging of the kernels.

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 on 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 setup required. It automatically manages the environment setup for hardware or software emulation. It configures Xilinx Runtime (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.

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 the Debug () button. 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 consoles and source code windows.

After starting the application, by default the application is stopped right 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.

Note: In hardware emulation, because the C/C++/OpenCL™ kernel code is translated for efficient implementation, breakpoints cannot be placed on all statements. Mostly, untouched loops and functions are available for breakpoints, and only preserved variables can be accessed.