xbsak Commands and Options

The following documents the xbsak command line format, and the available commands and options .

xbsak <command> [options]

Commands and Options

  • help: Print help messages.

  • list : List all supported devices installed on the server in the format of [device_id] : device_name.

    The following is an example output where the device ID is 0 and the device name is xilinx_vcu1525_dynamic_5_0.

    
$xbsak list
Linux:xxxx
Distribution: yyyy
GLIBC: 2.17
--- 
XILINX_OPENCL="/opt/dsa/xilinx_vcu1525_dynamic_5_0/xbinst"
LD_LIBRARY_PATH="/opt/dsa/xilinx_vcu1525_dynamic_5_0/xbinst/runtime/lib/x86_64:"
--- 
INFO: Found 1 device(s)
[0] xilinx:vcu1525:dynamic:5.0
  • query [-d device_id] [-r region_id]
    Query the specified device and programmable region on the device to get detailed status information.

    • -d device_id - Specify the target device. Optional. Default=0 if not specified.

    • -r region_id - Specify the target region. Optional. Default=0 if not specified.

  • boot [-d <device_id>]: Attempts to boot the device <device_id>from its configuration memory, retain the PCIe® link without rebooting the host, and trigger a re-enumeration of the PCIe bus and bus re-scanning. If this option command does not complete as expected, xbsak notifies the user and requests for hard reboot (sometimes called cold reboot: shutdown and restart of the machine)
  • clock [-d <device_id>] [-r <region_id>] -f <clock1_freq> [-g <clock2_freq>]: Set frequencies of clocks driving the computing units.

    • -d <device_id> - Specify the target device. Optional. Default=0 if not specified.

    • -r <region_id> - Specify the target region. Optional. Default=0 if not specified.

    • -f <clock1_freq> - Specify clock frequency in MHz for the first clock. Required. All platforms have this clock.

    • -g <clock2_freq> - Specify clock frequency in MHz for the second clock. Optional: Some platforms have this clock to support IP based kernels.

  • dmatest [-d device_id] [-b blocksize]
    Test throughput of data transfer between the host machine and global memory on the device.

    • -d <device_id> - Specify the target device. Optional. Default=0 if not specified.

    • -b <blocksize> - Specify the test block size in KB. Optional: Default=65536 or 64MB if not specified. The block size can be specified in both decimal or hexadecimal formats. e.g. Both -b 1024 and -b 0x400 set the block size to 1024KB or 1MB.

  • flash [-d device_id] -m primary_mcs [-n secondary_mcs]

    This option helps program the configuration memory (flash memory device) on the FPGA board with specified configuration files for the FPGA device to boot from. If you know the platform installed currently on the board then you can use this method.

    If you do not know what DSA is installed or want to program from a starting point, you need to externally flash using the USB JTAG or USB cable as detailed in the board installation section for your FPGA board.

    • -d <device_id>: Specify the target device. Optional. Default=0 if not specified.

    • -m <primary_mcs>: Specify the primary configuration file. Required. All platforms have at least one configuration memory.

    • -n <secondary_mcs>: Specify the secondary configuration file. Optional. Some platform have two configuration memories and the secondary configuration file is required for the second configuration memory.

    IMPORTANT!:

    For the flash programming function of the xbsak to access and program the flash configuration memory on the board, certain hardware features must be present in the current platform programmed onto the FPGA. This means the flash programming function works with boards already programmed with a given firmware only, which are listed in the following table.

    The following are required steps:
    1. Have two xbinst-generated deployment areas.
      1. The first area corresponds tot the current platform deployed on the board. This provides the necessary xbsak that matches the current drivers installed on the deployment machine; most often you already have this area present on the deployment machine. You must source the setup.{sh,csh} from this area to use xbsak matching the installed drivers.
      2. The second area corresponds to the new platform to be deployed on the board; this provides the following:
        1. Configuration file(s) needed for the primary mcs (-m) and optional secondary mcs (-n) options
        2. New drivers needed to be deployed on the machine
    2. Find the new configuration files in the new platform with the command:$ find -name ‘*.mcs’ OR$ find /path/to/new/platform -name ‘*.mcs’
    3. Run xbsak to program the configuration file(s) onto the configuration memory of the board with the -m and -n options.
    4. Install the drivers of the new platform in the OS (to replace the old drivers) with $ sudo ./install.sh -k yes -f yes; the f and k options will force the install of the OS kernel drivers.

    The table lists the boards and their minimum required platform firmware versions for the flash programming to function. The entries show the platform names to use for the xbinst command.

    Board Platform Firmware used in xbinst 2017.2 Platform Firmware using in xbinst 2017.4
    ADM-PCIE-7V3 xilinx:adm-pcie-7v3:1ddr:3.0 or newer  
    ADM-PCIE-KU3
    • xilinx:adm-pcie-ku3:2ddr-xpr:3.3 or newer
    • xilinx:adm-pcie-ku3:2ddr:3.3 or newer
    • xilinx:adm-pcie-ku3:1ddr:3.3 or newer
    		  
    KCU1500 - xilinx_kcu1500_dynamic_5_0
    VCU1525 - xilinx_vcu1525_dynamic_5_0
    XIL-ACCEL-RD-KU115

    xilinx:xil-accel-rd-ku115:4ddr-xpr:3.2 or newer

    		  
  • program [-d device_id] [-r region_id] -p xclbin
    Download the OpenCL binary to the programmable region on the device.

    • -d device_id - Specify the target device. Optional. Default=0 if not specified.

    • -r region_id - Specify the target region. Optional. Default=0 if not specified.

    • -p xclbin - Specify the OpenCL binary file. Required.

  • reset [-d device_id] [-r region_id]
    Reset the programmable region on the device. All running compute units in the region will be stopped and reset.

    • -d device_id - Specify the target device. Optional. Default=0 if not specified.

    • -r region_id - Specify the target region. Optional. Default=0 if not specified.

  • status [--apm | --lapc]

    Displays the status of any AXI Performance Monitor (apm) or Lightweight AXI Protocol Checkers (lapc) that are available in the base platform.

    • --apm - Returns the value of the AXI Performance Monitor (apm) counters. This option is only applicable if one or more AXI Performance Monitors are available in the base platform.

    • --lapc - Returns the values of the violations codes detected by the Lightweight AXI Protocol Checkers (lapc). This option is only applicable if one or more Lightweight AXI Protocol Checkers are available in the base platform.

  • - scan

    Scans the system and displays any Xilinx PCIe devices, associated drivers and pertinent system information.