xbutil (Xilinx Board Utility)

The clock command 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 <card_id> (Optional): Specifies the target card. Default = 0 if not specified.
• -f <clock1_freq> (Required): Specifies clock frequency (in MHz) for the first clock. All platforms have this clock.
• -g <clock2_freq> (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.

The dmatest command performs throughput data transfer tests between the host machine and global memory on a specified card. Note, it is necessary to download an xclbin on the card prior to running dmatest, else running this command returns an error. The dmatest command only performs throughput tests on those DDR banks accessed by the xclbin downloaded 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 1024 and -b 0x400 set the block size to 1024 KB.

To run the dmatest command, enter the following:

$ xbutil dmatest

An example of the command output with an xclbin using 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 <card_id> (Optional): Specifies the target card ID, else flashes all cards if not specified.
• -a <shell_name>: Specifies the name of the deployment shell to program the card or you can set the shell_name to all. This will attempt to flash all the cards in the system with the installed deployment shell.
• -t <timestamp>: Specifies the timestamp associated with the shell_name.

For example, to flash the card with a deployment shell called xilinx_u200_xdma_201820_1 and timestamp 1535712995, 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 

The flash scan command returns the current firmware installed on both the card and the system.

It has the following option:

To run the flash scan command, 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]

The help command displays the available xbutil commands.

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

There are no options for this command.

To run the list command, enter the following:

$ xbutil list

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

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

• -a <address> (Optional): Specifies the starting address (in hexadecimal). Default address is 0x0.
• -i <size>: Specifies the size of memory read (in bytes).
• -o <file_name> (Optional): Specifies the output file name. Default output file is memread.out.

To run the mem --read command to read 256 bytes of data starting at memory address 0x0, 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 <address> (Optional): Specifies the starting address (in hexadecimal). Default address is 0x0.
• -i <size>: Specifies the size of memory read (in bytes).
• -e <pattern>: Specifies the pattern (in bytes) to write to memory.

To write the value 0xaa to 256 locations starting at memory address 0x0, 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 <card_id> (Optional): Specifies the target card ID. Default = 0 if not specified.
• -p <xclbin> (Required): Specifies the xclbin binary file to download to the card.

For example, to program the filter.xclbin file to card ID one, you would use the following command:

$ xbutil program -d 1 -p filter.xclbin

This output is displayed after the xclbin has 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 <card_id> (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, and PCIe information.

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 the SDAccel Environment Debugging Guide (UG1281). In the below output, there are no detected firewall errors.

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

The xclbin ID along with the contained Compute Units (CU) are displayed. For each CU, it displays the name, PCIe BAR address, and the status, which can be IDLE, START, and DONE. The output below shows the xclbin ID 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 by h2c, while card to host transfer are defined by c2h.

###############################################################################
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 <card_id> (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 the scan command, 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 the xclbin was compiled with the necessary profiling options.
• --lapc (Optional): Returns the values of the violation codes detected by the LAPC. This option is only applicable if xclbin was 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 [<ipname>(<count>)]: spm(2) 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.

An example output using the --spm option 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 the xclbin, 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 <seconds> (Optional): Refreshes rate (in seconds). Default is 1 second.

To run top with 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. Checks PCI Express link 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 through PCI Express.
   2. DDR test: Data transfers between kernels and FPGA DDR.

It has the following option:

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

For example, to run the validate command 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.