# xilinx/xrt architecture

> Architecture diagram of the GitHub repository xilinx/xrt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xilinx/xrt
- Repository: https://github.com/xilinx/xrt

## Overview

1. **What this repo is**
   - This is AMD’s XRT runtime stack: a host-side software platform that lets applications manage NPUs/FPGAs and program them with xclbin images.
   - The repo is split into **user-space runtime libraries**, **kernel/driver components**, **device-emulation backends**, and **developer tools/tests**.

2. **Top-level execution flow**
   - An application enters through XRT/OpenCL/HIP-style APIs.
   - Those calls flow into the runtime core, which resolves platform/device state, loads xclbin metadata, manages buffers/queues/context, and then dispatches to a backend-specific device/shim layer.
   - The backend talks to the actual kernel driver on Linux/Windows, or to emulation components in HW/SW emu modes.

3. **Public API surface**
   - `src/runtime_src/core/include` and `src/include` contain the exported headers: classic `xrt.h`, `xclhal2.h`, OpenCL compatibility headers, experimental `xrt/*` APIs, and AIE-related interfaces.
   - These headers define the stable boundary for application developers, while the implementation lives deeper under `core`, `xocl`, `xrt`, and `hip`.

4. **Core runtime engine**
   - `src/runtime_src/core/common` is the shared runtime backbone: device/context/kernel/buffer abstractions, xclbin parsing, error handling, tracing, scheduling, profiling, system info, and utility code.
   - It also contains reusable infrastructure for async queues, module loading, config parsing, archive handling, and telemetry.
   - This layer is the main place where device-agnostic runtime behavior is implemented.

5. **Backend split by platform and transport**
   - `src/runtime_src/core/pcie`, `src/runtime_src/core/edge`, and `src/runtime_src/core/xrt` represent platform-specific adaptations.
   - PCIe paths cover Alveo and similar cards; edge paths cover Zynq/Versal-style systems with tighter PS/PL integration and AIE/firmware-specific flows; `xrt/device` provides lower-level HAL abstractions.
   - The runtime chooses the right backend depending on host OS, device family, and execution mode.

6. **Driver boundary and kernel-space components**
   - Linux drivers live under `src/runtime_src/core/pcie/driver/linux/xocl` and edge DRM/ZOCL code under `src/runtime_src/core/edge/drm/zocl`.
   - These drivers expose ioctl/sysfs/DRM entry points, manage buffer objects, command submission, hardware context state, interrupts, mailbox communication, and device-specific subsystems like PCIe, memory, clocks, and flash.
   - Windows support is present under `src/runtime_src/core/pcie/driver/windows` and `src/runtime_src/core/pcie/windows/alveo`, matching the same logical driver boundary in a different OS model.

7. **Emulation and simulation support**
   - `src/runtime_src/core/pcie/emulation`, `src/runtime_src/core/edge/hw_emu`, and `src/runtime_src/core/edge/sw_emu` provide hardware-emulation and software-emulation shims.
   - These backends mimic device, scheduler, memory, and mailbox behavior so the same host APIs can be exercised without real hardware.
   - This is a key architectural boundary: the host runtime code stays mostly the same, while the backend is swapped for emulation.

8. **OpenCL compatibility layer**
   - `src/runtime_src/xocl` implements the OpenCL-facing runtime: API entry points (`clCreateBuffer`, `clEnqueue*`, etc.), core OpenCL objects, and ICD integration.
   - It acts as a compatibility layer over XRT primitives so existing OpenCL-style applications can use the same underlying device/runtime stack.
   - The `icd` and `khronos` subtrees show that this is a wrapper layer rather than the fundamental runtime.

9. **HIP integration**
   - `src/runtime_src/hip` provides HIP-facing APIs and core objects for device, memory, stream, event, graph, and module handling.
   - Architecturally, this is another frontend over the shared runtime/device machinery, aimed at a different application ecosystem.
   - It is not a separate backend; it reuses the same device/runtime abstractions below it.

10. **AIE and edge-specific control paths**
    - The edge tree contains extensive AIE support: graph control, profiling, parser code, PS kernels, and plugins for AIE/trace/debug.
    - These pieces sit alongside PS/PL control and are important on Versal/Zynq-style platforms where the runtime must manage both programmable logic and AI Engine subsystems.
    - This is a distinct subsystem from the generic PCIe buffer/command path.

11. **xclbin and metadata tooling**
    - `src/runtime_src/tools/xclbinutil` is the canonical xclbin packing/unpacking utility.
    - It handles sections for bitstreams, memory topology, connectivity, debug IP, AIE metadata, signatures, and vendor/user metadata.
    - This tool feeds the runtime because the runtime and drivers rely on xclbin section data to understand what a device image contains and how to configure it.

