vitis -debug Command Line - 2023.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2023-07-17
Version
2023.1 English

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