Useful Command Line Utilities

There are several Xilinx® command line utilities that provide detailed information to help construct xocc command line and give data about the platform, including SLR resource availability. These include platforminfo, kernelinfo, and xclbininfo.

Platforminfo Utility

The platforminfo command line utility reports platform meta-data including information on interface, clock, valid SLRs and allocated resources, and memory in a structured format. This information can be referenced when allocating kernels to SLRs or memory resources for instance.

The following command will report information on the xilinx_u200_xdma_201830_1.xpfm platform.

platforminfo -p $PLATFORM_REPO_PATHS/xilinx_u200_xdma_201830_1.xpfm

Condensed output examples, using the above command, are given below.

For more information, including command options, see the SDx Command and Utility Reference Guide.

Basic Platform Information

Platform information and high-level description are reported. The xdma performs memory transfers between the host and Xilinx accelerator card over a PCIe®.

Platform:      xdma
File:          /opt/xilinx/platforms/xilinx_u200_xdma_201830_1/
			   xilinx_u200_xdma_201830_1.xpfm
Description:   This platform targets the Alveo U200 Data Center Accelerator 
			   Card. This high-performance acceleration platform features 
			   up to four channels of DDR4-2400 SDRAM which are 
			   instantiated as required by the user kernels for high fabric 
			   resource availability, and Xilinx DMA Subsystem for PCI 
			   Express with PCIe Gen3 x16 connectivity.
Platform Type: SDAccel

Hardware Platform Information

General information on the hardware platform is reported. For the Software Emulation and Hardware Emulation field, a "1" indicates this platform is suitable for these configurations. The Maximum Number of Compute Units field gives the maximum number of compute units allowable in this platform.

Vendor:                           xilinx
Board:                            U200 (xdma)
Name:                             xdma
Version:                          201830.1
Generated Version:                2018.3
Software Emulation:               1
Hardware Emulation:               1
FPGA Family:                      virtexuplus
FPGA Device:                      xcu200
Board Vendor:                     xilinx.com
Board Name:                       xilinx.com:au200:1.0
Board Part:                       xcu200-fsgd2104-2-e
Maximum Number of Compute Units:  60

Interface Information

The following shows the reported PCIe interface information.

  Interface Name: PCIe
  Interface Type: gen3x16
  PCIe Vendor Id:    0x10EE
  PCIe Device Id:    0x5000
  PCIe Subsystem Id: 0x000E

Clock Information

Reports the maximum kernel clock frequencies available. The Clock Index is the reference used in the --kernel_frequency xocc directive when overriding the default value. For specific details, see SDx Command and Utility Reference Guide.

  Default Clock Index: 0
  Clock Index:         1
    Frequency:         500.000000
  Clock Index:         0
    Frequency:         300.000000

Valid SLRs

Reports the valid SLRs in the platform.

  SLR0, SLR1, SLR2

Resource Availability

The total available resources and resources available per SLR are reported. This information can be used to assess applicability of the platform for the design and help guide allocation of compute unit to available SLRs.

  Total...
    LUTs:  1051996
    FFs:   2197301
    BRAMs: 1896
    DSPs:  6833
  Per SLR...
    SLR0:
      LUTs:  354825
      FFs:   723370
      BRAMs: 638
      DSPs:  2265
    SLR1:
      LUTs:  159108
      FFs:   329166
      BRAMs: 326
      DSPs:  1317
    SLR2:
      LUTs:  354966
      FFs:   723413
      BRAMs: 638
      DSPs:  2265

Memory Information

