Vitis Run and Debug Configuration Settings - 2023.1 English

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

Document ID
UG1393
Release Date
2023-07-17
Version
2023.1 English

Launching the compiled, linked, and packaged application, to run or to debug within the Vitis IDE requires the use of the Launch Configuration dialog box, as shown in the figure below. When the build process has completed, the tool enables both the Run button and the Debug button in the Assistant view to let you specify a Launch Configuration to use.

Tip: The Launch Configuration is the same for both running and debugging the application. There are differences in the steps that the tool follows when running the application or launching the debugger, but you can use the same configuration for both purposes.

To edit the settings for a launch configuration, select a build target and click the Run button to open the Run Configurations dialog box. The Run Configuration dialog box, as shown below, lets you specify debug options, enable profiling of the running application, and specify the types of profiling data to collect.

Figure 1. Run Configuration Settings
Tip: The options displayed in the Launch Configuration dialog box vary for Data Center and Embedded Processor platforms, and also for the software and hardware emulation builds, and the hardware build.
Name
Specify the name of the run configuration. The Vitis IDE creates a folder named after the run configuration in the specific build configuration being run. For instance ./project/Emulation-HW/run_config. The output files and logs from the application run are written to this folder. All arguments passed to the host program should be written relative to this folder.
Project
Display the current project, but can be changed to other open projects.
Build Configuration
Select the build target that the launch configuration applies to, or it applies to the active build configuration.
Disable Build Before Launch
When enabled this check box prevents the tool from rebuilding the project before running or debugging it.
Target
Specify the run or debug target for the configuration. Note that emulation builds targets the Linux TCF agent, while the hardware build requires the hw_server, as described in Debugging Applications and Kernels.
Remote Working Directory
For embedded processor systems, specifies the mount disk for the QEMU environment, or for the physical device.
Program Arguments
Display the Programs Argument dialog box. This lets you specify command line arguments for your application if any are needed. Enabling the Automatically update arguments check box allows the tool to automatically specify the xclbin file as an argument for the application. The xclbin file is appended at the end of the command line, after any other specified arguments.
Note: Program arguments should be specified relative to the run configuration folder that is created during the run. You can refer to the Vitis log window in the IDE to review a copy of the command line used to launch the application.
Override Application Options
Generate an options file for the launch_emulator.py command, that you can manually edit to customize as needed for your purposes. Click the Generate button to create a new launch_options.cfg file, or use the Browse button to locate an existing one.
Xilinx Runtime Profiling
This specifies the profiling and event trace features that are enabled during the application run. The specified options are stored in a configuration file and written to the xrt.ini file to use while running the application. Click the Edit button to open the Xilinx Runtime Profiling dialog box as shown below.
Note: The options on the Xilinx Runtime Profiling window are displayed based on the Build Configuration selected in the Run Configuration window.
Host Trace
Specify the type of host profiling you want enabled for the run. The Host trace option is enabled by default, but can be overridden by adding one or more of the other selections as described in Enabling Profiling in Your Application.
Tip: For hardware builds you can also enable Power profiling or Device Counters for the accelerator card.
Device Trace
Specify level of profiling performed on the hardware kernels. This option relates to the device_trace as described in xrt.ini File. Coarse device profiling shows data transfer activity of the CU. Fine device profiling shows all AXI-level transactions on the ports.
Collect Stall Trace
Indicate the capture of stall data for a variety of conditions, as described in --profile Options, and xrt.ini File.
Device Trace Offload
Specify the amount of global memory to allocate to the capture of trace data, and also to enable continuous trace offload at the specified interval to prevent the loss of Timeline Trace data in the case of an interrupted process, as described in Enabling Profiling in Your Application.

The Launch Configuration dialog box has additional tabs to help configure the runtime environment for your application. The three tabs are:

Target Setup
Mainly for embedded platforms with a bare-metal application. It provides options to initialize, manage, and reset the board, device, and program.
Environment
Lets you set up and manage environment variables needed for the Vitis IDE.
Common
This tab is inherited from Eclipse. These are settings and feature common to the Eclipse environment.