12. **Operational tools and diagnostics**
    - `src/runtime_src/core/tools` contains the user-facing operational utilities: `xbutil2`, `xbmgmt2`, `xbflash2`, `xbtop`, `xbtracer`, and supporting libraries.
    - These tools inspect health, telemetry, firmware status, PCIe info, memory, clocks, AIE state, and can also perform configuration or flashing tasks.
    - They sit on top of the same runtime/driver APIs used by applications, but are focused on administration and observability.

13. **Python bindings and scripting**
    - `src/python/pybind11` exposes a Python binding (`pyxrt`) for selected runtime APIs.
    - `src/runtime_src/tools/scripts` contains packaging, environment setup, platform build helpers, and release-oriented scripts.
    - These are auxiliary surfaces around the core runtime, not separate execution paths.

14. **Tests and validation**
    - `tests/unit_test`, `tests/xrt`, `tests/hip`, `tests/python`, `tests/pyopencl`, and `tests/mcdm` cover API correctness, device behavior, emulation, and platform-specific features.
    - The tests mirror the main architectural layers: API-level validation, backend/runtime behavior, driver interaction, and tooling correctness.
    - This helps confirm that the same abstractions work across hardware, emulation, Linux, and Windows.

15. **Build, packaging, and CI**
    - The repo is CMake-driven, with many platform-specific build scripts under `build/` and CI workflows under `.github/workflows`.
    - Packaging targets include Linux packages, Windows builds, embedded/Yocto flows, DKMS driver packaging, and cloud/container variants.
    - This build structure reflects the architecture: one codebase producing multiple runtime/driver/tool combinations for different host OSes and device families.

