# amd/xdna-driver architecture

> Architecture diagram of the GitHub repository amd/xdna-driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amd/xdna-driver
- Repository: https://github.com/amd/xdna-driver

## Overview

##### Main components (each represented as a clearly labeled block)
- Kernel Module (Driver)
– Located primarily in “src/driver/amdxdna”
– Sub-components: PCI handling (amdxdna_pci_drv.c/h, etc.), DRM integration (amdxdna_drm.c/h), mailbox messaging, debugfs, error handling, and other low-level driver functionalities.
- User-space SHIM Library
– Found in “src/shim” (and its subdirectories including alternative implementations in “kmq”, “umq”, “virtio”)
– Provides an abstraction layer between user applications (via the XRT plugin) and the lower-level driver.
- XRT Plugin & Base Package
– Built by the “build” scripts (e.g., build/build.sh) and deployed as a DEB package containing the .so files (installed into /opt/xilinx/xrt/lib)
– Interfaces with the driver through the SHIM library.
- Firmware Binaries
– Provided in the “tools/bins” directories and installed into /usr/lib/firmware/amdnpu
– Loaded by the driver to run on AMD XDNA devices.
- Build & Packaging Infrastructure
– CMake configuration folders (CMake, src/CMakeLists.txt, etc.), DKMS-specific configurations (e.g., dkms.conf.in within “src/driver/CMake/config”) and scripts in “tools/”
– Provides the automated build, compile, and packaging cycle.
- Testing & Example Programs
– Located in “example”, “test”, and “tools” directories
– Validate proper integration and communication between the kernel driver, firmware, and user-space libraries.

##### Out the relationships and interactions
- From the SHIM library, indicate the interactions with the kernel driver (amdxdna.ko) – for instance, via IOCTL calls, sysfs interfaces, or DRM APIs.
- That the driver integrates with the hardware/firmware layer (firmware binaries loaded from /usr/lib/firmware/amdnpu).
- Build system as an external process that compiles, packages, and deploys both the user-space library and the kernel module.
- Optionally, add testing as a separate component that validates each of these interactions.

##### Architectural patterns/design principles
- Modularity: Separate modules for the kernel driver and user-space libraries.
- Clear separation of concerns: Distinct components for hardware-interfacing (kernel module), abstraction (SHIM), and user application integration (XRT plugin).
- Use of DKMS and CMake indicates that the project is designed for portability and dynamic module updating.
- Interaction layering: The stack moves from user applications → XRT plugin & SHIM library → Kernel driver → Firmware & hardware.

##### Incorporate relevant technologies
- Linux Kernel module framework (with DKMS support)
- CMake for configurable builds across multiple components (driver, shim, tests)
- Integration with XRT (Xilinx Runtime) – both in terms of plugin libraries and possibly shared user-space drivers.
- Standard Linux subsystems (PCI, DRM, sysfs, debugfs)
- Shell/Bash scripts that aid in building dependencies and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Build & Packaging Infrastructure Subgraph
    subgraph "Build & Packaging Infrastructure"
        BS_C["CMake Scripts"]:::build
        BS_D["DKMS Config (dkms.conf.in)"]:::build
        BS_L["CMakeLists.txt"]:::build
    end

    %% Aggregated Build System Node
    BSAggregate(("Build System")):::build

    %% Converge build nodes to an aggregate node
    BS_C --> BSAggregate
    BS_D --> BSAggregate
    BS_L --> BSAggregate

    %% User-Space Components Subgraph
    subgraph "User-Space Components"
        XRT["XRT Plugin / Library"]:::userspace
        Shim["User-Space SHIM Library"]:::userspace
    end

    %% Kernel Components Subgraph
    subgraph "Kernel Components"
        Kernel["Kernel Driver (amdxdna.ko)"]:::kernel
        Firmware["Firmware Binaries"]:::firmware
    end

    %% Test Suite Node (placed separately)
    Test["Test Suite"]:::test

    %% Connections between components
    BSAggregate -->|"produces"| XRT
    BSAggregate -->|"produces"| Shim
    XRT -->|"invokes"| Shim
    Shim -->|"IOCTL/DRM"| Kernel
    Kernel -->|"loads"| Firmware

    %% Test suite validating multiple components
    Test -->|"validates"| XRT
    Test -->|"validates"| Shim
    Test -->|"validates"| Kernel
    Test -->|"validates"| Firmware

    %% Click Events (using project file tree paths)
    click BS_C "https://github.com/amd/xdna-driver/tree/main/CMake"
    click BS_D "https://github.com/amd/xdna-driver/blob/main/src/driver/CMake/config/dkms.conf.in"
    click BS_L "https://github.com/amd/xdna-driver/blob/main/CMakeLists.txt"
    click XRT "https://github.com/amd/xdna-driver/blob/main/build/build.sh"
    click Shim "https://github.com/amd/xdna-driver/tree/main/src/shim"
    click Kernel "https://github.com/amd/xdna-driver/tree/main/src/driver/amdxdna"
    click Firmware "https://github.com/amd/xdna-driver/tree/main/tools/bins"
    click Test "https://github.com/amd/xdna-driver/tree/main/example"

    %% Styles for different layers
    classDef kernel fill:#ADD8E6,stroke:#0000FF,stroke-width:2px
    classDef userspace fill:#90EE90,stroke:#006400,stroke-width:2px
    classDef build fill:#FFD700,stroke:#B8860B,stroke-width:2px
    classDef firmware fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px
    classDef test fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px
```
