xbutil Utility - Legacy

TIP: This describes the legacy version of the xbutil command that can be accessed by calling the xbutil --legacy command.

The Xilinx® Board Utility (xbutil) is a standalone command line utility that is included with the Xilinx Runtime (XRT) installation package. The xbutil command only supports platforms on Alveo Data Center accelerator cards, and embedded processor-based platforms.

Accelerator cards are partitioned into a user function and a management function to provide different levels of card access. The user function allows end users to load and run their applications, while the management function is for system administrators to manage the card. The xbutil utility interacts with the user function. The xbmgmt utility, which requires root privilege, is for interacting with the management function. The reason for splitting the function access between the two utilities is to provide some security for the management features of the tool.

XRT needs to be installed and identified on the card. For customized Alveo card setups in a Vivado flow, xbutil is not used. It includes multiple commands to validate and identify the installed accelerator card(s) along with additional card details including on card memory, host interface, target platform name, and system information. This information can be used for both card administration and application debugging.

IMPORTANT: Although xbutil supports embedded processor platforms, only the following commands are available for use with those platforms: dump, help, program (for DFX platforms only), query, scan, and status.

The xbutil command line format is as follows:

xbutil <command> [options]

Where the available commands and options are given below.

TIP: You can use the help command to list the available xbutil commands and options:
xbutil help

clock

IMPORTANT: This option cannot be used with embedded processor platforms.
The clock command allows you to change the clock frequencies of the clock(s) to the Compute Units (CUs) inside a xclbin. It has the following command line format:
xbutil clock [-d card] [-r region] [-f clock1_freq_MHz] 
[-g clock2_freq_MHz] [-h clock3_freq_MHz]

The clock frequency specified with the -f switch is applied to all CUs. Clock frequency for individual CUs cannot be changed independently. In addition, the xclbin must be programmed and be capable or running at the specified clock frequency. CUs generated with the Vitis tools only have clock1. RTL-based kernels can have clock2 and clock3 connected.

The following table lists the available options.

Table 1. xbutil clock 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
-r <region> Deprecated and has no effect. Option will be removed in subsequent release. N
-f <clock1_freq_MHz> Specifies clock frequency (in MHz) for the first clock. All platforms have this clock. Y
-g <clock2_freq_MHz> Specifies clock frequency (in MHz) for the second clock. Some platforms might not have this clock. N
-h <clock3_freq_MHz> Specifies clock frequency (in MHz) for the third clock. Some platforms might not have this clock. N

Use the xclbinutil Utility tool to list the available xclbin clocks.

It is necessary to program the xclbin prior to changing the clock frequency. See program to program the xclbin. Once the xclbin is programmed, the clock frequency can be changed.

For example, to change clock1 in card_ID = 0 to 100 MHz, run the following command:

xbutil clock -d 0 -f 100

Similarly, to change two clocks in card_ID = 0, such that clock1 is set to 200 MHz and clock2 is set to 250 MHz, run this command:

xbutil clock -d 0 -f 200 -g 250

The following example is an output after running this command successfully:

INFO: Found total 1 card(s), 1 are usable
INFO: xbutil clock succeeded.

If no xclbin is programmed, a message similar to the following will be displayed. Program the xclbin before running the clock command.

INFO: Found total 1 card(s), 1 are usable
WARNING: 'uuid' invalid, unable to find uuid.
Has the bitstream been loaded? See 'xbutil program'.
ERROR: xbutil clock failed.

dmatest

IMPORTANT: This option cannot be used with embedded processor platforms.

The dmatest command is used to validate the card memory throughput by performing data transfer tests between the host machine and global memory on a specified card. The dmatest is run as part of the validate command.

It has the following command line format:

xbutil dmatest [-d card] [-b [0x]block_size_KB]

The following table lists the available options.

Table 2. xbutil dmatest 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
-b blocksize Specifies the test block size (in KB). Block size defaults to 65536 (KB) if -b option is not specified. Block size must be a power of 2.

The block size can be specified in both decimal or hexadecimal formats. For example, both -b 1024 and -b 0x400 set the block size to 1024 KB.

 N

It is necessary to program the xclbin prior to running dmatest. See program to program the xclbin.

The dmatest command only performs throughput tests on those DDR banks or HBM pseudo-channels (PCs) accessed by the xclbin programmed to the card.

An example of the command output on a U200 with an xclbin using DDR banks 0, 1, 2, and 3 is shown below:

INFO: Found total 1 card(s), 1 are usable
Total DDR size: 65536 MB
Reporting from mem_topology:
Data Validity & DMA Test on bank0
Host -> PCIe -> FPGA write bandwidth = 11341.5 MB/s
Host <- PCIe <- FPGA read bandwidth = 11097.3 MB/s
Data Validity & DMA Test on bank1
Host -> PCIe -> FPGA write bandwidth = 11414.6 MB/s
Host <- PCIe <- FPGA read bandwidth = 10981.7 MB/s
Data Validity & DMA Test on bank2
Host -> PCIe -> FPGA write bandwidth = 11345.1 MB/s
Host <- PCIe <- FPGA read bandwidth = 11189.2 MB/s
Data Validity & DMA Test on bank3
Host -> PCIe -> FPGA write bandwidth = 11121.7 MB/s
Host <- PCIe <- FPGA read bandwidth = 11375.7 MB/s
INFO: xbutil dmatest succeeded.

