scan (xbutil) - 2021.2 English

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

Document ID
English (United States)
Release Date
2021.2 English

The xbutil scan command returns detailed system information including:

  • System configuration details
  • XRT information
  • List of all cards installed on the system, except cards in GOLDEN state.

It has the following command line format and does not have any options.

xbutil scan

The following tables lists the fields returned from various sections of the xbutil scan command.

Table 1. System Configuration Field Definition
Field Description
OS Name Name of the OS running on the machine
Release OS release number
Version OS Version
Machine CPU-based architecture
Model Machine model
CPU Cores Number CPU cores on the machine
Memory Total installed memory on the machine in MB
Glibc GLIBC version installed
Distribution Distribution
Now Current date and time
Table 2. XRT Field Definition
Field Description
Version XRT version
Git Hash Associated GIT hash
Git Branch Associated GIT branch
Build Date XRT build date
XOCL XOCL version

A list of each card installed on the system will also be returned. A separate line for each card will be displayed. An example output for one card is shown below. It provides multiple fields detailing the installed card. The fields are separated with a space.

[0] 0000:65:00.1 xilinx_u50_gen3x16_xdma_201920_3 user(inst=128)

The fields are defined in the following table.

Table 3. Installed Cards Field Definition
Field Description
[card_id] Provides an assigned card_id based on the card enumeration in the driver data structures. A unique card_id is assigned for each card detected. The order can change after a warm or cold reboot.
Bus : Device : Function Provides the enumerated card Bus:Device:Function (BDF) for each card installed. It has the following format:

[ Bus : Device : Function ]

A card's BDF is determined based on the PCIe slot it is plugged into.

Note: Use the xbutil scan command to display both the card_id and BDF for installed cards.
Platform name Platform name in the following format:

See Alveo Data Center Accelerator Card Platforms User Guide (UG1120) for platform naming information.

user (inst = <value>) Returns the user function instance number associated with the card. The instance number allows you to easily find the device node for each function.

In Linux OS, the device node can be found at: /dev/dri/renderD<inst>

In addition, the instance can be useful when mapping the dmesg information to a specific card.

Below is an example of the xbutil scan output. The system configuration and XRT information sections are first displayed followed by the detected card(s). In the below example, one card is detected and assigned card_ID 0 and BDF is 0000:65:00.1. The platform flashed and running on the card is xilinx_u50_gen3x16_xdma_201920_3 and the user instance has been assigned 128.

INFO: Found total 1 card(s), 1 are usable
System Configuration
OS name:    Linux
Release:    4.15.0-96-generic
Version:    #97~16.04.1-Ubuntu SMP Wed Apr 1 03:03:31 UTC 2020
Machine:    x86_64
Model:      Super Server
CPU cores:  16
Memory:     15703 MB
Glibc:      2.23
Distribution:   Ubuntu 16.04.6 LTS
Now:        Tue Apr 14 21:08:05 2020
XRT Information
Version:    2.5.309
Git Hash:   9a03790c11f066a5597b133db737cf4683ad84c8
Git Branch: 2019.2_PU2
Build Date: 2020-02-23 18:51:37
XOCL:       2.5.309,9a03790c11f066a5597b133db737cf4683ad84c8
XCLMGMT:    2.5.309,9a03790c11f066a5597b133db737cf4683ad84c8
 [0] 0000:65:00.1 xilinx_u50_gen3x16_xdma_201920_3 user(inst=128)

In cases where multiple cards are installed, the list of detected cards will be expanded. In the example shown below, three cards are detected and assigned card_ID 0, 1, and 2, respectively.

[0] 0000:a6:00.1 xilinx_u280_xdma_201920_2 user(inst=130)
[1] 0000:73:00.1 xilinx_u250_xdma_201830_2 user(inst=129)
[2] 0000:17:00.1 xilinx_u200_xdma_201830_2 user(inst=128)
An asterisk proceeding the listed card indicates the card it not ready. An example message given for unusable card is given below:
*[0] 0000:a6:00.1 xilinx_u280_xdma_201920_2(ts=0x5e172e16) user(inst=130)
WARNING: card(s) marked by '*' are not ready, run xbmgmt flash --scan --verbose to further check the details.
Note: Cards in golden state (no partition flashed) will not be displayed.