xbutil

This document describes the latest xbutil commands. These latest commands are default from 21.1 release.

For an instructive video on xbutil commands listed below click here.

Global options: These are the global options can be used with any command.

  • --verbose: Turn on verbosity and shows more outputs whenever applicable
  • --batch: Enable batch mode
  • --force: When possible, force an operation
  • --help : Get help message
  • --version : Report the version of XRT and its drivers

Currently supported xbutil commands are

  • xbutil program
  • xbutil validate
  • xbutil examine
  • xbutil configure
  • xbutil reset

xbutil program

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

The supported options

xbutil program [--device|-d] <user bdf> [--user|-u] <xclbin>

The details of the supported options

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

    • <user bdf> : The Bus:Device.Function of the device of interest

  • The --user (or -u) is required to specify the .xclbin file

    • <xclbin file> : The xclbin file with full-path to program the device

Example commands

xbutil program --device 0000:b3:00.1 --user ./my_kernel.xclbin

xbutil validate

The command xbutil validate validates the installed card by running precompiled basic tests <video reference>.

The supported options

xbutil validate [--device| -d] <user bdf> [--run| -r] <test> [--format| -f] <report format> [--output| -o] <filename> [--param] <test>:<key>:<value>

The details of the supported options

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

    • <user bdf> : The Bus:Device.Function of the device of interest

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

    • all (default): runs all the tests listed below
    • 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: Run ‘Hello World’ kernel test
    • dma: Run dma test
    • iops: Run test to measure performance of scheduler (number of hello world kernel execution per second)
    • mem-bw: Run ‘bandwidth kernel’ and check the throughput
    • p2p: Run peer-to-peer test
    • m2m: Run zero copy memory to memory data transfer test
    • hostmem-bw: Run ‘bandwidth kernel’ when host memory is enabled
    • bist: Run BIST test
    • vcu: Run decoder test (only applicable for specific platform).
    • quick: Run first four tests (Aux connection, PCIE link, SC version and Verify kernel)
    • aie-pl: Run AIE PL test

  • The --format (or -f) specifies the report format. Note that --format also needs an --output to dump the report in json format. If --output is missing text format will be shown in stdout

    • JSON: The report is shown in latest JSON schema
    • JSON-2020.2: The report is shown in JSON 2020.2 schema

  • The --output (or -o) specifies the output file to direct the output

  • The --param specifies the extended parameters that can be passed to a test. Valid values:

    • test: dma
    • key: block-size
    • value: value in bytes

Example commands

# Run all the tests
xbutil validate --device 0000:b3:00.1

# Run "DMA" test, produce text output in stdout
xbutil validate --device 0000:b3:00.1 --run DMA

# Run "DMA" and "Validate Kernel" test and generates Json format
xbutil validate --device 0000:b3:00.1 --run DMA "Verify Kernel" --format JSON --output xyz.json

# Pass in a custom block size to dma test
xbutil validate --device 0000:b3:00.1 --run DMA --param dma:block-size:1024

xbutil examine

The command xbutil examine can be used to find the details of the specific device <video reference>.

The supported options

xbutil examine [--device|-d] <user bdf> [--report| -r] <report of interest> [--format| -f] <report format> [--output| -o] <filename>

The details of the supported options

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

    • <user bdf> : The Bus:Device.Function of the device of interest

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

    • aie: Reports AIE kernels metadata from the .xclbin
    • aieshim: Reports AIE shim tile status
    • all: All known reports are generated
    • debug-ip-status: Reports information related to Debug-IPs inserted during the kernel compilation
    • dynamic-regions: Information about the xclbin and the compute units (default when --device is provided)
    • electrical: Reports Electrical and power sensors present on the device
    • error: Asyncronus Error present on the device
    • firewall: Reports the current firewall status
    • host: Reports the host configuration and drivers (default when --device is not provided)
    • mailbox: Mailbox metrics of the device
    • mechanical: Mechanical sensors on and surrounding the device
    • memory: Reports memory topology of the XCLBIN (if XCLBIN is already loaded)
    • pcie-info : Pcie information of the device
    • platform: Platforms flashed on the device (default when --device is provided)
    • qspi-status: QSPI write protection status
    • thermal: Reports thermal sensors present on the device

  • The --format (or -f) specifies the report format. Note that --format also needs an --output to dump the report in json format. If --output is missing text format will be shown in stdout

    • JSON: The report is shown in latest JSON schema
    • JSON-2020.2: The report is shown in JSON 2020.2 schema

  • The --output (or -o) specifies the output file to direct the output

Example commands

# Shows ``xbutil examine --host``
xbutil examine

# Reports electrical information in the stdout
xbutil examine --device 0000:b3:00.1 --report electrical

# Reports "electrical" and "firewall" and dump in json format
xbutil examine --device 0000:b3:00.1  --report electrical firewall --format JSON --output n.json

xbutil configure

Command xbutil configure is used to configure specific settings based on the need of user application (requires sudo) <video reference>.

The supported options

xbutil configure [ --host-mem | --p2p | --performance ] [--help]

The details of the supported options

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

    • <user bdf> : The Bus:Device.Function of the device of interest

  • The --host-mem or --p2p select specific configuration

    • enable: Enable the host-memory or p2p
    • disable: Disable the host-memory or p2p

  • The --size is used in conjuction with xbutil configure --host-mem enable to specify the host-memory size to be enabled

    • <size>: Size and unit specified as a combined string

  • The --performance select specific configuration for benchmarking tests

    • low: Set performance mode to low
    • medium: Set performance mode to medium
    • high: Set performance mode to high
    • default: Set performance mode to default

Example commands

# Enable Host-Memory of Size 1 GB
sudo xbutil configure --device 0000:b3:00.1 --host-mem enable --size 1G

# Enable Host-Memory of size 256 MB
sudo xbutil configure --device 0000:b3:00.1 --host-mem enable --size 256M

# Disable previously enabled Host-Memory
sudo xbutil configure --device 0000:b3:00.1 --host-mem disable

# Enable P2P
sudo xbutil configure --device 0000:b3:00.1 --p2p enable

# Disable P2P
sudo xbutil configure --device 0000:b3:00.1 --p2p disable

xbutil reset

This xbutil reset command can be used to reset device <video reference>.

The supported options

xbutil reset [--device| -d] <user bdf> [--type| -t] <reset type>

The details of the supported options

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

    • <user bdf> : The Bus:Device.Function of the device of interest

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

    • hot (default): Complete reset of the device

Example commands

xbutil reset --device 0000:65:00.1