Reports the available DDR and PLRAM memory connections per SLR as shown in the example output below.

  Type: ddr4
  Bus SP Tag: DDR
    Segment Index: 0
      Consumption: automatic
      SP Tag:      bank0
      SLR:         SLR0
      Max Masters: 15
    Segment Index: 1
      Consumption: default
      SP Tag:      bank1
      SLR:         SLR1
      Max Masters: 15
    Segment Index: 2
      Consumption: automatic
      SP Tag:      bank2
      SLR:         SLR1
      Max Masters: 15
    Segment Index: 3
      Consumption: automatic
      SP Tag:      bank3
      SLR:         SLR2
      Max Masters: 15
  Bus SP Tag: PLRAM
    Segment Index: 0
      Consumption: explicit
      SLR:         SLR0
      Max Masters: 15
    Segment Index: 1
      Consumption: explicit
      SLR:         SLR1
      Max Masters: 15
    Segment Index: 2
      Consumption: explicit
      SLR:         SLR2
      Max Masters: 15

The Bus SP Tag heading can be DDR or PLRAM and gives associated information below.

The Segment Index field is used in association with the SP Tag to generate the associated memory resource index as shown below.

Bus SP Tag[Segment Index]

For example, if Segment Index is 0, then the associated DDR resource index would be DDR[0].

This memory index is used when specifying memory resources in the xocc command as shown below:

xocc … --sp vadd.m_axi_gmem:DDR[3]

There can be more than one Segment Index associated with an SLR. For instance, in the output above, SLR1 has both Segment Index 1 and 2.

The Consumption field indicates how a memory resource is used when building the design:

default: If an --sp directive is not specified, it uses this memory resource by default during xocc build. For example in the report below, DDR with Segment Index 1 is used by default.

automatic: When the maximum number of memory interfaces have been used under Consumption: default have been fully applied, then the interfaces under automatic is used. The maximum number of interfaces per memory resource are given in the Max Masters field.

explicit: For PLRAM, consumption is set to explicit which indicates this memory resource is only used when explicitly indicated through the xocc command line.

Feature ROM Information

The feature ROM information provides build related information on ROM platform and can be requested by Xilinx Support when debugging system issues.

  ROM Major Version:       10
  ROM Minor Version:       1
  ROM Vivado Build ID:     2388429
  ROM DDR Channel Count:   5
  ROM DDR Channel Size:    16
  ROM Feature Bit Map:     655885
  ROM UUID:                00194bb3-707b-49c4-911e-a66899000b6b
  ROM CDMA Base Address 0: 620756992
  ROM CDMA Base Address 1: 0
  ROM CDMA Base Address 2: 0
  ROM CDMA Base Address 3: 0

Software Platform Information

Although software platform information is reported, it is only useful for SDSoC™ users, which have an OS running on the device, and not applicable to SDAccel™ users which use a host machine.

Number of Runtimes:            1
Linux root file system path:   tbd
Default System Configuration:  config0_0
System Configurations:
  System Config Name:                      config0_0
  System Config Description:               config0_0 Linux OS on x86_0
  System Config Default Processor Group:   x86_0
  System Config Default Boot Image:        
  System Config Is QEMU Supported:         0
  System Config Processor Groups:
    Processor Group Name:      x86_0
    Processor Group CPU Type:  x86
    Processor Group OS Name:   Linux OS
  System Config Boot Images:
Supported Runtimes:
  Runtime: OpenCL

Kernelinfo Utility

The kernelinfo utility extracts information from .xo files which can be used during host code development. This information includes hardware function names, arguments, offsets, and port data.

To run the kernelinfo utility, enter the following in a Linux terminal:

kernelinfo <filename.xo>

The output is divided into three categories:

Kernel Definitions
Arguments
Ports

Examples of each are shown below based on the following command:

kernelinfo krnl_vadd.xo

Where krnl_vadd.xo is a packaged kernel.

For more information, including command options, see SDx Command and Utility Reference Guide.

Kernel Definition

Reports high-level kernel definition information. Importantly, for the host code development, the kernel name is given in the name field. In this example, the kernel name is krnl_vadd.

=== Kernel Definition ===
name: krnl_vadd
language: c
vlnv: xilinx.com:hls:krnl_vadd:1.0
preferredWorkGroupSizeMultiple: 1
workGroupSize: 1
debug: true
containsDebugDir: 1
sourceFile: krnl_vadd/cpu_sources/krnl_vadd.cpp

