query - 2021.1 English

Important: This option cannot be used with embedded processor platforms.

The query command returns detailed card status information in human readable format. See dump for output in JSON format.

It has the following command line format:

xbutil query [-d card [-r region]]

The following table lists the available options.

Table 1. xbutil query Command Options
Option	Description	Required
`-d <card>`	Specifies the target card. <card> can be specified as either the card_id or Bus:Device:Function (BDF). Defaults to card_id = 0 if not specified. Note: Use the `xbutil scan` command to display both the card_id and BDF for installed cards.	N
`-r <region>`	Deprecated and has no effect. Option will be removed in subsequent release.	N

There is a significant amount of information returned. An example of the output is given below. The output has been divided into separate sections to better describe the content.

System Configuration

Table 2. System Configuration Field Definition
Field	Description
OS Name	Name of the OS running on the machine
Release	OS release number
Version	OS Version
Machine	CPU-based architecture
Glibc	GLIBC version installed
Distribution	Distribution
Now	Current date and time

An example of the system configuration is shown below:

System Configuration
OS name:    Linux
Release:    4.15.0-74-generic
Version:    #83~16.04.1-Ubuntu SMP Wed Dec 18 04:56:23 UTC 2019
Machine:    x86_64
Glibc:      2.23
Distribution:   Ubuntu 16.04.6 LTS
Now:        Wed Jan 22 15:30:36 2020

XRT Information

Table 3. XRT Field Definition
Field	Description
Version	XRT version
Git Hash	Associated GIT hash
Git Branch	Associated GIT branch
Build Date	XRT build date
XOCL	XOCL version
XCLMGMT	XCLMGMT version

XRT Information
Version:    2.3.1301
Git Hash:   192e706aea53163a04c574f9b3fe9ed76b6ca471
Git Branch: 2019.2
Build Date: 2019-10-24 20:04:29
XOCL:       2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471
XCLMGMT:    2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471

Card Platform (Shell) Information

Table 4. Card Platform (Shell) Field Definition
Field	Description
Shell	Platform installed on the card
FPGA	FPGA name
IDCode	ID code of platform
Vendor	Vendor ID
Device	Device ID
SubDevice	SubDevice ID
SubVendor	SubVendor ID
SerNum	Unique card serial number
DDR Size	Total amount of DDR RAM available on the card in GB
DDR Count	Total number of DDR DIMMs installed on the card
Clock0	Clock0 frequency in MHz
Clock1	Clock1 frequency in MHz
Clock2	Clock2 frequency in MHz
PCIe	Trained PCIe link status
DMA chan(bidir)	Number of DMA channels on the card
MIG Calibrated	When TRUE MIG has been calibrated, FALSE indicates the MIG has not been calibrated.
P2P Enabled	Returns status of P2P. Status will be one of the following: true: P2P is enabled false: P2P is disabled no_iomem: P2P is enabled in device but system could not allocate I/O memory, warm reboot is needed
OEM ID	ID used by OEMs
Interface UUID	A unique identifier which can be used to determine whether partial bitstreams containing the various partitions of the platform are logically and physically compatible with each other.
Logic UUID	A unique identifier which can be used to determine whether partial bitstreams containing the various partitions of the platform are logically and physically compatible with each other.

This is an example output of the card information:

Shell                         FPGA                         IDCode
xilinx_u50_gen3x16_xdma_201920_3                           0x14b77093
Vendor        Device          SubDevice       SubVendor    SerNum         
0x10ee        0x5021          0x000e          0x10ee       00501201A030   
DDR size      DDR count       Clock0          Clock1       Clock2         
0 Byte        0               250             500          450            
PCIe          DMA chan(bidir) MIG Calibrated  P2P Enabled  OEM ID         
GEN 3x16      2               true            false        0x0            
Interface UUID
862c7020a250293e32036f19956669e5
Logic UUID
f465b0a3ae8c64f619bc150384ace69b
DNA

Temperature

Card power and thermal information are given next. Temperatures are reported in Celsius.

