xbutil Utility

The Xilinx® Board Utility (xbutil) is a standalone command line utility that is included with the Xilinx Run Time (XRT) installation package. The xbutil command supports both Alveo Data Center accelerator cards and embedded processor-based platforms. It includes multiple commands to validate and identify the installed accelerator card(s) along with additional card details including DDR, PCIe®, 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, list, mem read, mem write, program, and query.

The xbutil command line format is:

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, and access help for individual commands by using the following:
xbutil help <command>
Set up the xbutil command using the following scripts:
  • For csh shell: 
    $ source /opt/xilinx/xrt/setup.csh
  • For bash shell: 
    $ source /opt/xilinx/xrt/setup.sh

clock

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

The clock command allows you to change the clock frequencies driving the computing units. Note that your compute units must be capable or running at the specified clock. You can modify both clock1 and clock2 using this command.

It has the following options:

  • -d <card> (Optional): Specifies the target card. Default = 0 if not specified.
  • -r <region> (Optional): Specifies the target region. Default = 0 if not specified.
  • -f <clock1_freq_MHz> (Required): Specifies clock frequency (in MHz) for the first clock. All platforms have this clock.
  • -g <clock2_freq_MHz> (Optional): Specifies clock frequency (in MHz) for the second clock. Some platforms may not have this clock.
  • -h <clock3_freq_MHz> (Optional): Specifies clock frequency (in MHz) for the third clock. Some platforms may not have this clock.

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

$ xbutil clock -d 0 -f 100

Similarly, to change two clocks in card 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:

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

dmatest

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

The dmatest command performs throughput data transfer tests between the host machine and global memory on a specified card. Note, it is necessary to download an xclbin on the card prior to running dmatest, else running this command returns an error. The dmatest command only performs throughput tests on those DDR banks accessed by the xclbin downloaded to the card.

The command has the following options:

  • -d card_id (Optional): Specifies the target card. Default = 0 if not specified.
  • -b blocksize (Optional): Specifies the test block size (in KB). Default = 65536 (KB) if not specified. 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.

To run the dmatest command, enter the following:

$ xbutil dmatest

An example of the command output 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.

dump

The dump command prints out device information in JSON format to the terminal.

The command has the following options:

  • -d <card> (Optional): Specifies the target card. Default = 0 if not specified.

To run the dump command, run the following command:

$ xbutil dump

An example of the command output on a U250 card is shown below:

{
    "version": "1.1.0",
    "system": {
        "sysname": "Linux",
        "release": "4.15.0-43-generic",
        "version": "#46~16.04.1-Ubuntu SMP Fri Dec 7 13:31:08 UTC 2018",
        "machine": "x86_64",
        "glibc": "2.23",
        "linux": "Ubuntu 16.04.4 LTS",
        "now": "Tue May 21 14:13:00 2019"
    },
    "runtime": {
        "build": {
            "version": "2.3.0",
            "hash": "42f90bb223343431a63d520c036f03c28fff2550",
            "date": "2019-05-20 20:06:52",
            "branch": "master",
            "xocl": "2.3.0,42f90bb223343431a63d520c036f03c28fff2550",
            "xclmgmt": "2.3.0,42f90bb223343431a63d520c036f03c28fff2550"
        }
    },
    "board": {
        "info": {
            "dsa_name": "xilinx_u250_xdma_201830_2",
            "vendor": "4334",
            "device": "20485",
            "subdevice": "14",
            "subvendor": "4334",
            "xmcversion": "0",
            "ddr_size": "68719476736",
            "ddr_count": "4",
            "clock0": "300",
            "clock1": "500",
            "clock2": "0",
            "pcie_speed": "3",
            "pcie_width": "16",
            "dma_threads": "2",
            "mig_calibrated": "false",
            "idcode": "0x4b57093",
            "fpga_name": "xcu250-figd2104-2L-e",
            "dna": "",
            "p2p_enabled": "0"
        },
        "physical": {
            "thermal": {
                "pcb": {
                    "top_front": "40",
                    "top_rear": "35",
                    "btm_front": "42"
                },
                "fpga_temp": "48",
                "tcrit_temp": "41",
                "fan_speed": "1262",
                "cage": {
                    "temp0": "0",
                    "temp1": "0",
                    "temp2": "0",
                    "temp3": "0"
                }
            },
            "electrical": {
                "12v_pex": {
                    "voltage": "11960",
                    "current": "2128"
                },
                "12v_aux": {
                    "voltage": "468",
                    "current": "0"
                },
                "3v3_pex": {
                    "voltage": "3301"
                },
                "3v3_aux": {
                    "voltage": "3307"
                },
                "ddr_vpp_bottom": {
                    "voltage": "2500"
                },
                "ddr_vpp_top": {
                    "voltage": "2500"
                },
                "sys_5v5": {
                    "voltage": "5487"
                },
                "1v2_top": {
                    "voltage": "1201"
                },
                "1v2_btm": {
                    "voltage": "151"
                },
                "1v8_top": {
                    "voltage": "1847"
                },
                "0v85": {
                    "voltage": "855"
                },
                "mgt_0v9": {
                    "voltage": "906"
                },
                "12v_sw": {
                    "voltage": "11971"
                },
                "mgt_vtt": {
                    "voltage": "1200"
                },
                "vccint": {
                    "voltage": "850",
                    "current": "8657"
                }
            },
            "power": "25"
        },
        "error": {
            "firewall": {
                "firewall_level": "0",
                "status": "(GOOD)"
            }
        },
        "pcie_dma": {
            "transfer_metrics": {
                "chan": {
                    "0": {
                        "h2c": "0 Byte",
                        "c2h": "20 Byte"
                    },
                    "1": {
                        "h2c": "0 Byte",
                        "c2h": "0 Byte"
                    }
                }
            }
        },
        "memory": {
            "mem": {
                "0": {
                    "type": "MEM_DDR4",
                    "temp": "4294967295",
                    "tag": "bank0",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "1": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank1",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "2": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank2",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "3": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank3",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "4": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[0]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "5": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[1]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "6": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[2]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "7": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[3]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                }
            }
        },
        "xclbin": {
            "uuid": "1e941bf2-3945-4951-8f67-7bd78664513d"
        },
        "compute_unit": {
            "0": {
                "name": "hello:hello_1",
                "base_address": "25165824",
                "status": "(IDLE)"
            }
        }
    },
    "debug_profile": {
        "device_info": {
            "error": "0",
            "device_index": "0",
            "user_instance": "128",
            "nifd_instance": "0",
            "device_name": "\/dev\/dri\/renderD128",
            "nifd_name": "\/dev\/nifd0"
        }
    }
}

flash (xbutil)

IMPORTANT: The xbutil flash command has been deprecated. Use xbmgmt flash instead.

The flash command programs the flash configuration memory on the card with a specified deployment shell.

It has the following options:

  • -d <card_>

    (Optional): Specifies the target card BDF, else flashes all cards if not specified.

    Note: The Bus Device Function (BDF) is a set of numbers in the format Bus:device.f that identifies a particular device. This number can be found using the lspci(8) Linux command.
  • -a <all | shell>: Specifies the name of the deployment shell to program the card or you can set the shell_name to all. This will attempt to flash all the cards in the system with the installed deployment shell.
  • -t <timestamp>: Specifies the timestamp associated with the shell_name.

For example, to flash the card with a deployment shell called xilinx_u200_xdma_201820_1 and timestamp 1535712995, enter the following command:

sudo xbutil flash -a xilinx_u200_xdma_201820_1 -t 1535712995

Below is an example of the output after the card has been flashed:

INFO: ***Found 880 ELA Records
Idcode byte[0] ff
Idcode byte[1] 20
Idcode byte[2] bb
Idcode byte[3] 21
Idcode byte[4] 10
Enabled bitstream guard. Bitstream will not be loaded until flashing is finished.
Erasing flash............................................
Programming flash............................................
Cleared bitstream guard. Bitstream now active.
DSA image flashed succesfully
Cold reboot machine to load the new image on FPGA

flash scan

IMPORTANT: The xbutil flash scan command has been deprecated. Use xbmgmt flash scan instead.

The flash scan command returns the current firmware installed on both the card and the system.

It has the following option:

  • -v (Optional): Verbose output displays additional information including the MAC address.

To run the flash scan command in verbose mode, enter the following:

sudo xbutil flash scan -v
You should see an output similar to the example below. In this example, the deployment shell name is xilinx_u200_xdma_201830_1, the timestamp is 0x000000005bece8e1, and the BMC version is 3.1. In this output, platform is referring to the deployment shell, TS is the timestamp, and BMC is referring to the Satellite Controller.
XBFLASH -- Xilinx Card Flash Utility
Card_ID[0]
        Card BDF:               0000:d8:00.0
        Card type:              u200
        Flash type:             SPI
        Shell running on FPGA:
                xilinx_u200_xdma_201830_1,[TS=0x000000005bece8e1],[BMC=3.1]
        Shell package installed in system:
                xilinx_u200_xdma_201830_1,[TS=0x000000005bece8e1],[BMC=3.1]
        Card name               A S00A64G
        Card S/N:               2129048BF083
        Config mode:            7
        Fan presence:           A
        Max power level:        225W
        MAC address0:           00:0A:35:05:EC:5A
        MAC address1:           00:0A:35:05:EC:5B
        MAC address2:           FF:FF:FF:FF:FF:FF
        MAC address3:           FF:FF:FF:FF:FF:FF

list

The list command lists all supported working cards installed on the system along with the card ID. The card ID is used in other xbutil commands or in your host code when specifying a particular card.

The output format displays the following three items in this order:

[card_id] BDF platform_name

There are no options for this command.

To run the list command, enter the following:

$ xbutil list

In this example, the card ID is 0, the BDF is 65:00.0, and the platform name is xilinx_u250_xdma_201820_1. 

INFO: Found total 1 card(s), 1 are usable
[0] 65:00.0 xilinx_u250_xdma_201820_1

m2m

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

The command has the following option:

  • -d <card> (Optional): Specifies the target card. Default = 0 if not specified.

To run the dmatest command, run the following command:

$ xbutil dmatest

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.

mem read

The mem --read command reads the specified number of bytes starting at a specified memory address and writes the contents into an output file.
  • -a <address> (Optional): Specifies the starting address (in hexadecimal). Default address is 0x0.
  • -i <size>: Specifies the size of memory read (in bytes).
  • -o <file_name> (Optional): Specifies the output file name. Default output file is memread.out.

To run the mem --read command to read 256 bytes of data starting at memory address 0x0, enter the following:

$ xbutil mem --read -a 0x0 -i 256 -o read.out

This is an example output:

INFO: Found total 1 card(s), 1 are usable
INFO: Reading from single bank, 256 bytes from DDR address 0x4000000000
INFO: Read size 0x100 B. Total Read so far 0x100
INFO: Read data saved in file: read.out; Num of bytes: 256 bytes 
INFO: xbutil mem succeeded.

mem write

The mem --write command writes a defined value to a specified memory location and size.
  • -a <address> (Optional): Specifies the starting address (in hexadecimal). Default address is 0x0.
  • -i <size>: Specifies the size of memory read (in bytes).
  • -e <pattern>: Specifies the pattern (in bytes) to write to memory.

To write the value 0xaa to 256 locations starting at memory address 0x0, enter the following:

$ xbutil mem --write -a 0x0 -i 256 -e 0xaa

This is an example output:

INFO: Found total 1 card(s), 1 are usable
INFO: Writing to single bank, 256 bytes from DDR address 0x4000000000
INFO: Writing DDR with 256 bytes of pattern: 0xaa from address 0x4000000000
INFO: xbutil mem succeeded.

p2p

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

The p2p command is used to enable/disable P2P feature and check current configuration. P2P configuration is persistent across warm reboot. Enabling or disabling P2P requires root privilege.

See PCIe Peer-to-Peer Support for more information.

program

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

It has the following options:

  • -d <card_id> (Optional): Specifies the target card ID. Default = 0 if not specified.
  • -p <xclbin> (Required): Specifies the xclbin binary file to download to the card.

For example, to program the filter.xclbin file to card ID one, you would use the following command:

$ xbutil program -d 1 -p filter.xclbin

This output is displayed after the xclbin has been successfully downloaded to the card:

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

query

The query command returns detailed status information for the specified card. It has the following option:
  • -d <card_id> (Optional): Specifies the target card. Default = 0 if not specified.
For example, to query card ID zero, run the following command:
xbutil query -d 0

An example of the output is given below. The output has been divided into separate sections to better describe the content.

The first section gives details of the installed card including the platform name, vendor information, installed DDR, clock, and PCIe information.
INFO: Found total 1 card(s), 1 are usable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
System Configuration
OS name:	Linux
Release:	3.10.0-862.el7.x86_64
Version:	#1 SMP Fri Apr 20 16:44:24 UTC 2018
Machine:	x86_64
Glibc:		2.17
Distribution:	CentOS Linux 7 (Core)
Now:		Tue Oct 22 09:42:36 2019
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XRT Information
Version:	2.3.1148
Git Hash:	4416230140a8e15d3ca9f56dc6e7522c65968c30
Git Branch:	master
Build Date:	2019-09-04 22:53:35
XOCL:		2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
XCLMGMT:	2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Shell                           FPGA                            IDCode
xilinx_u200_xdma_201830_2       xcu200-fsgd2104-2-e             0x14b37093
Vendor          Device          SubDevice       SubVendor       SerNum          
0x10ee          0x5001          0x000e          0x10ee          2129048BF05Y    
DDR size        DDR count       Clock0          Clock1          Clock2          
64 GB           4               300             500             0               
PCIe            DMA chan(bidir) MIG Calibrated  P2P Enabled     
GEN 3x16        2               true            false
Card power and thermal information are given next.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Temperature(C)
PCB TOP FRONT   PCB TOP REAR    PCB BTM FRONT   
51              42              51              
FPGA TEMP       TCRIT Temp      FAN Presence    FAN Speed(RPM)  
50              50              A               1163            
QSFP 0          QSFP 1          QSFP 2          QSFP 3          
0               0               0               0               
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Electrical(mV|mA)
12V PEX         12V AUX         12V PEX Current 12V AUX Current 
12257           12197           1176            1001            
3V3 PEX         3V3 AUX         DDR VPP BOTTOM  DDR VPP TOP     
3356            3350            2500            2500            
SYS 5V5         1V2 TOP         1V8 TOP         0V85            
5510            1198            1844            858             
MGT 0V9         12V SW          MGT VTT         1V2 BTM         
910             12173           1203            1203            
VCCINT VOL      VCCINT CURR     DNA             VCC3V3 VOL      
851             13220                           0               
3V3 PEX CURR    VCC0V85 CURR    HBM1V2 VOL      VPP2V5 VOL      
0               0               0               0               
VCCINT BRAM VOL 
0               
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Card Power(W)
26
Note: HBM temperatures are only reported when an .xclbin file has been loaded into the target platform.
After power and thermal information, the Firewall Status 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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Firewall Last Error Status
Level 0 : 0x0(GOOD)
ECC Error Status
Tag     Errors      CE Count  UE Count  CE FFA              UE FFA              
bank1   (None)      0         0         0x0                 0x0
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. 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Memory Status
     Tag         Type        Temp(C)  Size    Mem Usage       BO count
[ 0] bank0       **UNUSED**  39       16 GB   0 Byte          0       
[ 1] bank1       MEM_DDR4    42       16 GB   0 Byte          0       
[ 2] bank2       **UNUSED**  46       16 GB   0 Byte          0       
[ 3] bank3       **UNUSED**  43       16 GB   0 Byte          0       
[ 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
Chan[0].h2c:  32930 MB
Chan[0].c2h:  25317 MB
Chan[1].h2c:  994 MB
Chan[1].c2h:  11612 KB
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Streams
     Tag         Flow ID  Route ID Status   Total (B/#)     Pending (B/#)
The xclbin ID along with the contained Compute Units (CU) 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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Xclbin UUID
02954196-6dd8-4281-9fb8-ddad17c7a6b1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Compute Unit Status
CU[ 0]: runOnfpga:runOnfpga_1           @0x18c0000         (IDLE)
CU[ 1]: runOnfpga:runOnfpga_2           @0x18d0000         (IDLE)
Finally, here is the successful output:
INFO: xbutil query succeeded.

reset

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

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

It has the following options:

  • -d <card_id> (Optional): Specifies the target card ID number. Default = 0 if not specified.

Enter the following command:

$ xbutil reset

This output is displayed after the reset has been successfully completed:

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

scan

The xbutil scan option scans the system, displays drivers and system information related to user platforms. The command reports information on accelerator cards that have been configured with a target platform as described in the xbmgmt flash command.

Note: The xbutil scan command will not report cards that are in their original factory condition, or have been restored to factory condition using the xbmgmt flash --factory_reset option.

The xbutil scancommand has no options, and can be run as follows: 

$ xbutil scan

An example of the output is shown below:

INFO: Found total 1 card(s), 1 are usable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
System Configuration
OS name:	Linux
Release:	3.10.0-862.el7.x86_64
Version:	#1 SMP Fri Apr 20 16:44:24 UTC 2018
Machine:	x86_64
Glibc:		2.17
Distribution:	CentOS Linux 7 (Core)
Now:		Tue Oct 22 09:44:17 2019
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XRT Information
Version:	2.3.1148
Git Hash:	4416230140a8e15d3ca9f56dc6e7522c65968c30
Git Branch:	master
Build Date:	2019-09-04 22:53:35
XOCL:		2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
XCLMGMT:	2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 [0]:[0000:03:00.1]:xilinx_u200_xdma_201830_2(ts=0x5d1211e8):user(inst=129)

status

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:
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. Currently, this command can read and report the status of Vitis™ performance monitors, and lightweight AXI protocol checker (LAPC) debug IP, as well as trace IP. For more information on adding performance monitor counters (AM, AIM, ASM) and LAPC in your design, see Techniques for Debugging Application Hangs.

The list of available IP include:
  • Accelerator Monitor (AM) - Count and trace the executions of compute units. Performance Monitors are added using the --profile_kernel option as discussed in described in Vitis Compiler General Options.
  • AXI Interface Monitor (AIM) - Count and trace transactions on AXI MM connections.
  • AXI Streaming Monitor (ASM) - Count and trace transactions on AXI streams.
  • Lightweight AXI Protocol Monitor (LAPC) - Protocol checking of AXI-MM. Protocol checkers are added using the --dk option as described in Vitis Compiler General Options.
  • Streaming Protocol Checker (SPC) - Protocol checking of AXI streams.
  • Trace Funnel - Collects trace events from all monitors. If present, then trace was enabled using the --profile_kernel option during compilation as described in Vitis Compiler General Options, and using the timeline_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 can be turned on via xrt.ini switches.
  • 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>

Below are the available options. If you are running without arguments, it shows the list of available debug IPs:

  • --<ipname> (Optional): Returns the status of the specified IP. This option is only applicable if the xclbin was compiled with the necessary profiling options.

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            Write Bytes       Write Trans.      Read Bytes        Read Tranx.       Outstanding Cnt   Last Wr Addr      Last Wr Data      Last Rd Addr      Last Rd Data    
runOnfpga_1      m_axi_maxiport0-DDR[1]  0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
runOnfpga_1      m_axi_maxiport1-DDR[1]  0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Memory to Memory        0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Host to Device          0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Peer to Peer            0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
INFO: xbutil status succeeded.

When there are no debug IPs in the xclbin, you will see a similar output as shown 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.

top

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

The top command outputs card statistics including memory topology and 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.

It has the following option:

  • -i <seconds> (Optional): Refreshes rate (in seconds). Default is 1 second.

To run top with a refresh rate of two seconds, enter the following command:

$ xbutil top -i 2

An output similar to the one below is displayed:

Device Memory Usage
 [0] bank0      [                                                    0.00% ]
 [1] bank1      [                                                    0.00% ]
 [2] bank2      [                                                    0.00% ]
 [3] bank3      [                                                    0.00% ]


Power
34.8W

Mem Topology                                    Device Memory Usage
Tag             Type        Temp        Size    Mem Usage       BO nums
 [0] bank0      MEM_DDR4    41 C        16 GB   0 Byte          0
 [1] bank1      MEM_DDR4    42 C        16 GB   0 Byte          0
 [2] bank2      MEM_DDR4    54 C        16 GB   0 Byte          0
 [3] bank3      MEM_DDR4    49 C        16 GB   0 Byte          0

Total DMA Transfer Metrics:
  Chan[0].h2c:  4160 MB
  Chan[0].c2h:  8448 MB
  Chan[1].h2c:  4160 MB
  Chan[1].c2h:  4 GB

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

Compute Unit Usage:
CU[@0x1800000] : 68
CU[@0x1810000] : 68

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

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 FPGA DDR through PCI Express.
    2. DDR test: Data transfers between kernels and FPGA DDR.

It has the following option:

  • -d <card_id> (Optional): Specifies the target card ID. Default validates all the cards installed in the system.

For example, to run the validate command on card ID = 0, enter the following:

$ xbutil validate -d 0

An example of the returned information is shown below:


INFO: Found 1 cards

INFO: Validating card[0]: xilinx_u250_xdma_201820_1
INFO: Checking PCIE link status: PASSED
INFO: Starting verify kernel test: 
INFO: verify kernel test PASSED
INFO: Starting DMA test
Host -> PCIe -> FPGA write bandwidth = 11736.3 MB/s
Host <- PCIe <- FPGA read bandwidth = 12190.3 MB/s
INFO: DMA test PASSED
INFO: Starting DDR bandwidth test: ............
Maximum throughput: 45475.441406 MB/s
INFO: DDR bandwidth test PASSED
INFO: Card[0] validated successfully.

INFO: All cards validated successfully.