Arguments

Reports kernel function arguments. For each argument, it reports the following:

name
addressQualifier
id
port
size
offset
hostOffset
hostSize
type

In the following example, there are four arguments:

a
b
c
n_elements

=== Arg ===
name: a
addressQualifier: 1
id: 0
port: M_AXI_GMEM
size: 0x8
offset: 0x10
hostOffset: 0x0
hostSize: 0x8
type: int*

=== Arg ===
name: b
addressQualifier: 1
id: 1
port: M_AXI_GMEM
size: 0x8
offset: 0x1C
hostOffset: 0x0
hostSize: 0x8
type: int*

=== Arg ===
name: c
addressQualifier: 1
id: 2
port: M_AXI_GMEM1
size: 0x8
offset: 0x28
hostOffset: 0x0
hostSize: 0x8
type: int*

=== Arg ===
name: n_elements
addressQualifier: 0
id: 3
port: S_AXI_CONTROL
size: 0x4
offset: 0x34
hostOffset: 0x0
hostSize: 0x4
type: int const

Ports

Reports the memory and control ports used by the kernel.

=== Port ===
name: M_AXI_GMEM
mode: master
range: 0xFFFFFFFF
dataWidth: 32
portType: addressable
base: 0x0

=== Port ===
name: M_AXI_GMEM1
mode: master
range: 0xFFFFFFFF
dataWidth: 32
portType: addressable
base: 0x0

=== Port ===
name: S_AXI_CONTROL
mode: slave
range: 0x1000
dataWidth: 32
portType: addressable
base: 0x0

Xclbinutil Utility

The xclbinutil utility can create, modify, and report xclbin content information. Detailed command options can be found in "xclbinutil Utility" section in SDx Command and Utility Reference Guide. For most users, the contents and how the xclbin was created is desired. This information can be obtained through the --info option and reports information on the xclbin, hardware platform, clocks, memory configuration, kernel, and how the xclbin was generated.

An example of the xclbinutil command using the --info option is shown below. In addition, an example of the generated output, divided into sections, based on the command is also given.

xclbinutil -i binary_container_1.xclbin --info

xclbin Information

Generated by:           xocc (2018.3) on Tue Nov 20 19:42:42 MST 2018
Version:                2.1.1660
Kernels:                krnl_vadd
Signature:              Not Present
Content:                HW Emulation Binary
UUID:                   979eb04c-b99c-4cbe-9a67-ad07b89f303b
Sections:               BITSTREAM, MEM_TOPOLOGY, IP_LAYOUT, CONNECTIVITY, 
                        DEBUG_IP_LAYOUT, CLOCK_FREQ_TOPOLOGY, BUILD_METADATA, 
                        EMBEDDED_METADATA, DEBUG_DATA

Hardware Platform (Shell) Information

Vendor:                 xilinx
Board:                  u200
Name:                   xdma
Version:                201830.1
Generated Version:      Vivado 2018.3 (SW Build: 2388429)
Created:                Wed Nov 14 20:06:10 2018
FPGA Device:            xcu200
Board Vendor:           xilinx.com
Board Name:             xilinx.com:au200:1.0
Board Part:             xilinx.com:au200:part0:1.0
Platform VBNV:          xilinx_u200_xdma_201830_1
Static UUID:            00194bb3-707b-49c4-911e-a66899000b6b
Feature ROM TimeStamp:  1542252769

Clocks

Reports the maximum kernel clock frequencies available. Both the clock names and clock indexes are provided. The clock indexes are identical as reported in the Platforminfo Utility.

Name:      DATA_CLK
Index:     0
Type:      DATA
Frequency: 300 MHz

Name:      KERNEL_CLK
Index:     1
Type:      KERNEL
Frequency: 500 MHz

Memory Configuration

Name:         bank0
Index:        0
Type:         MEM_DDR4
Base Address: 0x0
Address Size: 0x400000000
Bank Used:    No

Name:         bank1
Index:        1
Type:         MEM_DDR4
Base Address: 0x400000000
Address Size: 0x400000000
Bank Used:    Yes