Similarly, an example of the command output on a U50 with an xclbin using HBM port 0, 1, 2, and 3 is shown below:

INFO: Found total 1 card(s), 1 are usable
Total DDR size: 0 MB
Reporting from mem_topology:
Data Validity & DMA Test on HBM[0]
Buffer Size: 256 MB
Host -> PCIe -> FPGA write bandwidth = 11950.9 MB/s
Host <- PCIe <- FPGA read bandwidth = 11940.3 MB/s
Data Validity & DMA Test on HBM[1]
Buffer Size: 256 MB
Host -> PCIe -> FPGA write bandwidth = 11947 MB/s
Host <- PCIe <- FPGA read bandwidth = 11958.1 MB/s
Data Validity & DMA Test on HBM[2]
Buffer Size: 256 MB
Host -> PCIe -> FPGA write bandwidth = 12077.2 MB/s
Host <- PCIe <- FPGA read bandwidth = 12064.1 MB/s
Data Validity & DMA Test on HBM[3]
Buffer Size: 256 MB
Host -> PCIe -> FPGA write bandwidth = 11989.5 MB/s
Host <- PCIe <- FPGA read bandwidth = 11976 MB/s
INFO: xbutil dmatest succeeded.

If no xclbin is programmed, a message similar to the following will be displayed.

INFO: Found total 1 card(s), 1 are usable
'uuid' invalid, please re-program xclbin.

dump

The dump command returns extensive card and system information including OS, XRT, board, electrical, thermal and xclbin in JSON format to allow for scripted flows. The output format and content are committed and will be backward compatible when changes are made to this command.

It has the following command line format:

xbutil dump [-d card]

The following table lists the available option.

Table 3. xbutil dump Command Option
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

An example of the command output is shown below:

