XRT工具之Xbmgmt的使用方法

本文来自AMD XILINX 工程师 Chen Yang

XRT 自2021.1更新后，原有的 XRT Tool指令发生了一些变化。包括xbmgmt，xclbinutil，xbutil，xbflash2（standalone），xball，xbtop。其中xbmgmt是用于管理板卡，例如刷新shell，检测板卡的信息等，也是初次上手新版卡安装固件的必需工具。此次试验平台为U50，操作系统为Ubuntu 18.04，请预先安装XRT。因平台受限，有些功能无法完全展示。

xbmgmt有5个通用选项，分别是：
verbose：启用更详细的信息打印，帮助用户从log中得到更多的信息。
batch：使能batch模式
force：强制进行操作，例如已存在文件，可以强制覆盖
help：显示help信息
 

另外xbmgmt还有五个功能选项，可以理解为二级菜单：
xbmgmt configure
xbmgmt dump
xbmgmt examine
xbmgmt program
xbmgmt reset

类似configure前面是不加--”，接下来结合实际的板子来看一下是怎么用的：
在开始使用前需要先查找到板卡的BDF，BDF可以在多个Alveo板卡的时候可以作为识别标志。在终端输入sudo lspci -vd 10ee: (xdmgmt examine也可以输出显示BDF，但是为了先后关系，先使用lspci找到BDF) ，BDF的格式一般是vvvv: xx: yy.0/1，例如000000.0（可能会省略0000，显示为01:00.0）。

1//  xbmgmt configure    

xbmgmt configure主要用用于内存的配置，它有3个选项可以使用：--device，--input，--retention。

a) 其中device就是 指定BDF；

b) input是指定内存配置的INI文件; 

c) retention是使能或关闭DDR内存保留。（如有相同的选项，后面不再赘述，例如device)

常见的用法是：

xbmgmt configure --device 000000.0 --input ./memory_config.ini 

xbmgmt configure --device 000000.0 --retention ENABLE(DISABLE)

2//  xbmgmt dump

xbmgmt dump 主要用于打印出一些指定选项的内容，它有4个选项：

--device，--flash，--config，--output。 

a) device（略）；

b) falsh是可编程镜像；

c) config 是系统配置；

d) output是指定输出的文件。

常见的用法是：

xbmgmt dump --device 000000.0 --flash --output ./flash_dump.txt 

xbmgmt dump --device 000000.0 --config --output ./config_dump.ini

3//  xbmgmt examine

相比前两个功能，xbmgmt examine用的比较多，所以比较重要。它主要打印出设备和主机状态信息，比如运行的shell版本等，易于调试和配置。
它有四个选项：--device，--report，--format，--output:

a) device（略）
b) 其中report是指定具体内容，可以指定如下选项：
all：所有已知的信息
firewall：防火墙状态
host：主机状态
mailbox：设备的mailbox
mechanical：设备上和周围的传感器
platform：平台信息

c)  format 是指定报告的格式，格式为JSON和JSON-2020.2。这个功能需要跟--output配合，如果缺失--output，将直接输出至终端上。
d) output（略）            
常见的用法是：

xbmgmt examine --device 000000.0 --report all

有些信息需要root权限，不然无法显示。

xbmgmt examine --device 000000.0 --report platform --format JSON --output output.json

以上介绍的 xbmgmt 功能偏重于Alveo的检测和查询，接下来介绍的是如何刷新Alveo板卡的镜像和shell，这也是一个很实用的功能。

4//  xbmgmt program

xbmgmt program主要用于对新版卡刷新固件和下载镜像，对于一块未开封的板卡，如果直接安装在服务器上，它是不能直接用的。它的出厂设置是一个golden image，需要我们刷新新的固件才能匹配Vitis版本进行使用。

它有6个选项可以使用：--device，--base，--image，--shell，--user，--revert-to-golden。

a) device（略）
b) base 就是指定安装的镜像版本，如果以u50为例，那么就是xilinx_u50_gen3x16_xdma_base_5。主机上的镜像只有一个的话，就不需要额外操作，使用base就能更新成功，但是如果主机上有不用版本的镜像，那么单单使用base功能是不能成功更新的，需要额外的--image配合使用。
c) image 需要配合base一起使用，在之前提到过，如果多个镜像在主机上，可以用image指定具体的版本，如何查询主机上安装的镜像版本，可以参考前一篇介绍的xbmgmt examine。
d) shell 的使用情况比较少一点，它是只能用于2PR平台。
e) user 是可以直接下载用户的xclbin到板卡上，而不通过xrt下载。
f) revert-to-golden，如果是板卡遇到问题，需要回滚到出厂设置，就是使用该功能到golden image。

常见的用法是:
xbmgmt program --device 000000.0 --base
如果主机上有多个镜像版本，例如 u50的2022版本和2019版本，我们可以使用如下来进行区分：
xbmgmt program --device 000000.0 --base --image xilinx_u50_gen3x16_xdma_base_5
xbmgmt program --device 000000.0 --shell
xbmgmt program --device 000000.0 --revert-to-golden

5//  xbmgmt reset

xbmgmt reset字面意思，复位板卡。用法很简单，指定对应的板卡：
xbmgmt reset --device 000000.0

　　审核编辑：汤梓红