xbutil (Xilinx Board Utility)

Theclockcommand allows you to change the clock frequencies driving the computing units. Note that your compute units must be capable or running at the specified clock. You can modify both clock1 and clock2 using this command.

It has the following options:

• -d (Optional): Specifies the target card. Default = 0 if not specified.
• -f (Required): Specifies clock frequency (in MHz) for the first clock. All platforms have this clock.
• -g (Optional): Specifies clock frequency (in MHz) for the second clock. Some platforms may not have this clock.

For example, to change clock1 in card 0 to 100 MHz, run the following command:

$ xbutil clock -d 0 -f 100

Similarly, to change two clocks in card 0, such that clock1 is set to 200 MHz and clock2 is set to 250 MHz, run this command:

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

The following example is an output after running this command:

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

Thedmatestcommand performs throughput data transfer tests between the host machine and global memory on a specified card. Note, it is necessary to download anxclbinon the card prior to runningdmatest, else running this command returns an error. Thedmatestcommand only performs throughput tests on those DDR banks accessed by thexclbindownloaded to the card.

The command has the following options:

• -d card_id(Optional): Specifies the target card. Default = 0 if not specified.
• -b blocksize(Optional): Specifies the test block size (in KB). Default = 65536 (KB) if not specified. The block size can be specified in both decimal or hexadecimal formats. For example, both-b 1024and-b 0x400set the block size to 1024 KB.

To run thedmatestcommand, enter the following:

$ xbutil dmatest

An example of the command output with anxclbinusing DDR banks 0, 1, 2, and 3 is shown below:

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.

It has the following options:

• -d (Optional): Specifies the target card ID, else flashes all cards if not specified.
• -a : Specifies the name of the deployment shell to program the card or you can set theshell_nametoall. This will attempt to flash all the cards in the system with the installed deployment shell.
• -t : Specifies the timestamp associated with theshell_name.

For example, to flash the card with a deployment shell calledxilinx_u200_xdma_201820_1and timestamp1535712995, enter the following command:

xbutil flash -a xilinx_u200_xdma_201820_1 -t 1535712995

Below is an example of the output after the card has been flashed:

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

Theflash scancommand returns the current firmware installed on both the card and the system.

It has the following option:

To run theflash scancommand, enter the following:

xbutil flash scan

Card [0] Card BDF: 0000:06:00.1 Card type: u200 Flash type: SPI DSA running on FPGA: xilinx_u200_xdma_201820_1,[TS=0x000000005b891ee3],[BMC=1.8] DSA package installed in system: xilinx_u200_xdma_201820_1,[TS=0x000000005b891ee3],[BMC=1.8]

Thehelpcommand displays the availablexbutilcommands.

The output format displays the following three items in this order:

There are no options for this command.

To run thelistcommand, enter the following:

$ xbutil list

In this example, the card ID is 0, the BDF is 65:00.0, and the shell name isxilinx_u250_xdma_201820_1.

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

• -a
  (Optional): Specifies the starting address (in hexadecimal). Default address is0x0.
• -i : Specifies the size of memory read (in bytes).
• -o (Optional): Specifies the output file name. Default output file ismemread.out.

To run themem --readcommand to read 256 bytes of data starting at memory address0x0, enter the following:

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

This is an example output:

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.

• -a
  (Optional): Specifies the starting address (in hexadecimal). Default address is0x0.
• -i : Specifies the size of memory read (in bytes).
• -e : Specifies the pattern (in bytes) to write to memory.

To write the value0xaato 256 locations starting at memory address0x0, enter the following:

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

This is an example output:

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.

It has the following options:

• -d (Optional): Specifies the target card ID. Default = 0 if not specified.
• -p (Required): Specifies thexclbinbinary file to download to the card.

For example, to program thefilter.xclbinfile to card ID one, you would use the following command:

$ xbutil program -d 1 -p filter.xclbin

This output is displayed after thexclbinhas been successfully downloaded to the card:

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

It has the following option:

• -d (Optional): Specifies the target card. Default = 0 if not specified.

