status - 2021.2 English

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

Document ID
UG1393
Release Date
2022-03-29
Version
2021.2 English

The status command reports the status of the Vitis performance monitor (SPM) and lightweight AXI protocol checker (LAPC) debug IPs contained in the xclbin programmed to the card.

It has the following command line format:
xbutil status [-d <card>] [--debug_ip_name]

The following table lists the available options.

Table 1. xbutil status Command Options
Option Description Required
-d <card> Specifies the target card. <card> can be specified as either the card_id or Bus:Device:Function (BDF). Defaults to card_id = 0 if not specified.
Note: Use the xbutil scan command to display both the card_id and BDF for installed cards.
N
--<ip_name> Returns status of the specified debug IP. N

The status command displays the type and number of the debug IP on the accelerator card.

xbutil status

An example output of the command is shown below. It lists all the debug IP found.

INFO: Found total 1 card(s), 1 are usable
Number of IPs found: 9
IPs found [<ipname>(<count>)]: aim(5) tracefunnel(1) monitorfifolite(1) monitorfifofull(1) accelmonitor(1)
Run 'xbutil status' with option --<ipname> to get more information about the IP
INFO: xbutil status succeeded.

The list of available IP is determined by the xclbin file compiled for use on the accelerator card and include:

Accelerator Monitor (AM)
Count and trace the executions of compute units. Performance Monitors are added using the --profile.exec option as discussed in described in --profile Options.
AXI Interface Monitor (AIM)
Count and trace transactions on AXI4 connections.
AXI4-Stream Monitor (ASM)
Count and trace transactions on AXI4-Stream.
Lightweight AXI Protocol Monitor (LAPC)
Protocol checking of AXI4. Protocol checkers are added using the --debug.protocol option as described in --debug Options.
Streaming Protocol Checker (SPC)
Protocol checking of AXI4-Stream.
Trace Funnel
Collects trace events from all monitors. If present, then trace was enabled using the --profile.data option during compilation as described in --profile Options, and using the opencl_trace option during runtime as described in xrt.ini File.
FIFO Lite
Control of the PL FIFO that stores trace events. If present, then trace was enabled during compilation and runtime, and memory offload was specified to be a FIFO in the PL using the --trace_memory option during compilation as described in Vitis Compiler General Options. Trace behavior is influenced by the settings in the xrt.ini File.
FIFO Full
The data offload of the PL FIFO that stores trace events. If present, then trace was enabled during compilation and runtime, and memory offload was specified to be a FIFO in the PL using the --trace_memory option during compilation.
TS2MM
Takes trace events and offloads them to a memory resource (DDR, HBM, PLRAM). If present, then trace was enabled during compilation and runtime, and memory offload was specified to be a memory resource using the --trace_memory option during compilation as described in Vitis Compiler General Options.

You can get the status of specific IP using the following command syntax:

$ xbutil status --<ipname>

An example output using the --aim option is shown below:

$ xbutil status --aim
INFO: Found total 1 card(s), 1 are usable
AXI Interface Monitor Counters
Region or CU Type or Port           Wr Bytes Wr Trans. Rd Bytes Rd Tranx. Outstanding Cnt
runOnfpga_1  m_axi_maxiport0-DDR[1] 0        0         0        0         0
runOnfpga_1  m_axi_maxiport1-DDR[1] 0        0         0        0         0
shell        Memory to Memory       0        0         0        0         0  
shell        Host to Device         0        0         0        0         0  
shell        Peer to Peer           0        0         0        0         0
INFO: xbutil status succeeded.

The following is a code continuation of the columns:

INFO: Found total 1 card(s), 1 are usable
AXI Interface Monitor Counters
Region or CU Type or Port           Last Wr Addr Last Wr Data Last Rd Addr Last Rd Data
runOnfpga_1  m_axi_maxiport0-DDR[1] 0x0          0x0          0x0          0x0
runOnfpga_1  m_axi_maxiport1-DDR[1] 0x0          0x0          0x0          0x0  
shell        Memory to Memory       0x0          0x0          0x0          0x0       
shell        Host to Device         0x0          0x0          0x0          0x0      
shell        Peer to Peer           0x0          0x0          0x0          0x0  
INFO: xbutil status succeeded.

If no debug IPs are found in the xclbin, the following message is displayed below:

INFO: Found total 1 card(s), 1 are usable
INFO: Failed to find any debug IPs on the platform. Ensure that a valid bitstream with debug IPs (SPM, LAPC) is successfully downloaded. 
INFO: xbutil status succeeded.

For more information on adding performance monitor counters (AM, AIM, ASM) and LAPC in your design, see Techniques for Debugging Application Hangs.