Table 5. Temperature Field Definition
Field	Description
PCB Top Front	Temperature at the top front of the PCB in Celsius
PCB Top Rear	Temperature at the top rear of the PCB in Celsius
PCB BTM Front	Temperature at the bottom front of the PCB in Celsius
FPGA Temp	FPGA core temperature in Celsius
TCRIT Temp	Critical temperature in Celsius of the fan controller. Present for both active and passive cards.
Fan Presence	Represents the presence of a fan on the card. A – Active cooling. Fan is present on card. P – Passive cooling. Fan is not present on the card and must be cooled by host server.
Fan Speed	Fan speed (RPM). Returned as N/A for passive cards.
QSFP 0,1,2,3	Temperature in Celsius of the QSFP module

An example of the temperature output is given below:

Temperature(C)
PCB TOP FRONT   PCB TOP REAR    PCB BTM FRONT  
42              37              42             
FPGA TEMP       TCRIT Temp      FAN Presence    FAN Speed(RPM) 
44              42              A               1108           
QSFP 0          QSFP 1          QSFP 2          QSFP 3         
0               0               0               0

Electrical

This provides various voltage (mV) and current (mA) readings.

Table 6. Electrical Field Definition
Field	Description
12V PEX	Voltage measurement (12V nominal) from the 12V Power source from the PCIe connector.
12V AUX	Voltage measurement (12V nominal) from the 12V, 6 or 8-pin PCIe AUX power cable.
12V PEX Current	Current measurement of the power drawn by the PCIe connector.
12V AUX Current	Current measurement of the power drawn by the 6 or 8-pin PCIe AUX power cable.
3V3 PEX	Voltage measurement (3.3V nominal) of the 3.3V Power source from the PCIe connector.
3V3 AUX	Voltage measurement (3.3V nominal) of the 3.3V AUX Power sourced from the PCIe connector.
DDR VPP BOTTOM	Voltage measurement (2.5V nominal) for powering the onboard VPP for the DDR4 parts on the lower portion of the card.
DDR VPP TOP	Voltage measurement (2.5V nominal) for powering the onboard VPP for the DDR4 parts on the upper portion of the card.
SYS 5V5	Voltage measurement (5.5V nominal) used for powering the onboard VCC_INT regulators. Only on U2XX cards.
1V2 TOP	Voltage measurement (1.2V nominal) for powering the onboard VDD for the DDR4 parts on the upper portion of the card.
1V8 TOP	Voltage measurement (1.8V nominal) for powering the onboard VCCAUX, VCCAUXIO, and MGTAVVCAUX regulator used by the FPGA.
0V85	Voltage measurement (0.85V nominal) of the onboard VCCINTIO and VCCBRAM regulator used by the FPGA.
MGT 0V9	Voltage measurement (0.9V nominal) of the onboard MGTAVCC regulator for the GTYs used by the FPGA.
12V SW	Voltage measurement (12V nominal) of the 12V, 6 or 8-pin PCIe AUX power cable.
MGT VTT	Voltage measurement (1.2V nominal) of the onboard MGTAVTT regulator for the GTYs used by the FPGA.
1V2 BTM	Voltage measurement (1.2V nominal) for powering the onboard VDD regulator for the DDR4 parts on the lower portion of the card.
VCCINT VOL	Voltage measurement (0.72-0.85V nominal) of the onboard VCCINT regulator for the FPGA.
VCCINT CURR	Current measurement of the VCCINT supply drawn by the card.
VCCINT BRAM VOL	Voltage measurement (0.85V nominal) of the onboard VCCINT, VCCINTIO, and VCCBRAM regulator used by the FPGA.
VCC3V3 VOL	Voltage measurement (3.3V nominal) of the onboard 3.3V regulator used by the QSFPs, and other circuits.
3V3 PEX CURR	Current measurement of the 3.3V motherboard PCIe rail drawn by the card.
VCC0V85 CURR	Current measurement of the VCCINTIO and VCCBRAM supply drawn by the card.
HBM1V2 VOL	Voltage of 1.2V for powering the onboard VDD on the DDR4 HBM parts on the card.
VPP2V5 VOL	Voltage of 2.5V for powering the onboard VPP on the DDR4 parts of the card.