For example, to query card ID zero, run the following command:

xbutil query -d 0

An example of the output is given below. The output has been divided into separate sections to better describe the content.

The first section gives details of the installed card including the shell name (DSA name), vendor information, installed DDR, clock, andPCIeinformation.

INFO: Found total 1 card(s), 1 are usable DSA name xilinx_u250_xdma_201820_1 Vendor Device SubDevice SubVendor XMC fw version 10ee 5004 000e 10ee 2018203 DDR size DDR count OCL Frequency Clock0 Clock1 64 GB 4 300 MHz 500 MHz PCIe DMA bi-directional threads MIG Calibrated GEN 3x16 2 true

Card power and thermal information are given next.

############################################################################### Power 34.9W PCB TOP FRONT PCB TOP REAR PCB BTM FRONT 33 C 28 C 32 C FPGA Temp TCRIT Temp Fan Speed 35 C 33 C 1100 rpm 12V PEX 12V AUX 12V PEX Current 12V AUX Current 11.9V 0.45V 2928mA 32mA 3V3 PEX 3V3 AUX DDR VPP BOTTOM DDR VPP TOP 3.36V 3.31V 2.50V 2.50V SYS 5V5 1V2 TOP 1V8 TOP 0V85 5.49V 1.20V 1.82V 0.85V MGT 0V9 12V SW MGT VTT 0.90V 11.9V 1.20V VCCINT VOL VCCINT CURR 0.85V 10094mA

The firewall provides information when an error has been detected in hardware. This includes a timestamp and the level of the firewall. The firewall has three levels. For more information, see theSDAccel Environment Debugging Guide(UG1281). In the below output, there are no detected firewall errors.

Firewall Last Error Status: Level 0: 0x0 (GOOD)

ThexclbinID along with the contained Compute Units (CU) are displayed. For each CU, it displays the name,PCIeBAR address, and the status, which can be IDLE, START, and DONE. The output below shows thexclbinID and two CUs both with IDLE status.

Xclbin ID: 0x5b996b13 Compute Unit Status: CU[0]: bandwidth1:kernel_1@0x1800000 (IDLE) CU[1]: bandwidth2:kernel_2@0x1810000 (IDLE)

The memory topology along with the DMA transfer metrics are provided next. The DMA metrics include the transfer of data between the host and card. Host to card transfers are indicated byh2c, while card to host transfer are defined byc2h.

############################################################################### Mem Topology Device Memory Usage Tag Type Temp Size Mem Usage BO nums [0] bank0 MEM_DDR4 31 C 16 GB 0 Byte 0 [1] bank1 MEM_DDR4 31 C 16 GB 0 Byte 0 [2] bank2 MEM_DDR4 33 C 16 GB 0 Byte 0 [3] bank3 MEM_DDR4 31 C 16 GB 0 Byte 0 [4] PLRAM[0] **UNUSED** Not Supp 128 KB 0 Byte 0 [5] PLRAM[1] **UNUSED** Not Supp 128 KB 0 Byte 0 [6] PLRAM[2] **UNUSED** Not Supp 128 KB 0 Byte 0 [7] PLRAM[3] **UNUSED** Not Supp 128 KB 0 Byte 0 Total DMA Transfer Metrics: Chan[0].h2c: 49888 MB Chan[0].c2h: 22656 MB Chan[1].h2c: 8096 MB Chan[1].c2h: 22592 MB

Finally, here is the successful output:

INFO: xbutil query succeeded.

It has the following options:

• -d (Optional): Specifies the target card ID number. Default = 0 if not specified.
• -h(Optional): Performs a hot-reset which resets the card and not just the programmable region. The card is still recognized by the operating system. It is recommended to always use this option.

Enter the following command:

$ xbutil reset

This output is displayed after the reset has been successfully completed:

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

It has no options.

To run thescancommand, enter the following:

$ xbutil scan

An example of the output is shown below:

