--debug Options - 2023.2 English

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

Document ID
Release Date
2023.2 English

This option enables debug IP core insertion in the device binary (.xclbin) for hardware debugging. This option lets you specify the type of debug core to add, and which compute unit and interfaces to monitor with ChipScope™ as described in Debugging During Hardware Execution. The --debug.xxx options lets you attach AXI protocol checkers and System ILA cores at the interfaces to kernels or specific compute units (CUs) for debugging and performance monitoring purposes:

  • The System Integrated Logic Analyzer (ILA) provides transaction level visibility into an accelerated kernel or function running on hardware. AXI traffic of interest can also be captured and viewed using the System ILA core.
  • The AXI Protocol Checker debug core is designed to monitor AXI interfaces on the accelerated kernel. When attached to an interface of a CU, the AXI Protocol Checker actively checks for protocol violations and provides an indication of which violation occurred.

The --debug.xxx commands can be specified in a configuration file under the [debug] section head using the following format as an example:

protocol=all:all           # Protocol analyzers on all CUs
protocol=cu2:port3         # Protocol analyzer on port3 of cu2
chipscope=cu2              # ILA on cu2

The various options of --debug include the following:


--debug.aie.chipscope <interface_name> | <adf_graph_arg_name>

Enables hardware debug for the Versal AI Engine through ChipScope. The <interface_name> argument applies to non-PL kernel interfaces such as AI Engine PLIO interfaces, or AXIS interfaces. The <adf_graph_arg_name> specifies arguments of the graph.


--debug.chipscope <cu_name>[:<interface_name>]

Adds the System Integrated Logic Analyzer debug core to the specified CUs in the design.

Important: The --debug.chipscope option requires the <cu_name> to be specified and does not accept the keyword all. You can optionally specify an <interface_name>.

For example, the following command adds an ILA core to the vadd_1 CU:

v++ --link --debug.chipscope vadd_1


Shows a list of valid compute units and port combinations in the current design. This is informational to help you with crafting a command line or config file for the --debug command.

This option needs to be specified during linking, but does not run the linking process. The required elements of the command line are shown in the following example, which returns the available ports when linking the specified kernels with the listed platform:

v++ --platform <platform> --link --debug.list_ports <kernel.xo>


--debug.protocol all|<cu_name>[:<interface_name>]

Adds the AXI Protocol Checker debug core to the design. This can be specified with the keyword all, or the <cu_name> and optional <interface_name> to add the protocol checker to the specified CU and interface.

For example:

v++ --link --debug.protocol all