An example of the output is given below:

Electrical(mV|mA)
12V PEX         12V AUX         12V PEX Current 12V AUX Current
12101           12202           1505            1268           
3V3 PEX         3V3 AUX         DDR VPP BOTTOM  DDR VPP TOP    
3357            3326            2500            2500           
SYS 5V5         1V2 TOP         1V8 TOP         0V85           
5515            1204            1836            855            
MGT 0V9         12V SW          MGT VTT         1V2 BTM        
910             12064           1207            1209           
VCCINT VOL      VCCINT CURR     VCCINT BRAM VOL VCC3V3 VOL     
851             15894           0               0              
3V3 PEX CURR    VCC0V85 CURR    HBM1V2 VOL      VPP2V5 VOL     
0               0               0               0

Card Power

Single field returning the total power (W) being consumed by the card.

An example of the output is given below:

Card Power(W)
33

Firewall Last Error Status

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, as discussed in AXI Firewall Trips. In the following output, there are no detected firewall errors.

Table 7. Firewall Last Error Status Field Definition
Field	Description
Tag	Name of memory bank
Errors	Indicates if an error occurred
CE Count	Number of correctable errors. Number is persistent, however can be reset through `xbmgmt reset`.
UE Count	Number of uncorrectable errors. The count is persistent, but it can be reset using `xbmgmt reset`.

An example of the output is given below:

Firewall Last Error Status
Level 0 : 0x0(GOOD)
 
ECC Error Status
Tag     Errors      CE Count  UE Count  CE FFA  UE FFA   
bank0   (None)      0         0         0x0     0x0          
bank1   (None)      0         0         0x0     0x0       
bank2   (None)      0         0         0x0     0x0        
bank3   (None)      0         0         0x0     0x0

On some cards, for example the U50, the Satellite Controller (SC) monitors operating conditions. If the card exceeds electrical or thermal limits, the SC will reset the workload on the card. In some cases, this will be seen in the xbutil query output as a firewall trip. It will display the time the trip occurred. An example of the post trip state is given below:

Firewall Last Error Status
Level 3 : 0x80004(RECS_CONTINUOUS_RTRANSFERS_MAX_WAIT|RECS_WRITE_TO_BVALID_MAX_WAIT)
Error occurred on: Tue 2020-04-28 15:16:47 MDT

The card should be okay to use in this state.

Memory Status

The memory topology along with the DMA transfer metrics are provided next, followed by streaming transfers. 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.

An example of the output is given below. If no xclbin has been loaded, no memory status will be displayed.

Memory Status
     Tag         Type        Temp(C)  Size    Mem Usage       BO count
[ 0] bank0       MEM_DDR4    37       16 GB   16 MB           1      
[ 1] bank1       MEM_DDR4    39       16 GB   16 MB           1      
[ 2] bank2       MEM_DDR4    47       16 GB   16 MB           1      
[ 3] bank3       MEM_DDR4    43       16 GB   16 MB           1      
[ 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

An example of the output is given below. If no xclbin has been loaded, no metrics will be displayed.

DMA Transfer Metrics
Chan[0].h2c:  12384 MB
Chan[0].c2h:  15200 MB
Chan[1].h2c:  6240 MB
Chan[1].c2h:  6144 MB

Streams

This is available for streaming platforms only.

An example of the output is given below:

Streams
Tag Flow ID Route ID Status Total (B/#) Pending (B/#)

Xclbin UUID

This displays the xclbin UUID. An example of the output is given below. If no xclbin has been loaded, it will return all zeros as the UUID.

Xclbin UUID
dfd5a66a-36aa-41c6-88bb-c85a86d15512

Compute Unit Status

The Compute Units (CU) present in the xclbin loaded to the card 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.

An example of the output is given below. If no xclbin has been loaded, no CU status will be displayed.

Compute Unit Status
CU[ 1]: bandwidth1:kernel_1         @0x1c00000         (IDLE)
CU[ 0]: bandwidth2:kernel_2         @0x1800000         (IDLE)