XRT工具之Xbmgmt的使用方法

本文來自AMD XILINX 工程師 Chen Yang

XRT 自2021.1更新后，原有的 XRT Tool指令發(fā)生了一些變化。包括xbmgmt，xclbinutil，xbutil，xbflash2（standalone），xball，xbtop。其中xbmgmt是用于管理板卡，例如刷新shell，檢測板卡的信息等，也是初次上手新版卡安裝固件的必需工具。此次試驗平臺為U50，操作系統(tǒng)為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前面是不加--”，接下來結(jié)合實際的板子來看一下是怎么用的：
在開始使用前需要先查找到板卡的BDF，BDF可以在多個Alveo板卡的時候可以作為識別標志。在終端輸入sudo lspci -vd 10ee: (xdmgmt examine也可以輸出顯示BDF，但是為了先后關(guān)系，先使用lspci找到BDF) ，BDF的格式一般是vvvv: xx: yy.0/1，例如000000.0（可能會省略0000，顯示為01:00.0）。

1// xbmgmt configure

xbmgmt configure主要用用于內(nèi)存的配置，它有3個選項可以使用：--device，--input，--retention。

a) 其中device就是 指定BDF；

b) input是指定內(nèi)存配置的INI文件;

c) retention是使能或關(guān)閉DDR內(nèi)存保留。（如有相同的選項，后面不再贅述，例如device)

常見的用法是：

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

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

2// xbmgmt dump

xbmgmt dump 主要用于打印出一些指定選項的內(nèi)容，它有4個選項：

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

a) device（略）；

b) falsh是可編程鏡像；

c) config 是系統(tǒng)配置；

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用的比較多，所以比較重要。它主要打印出設備和主機狀態(tài)信息，比如運行的shell版本等，易于調(diào)試和配置。
它有四個選項：--device，--report，--format，--output:

a) device（略）
b) 其中report是指定具體內(nèi)容，可以指定如下選項：
all：所有已知的信息
firewall：防火墻狀態(tài)
host：主機狀態(tài)
mailbox：設備的mailbox
mechanical：設備上和周圍的傳感器
platform：平臺信息

c) format 是指定報告的格式，格式為JSON和JSON-2020.2。這個功能需要跟--output配合，如果缺失--output，將直接輸出至終端上。
d) output（略）
常見的用法是：

xbmgmt examine --device 000000.0 --report all

有些信息需要root權(quán)限，不然無法顯示。

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版本，我們可以使用如下來進行區(qū)分：
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