Xbutil Next Generation

The next generation of the xbutil command-line tool is in preview mode for the 2020.2 release of XRT. This version will replace the current xbutil in a future release of XRT. This document describes the usage of this new version of the tool.

To invoke the new version please set the following environment variable

export XRT_TOOLS_NEXTGEN=true

The xbutil command options are

  • xbutil program
  • xbutil validate
  • xbutil examine
  • xbutil reset
  • xbutil advanced

A note about multidevice system: All the xbutil command supports a --device (or -d) switch to specify the target device of interest. The xbutil command accept the PCIe user function bdf as an argument of --device switch. The user can check the user function bdf from xbutil examine command.

xbutil examine
....
....
Devices present
[0000:b3:00.1] : xilinx_u200_xdma_201830_2
[0000:65:00.1] : xilinx_u50_gen3x16_xdma_201920_3

The above output shows two devices and their user function bdf (0000:b3:00.1 and 0000:65:00.1) can be used with the --device switch

xbutil program

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

The supported options

The details of the supported options

  • The --device (or -d) specifies the target device to be programmed

    • <none> : Optional for a single device system.
    • <user bdf>+ : Mandetory for multiple device system, has to be specified with one or more device user bdf information
    • all: To specify all devices –-device all or -d all can be used

  • The --program (or -p) is required to specify the .xclbin file

    • <xclbin file> : The xclbin file to be used to program the device

Example commands

xbutil validate

The command xbutil validate validates the card installation by running precompiled basic tests.

The supported options

The details of the supported options

  • The --device (or -d) specifies the target device to be validate

    • <none> : Optional for a single device system.
    • <user bdf>+ : Mandetory for multiple device system, has to be specified with one or more device user bdf information
    • all: To specify all devices –-device all or -d all can be used

  • The --run (or -r) specifies the perticular test to execute

    • all (default): runs all the tests listed below
    • Kernel version: Check if the kernel version is supported by XRT
    • Aux connection: Check if auxiliary power is connected
    • PCIE link: Check if PCIE link is active
    • SC version: Check if SC firmware is up-to-date
    • Verify kernel: Run ‘Hello World’ kernel test
    • DMA: Run dma test
    • Bandwidth kernel: Run ‘bandwidth kernel’ and check the throughput
    • Peer to peer bar: Run P2P test
    • Memory to memory DMA: Run M2M test
    • Host memory bandwidth test: Run ‘bandwidth kernel’ when slave bridge is enabled
    • quick: Run first five tests (Kernel version, Aux connection, PCIE link, SC version and Verify kernel)

  • The --format (or -f) specifies the report format

    • text (default): The report is shown in the text format, default behavior
    • json: The report is shown in json-2020.2

Example commands

xbutil examine

The command xbutil examine can be used to find the details of the specific device(s),

The supported options

The details of the supported options

  • The --device (or -d) specifies the target device to be validate

    • <none> : Optional for a single device system.
    • <user bdf>+ : Mandetory for multiple device system, has to be specified with one or more device user bdf information
    • all:To specify all devices –-device all or -d all can be used

  • The --report (or -r) switch can be used to view specific report(s) of interest from the following options

    • scan (default): Shows System Configuration, XRT and Device user bdf information.
    • aie: Reports AIE kernels metadata from the .xclbin
    • electrical: Reports Electrical and power sensors present on the device
    • debug-ip-status: Reports information related to Debug-IPs inserted during the kernel compilation
    • firewall: Reports the current firewall status
    • host: Reports the host configuration and drivers
    • fan: Reports fans present on the device
    • memory: Reports memory topology of the XCLBIN (if XCLBIN is already loaded)
    • thermal: Reports thermal sensors present on the device
    • verbose: Reports everything

  • The --format (or -f) can be used to specify the output format

    • text (default): The output is shown in the text format, default behavior
    • json: The output is shown in json-2020.2

  • The --output (or -o) can be used to dump output in a file instead of stdout

    • <filename> : The output file to be dumped

Example commands

xbutil reset

This xbutil reset command can be used to reset one or more devices.

The supported options

The details of the supported options

  • The --device (or -d) used to specify the device to be reset

    • <user bdf>+ : Mandetory, has to be specified with one or more device user bdf
    • all: To specify all devices –-device all or -d all can be used

  • The --type (or -t) can be used to specify the reset type. Currently supported reset type

    • hot (default): Complete reset of the device

Example commands

xbutil advanced

The xbutil advanced commands are the group of commands only recommended for the advanced users.

As a disclaimer, the formats of these commands can change significantly as we know more about the advnced use-cases.

The supported options

Read from Memory

Fill Memory with binary value

Fill Memory from a file content

P2P Enable, disable or valiadte

The details of the supported options

  • The --device (or -d) used to specify the device to be reset

    • <user bdf>+ : Mandetory, has to be specified with one or more device user bdf
    • all: To specify all devices –-device all or -d all can be used

  • The --read-mem is used to read from perticular memory location. It has to use with following arguments

    • <address> <number of bytes> : The read location and the size of the read.

  • The --output can be used with --read-mem to dump the read data to a file instead of console

    • <filename> : When specified the output of --read-mem commands are dumped into the user provided file

  • The --write-mem is used to write to the perticular memory location. It has to use with following arguments

    • <address> <number of bytes> : The write location and the size of the write.

  • The --fill can be used with --write-mem to fill the memory location with a perticular binary value

    • <uint8> : The filled value in byte

  • The --input can be used with --write-mem to write the memory location from a file content

    • <binary file> : The binary file

  • The --p2p can be used to enable, disable or validate p2p operation

    • enable: Enable the p2p
    • disable: Disable the p2p
    • validate: Validate the p2p

Example commands