xbutil ユーティリティ

ザイリンクス ボード ユーティリティ (xbutil) は、ザイリンクス ランタイム (XRT) インストール パッケージに含まれるスタンドアロンのコマンド ライン ユーティリティです。xbutil コマンドでは、Alveo データセンター アクセラレータ カードとエンベデッド ベースのプラットフォームの両方がサポートされます。インストール済みのアクセラレータ カードのほか、DDR、PCIe®、ターゲット プラットフォーム名、システム情報などのカードの詳細を検証および特定する複数のコマンドが含まれます。この情報は、カードの管理およびアプリケーションのデバッグに使用できます。

重要: xbutil ではエンベデッド プロセッサ プラットフォームがサポートされますが、これらのプラットフォームで使用できるコマンドは dumplistmem read mem writeprogram、および query だけです。

xbutil コマンド ラインの構文は次のとおりです。

xbutil <command> [options]

使用可能なコマンドおよびオプションは、次のとおりです。

ヒント: help コマンドを使用すると、使用可能な xbutil コマンドおよびオプションがリストできるほか、次を使用して各コマンドのヘルプを表示することもできます。
xbutil help <command>
次のスクリプトを使用して xbutil コマンドを設定します。
  • csh シェル:
    $ source /opt/xilinx/xrt/setup.csh
  • bash シェル:
    $ source /opt/xilinx/xrt/setup.sh

clock

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

clock コマンドは、計算ユニットを駆動するクロック周波数を設定します。計算クロックが指定したクロック周波数で動作可能であることが必要です。このコマンドを使用して、clock1 と clock2 の両方を変更できます。

次のオプションがあります。

  • -d <card> (オプション): ターゲット カードを指定します。指定しない場合、デフォルト値は 0 です。
  • -r <region> (オプション): ターゲット領域を指定します。指定しない場合、デフォルト値は 0 です。
  • -f <clock1_freq_MHz> (必須): 1 つ目のクロックのクロック周波数を MHz で指定します。このクロックはすべてのプラットフォームにあります。
  • -g <clock2_freq_MHz> (オプション): 2 つ目のクロックのクロック周波数を MHz で指定します。プラットフォームによってはこのクロックが含まれないものもあります。
  • -h <clock3_freq_MHz> (オプション): 3 つ目のクロックのクロック周波数を MHz で指定します。プラットフォームによってはこのクロックが含まれないものもあります。

カード 0 の clock1 を 100 MHz に変更するには、次のコマンドを実行します。

$ xbutil clock -d 0 -f 100

カード 0 の clock1 を 200 MHz、clock2 を 250 MHz に変更するには、次のコマンドを実行します。

$ xbutil clock -d 0 -f 200 -g 250

次に、このコマンドの出力例を示します。

INFO: Found total 1 card(s), 1 are usable
INFO: xbutil clock succeeded.

dmatest

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

dmatest コマンドは、ホスト マシンとカード上のグローバル メモリ間のデータ転送のスループットをテストします。dmatest を実行する前に、カードに xclbin をダウンロードする必要があります。そうしないとエラーが返されます。dmatest コマンドは、カードにダウンロードされている xclbin でアクセス可能な DDR バンクに対してのみスループット テストを実行します。

このコマンドには、次のオプションがあります。

  • -d card_id (オプション): ターゲット カードを指定します。指定しない場合、デフォルト値は 0 です。
  • -b blocksize (オプション): テスト ブロックのサイズを KB で指定します。デフォルトは 65536 KB です。ブロック サイズは 10 進数でも、16 進数でも指定できます。たとえば、-b 1024 および -b 0x400 はどちらもブロック サイズを 1024 KB に設定します。

dmatest コマンドを実行するには、次のコマンドを入力します。

$ xbutil dmatest

次に、DDR バンク 0、1、2、および 3 に関する xclbin コマンドの出力例を示します。