Linux:4.15.0-33-generic:#36~16.04.1-Ubuntu SMP Wed Aug 15 17:21:05 UTC 2018:x86_64 Distribution: Ubuntu 16.04.5 LTS GLIBC: 2.23 --- XILINX_OPENCL="" LD_LIBRARY_PATH="/opt/xilinx/xrt/lib:" --- [0]mgmt:[65:00.1]:0x5004:0x000e:[xclmgmt:2018.3.2:25857] [0]user:[65:00.0]:0x5005:0x000e:[xocl_xdma:2018.3.8:128]

Below are the available options. If you are running without arguments, it shows the list of available debug IPs.

• --spm(Optional): Returns the value of the SPM counters. This option is only applicable if thexclbinwas compiled with the necessary profiling options.
• --lapc(Optional): Returns the values of the violation codes detected by the LAPC. This option is only applicable ifxclbinwas compiled with necessary option to insert AXI protocol checkers at the AXI ports of the compute units.

An example output of the following command is shown below:

$ xbutil status

INFO: Found total 1 card(s), 1 are usable Number of IPs found: 6 IPs found [()]: spm(2) tracefunnel(1) monitorfifolite(1) monitorfifofull(1) accelmonitor(1) Run 'xbutil status' with option -- to get more information about the IP INFO: xbutil status succeeded.

An example output using the--spmoption is shown below:

$ xbutil status --spm

INFO: Found total 1 card(s), 1 are usable SDx Performance Monitor Counters CU Name AXI Portname Write Bytes Write Trans. interconnect_aximm_host M00_AXI 8192 16 simple_1 M_AXI_GMEM 4096 1024

CU Name Read Bytes Read Trans. Outstanding Cnt interconnect_aximm_host 4096 1 0 simple_1 4096 1024 0

CU Name Last Wr Addr Last Wr Data Last Rd Addr interconnect_aximm_host 0x0 0 0xe00 simple_1 0x0 0 0xffc

CU Name Last Rd Data interconnect_aximm_host 1483476076 simple_1 1062897 INFO: xbutil status succeeded.

When there are no debug IPs in thexclbin, you will see a similar output as shown below:

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.

It has the following option:

• -i (Optional): Refreshes rate (in seconds). Default is 1 second.

To runtopwith a refresh rate of two seconds, enter the following command:

$ xbutil top -i 2

An output similar to the one below is displayed:

Device Memory Usage [0] bank0 [ 0.00% ] [1] bank1 [ 0.00% ] [2] bank2 [ 0.00% ] [3] bank3 [ 0.00% ] [4] PLRAM0 [ 0.00% ] [5] PLRAM1 [ 0.00% ] [6] PLRAM2 [ 0.00% ] Power 25.0W Mem Topology Device Memory Usage Tag Type Temp Size Mem Usage Bo nums [0] bank0 **UNUSED** 32 C 16 GB 0 Byte 0 [1] bank1 MEM_DDR4 37 C 17 GB 0 Byte 0 [2] bank2 **UNUSED** 34 C 18 GB 0 Byte 0 [3] bank3 **UNUSED** 32 C 19 GB 0 Byte 0 [4] PLRAM0 **UNUSED** Not Supp 128 KB 0 Byte 0 [5] PLRAM1 **UNUSED** Not Supp 128 KB 0 Byte 0 [6] PLRAM2 **UNUSED** Not Supp 128 KB 0 Byte 0 Total DMA Transfer Metrics: Chan[0].h2c: 0 Byte Chan[0].c2h: 0 Byte Chan[1].h2c: 0 Byte Chan[1].c2h: 0 Byte

1. Validates the card found.
2. ChecksPCI Expresslink status.
3. Runs a verify kernel on the card.
4. Performs the following data bandwidth tests:
   1. DMA test: Data transfers between host and FPGA DDR throughPCI Express.
   2. DDR test: Data transfers between kernels and FPGA DDR.

It has the following option:

• -d (Optional): Specifies the target card ID. Default validates all the cards installed in the system.

For example, to run thevalidatecommand on card ID = 0, enter the following:

$ xbutil validate -d 0

An example of the returned information is shown below:

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.