Name:         bank2
Index:        2
Type:         MEM_DDR4
Base Address: 0x800000000
Address Size: 0x400000000
Bank Used:    No

Name:         bank3
Index:        3
Type:         MEM_DDR4
Base Address: 0xc00000000
Address Size: 0x400000000
Bank Used:    No

Name:         PLRAM[0]
Index:        4
Type:         MEM_DDR4
Base Address: 0x1000000000
Address Size: 0x20000
Bank Used:    No

Name:         PLRAM[1]
Index:        5
Type:         MEM_DRAM
Base Address: 0x1000020000
Address Size: 0x20000
Bank Used:    No

Name:         PLRAM[2]
Index:        6
Type:         MEM_DRAM
Base Address: 0x1000040000
Address Size: 0x20000
Bank Used:    No

Kernel Information

For each kernel in the xclbin the function definition, ports, and instance information is reported.

Below is an example of the reported function definition.

Definition
----------
   Signature: krnl_vadd (int* a, int* b, int* c, 
			 int const  n_elements)

Below is an example of the reported ports.

Ports
-----
   Port:          M_AXI_GMEM
   Mode:          master
   Range (bytes): 0xFFFFFFFF
   Data Width:    32 bits
   Port Type:     addressable

   Port:          M_AXI_GMEM1
   Mode:          master
   Range (bytes): 0xFFFFFFFF
   Data Width:    32 bits
   Port Type:     addressable

   Port:          S_AXI_CONTROL
   Mode:          slave
   Range (bytes): 0x1000
   Data Width:    32 bits
   Port Type:     addressable

Below is an example of the reported instance(s) of the kernel.


Instance:        krnl_vadd_1
   Base Address: 0x0

   Argument:          a
   Register Offset:   0x10
   Port:              M_AXI_GMEM
   Memory:            bank1 (MEM_DDR4)

   Argument:          b
   Register Offset:   0x1C
   Port:              M_AXI_GMEM
   Memory:            bank1 (MEM_DDR4)

   Argument:          c
   Register Offset:   0x28
   Port:              M_AXI_GMEM1
   Memory:            bank1 (MEM_DDR4)

   Argument:          n_elements
   Register Offset:   0x34
   Port:              S_AXI_CONTROL
   Memory:            <not applicable>

Tool Generation Information

The utility also reports the xocc command line used to generate the xclbin. The Command Line section gives the actual xocc command line used, while the Options section displays each option used in the command line, but in a more readable format with one option per line.

Generated By
------------
Command:       xocc
Version:       2018.3 - Tue Nov 20 19:42:42 MST 2018 (SW BUILD: 2394611)
Command Line:  xocc -t hw_emu --platform /opt/xilinx/platforms/xilinx_u200_xdma_201830_1/xilinx_
			   u200_xdma_201830_1.xpfm --save-temps -l --nk krnl_vadd:1 -g 
			   --messageDb binary_container_1.mdb 
			   --xp misc:solution_name=link --temp_dir binary_container_1 
			   --report_dir binary_container_1/reports --log_dir binary_
			   container_1/logs --remote_ip_cache
			   /wrk/tutorials/ip_cache -obinary_container_1.xclbin binary_
			   container_1/krnl_vadd.xo 
Options:       -t hw_emu
               --platform /opt/xilinx/platforms/xilinx_u200_xdma_201830_1/xilinx_u200_xdma_201830_1.xpfm
               --save-temps
               -l
               --nk krnl_vadd:1
               -g
               --messageDb binary_container_1.mdb
               --xp misc:solution_name=link
               --temp_dir binary_container_1
               --report_dir binary_container_1/reports
               --log_dir binary_container_1/logs
               --remote_ip_cache /wrk/tutorials/ip_cache
			   -obinary_container_1.xclbin binary_container_1/krnl_vadd.xo 
==============================================================================
User Added Key Value Pairs
--------------------------
   <empty>
==============================================================================