INFO: Found total 1 card(s), 1 are usable
Total DDR size: 65536 MB
Reporting from mem_topology:
Data Validity & DMA Test on bank0
Host -> PCIe -> FPGA write bandwidth = 11341.5 MB/s
Host <- PCIe <- FPGA read bandwidth = 11097.3 MB/s
Data Validity & DMA Test on bank1
Host -> PCIe -> FPGA write bandwidth = 11414.6 MB/s
Host <- PCIe <- FPGA read bandwidth = 10981.7 MB/s
Data Validity & DMA Test on bank2
Host -> PCIe -> FPGA write bandwidth = 11345.1 MB/s
Host <- PCIe <- FPGA read bandwidth = 11189.2 MB/s
Data Validity & DMA Test on bank3
Host -> PCIe -> FPGA write bandwidth = 11121.7 MB/s
Host <- PCIe <- FPGA read bandwidth = 11375.7 MB/s
INFO: xbutil dmatest succeeded.

dump

dump コマンドは、デバイス情報を JSON フォーマットでターミナルに表示します。

このコマンドには、次のオプションがあります。

  • -d <card> (オプション): ターゲット カードを指定します。指定しない場合、デフォルト値は 0 です。

dump コマンドを実行するには、次のコマンドを実行します。

$ xbutil dump

次に、U250 カードのコマンド出力例を示します。

