Utility Migration Guide¶

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

The new utilities are complete redesign and architecture, hence there may not be exact 1-to-1 mapping.

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.

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 xrt-smi and xbmgmt .

xrt-smi¶

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

xrt-smi query

or

xrt-smi dump

New command

xrt-smi examine --device 0000:b3:00.1 --report all

2. Validate the card

Legacy command

xrt-smi validate

New command

xrt-smi 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

xrt-smi --reset

New command

xrt-smi --reset --device 0000:d8:00.1