DOCSEARCHbyAlgolia
Submit Docs

XRT (FleXible RunTime)

repository·master·Indexed 20 days ago

https://github.com/xilinx/xrt

An abstraction layer and unified software interface for AMD NPUs and FPGAs, supporting platforms such as AMD Ryzen, Versal Adaptive SoCs, Alveo Accelerator Cards, and Zynq UltraScale+ MPSoCs. It includes user-space and kernel driver components for Linux and Windows, the xrt-runner.exe for model execution via recipes and profiles, and the xrt-smi tool for examining, configuring, and validating device status.

Tokens
59.3K
Snippets
165
Records
246
Agent score
71%

What's inside XRT

  1. Overview of xbflash2 utility

    master

    The Xilinx Board Flash utility (xbflash2) is a standalone command-line tool used to flash custom images onto Alveo platforms.

    Key Characteristics:

    • Target Platforms: Supported for all Alveo platforms.
    • Design Requirement: Verified and supported only on XDMA PCIe DMA designs.
    • Installation: It is provided as a separate xbflash package and is not part of the standard XRT package. After installation, the binary is located in /usr/local/bin.
    • Availability: Can be found on the Alveo card web page under the 'getting started' session, specifically the xbflash2 tab.

  2. Overview of AIE Binary Utilities (aiebu)

    master

    AIE Binary Utilities (aiebu) is a set of utilities and libraries designed for working with AIE ctrlcode. It includes an assembler and disassembler for specific AIE architectures and defines the ctrlcode ELF format and ISA (Instruction Set Architecture).

    Supported architectures include:

    • aie2p
    • aie2ps
    • aie4

  3. Overview of FleXible RunTime (XRT)

    master

    FleXible RunTime (XRT) is a runtime software interface composed of user-space and kernel driver components. It provides an abstraction layer for accessing AMD NPUs and AMD FPGAs across various hardware platforms including AMD Ryzen™, AMD Ryzen™ Embedded, AMD Versal™ Adaptive SoCs, AMD Alveo™ Adaptable Accelerator Cards, and AMD Zynq™ UltraScale+™ MPSoCs.

    Key Characteristics:

    • Supported OS: Linux and Windows.
    • Supported Architectures: x86_64 and aarch64 host CPUs.
    • Driver Models: Uses the Linux accel driver model on Linux and the Windows MCDM driver model on Windows.
    • Management Tool: Includes the xrt-smi command-line tool for examining, configuring, and validating NPU and FPGA devices.

  6. Identify host platform requirements for AMD NPU and PCIe Accelerator Cards

    master

    XRT host platform requirements depend on the hardware type being used:

    AMD NPU

    • Windows or Linux running on x86_64 architecture.
    • Linux running on aarch64 architecture.

    PCIe Accelerator Cards

    • Linux running on x86_64 architecture.
    • Linux running on aarch64 architecture.

    Note: Supported AMD Alveo Accelerator Cards are specified in the specific platform documentation for your card or board.

  7. Use the XRT Native C++ API

    master
    The XRT Native Library provides a C++ interface for managing hardware acceleration resources on Xilinx devices. The API is organized into several functional modules including buffer management, device control, kernel execution, and system information. Developers can use these classes and namespaces to interact with FPGA hardware, manage memory (BOs), load XCLBIN files, and execute kernels.

  8. What is an XRT Run Recipe?

    master
    An XRT run recipe is a JSON-based graph model that defines a sequence of operations to be executed by the xrt::runner class. It specifies the hardware configurations, kernels, CPU functions, and buffers required to run a specific workload. Tools like VAIML can generate these recipes alongside xclbin files and kernel control code. A recipe is associated with exactly one configuration (an xclbin or a config ELF) that must be loaded into a device region to execute the recipe.

  9. What is an XRT execution profile?

    master

    An execution profile is an extension to an XRT run recipe. While the xrt::runner class can be used stand-alone for manual resource management, an execution profile automates the process by binding resources to the runner.

    It is primarily used for testing run recipes by defining:

    • How data is bound to resources.
    • How validation is performed.
    • How many times a run recipe is executed and with what data.

  10. Configure iteration lifecycle with the iteration sub-element

    master

    The iteration sub-element allows you to specify actions that occur before or after each iteration. Note: This sub-element is ignored if mode is set to latency or throughput.

    Available keys within iteration:

    • bind: If true, re-binds buffers to the recipe before an iteration (only for buffers where the binding element specifies rebind).
    • init: If true, re-initializes buffers before an iteration (only for buffers where the binding element specifies reinit).
    • wait: If true, the execution waits for completion between iterations and after the last iteration.
    • sleep: Specifies the number of milliseconds to sleep between iterations. If both wait and sleep are used, the sleep occurs after the wait completes.
    • validate: Performs buffer validation as specified in the binding element.
    "execution" : {
  "iterations": 500,
  "iteration" : {
    "bind": false,
    "init": true,
    "wait": true,
    "sleep": 1000,
    "validate": true
  }
}

  11. Troubleshoot Frequency Scaling and CU Deadlocks

    master

    Incorrect Frequency Scaling

    If kernels produce incorrect results or hang intermittently, the dynamic region clocks might be running at a higher frequency than specified in the xclbin's clock_freq_topology section.

    • Check Frequency: Compare the current board frequency against the xclbin metadata using xrt-smi examine --device <bdf> --report platform and xclbinutil.

    CU and AXI Bus Deadlocks

    • CU Deadlock: Often caused by HLS scheduler bugs. The CU will appear stuck in START or --- state. Observe this via: xrt-smi examine --device <bdf> --report dynamic-regions or xrt-smi examine --device <bdf> --report debug-ip-status.
    • AXI Bus Deadlock: Can be caused by Memory Read Before Write or CU Deadlock. This may also trigger an AXI Firewall trip. Check status with: xrt-smi examine --device <bdf> --report firewall.

  12. How Embedded Platforms (Zynq/Versal) Work

    master

    XRT supports ZYNQ-7000, ZYNQ UltraScale+ MPSoC, and Versal ACAP embedded platforms. These platforms typically use a PetaLinux-based root filesystem and kernel.

    The heavy lifting is performed by the zocl Linux kernel driver, which provides APIs via xrt.h and xrt_aie.h (for AI Engines).

    Key zocl functionalities:

    • Memory Management: Managing PS memory CMA buffers, cache, and SMMU (on SVM-enabled platforms). It also manages PL-DDR if a MIG is instantiated.
    • Execution: Managing compute unit execution pipelines.
    • Partial Reconfiguration: Loading xclbin images for platforms supporting it.
    • Data Movement: Programming ZynqMP DMA engines (PS DDR to PL-DDR) and AIE GMIO data movers (NOC to AIE).
    • AIE Support: Programming AIE arrays and executing graphs.
    • DMA-BUF: Importing and exporting buffer objects.