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:

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