Main entry points: [`tests`](https://github.com/xilinx/xrt/tree/master/tests) (Tests), [`src/runtime_src/core/common`](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common) (Core Common), [`src/runtime_src/xrt/device`](https://github.com/xilinx/xrt/tree/master/src/runtime_src/xrt/device) (HAL Device), [`src/runtime_src/core/common/api`](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common/api) (Core API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public_api["Public APIs"]
  node_node_xrt_headers["XRT Headers<br/>public api"]
  node_node_extra_headers["Extra Headers<br/>public api"]
end

subgraph group_group_runtime_core["Runtime Core"]
  node_node_core_api["Core API<br/>runtime facade"]
  node_node_core_common["Core Common<br/>runtime engine"]
  node_node_xrt_device["HAL Device<br/>device hal"]
end

subgraph group_group_platform_backends["Platform Backends"]
  node_node_pcie_common["PCIe Common<br/>pcie runtime"]
  node_node_pcie_linux["Linux Backend<br/>pcie backend"]
  node_node_pcie_windows["Windows Backend<br/>pcie backend"]
  node_node_edge_common["Edge Common<br/>edge runtime"]
  node_node_edge_user["Edge User<br/>edge host shim"]
  node_node_edge_drm["ZOCL Driver<br/>edge kernel driver"]
  node_node_edge_emu["Edge Emu"]
  node_node_pcie_emu["PCIe Emu"]
end

subgraph group_group_driver_tools["Drivers & Tools"]
  node_node_xocl["OpenCL Layer<br/>opencl compatibility"]
  node_node_hip["HIP Layer<br/>hip frontend"]
  node_node_xclbinutil["xclbinutil<br/>xclbin tool"]
  node_node_operational_tools["Ops Tools<br/>admin tools"]
end

subgraph group_group_language_validation["Language & Validation"]
  node_node_pybind["Python Bindings"]
  node_node_scripts["Scripts"]
  node_node_tests["Tests<br/>validation"]
end

node_node_xrt_headers -->|"declares"| node_node_core_api
node_node_extra_headers -->|"declares"| node_node_core_api
node_node_core_api -->|"uses"| node_node_core_common
node_node_core_common -->|"dispatches"| node_node_xrt_device
node_node_xrt_device -->|"targets"| node_node_pcie_common
node_node_xrt_device -->|"targets"| node_node_edge_common
node_node_xrt_device -->|"targets"| node_node_pcie_emu
node_node_xrt_device -->|"targets"| node_node_edge_emu
node_node_pcie_common -->|"implements"| node_node_pcie_linux
node_node_pcie_common -->|"implements"| node_node_pcie_windows
node_node_pcie_common -->|"pairs with"| node_node_pcie_emu
node_node_edge_common -->|"supports"| node_node_edge_user
node_node_edge_common -->|"supports"| node_node_edge_drm
node_node_edge_common -->|"supports"| node_node_edge_emu
node_node_xocl -->|"wraps"| node_node_core_common
node_node_hip -->|"wraps"| node_node_core_common
node_node_xclbinutil -->|"feeds"| node_node_core_common
node_node_operational_tools -->|"queries"| node_node_core_common
node_node_operational_tools -->|"controls"| node_node_pcie_linux
node_node_operational_tools -->|"controls"| node_node_edge_drm
node_node_pybind -->|"binds"| node_node_core_api
node_node_scripts -->|"drives"| node_node_tests
node_node_tests -->|"validates"| node_node_xocl
node_node_tests -->|"validates"| node_node_hip
node_node_tests -->|"validates"| node_node_core_api
node_node_tests -->|"validates"| node_node_pcie_emu
node_node_tests -->|"validates"| node_node_edge_user

click node_node_xrt_headers "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/include"
click node_node_extra_headers "https://github.com/xilinx/xrt/tree/master/src/include"
click node_node_core_api "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common/api"
click node_node_core_common "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common"
click node_node_xrt_device "https://github.com/xilinx/xrt/tree/master/src/runtime_src/xrt/device"
click node_node_pcie_common "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/common"
click node_node_pcie_linux "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/linux"
click node_node_pcie_windows "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/windows/alveo"
click node_node_edge_common "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/common"
click node_node_edge_user "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/user"
click node_node_edge_drm "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/drm/zocl"
click node_node_edge_emu "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/hw_emu"
click node_node_pcie_emu "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/emulation"
click node_node_xocl "https://github.com/xilinx/xrt/tree/master/src/runtime_src/xocl"
click node_node_hip "https://github.com/xilinx/xrt/tree/master/src/runtime_src/hip"
click node_node_xclbinutil "https://github.com/xilinx/xrt/tree/master/src/runtime_src/tools/xclbinutil"
click node_node_operational_tools "https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/tools"
click node_node_pybind "https://github.com/xilinx/xrt/tree/master/src/python/pybind11"
click node_node_scripts "https://github.com/xilinx/xrt/tree/master/src/runtime_src/tools/scripts"
click node_node_tests "https://github.com/xilinx/xrt/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_xrt_headers,node_node_extra_headers toneBlue
class node_node_core_api,node_node_core_common,node_node_xrt_device toneAmber
class node_node_pcie_common,node_node_pcie_linux,node_node_pcie_windows,node_node_edge_common,node_node_edge_user,node_node_edge_drm,node_node_edge_emu,node_node_pcie_emu toneMint
class node_node_xocl,node_node_hip,node_node_xclbinutil,node_node_operational_tools toneRose
class node_node_pybind,node_node_scripts,node_node_tests toneIndigo
```

## Components

### Public APIs

Headers and frontend API surfaces used by applications.

- [XRT Headers](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/include): public api · Stable exported runtime headers for XRT, OpenCL compatibility, experimental APIs, and AIE interfaces. · `src/runtime_src/core/include`
- [Extra Headers](https://github.com/xilinx/xrt/tree/master/src/include): public api · Additional public headers and compatibility includes outside the core include tree. · `src/include`

### Runtime Core

Shared device-agnostic runtime and backend selection.

- [Core API](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common/api): runtime facade · Implementation of the device, buffer, queue, context, kernel, module, and xclbin-facing XRT API objects. · `src/runtime_src/core/common/api`
- [Core Common](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/common): runtime engine · Shared runtime infrastructure: parsing, tracing, scheduling, profiling, config, utilities, and system info. · `src/runtime_src/core/common`
- [HAL Device](https://github.com/xilinx/xrt/tree/master/src/runtime_src/xrt/device): device hal · Lower-level device and HAL abstractions that bridge core runtime logic to platform implementations. · `src/runtime_src/xrt/device`

### Platform Backends

PCIe, edge, emulation, and OS-specific device shims.

- [PCIe Common](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/common): pcie runtime · Device and system abstractions for PCIe-attached platforms. · `src/runtime_src/core/pcie/common`
- [Linux Backend](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/linux): pcie backend · Linux PCIe runtime shim and driver-facing host-side implementation. · `src/runtime_src/core/pcie/linux`
- [Windows Backend](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/windows/alveo): pcie backend · Windows PCIe runtime implementation for Alveo-class devices. · `src/runtime_src/core/pcie/windows/alveo`
- [Edge Common](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/common): edge runtime · Edge/embedded runtime abstractions and edge-specific device/system glue. · `src/runtime_src/core/edge/common`
- [Edge User](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/user): edge host shim · User-space edge runtime, device management, AIE objects, and plugin hooks. · `src/runtime_src/core/edge/user`
- [ZOCL Driver](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/drm/zocl): edge kernel driver · Kernel-side DRM/ZOCL implementation for edge devices, including ioctl, buffer, KDS, mailbox, and AIE paths. · `src/runtime_src/core/edge/drm/zocl`
- [Edge Emu](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/edge/hw_emu): edge emulation · Hardware/software emulation shims for edge platforms. · `src/runtime_src/core/edge/hw_emu`
- [PCIe Emu](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/pcie/emulation): pcie emulation · Hardware/software emulation backends for PCIe-style platforms. · `src/runtime_src/core/pcie/emulation`

### Drivers & Tools

Kernel-space drivers, operational tools, and utilities.

- [OpenCL Layer](https://github.com/xilinx/xrt/tree/master/src/runtime_src/xocl): opencl compatibility · OpenCL-facing API entry points, core OpenCL objects, ICD integration, and XRT compatibility glue. · `src/runtime_src/xocl`
- [HIP Layer](https://github.com/xilinx/xrt/tree/master/src/runtime_src/hip): hip frontend · HIP-facing API and core objects built on the shared runtime machinery. · `src/runtime_src/hip`
- [xclbinutil](https://github.com/xilinx/xrt/tree/master/src/runtime_src/tools/xclbinutil): xclbin tool · xclbin pack/unpack utility for sections, metadata, signatures, and platform-specific image data. · `src/runtime_src/tools/xclbinutil`
- [Ops Tools](https://github.com/xilinx/xrt/tree/master/src/runtime_src/core/tools): admin tools · xbutil2, xbmgmt2, xbflash2, xbtop, xbtracer, and related reporting/diagnostic utilities. · `src/runtime_src/core/tools`

### Language & Validation

Language bindings, packaging scripts, and tests.

- [Python Bindings](https://github.com/xilinx/xrt/tree/master/src/python/pybind11): bindings · pyxrt Python bindings for selected runtime APIs. · `src/python/pybind11`
- [Scripts](https://github.com/xilinx/xrt/tree/master/src/runtime_src/tools/scripts): packaging scripts · Environment setup, packaging, build helpers, and release/installation scripts. · `src/runtime_src/tools/scripts`
- [Tests](https://github.com/xilinx/xrt/tree/master/tests): validation · Repository-wide runtime, frontend, emulation, and tooling validation suites. · `tests`

## Connections

- XRT Headers → Core API: declares · Public headers define the API surface implemented by the core runtime.
- Extra Headers → Core API: declares · Compatibility headers mirror the same runtime interface.
- Core API → Core Common: uses · API objects delegate to shared device-agnostic runtime services.
- Core Common → HAL Device: dispatches · Common runtime resolves to HAL/device abstractions.
- HAL Device → PCIe Common: targets · HAL abstractions bind to PCIe device/system implementations.
- HAL Device → Edge Common: targets · HAL abstractions also bind to edge device/system implementations.
- HAL Device → PCIe Emu: targets · HAL layer can swap in PCIe emulation backends.
- HAL Device → Edge Emu: targets · HAL layer can swap in edge emulation backends.
- PCIe Common → Linux Backend: implements · Linux backend provides the main PCIe runtime/driver path.
- PCIe Common → Windows Backend: implements · Windows backend provides the PCIe path on that OS.
- PCIe Common → PCIe Emu: pairs with · PCIe common logic is reused by emulation shims.
- Edge Common → Edge User: supports · Edge common logic feeds the user-space edge runtime.
- Edge Common → ZOCL Driver: supports · Edge common logic pairs with kernel-side ZOCL/DRM support.
- Edge Common → Edge Emu: supports · Edge common logic also feeds hardware/software emulation.
- OpenCL Layer → Core Common: wraps · OpenCL layer wraps shared XRT primitives.
- HIP Layer → Core Common: wraps · HIP layer reuses the same core runtime machinery.
- xclbinutil → Core Common: feeds · xclbin metadata and section handling informs runtime/device loading.
- Ops Tools → Core Common: queries · Operational tools inspect runtime state through shared APIs.
- Ops Tools → Linux Backend: controls · Administrative tools talk to deployed Linux drivers and devices.
- Ops Tools → ZOCL Driver: controls · Edge management tools interact with ZOCL and edge subsystems.
- Python Bindings → Core API: binds · Python binding exposes selected API entry points.
- Scripts → Tests: drives · Build and setup scripts support test and packaging workflows.
- Tests → OpenCL Layer: validates · Tests cover OpenCL compatibility behavior.
- Tests → HIP Layer: validates · Tests cover HIP-facing behavior.
- Tests → Core API: validates · Tests exercise the shared XRT API layer.
- Tests → PCIe Emu: validates · Tests cover emulation paths as well as hardware paths.
- Tests → Edge User: validates · Tests cover edge runtime and AIE-oriented flows.