{
    "version": "1.1.0",
    "system": {
        "sysname": "Linux",
        "release": "4.15.0-74-generic",
        "version": "#84-Ubuntu SMP Thu Dec 19 08:06:28 UTC 2019",
        "machine": "x86_64",
        "glibc": "2.27",
        "linux": "Ubuntu 18.04.3 LTS",
        "cores": "48",
        "memory": "31812",
        "model": "Precision 7920 Tower",
        "now": "Mon Jan 13 15:57:59 2020"
    },
    "runtime": {
        "build": {
            "version": "2.4.19",
            "hash": "be6279809c82b3b6abfd6a6baed6343bd4bda232",
            "date": "2020-01-09 10:57:59",
            "branch": "2019.2_PU1",
            "xocl": "2.4.19,be6279809c82b3b6abfd6a6baed6343bd4bda232",
            "xclmgmt": "2.4.19,be6279809c82b3b6abfd6a6baed6343bd4bda232"
        }
    },
    "board": {
        "info": {
            "dsa_name": "xilinx_u250_xdma_201830_2",
            "vendor": "0x10ee",
            "device": "0x5005",
            "subdevice": "0x000e",
            "subvendor": "0x10ee",
            "xmcversion": "2019107",
            "xmc_oem_id": "0x0",
            "serial_number": "21320493802N",
            "max_power": "225W",
            "sc_version": "4.2.0",
            "ddr_size": "68719476736",
            "ddr_count": "4",
            "clock0": "250",
            "clock1": "500",
            "clock2": "0",
            "pcie_speed": "3",
            "pcie_width": "16",
            "dma_threads": "2",
            "mig_calibrated": "true",
            "idcode": "0x4b57093",
            "fpga_name": "xcu250-figd2104-2L-e",
            "dna": "",
            "p2p_enabled": "0"
        },
        "physical": {
            "thermal": {
                "pcb": {
                    "top_front": "51",
                    "top_rear": "41",
                    "btm_front": "50"
                },
                "fpga_temp": "53",
                "tcrit_temp": "51",
                "fan_presence": "A",
                "fan_speed": "1262",
                "cage": {
                    "temp0": "0",
                    "temp1": "0",
                    "temp2": "0",
                    "temp3": "0"
                }
            },
            "electrical": {
                "12v_pex": {
                    "voltage": "12100",
                    "current": "1480"
                },
                "12v_aux": {
                    "voltage": "12121",
                    "current": "1369"
                },
                "3v3_pex": {
                    "voltage": "3349",
                    "current": "0"
                },
                "3v3_aux": {
                    "voltage": "3316"
                },
                "ddr_vpp_bottom": {
                    "voltage": "2500"
                },
                "ddr_vpp_top": {
                    "voltage": "2500"
                },
                "sys_5v5": {
                    "voltage": "5492"
                },
                "1v2_top": {
                    "voltage": "1207"
                },
                "1v2_btm": {
                    "voltage": "1199"
                },
                "1v8": {
                    "voltage": "1824"
                },
                "0v85": {
                    "voltage": "856",
                    "current": "0"
                },
                "mgt_0v9": {
                    "voltage": "908"
                },
                "12v_sw": {
                    "voltage": "12038"
                },
                "mgt_vtt": {
                    "voltage": "1203"
                },
                "vccint": {
                    "voltage": "850",
                    "current": "16668"
                },
                "vcc3v3": {
                    "voltage": "0"
                },
                "hbm_1v2": {
                    "voltage": "0"
                },
                "vpp2v5": {
                    "voltage": "0"
                },
                "vccint_bram": {
                    "voltage": "0"
                }
            },
            "power": "34"
        },
        "error": {
            "firewall": {
                "firewall_level": "0",
                "firewall_status": "0",
                "firewall_time": "0",
                "status": "(GOOD)"
            }
        },
        "pcie_dma": {
            "transfer_metrics": {
                "chan": {
                    "0": {
                        "h2c": "6240 MB",
                        "c2h": "12160 MB"
                    },
                    "1": {
                        "h2c": "6240 MB",
                        "c2h": "6144 MB"
                    }
                }
            }
        },
        "memory": {
            "mem": {
                "0": {
                    "ecc_status": "(None)",
                    "ecc_ce_cnt": "0",
                    "ecc_ue_cnt": "0",
                    "ecc_ce_ffa": "0",
                    "ecc_ue_ffa": "0",
                    "type": "MEM_DDR4",
                    "temp": "41",
                    "tag": "bank0",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "1": {
                    "ecc_status": "(None)",
                    "ecc_ce_cnt": "0",
                    "ecc_ue_cnt": "0",
                    "ecc_ce_ffa": "0",
                    "ecc_ue_ffa": "0",
                    "type": "MEM_DDR4",
                    "temp": "41",
                    "tag": "bank1",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "2": {
                    "ecc_status": "(None)",
                    "ecc_ce_cnt": "0",
                    "ecc_ue_cnt": "0",
                    "ecc_ce_ffa": "0",
                    "ecc_ue_ffa": "0",
                    "type": "MEM_DDR4",
                    "temp": "54",
                    "tag": "bank2",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "3": {
                    "ecc_status": "(None)",
                    "ecc_ce_cnt": "0",
                    "ecc_ue_cnt": "0",
                    "ecc_ce_ffa": "0",
                    "ecc_ue_ffa": "0",
                    "type": "MEM_DDR4",
                    "temp": "48",
                    "tag": "bank3",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "4": {
                    "type": "**UNUSED**",
                    "temp": "0",
                    "tag": "PLRAM[0]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "5": {
                    "type": "**UNUSED**",
                    "temp": "0",
                    "tag": "PLRAM[1]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "6": {
                    "type": "**UNUSED**",
                    "temp": "0",
                    "tag": "PLRAM[2]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "7": {
                    "type": "**UNUSED**",
                    "temp": "0",
                    "tag": "PLRAM[3]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                }
            }
        },
        "xclbin": {
            "uuid": "c5b9a584-9b70-4902-ae32-addf5c1c6e0c"
        },
        "compute_unit": {
            "0": {
                "name": "bandwidth1:kernel_1",
                "base_address": "25165824",
                "status": "(IDLE)"
            },
            "1": {
                "name": "bandwidth2:kernel_2",
                "base_address": "25231360",
                "status": "(IDLE)"
            }
        }
    },
    "debug_profile": {
        "device_info": {
            "error": "0",
            "device_index": "0",
            "user_instance": "129",
            "nifd_instance": "0",
            "device_name": "\/dev\/dri\/renderD129",
            "nifd_name": "\/dev\/nifd0"
        }
    }
}

If an invalid card index is supplied, the following message will be displayed:

ERROR: Card index 1 is out of range

m2mtest

IMPORTANT: This option cannot be used with embedded processor platforms.

The m2mtest command performs throughput data transfer tests between two device memory banks on a specified card. Note, only platforms supporting M2M feature, see Alveo Data Center Accelerator Card Platforms User Guide (UG1120), can run this command. In addition, it is necessary to download an xclbin on the card which uses at least two memory banks prior to running m2mtest, else running this command returns an error. The m2mtest command only performs throughput tests on those memory banks accessed by the xclbin downloaded to the card.

It has the following command line format:

xbutil m2mtest [-d card]

The following table lists the available option.

Table 4. xbutil m2mtest Command Option
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

An example of the command output with an xclbin using DDR banks 0, 1, 2, and 3 is shown below:

INFO: Found total 2 card(s), 2 are usable
bank0 -> bank1 M2M bandwidth: 12050.5 MB/s 
bank0 -> bank2 M2M bandwidth: 12074.3 MB/s 
bank0 -> bank3 M2M bandwidth: 12082.9 MB/s 
bank1 -> bank2 M2M bandwidth: 12061.8 MB/s 
bank1 -> bank3 M2M bandwidth: 12105.2 MB/s 
bank2 -> bank3 M2M bandwidth: 12065.8 MB/s 
INFO: xbutil m2mtest succeeded.

If no xclbin has been loaded, the following error message will be displayed:

'uuid' invalid, please re-program xclbin.

If the command is run on platforms not supporting M2M feature, the following error will be displayed:

M2M is not available. Skipping validation
ERROR: xbutil m2mtest failed.

mem --read

IMPORTANT: This option cannot be used with embedded processor platforms.

The mem --read command reads the indicated number of bytes starting at a specified memory address and writes the contents into an output file.

It has the following command line format:

xbutil mem --read [-d card] [-a [0x]start_addr] 
[-i size_bytes] [-o output filename]

The following table lists the available options.

Table 5. xbutil mem --read 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
-a <start_addr> Specifies a valid starting address in either hex or decimal format. Hex format requires leading 0x that is, 0x100. Default address is 0x0.

Valid addresses can be obtained using the Linux dmesg command as outlined below.

 N
-i <size_bytes> Specifies the memory transfer size in bytes in either hex or decimal format. Hex format requires leading 0x that is, 0x100. Default size is 0x20000. N
-o <output_file_name> Output file name. Default output file is memread.out if output file name not specified. N

An example of the output using the following command with xclbin using DDR banks 0, 1, 2, and 3 shown below:

xbutil mem --read -a 0x0 -d2 -i 0x10
INFO: Found total 3 card(s), 3 are usable
INFO: Reading from single bank, 256 bytes from DDR/HBM/PLRAM address 0x4000000000
INFO: Read size 0x100 B. Total Read so far 0x100
INFO: Read data saved in file: memread.out; Num of bytes: 256 bytes
INFO: xbutil mem succeeded.

An example of the content of the file generated with the above command is given below. The Linux hex dump command xxd was used to display the file.

00000000: 3d3d 3d3d 5354 4152 5420 6f66 2044 4452  ====START of DDR
00000010: 2044 6174 613d 3d3d 3d3d 3d3d 3d3d 0a00   Data=========..
00000020: 4141 4141 4141 4141 4141 4141 4141 4141  AAAAAAAAAAAAAAAA
00000030: 0a3d 3d3d 3d3d 454e 4420 6f66 2044 4452  .=====END of DDR
00000040: 2044 6174 613d 3d3d 3d3d 3d3d 3d3d 0a00   Data=========..

The following error is returned if an invalid starting address is used. The starting address must be within the address space of the device. In this example 0x400 is an invalid starting address:

ERROR: Start address 0x400 is not valid
Available memory banks:
ERROR: xbutil mem failed.
TIP: Use grep to display the available address spaces. For instance, the following command displays the DDR memory base addresses:
dmesg | grep -A 10 -i ddr

The Linux dmesg output will give the base address for the various DDR memories. A sample of the output for DDR[1] is shown below:

[23174.283512] xocl 0000:a6:00.1: xocl_init_mem: Memory Bank: DDR[1]
[23174.283514] xocl 0000:a6:00.1: xocl_init_mem: Base Address:0x8000000000
[23174.283515] xocl 0000:a6:00.1: xocl_init_mem: Size:0x400000000

Replace the -i ddr search term above with the -i hbm to look up the base address for HBM memories.

To write a known byte pattern, see mem --write.

mem --write

IMPORTANT: This option cannot be used with embedded processor platforms.

The mem --write command writes a defined pattern to a specified set of memory locations.

It has the following command line format:

xbutil mem --write [-d card] [-a [0x]start_addr] 
[-i size_bytes] [-e pattern_byte]

The following table lists the available options.

Table 6. xbutil mem --write 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
-a <start_addr> Specifies a valid starting address in either hex or decimal format. Hex format requires leading 0x that is, 0x100. Default address is 0x0.

Valid addresses can be obtained using the Linux dmesg command as outlined below.

 N
-i <size_bytes> Specifies the memory transfer size in bytes in either hex or decimal format. Hex format requires leading 0x that is, 0x100. N
-e <pattern> Specifies the byte pattern written to all defined byte locations in either hex or decimal format. Hex format requires leading 0x that is, 0xEF. N

An example of the output using the following command with xclbin using DDR banks 0, 1, 2, and 3 shown below:

xbutil mem --write -a 0x0 -d2 -i 0x10 -e 0xef
INFO: Found total 1 card(s), 1 are usable
INFO: Writing to single bank, 16 bytes from DDR/HBM/PLRAM address 0x0
INFO: Writing DDR/HBM/PLRAM with 16 bytes of pattern: 0xef from address 0x0
INFO: xbutil mem succeeded.

The following error is returned if an invalid starting address is used. The starting address must be within the address space of the device. In this example 0x400 is an invalid starting address.

ERROR: Start address 0x400 is not valid
Available memory banks:
ERROR: xbutil mem failed.
TIP: Use grep to display the available address spaces. For instance, the following command displays the DDR memory base addresses:
dmesg | grep -A 10 -i ddr

The Linux dmesg output will give the base address for the various DDR memories. A sample of the output for DDR[1] is shown below:

[23174.283512] xocl 0000:a6:00.1: xocl_init_mem: Memory Bank: DDR[1]
[23174.283514] xocl 0000:a6:00.1: xocl_init_mem: Base Address:0x8000000000
[23174.283515] xocl 0000:a6:00.1: xocl_init_mem: Size:0x400000000

Replace the -i ddr search term above with the -i hbm to look up the base address for HBM memories.

To read memory addresses, see mem --read.

p2p

IMPORTANT: This option cannot be used with embedded processor platforms.

The p2p command is used to enable/disable (PCIe Peer-to-Peer Support) feature and check current configuration.

IMPORTANT: Only platforms supporting P2P feature, see Alveo Data Center Accelerator Card Platforms User Guide (UG1120), can run this command.

P2P configuration is persistent across warm reboot.

Note: Enabling or disabling P2P requires root privilege.

It has the following command line format:

xbutil p2p [-d card] --[enable | disable | validate]

The following table lists the available options.

Table 7. xbutil p2p 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
--enable Enables p2p

Option –-enable, –-disable, and –-validatee mutually exclusive. Only one can be in the command.

A warm reboot is required if the returned xbutil query status for P2P is no_iomem.

 --enable,

--disable,

--validate

mutually exclusive
--disable Enables p2p

Option --enable, –-disable, and –-validate are mutually exclusive. Only one can be in the command.

This might require warm reboot to fully disable.

 --enable,

--disable,

--validate

mutually exclusive
--validate Validates p2p feature.

Option –-enable, –-disable, and –-validate are mutually exclusive. Only one can be in the command.

Run after a warm reboot if it is needed.

 --enable,

--disable,

--validate

mutually exclusive
Use xbutil query to display the current status of P2P. The following is a partial output of the xbutil query command showing the current status under the heading P2P Enabled.
PCIe            DMA chan(bidir) MIG Calibrated  P2P Enabled
GEN 3x16        2               true            false
Table 8. P2P Enabled Returned Value Definition
Value Comment
true P2P is enabled.
false P2P is disabled.
no_iomem P2P is enabled in device but system could not allocate I/O memory, warm reboot is needed.

If P2P is not enabled when trying to validate, validation will be skipped and the following message will be displayed:

P2P BAR is not enabled. Skipping validation

If the card platform does not support P2P, the following message will be displayed:

ERROR: P2P is not supported on this platform

If no xclbin is programmed, the following message will be displayed:

'uuid' invalid, please re-program xclbin.

program

IMPORTANT: This option is supported for use with embedded processor DFX platforms.

The program command downloads a specified xclbin binary to the programmable region on the card.

It has the following command line format:

xbutil program [-d card] [-r region] -p <xclbin_filename>

The following table lists the available options.

Table 9. xbutil program 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
-r <region> Deprecated and has no effect. Option will be removed in subsequent release. N
-p <xclbin_filename> Specifies the file name of the xclbin binary file to download to the card. Y

When an xclbin is successfully downloaded to the card, the following message is displayed:

INFO: Found total 1 card(s), 1 are usable
INFO: xbutil program succeeded.

If the subsequent use of the xbutil program uses the same xbutil_filename, the xbutil will not be downloaded as it already exists on the card, but the above message will be identical.

If the specified xclbin file does not exist, the following message will be displayed:

ERROR: Cannot open <my_xclbin>.xclbin. Check that it exists and is readable.
ERROR: xbutil program failed.

query

IMPORTANT: This option cannot be used with embedded processor platforms.

The query command returns detailed card status information in human readable format. See dump for output in JSON format.

It has the following command line format:

xbutil query [-d card [-r region]]

The following table lists the available options.

Table 10. xbutil query 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
-r <region> Deprecated and has no effect. Option will be removed in subsequent release. N

There is a significant amount of information returned. An example of the output is given below. The output has been divided into separate sections to better describe the content.

System Configuration

Table 11. 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
Glibc GLIBC version installed
Distribution Distribution
Now Current date and time

An example of the system configuration is shown below:

System Configuration
OS name:    Linux
Release:    4.15.0-74-generic
Version:    #83~16.04.1-Ubuntu SMP Wed Dec 18 04:56:23 UTC 2019
Machine:    x86_64
Glibc:      2.23
Distribution:   Ubuntu 16.04.6 LTS
Now:        Wed Jan 22 15:30:36 2020

XRT Information

Table 12. 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
XCLMGMT XCLMGMT version 
XRT Information
Version:    2.3.1301
Git Hash:   192e706aea53163a04c574f9b3fe9ed76b6ca471
Git Branch: 2019.2
Build Date: 2019-10-24 20:04:29
XOCL:       2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471
XCLMGMT:    2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471

Card Platform (Shell) Information

Table 13. Card Platform (Shell) Field Definition
Field Description
Shell Platform installed on the card
FPGA FPGA name
IDCode ID code of platform
Vendor Vendor ID
Device Device ID
SubDevice SubDevice ID
SubVendor SubVendor ID
SerNum Unique card serial number
DDR Size Total amount of DDR RAM available on the card in GB
DDR Count Total number of DDR DIMMs installed on the card
Clock0 Clock0 frequency in MHz
Clock1 Clock1 frequency in MHz
Clock2 Clock2 frequency in MHz
PCIe Trained PCIe link status
DMA chan(bidir) Number of DMA channels on the card
MIG Calibrated When TRUE MIG has been calibrated, FALSE indicates the MIG has not been calibrated.
P2P Enabled Returns status of P2P. Status will be one of the following:
  • true: P2P is enabled
  • false: P2P is disabled
  • no_iomem: P2P is enabled in device but system could not allocate I/O memory, warm reboot is needed
OEM ID ID used by OEMs
Interface UUID A unique identifier which can be used to determine whether partial bitstreams containing the various partitions of the platform are logically and physically compatible with each other.
Logic UUID A unique identifier which can be used to determine whether partial bitstreams containing the various partitions of the platform are logically and physically compatible with each other.

This is an example output of the card information:

Shell                         FPGA                         IDCode
xilinx_u50_gen3x16_xdma_201920_3                           0x14b77093
Vendor        Device          SubDevice       SubVendor    SerNum         
0x10ee        0x5021          0x000e          0x10ee       00501201A030   
DDR size      DDR count       Clock0          Clock1       Clock2         
0 Byte        0               250             500          450            
PCIe          DMA chan(bidir) MIG Calibrated  P2P Enabled  OEM ID         
GEN 3x16      2               true            false        0x0            
Interface UUID
862c7020a250293e32036f19956669e5
Logic UUID
f465b0a3ae8c64f619bc150384ace69b
DNA

Temperature

Card power and thermal information are given next. Temperatures are reported in Celsius.

Table 14. Temperature Field Definition
Field Description
PCB Top Front Temperature at the top front of the PCB in Celsius
PCB Top Rear Temperature at the top rear of the PCB in Celsius
PCB BTM Front Temperature at the bottom front of the PCB in Celsius
FPGA Temp FPGA core temperature in Celsius
TCRIT Temp Critical temperature in Celsius of the fan controller. Present for both active and passive cards.
Fan Presence Represents the presence of a fan on the card.
  • A – Active cooling. Fan is present on card.
  • P – Passive cooling. Fan is not present on the card and must be cooled by host server.
Fan Speed Fan speed (RPM). Returned as N/A for passive cards.
QSFP 0,1,2,3 Temperature in Celsius of the QSFP module

An example of the temperature output is given below:

Temperature(C)
PCB TOP FRONT   PCB TOP REAR    PCB BTM FRONT  
42              37              42             
FPGA TEMP       TCRIT Temp      FAN Presence    FAN Speed(RPM) 
44              42              A               1108           
QSFP 0          QSFP 1          QSFP 2          QSFP 3         
0               0               0               0

Electrical

This provides various voltage (mV) and current (mA) readings.

Table 15. Electrical Field Definition
Field Description
12V PEX Voltage measurement (12V nominal) from the 12V Power source from the PCIe connector.
12V AUX Voltage measurement (12V nominal) from the 12V, 6 or 8-pin PCIe AUX power cable.
12V PEX Current Current measurement of the power drawn by the PCIe connector.
12V AUX Current Current measurement of the power drawn by the 6 or 8-pin PCIe AUX power cable.
3V3 PEX Voltage measurement (3.3V nominal) of the 3.3V Power source from the PCIe connector.
3V3 AUX Voltage measurement (3.3V nominal) of the 3.3V AUX Power sourced from the PCIe connector.
DDR VPP BOTTOM Voltage measurement (2.5V nominal) for powering the onboard VPP for the DDR4 parts on the lower portion of the card.
DDR VPP TOP Voltage measurement (2.5V nominal) for powering the onboard VPP for the DDR4 parts on the upper portion of the card.
SYS 5V5 Voltage measurement (5.5V nominal) used for powering the onboard VCC_INT regulators. Only on U2XX cards.
1V2 TOP Voltage measurement (1.2V nominal) for powering the onboard VDD for the DDR4 parts on the upper portion of the card.
1V8 TOP Voltage measurement (1.8V nominal) for powering the onboard VCCAUX, VCCAUXIO, and MGTAVVCAUX regulator used by the FPGA.
0V85 Voltage measurement (0.85V nominal) of the onboard VCCINTIO and VCCBRAM regulator used by the FPGA.
MGT 0V9 Voltage measurement (0.9V nominal) of the onboard MGTAVCC regulator for the GTYs used by the FPGA.
12V SW Voltage measurement (12V nominal) of the 12V, 6 or 8-pin PCIe AUX power cable.
MGT VTT Voltage measurement (1.2V nominal) of the onboard MGTAVTT regulator for the GTYs used by the FPGA.
1V2 BTM Voltage measurement (1.2V nominal) for powering the onboard VDD regulator for the DDR4 parts on the lower portion of the card.
VCCINT VOL Voltage measurement (0.72-0.85V nominal) of the onboard VCCINT regulator for the FPGA.
VCCINT CURR Current measurement of the VCCINT supply drawn by the card.
VCCINT BRAM VOL Voltage measurement (0.85V nominal) of the onboard VCCINT, VCCINTIO, and VCCBRAM regulator used by the FPGA.
VCC3V3 VOL Voltage measurement (3.3V nominal) of the onboard 3.3V regulator used by the QSFPs, and other circuits.
3V3 PEX CURR Current measurement of the 3.3V motherboard PCIe rail drawn by the card.
VCC0V85 CURR Current measurement of the VCCINTIO and VCCBRAM supply drawn by the card.
HBM1V2 VOL Voltage of 1.2V for powering the onboard VDD on the DDR4 HBM parts on the card.
VPP2V5 VOL Voltage of 2.5V for powering the onboard VPP on the DDR4 parts of the card.

An example of the output is given below:

Electrical(mV|mA)
12V PEX         12V AUX         12V PEX Current 12V AUX Current
12101           12202           1505            1268           
3V3 PEX         3V3 AUX         DDR VPP BOTTOM  DDR VPP TOP    
3357            3326            2500            2500           
SYS 5V5         1V2 TOP         1V8 TOP         0V85           
5515            1204            1836            855            
MGT 0V9         12V SW          MGT VTT         1V2 BTM        
910             12064           1207            1209           
VCCINT VOL      VCCINT CURR     VCCINT BRAM VOL VCC3V3 VOL     
851             15894           0               0              
3V3 PEX CURR    VCC0V85 CURR    HBM1V2 VOL      VPP2V5 VOL     
0               0               0               0

Card Power

Single field returning the total power (W) being consumed by the card.

An example of the output is given below:

Card Power(W)
33

Firewall Last Error Status

The firewall provides information when an error has been detected in hardware. This includes a timestamp and the level of the firewall. The firewall has three levels, as discussed in AXI Firewall Trips. In the following output, there are no detected firewall errors.

Table 16. Firewall Last Error Status Field Definition
Field Description
Tag Name of memory bank
Errors Indicates if an error occurred
CE Count Number of correctable errors.

Number is persistent, however can be reset through xbmgmt reset.
UE Count Number of uncorrectable errors. The count is persistent, but it can be reset using xbmgmt reset.

An example of the output is given below:

Firewall Last Error Status
Level 0 : 0x0(GOOD)
 
ECC Error Status
Tag     Errors      CE Count  UE Count  CE FFA  UE FFA   
bank0   (None)      0         0         0x0     0x0          
bank1   (None)      0         0         0x0     0x0       
bank2   (None)      0         0         0x0     0x0        
bank3   (None)      0         0         0x0     0x0

On some cards, for example the U50, the Satellite Controller (SC) monitors operating conditions. If the card exceeds electrical or thermal limits, the SC will reset the workload on the card. In some cases, this will be seen in the xbutil query output as a firewall trip. It will display the time the trip occurred. An example of the post trip state is given below:

Firewall Last Error Status
Level 3 : 0x80004(RECS_CONTINUOUS_RTRANSFERS_MAX_WAIT|RECS_WRITE_TO_BVALID_MAX_WAIT)
Error occurred on: Tue 2020-04-28 15:16:47 MDT

The card should be okay to use in this state.

Memory Status

The memory topology along with the DMA transfer metrics are provided next, followed by streaming transfers. The DMA metrics include the transfer of data between the host and card. Host to card transfers are indicated by h2c, while card to host transfer are defined by c2h.

An example of the output is given below. If no xclbin has been loaded, no memory status will be displayed.

Memory Status
     Tag         Type        Temp(C)  Size    Mem Usage       BO count
[ 0] bank0       MEM_DDR4    37       16 GB   16 MB           1      
[ 1] bank1       MEM_DDR4    39       16 GB   16 MB           1      
[ 2] bank2       MEM_DDR4    47       16 GB   16 MB           1      
[ 3] bank3       MEM_DDR4    43       16 GB   16 MB           1      
[ 4] PLRAM[0]    **UNUSED**  N/A      128 KB  0 Byte          0      
[ 5] PLRAM[1]    **UNUSED**  N/A      128 KB  0 Byte          0      
[ 6] PLRAM[2]    **UNUSED**  N/A      128 KB  0 Byte          0

DMA Transfer Metrics

An example of the output is given below. If no xclbin has been loaded, no metrics will be displayed.

DMA Transfer Metrics
Chan[0].h2c:  12384 MB
Chan[0].c2h:  15200 MB
Chan[1].h2c:  6240 MB
Chan[1].c2h:  6144 MB

Streams

This is available for streaming platforms only.

An example of the output is given below:

Streams
Tag Flow ID Route ID Status Total (B/#) Pending (B/#)

Xclbin UUID

This displays the xclbin UUID. An example of the output is given below. If no xclbin has been loaded, it will return all zeros as the UUID.

Xclbin UUID
dfd5a66a-36aa-41c6-88bb-c85a86d15512

Compute Unit Status

The Compute Units (CU) present in the xclbin loaded to the card are displayed. For each CU, it displays the name, PCIe BAR address, and the status, which can be IDLE, START, and DONE. The output below shows the xclbin ID and two CUs both with IDLE status.

An example of the output is given below. If no xclbin has been loaded, no CU status will be displayed.

Compute Unit Status
CU[ 1]: bandwidth1:kernel_1         @0x1c00000         (IDLE)
CU[ 0]: bandwidth2:kernel_2         @0x1800000         (IDLE)

reset

IMPORTANT: This option cannot be used with embedded processor platforms.

The reset command resets the programmable region on the card. All running CUs in the region are stopped and reset.

It has the following command line format:

xbutil reset [-d card]

The following table lists the available option.

Table 17. xbutil reset Command Option
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

The following example shows the output after running this command successfully:

All existing processes will be killed.
Are you sure you wish to proceed? [y/n]: y

scan (xbutil)

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 18. 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 19. 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
XCLMGMT XCLMGMT 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 20. 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:
<company>_<card>_<customization>_<major_release>_<minor_release>

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.

status

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

top

IMPORTANT: This option cannot be used with embedded processor platforms.

The top command outputs card statistics including memory topology, DMA transfer metrics, and Compute Unit usage data. This command is similar to the Linux top command. When running, it continues to operate until q is entered in the terminal window to quit.

It has the following command line format:

xbutil top [-d card] [-i seconds]

The following table lists the available options.

Table 22. xbutil top 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
-i <seconds> Refresh rate (in seconds). Default is 1 second. N

For example, the following command will perform top with a two second refresh rate.

xbutil top -i 2
Table 23. Top Field Definition
Field Description
Device Memory Usage Percentage of memory used per memory bank.

Graphical usage bar will be displayed proportion to the amount of memory used. Bar will be similar to the following:

||||||||||
Power Total card power
Mem Topology Assigned tag to the memory bank
Memory type (that is, DDR or HBM)
Temperature of the memory bank
Total available memory per memory bank
Current memory usage
Number of buffers allocated
Total DMA Transfer Metrics Accumulated bytes transferred because of reboot
CU Usage Number of commands executed by this CU. Numbers are accumulated until the xclbin is changed where they are reset to zero.

The following example is an output after running this command:

Device Memory Usage
 [0] bank0      [ |||||||||||                                        25.0% ]
 [1] bank1      [                                                    0.00% ]
 [2] bank2      [                                                    0.00% ]
 [3] bank3      [                                                    0.00% ]
 
 
Power
34.0W
 
Mem Topology                                    Device Memory Usage
Tag             Type        Temp        Size    Mem Usage       BO nums
 [0] bank0      MEM_DDR4    36 C        16 GB   4 GB            16
 [1] bank1      MEM_DDR4    38 C        16 GB   0 Byte          0
 [2] bank2      MEM_DDR4    46 C        16 GB   0 Byte          0
 [3] bank3      MEM_DDR4    41 C        16 GB   0 Byte          0
 
Total DMA Transfer Metrics:
  Chan[0].h2c:  75 GB
  Chan[0].c2h:  78 GB
  Chan[1].h2c:  61600 MB
  Chan[1].c2h:  61440 MB
 
############################################################################
 
Compute Unit Usage:
CU[@0x1800000] : 68
CU[@0x1c00000] : 68
CU[@0x250000] : 6
 
############################################################################

If no xclbin is loaded, the following will be displayed:

Device Memory Usage
 [1] bank1      [                                                    0.00% ]

Power
23W

Mem Topology                                    Device Memory Usage
Tag              Type        Temp     Size      Mem Usage       BO nums
 [1] bank1       MEM_DDR4    36       64 GB     0 Byte          0

Total DMA Transfer Metrics:
  Chan[0].h2c:  0 Byte
  Chan[0].c2h:  0 Byte
  Chan[1].h2c:  0 Byte
  Chan[1].c2h:  0 Byte

############################################################################

Compute Unit Usage:

############################################################################

validate

IMPORTANT: This option cannot be used with embedded processor platforms.

The validate command generates a high-level, easy to read summary of the installed card. It validates correct installation by performing the following set of tests:

  1. Validates the card found.
  2. Checks PCI Express link status.
  3. Runs a verify kernel on the card.
  4. Performs the following data bandwidth tests:
    1. DMA test: Data transfers between host and card memory through PCI Express.
    2. DDR or HBM test: Data transfers between kernels and card memory.

It has the following command line format:

xbutil validate [-d card]

The following table lists the available option.

Table 24. xbutil validate Command Option
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

The following is an example of the output after running this command:

INFO: Found 1 cards
 
INFO: Validating card[0]: xilinx_u200_xdma_201830_2
INFO: == Starting AUX power connector check:
INFO: == AUX power connector check PASSED
INFO: == Starting PCIE link check:
INFO: == PCIE link check PASSED
INFO: == Starting verify kernel test:
INFO: == verify kernel test PASSED
INFO: == Starting DMA test:
Buffer Size: 256 MB
Host -> PCIe -> FPGA write bandwidth = 8775.99 MB/s
Host <- PCIe <- FPGA read bandwidth = 12136.8 MB/s
INFO: == DMA test PASSED
INFO: == Starting device memory bandwidth test:
...........
Maximum throughput: 52428 MB/s
INFO: == device memory bandwidth test PASSED
INFO: == Starting PCIE peer-to-peer test:
P2P BAR is not enabled. Skipping validation
INFO: == PCIE peer-to-peer test SKIPPED
INFO: == Starting memory-to-memory DMA test:
bank0 -> bank1 M2M bandwidth: 12010.3 MB/s  
bank0 -> bank2 M2M bandwidth: 12051.6 MB/s  
bank0 -> bank3 M2M bandwidth: 12063.5 MB/s  
bank1 -> bank2 M2M bandwidth: 12052.7 MB/s  
bank1 -> bank3 M2M bandwidth: 12048.2 MB/s  
bank2 -> bank3 M2M bandwidth: 12052.2 MB/s  
INFO: == memory-to-memory DMA test PASSED
INFO: Card[0] validated successfully.
 
INFO: All cards validated successfully.

version

IMPORTANT: This option cannot be used with embedded processor platforms.

The version command returns the XRT build version details. It is identical to the version command. It has the following command line format. There are no options.

xbutil version

The following table lists the fields returned from xbutil version command.

Table 25. Version Field Definition
Field Description
XRT Build Version XRT build version
Build Version Branch Build version branch
Build Version Hash Build version hash
Build Version Hash Date Build version branch date
Build Version Date Build version date
XOCL XOCL version
XCLMGMT XCLMGMT version
Below is an example output of xbutil version for a system with three cards installed.
      XRT Build Version: 2.3.1301
   Build Version Branch: 2019.2
     Build Version Hash: 192e706aea53163a04c574f9b3fe9ed76b6ca471
Build Version Hash Date: Thu, 24 Oct 2019 19:27:30 -0700
     Build Version Date: Thu, 24 Oct 2019 20:04:29 -0700
                   XOCL: 2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471
                XCLMGMT: 2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471

To return additional card details, use xbmgmt flash --scan.