{
    "version": "1.1.0",
    "system": {
        "sysname": "Linux",
        "release": "4.15.0-43-generic",
        "version": "#46~16.04.1-Ubuntu SMP Fri Dec 7 13:31:08 UTC 2018",
        "machine": "x86_64",
        "glibc": "2.23",
        "linux": "Ubuntu 16.04.4 LTS",
        "now": "Tue May 21 14:13:00 2019"
    },
    "runtime": {
        "build": {
            "version": "2.3.0",
            "hash": "42f90bb223343431a63d520c036f03c28fff2550",
            "date": "2019-05-20 20:06:52",
            "branch": "master",
            "xocl": "2.3.0,42f90bb223343431a63d520c036f03c28fff2550",
            "xclmgmt": "2.3.0,42f90bb223343431a63d520c036f03c28fff2550"
        }
    },
    "board": {
        "info": {
            "dsa_name": "xilinx_u250_xdma_201830_2",
            "vendor": "4334",
            "device": "20485",
            "subdevice": "14",
            "subvendor": "4334",
            "xmcversion": "0",
            "ddr_size": "68719476736",
            "ddr_count": "4",
            "clock0": "300",
            "clock1": "500",
            "clock2": "0",
            "pcie_speed": "3",
            "pcie_width": "16",
            "dma_threads": "2",
            "mig_calibrated": "false",
            "idcode": "0x4b57093",
            "fpga_name": "xcu250-figd2104-2L-e",
            "dna": "",
            "p2p_enabled": "0"
        },
        "physical": {
            "thermal": {
                "pcb": {
                    "top_front": "40",
                    "top_rear": "35",
                    "btm_front": "42"
                },
                "fpga_temp": "48",
                "tcrit_temp": "41",
                "fan_speed": "1262",
                "cage": {
                    "temp0": "0",
                    "temp1": "0",
                    "temp2": "0",
                    "temp3": "0"
                }
            },
            "electrical": {
                "12v_pex": {
                    "voltage": "11960",
                    "current": "2128"
                },
                "12v_aux": {
                    "voltage": "468",
                    "current": "0"
                },
                "3v3_pex": {
                    "voltage": "3301"
                },
                "3v3_aux": {
                    "voltage": "3307"
                },
                "ddr_vpp_bottom": {
                    "voltage": "2500"
                },
                "ddr_vpp_top": {
                    "voltage": "2500"
                },
                "sys_5v5": {
                    "voltage": "5487"
                },
                "1v2_top": {
                    "voltage": "1201"
                },
                "1v2_btm": {
                    "voltage": "151"
                },
                "1v8_top": {
                    "voltage": "1847"
                },
                "0v85": {
                    "voltage": "855"
                },
                "mgt_0v9": {
                    "voltage": "906"
                },
                "12v_sw": {
                    "voltage": "11971"
                },
                "mgt_vtt": {
                    "voltage": "1200"
                },
                "vccint": {
                    "voltage": "850",
                    "current": "8657"
                }
            },
            "power": "25"
        },
        "error": {
            "firewall": {
                "firewall_level": "0",
                "status": "(GOOD)"
            }
        },
        "pcie_dma": {
            "transfer_metrics": {
                "chan": {
                    "0": {
                        "h2c": "0 Byte",
                        "c2h": "20 Byte"
                    },
                    "1": {
                        "h2c": "0 Byte",
                        "c2h": "0 Byte"
                    }
                }
            }
        },
        "memory": {
            "mem": {
                "0": {
                    "type": "MEM_DDR4",
                    "temp": "4294967295",
                    "tag": "bank0",
                    "enabled": "true",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "1": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank1",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "2": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank2",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "3": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "bank3",
                    "enabled": "false",
                    "size": "16 GB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "4": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[0]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "5": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[1]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "6": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[2]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                },
                "7": {
                    "type": "**UNUSED**",
                    "temp": "4294967295",
                    "tag": "PLRAM[3]",
                    "enabled": "false",
                    "size": "128 KB",
                    "mem_usage": "0 Byte",
                    "bo_count": "0"
                }
            }
        },
        "xclbin": {
            "uuid": "1e941bf2-3945-4951-8f67-7bd78664513d"
        },
        "compute_unit": {
            "0": {
                "name": "hello:hello_1",
                "base_address": "25165824",
                "status": "(IDLE)"
            }
        }
    },
    "debug_profile": {
        "device_info": {
            "error": "0",
            "device_index": "0",
            "user_instance": "128",
            "nifd_instance": "0",
            "device_name": "\/dev\/dri\/renderD128",
            "nifd_name": "\/dev\/nifd0"
        }
    }
}

flash (xbutil)

重要: xbutil flash コマンドは、廃止されています。xbmgmt flash を代わりに使用してください。

flash コマンドは、カード上のフラッシュ コンフィギュレーション メモリを指定の運用シェルでプログラムします。

次のオプションがあります。

  • -d <card_>

    (オプション): ターゲット カード BDF を指定します。指定しない場合、すべてのカードのフラッシュ メモリがプログラムされます。

    注記: BDF (Bus Device Function) は、特定デバイスを識別する Bus:device.f 形式の数値のセットです。この数値は、Linux コマンドの lspci(8) を使用すると検出できます。
  • -a <all | shell>: カードにプログラムする運用シェルの名前を指定します。<shell_name> を all に設定すると、システムに含まれるすべてのカードのフラッシュ メモリがインストールされている運用シェルでプログラムされます。
  • -t <timestamp>: <shell_name> に関連付けるタイムスタンプを指定します。

たとえば、カードのフラッシュ メモリをタイムスタンプ 1535712995xilinx_u200_xdma_201820_1 という運用シェルでプログラムするには、次のコマンドを入力します。

sudo xbutil flash -a xilinx_u200_xdma_201820_1 -t 1535712995

カードのフラッシュ メモリのプログラムが終了すると、次のような出力が表示されます。

INFO: ***Found 880 ELA Records
Idcode byte[0] ff
Idcode byte[1] 20
Idcode byte[2] bb
Idcode byte[3] 21
Idcode byte[4] 10
Enabled bitstream guard. Bitstream will not be loaded until flashing is finished.
Erasing flash............................................
Programming flash............................................
Cleared bitstream guard. Bitstream now active.
DSA image flashed succesfully
Cold reboot machine to load the new image on FPGA 

flash scan

重要: xbutil flash scan コマンドは、廃止されています。xbmgmt flash scan を代わりに使用してください。

flash scan コマンドは、カードおよびシステム両方にインストールされている現在のファームウェアを返します。

次のオプションがあります。

  • -v (オプション): MAC アドレスなどの追加情報を含む詳細な出力を表示します。

flash scan コマンドを詳細モードで実行するには、次のコマンドを入力します。

sudo xbutil flash scan -v
次のような出力が表示されるはずです。この例では、運用シェル名は xilinx_u200_xdma_201830_1、タイムスタンプは 0x000000005bece8e1、BMC バージョンは 3.1 です。プラットフォームは運用シェル、TS タイムスタンプ、BMC はサテライト コントローラーを指します。
XBFLASH -- Xilinx Card Flash Utility
Card_ID[0]
        Card BDF:               0000:d8:00.0
        Card type:              u200
        Flash type:             SPI
        Shell running on FPGA:
                xilinx_u200_xdma_201830_1,[TS=0x000000005bece8e1],[BMC=3.1]
        Shell package installed in system:
                xilinx_u200_xdma_201830_1,[TS=0x000000005bece8e1],[BMC=3.1]
        Card name               A S00A64G
        Card S/N:               2129048BF083
        Config mode:            7
        Fan presence:           A
        Max power level:        225W
        MAC address0:           00:0A:35:05:EC:5A
        MAC address1:           00:0A:35:05:EC:5B
        MAC address2:           FF:FF:FF:FF:FF:FF
        MAC address3:           FF:FF:FF:FF:FF:FF

list

list コマンドは、システムにインストールされているサポートされるカードすべてとその ID をリストします。カード ID は、ほかの xbutil コマンドまたはホスト コードで特定のカードを指定する場合に使用します。

出力には、次の 3 つの項目が表示されます。

[card_id] BDF platform_name

このコマンドにはオプションはありません。

list コマンドを実行するには、次のコマンドを入力します。

$ xbutil list

この例では、カード ID は 0、BDF は 65:00.0、プラットフォーム名は xilinx_u250_xdma_201820_1 です。

INFO: Found total 1 card(s), 1 are usable
[0] 65:00.0 xilinx_u250_xdma_201820_1

m2m

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

m2mtest コマンドは、指定したカード上の 2 つのデバイス メモリ間で、スループット データ転送を実行します。m2mtest を実行する前に、2 つ以上のメモリ バンクを使用するカードに xclbin をダウンロードする必要があります。そうしないとエラーが返されます。

m2mtest コマンドは、カードにダウンロードされている xclbin でアクセス可能なメモリ バンクに対してのみスループット テストを実行します。

このコマンドには、次のオプションがあります。

  • -d <card> (オプション): ターゲット カードを指定します。指定しない場合、デフォルト値は 0 です。

dmatest コマンドを実行するには、次のコマンドを実行します。

$ xbutil dmatest

次に、DDR バンク 0、1、2、および 3 に関する xclbin コマンドの出力例を示します。

INFO: Found total 2 card(s), 2 are usable
bank0 -> bank1 M2M bandwidth: 12050.5 MB/s 
bank0 -> bank2 M2M bandwidth: 12074.3 MB/s 
bank0 -> bank3 M2M bandwidth: 12082.9 MB/s 
bank1 -> bank2 M2M bandwidth: 12061.8 MB/s 
bank1 -> bank3 M2M bandwidth: 12105.2 MB/s 
bank2 -> bank3 M2M bandwidth: 12065.8 MB/s 
INFO: xbutil m2mtest succeeded.

mem --read

mem --read コマンドは、指定したメモリ アドレスから指定したバイト数を読み出し、その内容を出力ファイルに書き込みます。
  • -a <address> (オプション): 開始アドレスを 16 進数で指定します。デフォルト アドレスは 0x0 です。
  • -i <size>: メモリ書き込みのサイズをバイト数で指定します。
  • -o <file_name> (オプション): 出力ファイルの名前を指定します。デフォルトの出力ファイル名は memread.out です。

mem --read コマンドを実行してメモリ アドレス 0x0 から 256 バイトデータを読み出すには、次のコマンドを入力します。

$ xbutil mem --read -a 0x0 -i 256 -o read.out

次に出力例を示します。

INFO: Found total 1 card(s), 1 are usable
INFO: Reading from single bank, 256 bytes from DDR address 0x4000000000
INFO: Read size 0x100 B. Total Read so far 0x100
INFO: Read data saved in file: read.out; Num of bytes: 256 bytes 
INFO: xbutil mem succeeded.

mem --write

mem --write コマンドは、定義した値を指定したメモリの位置およびサイズに書き込みます。
  • -a <address> (オプション): 開始アドレスを 16 進数で指定します。デフォルト アドレスは 0x0 です。
  • -i <size>: メモリ書き込みのサイズをバイト数で指定します。
  • -e <pattern>: メモリに書き込むパターンを指定します。

メモリ アドレス 0x0 から 256 バイトに値 0xaa を書き込むには、次のコマンドを入力します。

$ xbutil mem --write -a 0x0 -i 256 -e 0xaa

次に出力例を示します。

INFO: Found total 1 card(s), 1 are usable
INFO: Writing to single bank, 256 bytes from DDR address 0x4000000000
INFO: Writing DDR with 256 bytes of pattern: 0xaa from address 0x4000000000
INFO: xbutil mem succeeded.

p2p

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

p2p コマンドは、P2P 機能をイネーブル/ディスエーブルにし、現在の設定をチェックするために使用します。P2P 設定は、ウォーム リブートの後も保持されます。P2P をイネーブル/ディスエーブルにするには、ルート権限が必要です。

詳細は、PCIe ピアツーピア サポートを参照してください。

program

program コマンドは、カードのプログラマブル領域に xclbin バイナリをダウンロードします。

次のオプションがあります。

  • -d <card_id> (オプション): ターゲット カード ID を指定します。指定しない場合、デフォルト値は 0 です。
  • -p <xclbin> (必須): カードにダウンロードする xclbin バイナリ ファイルを指定します。

たとえばカード ID 1 に filter.xclbin をプログラムするには、次のコマンドを使用します。

$ xbutil program -d 1 -p filter.xclbin

カードに xclbin が正しくダウンロードされると、次のような出力が表示されます。

INFO: Found total 1 card(s), 1 are usable
INFO: xbutil program succeeded.

query

query コマンドは、指定したカードの詳細なステータス情報を表示します。次のオプションがあります。
  • -d <card_id> (オプション): ターゲット カードを指定します。指定しない場合、デフォルト値は 0 です。
たとえばカード ID 0 をクエリするには、次のコマンドを実行します。
xbutil query -d 0

次に、出力例を示します。出力は、内容がわかりやすいように 2 つのセクションに分けられています。

最初のセクションには、プラットフォーム名、ベンダー情報、インストールされている DDR、クロック、PCIe 情報など、インストールされているカードの詳細が示されます。
INFO: Found total 1 card(s), 1 are usable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
System Configuration
OS name:	Linux
Release:	3.10.0-862.el7.x86_64
Version:	#1 SMP Fri Apr 20 16:44:24 UTC 2018
Machine:	x86_64
Glibc:		2.17
Distribution:	CentOS Linux 7 (Core)
Now:		Tue Oct 22 09:42:36 2019
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XRT Information
Version:	2.3.1148
Git Hash:	4416230140a8e15d3ca9f56dc6e7522c65968c30
Git Branch:	master
Build Date:	2019-09-04 22:53:35
XOCL:		2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
XCLMGMT:	2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Shell                           FPGA                            IDCode
xilinx_u200_xdma_201830_2       xcu200-fsgd2104-2-e             0x14b37093
Vendor          Device          SubDevice       SubVendor       SerNum          
0x10ee          0x5001          0x000e          0x10ee          2129048BF05Y    
DDR size        DDR count       Clock0          Clock1          Clock2          
64 GB           4               300             500             0               
PCIe            DMA chan(bidir) MIG Calibrated  P2P Enabled     
GEN 3x16        2               true            false           
その後にカードの消費電力と温度情報が示されます。
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Temperature(C)
PCB TOP FRONT   PCB TOP REAR    PCB BTM FRONT   
51              42              51              
FPGA TEMP       TCRIT Temp      FAN Presence    FAN Speed(RPM)  
50              50              A               1163            
QSFP 0          QSFP 1          QSFP 2          QSFP 3          
0               0               0               0               
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Electrical(mV|mA)
12V PEX         12V AUX         12V PEX Current 12V AUX Current 
12257           12197           1176            1001            
3V3 PEX         3V3 AUX         DDR VPP BOTTOM  DDR VPP TOP     
3356            3350            2500            2500            
SYS 5V5         1V2 TOP         1V8 TOP         0V85            
5510            1198            1844            858             
MGT 0V9         12V SW          MGT VTT         1V2 BTM         
910             12173           1203            1203            
VCCINT VOL      VCCINT CURR     DNA             VCC3V3 VOL      
851             13220                           0               
3V3 PEX CURR    VCC0V85 CURR    HBM1V2 VOL      VPP2V5 VOL      
0               0               0               0               
VCCINT BRAM VOL 
0               
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Card Power(W)
26
注記: HBM 温度は、.xclbin ファイルがターゲット プラットフォームに読み込まれた場合にのみレポートされます。
消費電力および熱情報の後、「Firewall Status」にハードウェアでエラーが検出されたときの情報が示されます。これには、タイムスタンプとファイアウォールのレベルも含まれます。ファイアウォールには、AXI Firewall が作動する で説明されるように 3 つのレベルがあります。次の例では、ファイアウォール エラーは検出されていません。
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Firewall Last Error Status
Level 0 : 0x0(GOOD)
ECC Error Status
Tag     Errors      CE Count  UE Count  CE FFA              UE FFA              
bank1   (None)      0         0         0x0                 0x0                 
その後にメモリのトポロジと DMA 転送メトリクスが示され、ストリーミング転送が続きます。DMA メトリクスには、ホストとカード間のデータ転送が含まれます。ホストからカードへの転送は h2c、カードからホストへの転送は c2h と示されます。
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Memory Status
     Tag         Type        Temp(C)  Size    Mem Usage       BO count
[ 0] bank0       **UNUSED**  39       16 GB   0 Byte          0       
[ 1] bank1       MEM_DDR4    42       16 GB   0 Byte          0       
[ 2] bank2       **UNUSED**  46       16 GB   0 Byte          0       
[ 3] bank3       **UNUSED**  43       16 GB   0 Byte          0       
[ 4] PLRAM[0]    **UNUSED**  N/A      128 KB  0 Byte          0       
[ 5] PLRAM[1]    **UNUSED**  N/A      128 KB  0 Byte          0       
[ 6] PLRAM[2]    **UNUSED**  N/A      128 KB  0 Byte          0       
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DMA Transfer Metrics
Chan[0].h2c:  32930 MB
Chan[0].c2h:  25317 MB
Chan[1].h2c:  994 MB
Chan[1].c2h:  11612 KB
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Streams
     Tag         Flow ID  Route ID Status   Total (B/#)     Pending (B/#)
xclbin ID と含まれる計算ユニット (CU) が表示されます。各 CU に対して、名前、PCIe BAR アドレス、およびステータス (IDLE、START、または DONE) が示されます。次の出力には、xclbin ID および IDLE ステータスの 2 つの CU が示されています。
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Xclbin UUID
02954196-6dd8-4281-9fb8-ddad17c7a6b1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Compute Unit Status
CU[ 0]: runOnfpga:runOnfpga_1           @0x18c0000         (IDLE)
CU[ 1]: runOnfpga:runOnfpga_2           @0x18d0000         (IDLE)
次は、コマンドが正しく実行された場合の出力例です。
INFO: xbutil query succeeded.

reset

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

reset コマンドは、カードのプログラマブル領域をリセットします。この領域のすべての実行中、演算ユニットは停止し、リセットされます。

次のオプションがあります。

  • -d <card_id> (オプション): ターゲット カード ID 番号を指定します。指定しない場合、デフォルト値は 0 です。

次のコマンドを入力します。

$ xbutil reset

リセットが正しく完了すると、次のような出力が表示されます。

INFO: Found total 1 card(s), 1 are usable
INFO: xbutil reset succeeded.

scan

xbutil scan コマンドは、システムをスキャンし、ユーザー プラットフォームに関連するドライバーおよびシステム情報を表示します。xbmgmt flash コマンドで説明したように、ターゲット プラットフォームを使用して設定されたコアクセラレータ カードの情報をレポートします。

注記: xbutil scan コマンドは、元の工場出荷時の設定や、xbmgmt flash --factory_reset オプションを使用して工場出荷時の設定に復元したカードはレポートしません。

xbutil scan コマンドにオプションはなく、次のように実行できます。

$ xbutil scan

次に出力例を示します。

INFO: Found total 1 card(s), 1 are usable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
System Configuration
OS name:	Linux
Release:	3.10.0-862.el7.x86_64
Version:	#1 SMP Fri Apr 20 16:44:24 UTC 2018
Machine:	x86_64
Glibc:		2.17
Distribution:	CentOS Linux 7 (Core)
Now:		Tue Oct 22 09:44:17 2019
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XRT Information
Version:	2.3.1148
Git Hash:	4416230140a8e15d3ca9f56dc6e7522c65968c30
Git Branch:	master
Build Date:	2019-09-04 22:53:35
XOCL:		2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
XCLMGMT:	2.3.1148,4416230140a8e15d3ca9f56dc6e7522c65968c30
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 [0]:[0000:03:00.1]:xilinx_u200_xdma_201830_2(ts=0x5d1211e8):user(inst=129)

status

status コマンドは、アクセラレータ カード上のデバッグ IP のタイプと数を表示します。
$ xbutil status
次に、コマンドとその出力例を示します。
INFO: Found total 1 card(s), 1 are usable
Number of IPs found: 9
IPs found [<ipname>(<count>)]: aim(5) tracefunnel(1) monitorfifolite(1) monitorfifofull(1) accelmonitor(1) 
Run 'xbutil status' with option --<ipname> to get more information about the IP
INFO: xbutil status succeeded.

使用可能な IP のリストは、アクセラレータ カードで使用するためにコンパイルされた xclbin ファイルによって決まります。現在のところ、このコマンドでは Vitis™ パフォーマンス モニター、軽量 AXI プロトコル チェッカー (LAPC) デバッグ IP、トレース IP のステータスを読み込んでレポートできます。デザインにパフォーマンス モニター カウンター (AM、AIM、ASM) および LAPC を追加する方法は、アプリケーションのハングをデバッグするための手法 を参照してください。

使用可能な IP のリストには、次が含まれます。
  • Accelerator Monitor (AM) - 計算ユニットの実行をカウントおよびトレース。パフォーマンス モニターを追加するには、Vitis コンパイラの一般オプション で説明するように --profile_kernel オプションを使用します。
  • AXI Interface Monitor (AIM) - AXI MM 接続のトランザクションをカウントおよびトレース。
  • AXI Streaming Monitor (ASM) - AXI ストリームのトランザクションをカウントおよびトレース。
  • Lightweight AXI Protocol Monitor (LAPC) - AXI-MM のプロトコル チェック。プロトコル チェッカーを使用するには、Vitis コンパイラの一般オプション で説明するように --dk オプションを使します。
  • Streaming Protocol Checker (SPC) - AXI ストリームのプロトコル チェック。
  • Trace Funnel - すべてのモニターからトレース イベントを収集。これがあると、コンパイル中に --profile_kernel オプション (Vitis コンパイラの一般オプション を参照) を使用するとイネーブルになり、ランタイム中に timeline_trace オプション (xrt.ini ファイル を参照) を使用するとイネーブルになります。
  • FIFO Lite - トレース イベントを格納する PL FIFO の制御。これがあると、コンパイルおよびランタイム中にトレースがイネーブルになり、コンパイル中に --trace_memory オプション (Vitis コンパイラの一般オプション を参照) を使用すると、メモリ オフロードが PL の FIFO になるように指定されます。トレースは、xrt.ini オプションでオンにできます。
  • FIFO Full - トレース イベントを格納する PL FIFO のデータ オフロード。これがあると、コンパイルおよびランタイム中にトレースがイネーブルになり、コンパイル中に --trace_memory オプションを使用すると、メモリ オフロードが PL の FIFO になるように指定されます。
  • TS2MM - トレース イベントを取り込み、メモリ リソース (DDR、HBM、PLRAM) にオフロード。これがあると、コンパイルおよびランタイム中にトレースがイネーブルになり、コンパイル中に --trace_memory オプション (Vitis コンパイラの一般オプション を参照) を使用すると、メモリ オフロードがメモリ リソースになるように指定されます。
次のコマンド構文を使用すると、特定の IP のステータスを取得できます。
$ xbutil status --<ipname>

使用可能なオプションは次のとおりです。引数を指定しないで実行すると、使用可能なデバッグ IP のリストが表示されます。

  • --<ipname> (オプション): 特定の IP のステータスを返します。このオプションは、xclbin が必要なプロファイリング オプションでコンパイルされた場合にのみ使用できます。

次に、--aim オプションを使用した場合の出力例を示します。

$ xbutil status --aim
INFO: Found total 1 card(s), 1 are usable
AXI Interface Monitor Counters
Region or CU     Type or Port            Write Bytes       Write Trans.      Read Bytes        Read Tranx.       Outstanding Cnt   Last Wr Addr      Last Wr Data      Last Rd Addr      Last Rd Data    
runOnfpga_1      m_axi_maxiport0-DDR[1]  0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
runOnfpga_1      m_axi_maxiport1-DDR[1]  0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Memory to Memory        0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Host to Device          0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
shell            Peer to Peer            0                 0                 0                 0                 0                 0x0               0x0               0x0               0x0             
INFO: xbutil status succeeded.

xclbin にデバッグ IP がない場合は、出力は次のようになります。

INFO: Found total 1 card(s), 1 are usable
INFO: Failed to find any debug IPs on the platform. Ensure that a valid bitstream with debug IPs (SPM, LAPC) is successfully downloaded. 
INFO: xbutil status succeeded.

top

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

top コマンドは、メモリ トポロジおよび DMA 転送メトリクス、計算ユニットの使用量データを含むカードの統計を出力します。このコマンドは Linux の top コマンドと似ており、実行すると、ターミナル ウィンドウに q を入力するまで操作が継続実行されます。

次のオプションがあります。

  • -i <seconds> (オプション): 更新レートを秒で指定します。デフォルトは 1 秒です。

top コマンドを更新レート 2 秒で実行するには、次のコマンドを入力します。

$ xbutil top -i 2

次のような出力が表示されます。

Device Memory Usage
 [0] bank0      [                                                    0.00% ]
 [1] bank1      [                                                    0.00% ]
 [2] bank2      [                                                    0.00% ]
 [3] bank3      [                                                    0.00% ]


Power
34.8W

Mem Topology                                    Device Memory Usage
Tag             Type        Temp        Size    Mem Usage       BO nums
 [0] bank0      MEM_DDR4    41 C        16 GB   0 Byte          0
 [1] bank1      MEM_DDR4    42 C        16 GB   0 Byte          0
 [2] bank2      MEM_DDR4    54 C        16 GB   0 Byte          0
 [3] bank3      MEM_DDR4    49 C        16 GB   0 Byte          0

Total DMA Transfer Metrics:
  Chan[0].h2c:  4160 MB
  Chan[0].c2h:  8448 MB
  Chan[1].h2c:  4160 MB
  Chan[1].c2h:  4 GB

###############################################################################

Compute Unit Usage:
CU[@0x1800000] : 68
CU[@0x1810000] : 68

############################################################################### 

validate

重要: このオプションはエンベデッド プロセッサ プラットフォームでは使用できません。

validate コマンドは、インストールされているカードに関する読みやすいサマリを生成します。次のテストを実行して正しくインストールされていることを検証します。

  1. 検出されたカードを検証します。
  2. PCI Express リンク ステータスをチェックします。
  3. カード上のカーネルを検証します。
  4. 次のデータ帯域幅テストを実行します。
    1. DMA テスト: PCI Express を介したホストと FPGA DDR 間のデータ転送。
    2. DDR テスト: カーネルと FPGA DDR 間のデータ転送。

次のオプションがあります。

  • -d <card_id> (オプション): ターゲット カード ID を指定します。デフォルトでは、システムにインストールされているすべてのカードが検証されます。

たとえばカード ID 0 に対して validate を実行するには、次のコマンドを入力します。

$ xbutil validate -d 0

次に、表示される情報の例を示します。


INFO: Found 1 cards

INFO: Validating card[0]: xilinx_u250_xdma_201820_1
INFO: Checking PCIE link status: PASSED
INFO: Starting verify kernel test: 
INFO: verify kernel test PASSED
INFO: Starting DMA test
Host -> PCIe -> FPGA write bandwidth = 11736.3 MB/s
Host <- PCIe <- FPGA read bandwidth = 12190.3 MB/s
INFO: DMA test PASSED
INFO: Starting DDR bandwidth test: ............
Maximum throughput: 45475.441406 MB/s
INFO: DDR bandwidth test PASSED
INFO: Card[0] validated successfully.

INFO: All cards validated successfully.