Utility Migration Guide

This document maps the legacy xbutil/xbmgmt commands to the new xbutil/xbmgmt commands. It lists out the new xbutil/xbmgmt calls that replace the existing calls. A few points:

  1. The new utilities are complete redesign and architecture, hence there may not be exact 1-to-1 mapping.
  2. The help menus (--help) of these new utilities have also been improved and are highly descriptive with regards to both the commands and options. Please refer to them as needed.
  3. The new command opions have both short and long format, for example -d or --device. In the table below, only the longer option format is used.

You may refer the documentation of the new tools in the following links xbutil and xbmgmt .

xbutil

Subcommand Legacy Subcommand New Option Legacy Option New
help --help    
version --version    
reset reset -d <bdf> --device <bdf>
validate validate -d <bdf> --device <bdf>
    -q --run quick
      --run <testname>
      --format <type>
      --output <file>
scan examine    
query examine -d <bdf> --device <bdf>
      --report <list>
      --output <file>
dump examine   --format <type>
program program -d <bdf> --device <bdf>
dmatest validate -d <bdf> --device <bdf>
      --run DMA
    -b <blksize kb> n/a
    -p <xclbin> --user <xclbin>
host_mem configure -d <bdf> --device <bdf>
    --enable --size <sz> --host-mem enable --size <sz>
    --disable --host-mem disable
p2p configure -d <bdf> --device <bdf>
    --enable --p2p enable
    --disable --p2p disable
      --p2p validate
mem   --read --write Not Supported
top separate xbtop command

xbmgmt

Subcommand Legacy Subcommand New Option Legacy Option New
help --help    
version --version    
flash program -d <bdf> --device <bdf>
    --update --base
    --update --shell <name> --base --image <name w/ path>
    --factory_reset --revert-to-golden
partition program --card <bdf> --device <bdf>
    --program --name <shell name> --shell <shell-file w/ path>
    --path <xclbin w/ path> --user <xclbin w/ path>
scan examine   --report host
  examine   --device <bdf>
      --report <list>
      --format <type>
      --output <file>
reset reset -d <bdf> --device <bdf>
config  

--enable_retention

--disable_retention

To be implemented in next release

Few examples of legacy vs new commands

Here are few example use-cases of legacy vs new commands

1. Getting all the information obtained from the userspace kernel driver

Legacy command

There were two variants of legacy commands

xbutil query

or

xbutil dump

New command

xbutil examine --device 0000:b3:00.1 --report all

2. Validate the card

Legacy command

xbutil validate

New command

xbutil validate --device 0000:b3:00.1

3. Obtaining platform information such as SC version, flashed partition(s) running on the card, etc.

Legacy command

xbmgmt  flash --scan

New command

xbmgmt examine --device 0000:b3:00.0 --report platform

You need to use a combination of xball xbmgmt command if you prefer to see information from all the cards attached to the host server. Please see xball page for more details.

4. Programming the base partition

Legacy command

xbmgmt --update --shell <partition name>

New command

xbmgmt program --base --device 0000:d8:00.0 --base

or when a specific partition to choose

xbmgmt program --base --device 0000:d8:00.0 --base --image <partition name>

5. Resetting the device

Legacy command

xbutil --reset

New command

xbutil --reset --device 0000:d8:00.1