百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
X

xdna-driver

> 编程语言
开源

适用于 Linux 和 XRT SHIM 库的 AMD XDNA 驱动程序 (amdxdna.ko)

605 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

适用于 Linux 和 XRT SHIM 库的 AMD XDNA 驱动程序 (amdxdna.ko)

AMD XDNA™️ Driver for Linux®️

This repository is for the AMD XDNA™️ Driver (amdxdna.ko) for Linux®️ and XRT SHIM library development.

Table of Contents

  • Introduction
  • System Requirements
  • Linux compilation and installation
  • Clone
  • Build
  • Test
  • Q&A
  • Contributor Guidelines

Introduction

This repository is for supporting XRT on AMD XDNA devices. From this repository, you can build a XRT plugin DEB package. On a machine with XDNA device, with both XRT and XRT plugin packages installed, user can start using XDNA device on Linux.

System Requirements

To run AI applications, your system needs

  • Processor:
    • To run AI applications (test machine): RyzenAI processor
    • To build this repository (build machine): Any x86 processors, but recommend AMD processor :wink:
  • Operating System:
    • Ubuntu >= 22.04
    • Arch Linux
    • Fedora >= 44
  • Linux Kernel: v6.10 or above. (See Linux compilation and installation)
    • Due to Linux API change, XDNA driver doesn't always keep supporting old version.
  • Installed XRT base package (or you can install it along the following recipe)
    • To make sure the XRT base package works with the plug-in package, better build it from xrt submodule in this repo (/xrt)
    • Refer to https://github.com/Xilinx/XRT for more detailed information.

Linux compilation and installation

Ubuntu 25.04

Ubuntu 25.04 includes Linux kernel 6.14 that incorporates the amdxdna driver for AMD NPUs :partying_face:.

The XRT SHIM library is still needed from this repository.

Ubuntu 24.10

Ubuntu 24.10 includes Linux kernel 6.11 that meets the requirements for the xdna-driver.

Ubuntu 24.04

If you are using Ubuntu 24.04 you may need to update the Linux kernel. You can update to Linux 6.11 by installing the Hardware Enablement (HWE) stack:

bash
sudo apt update 
sudo apt install --install-recommends linux-generic-hwe-24.04
sudo reboot

Ubuntu 22.04

Since Linux v6.10 officially supports AMD IOMMU SVA, we can work with upstream Linux kernel source. If your system has Linux v6.10 or above installed, check if CONFIG_AMD_IOMMU and CONFIG_DRM_ACCEL are set. If not, the system is not good for XDNA driver.

If you want to manually build Linux kernel, follow below steps.

…

Clone

The vtd submodule stores binary archives via Git LFS. Install git-lfs and run git lfs install once before cloning (or before running git submodule update):

bash
# Ubuntu/Debian
sudo apt-get install git-lfs
# Fedora/RHEL
sudo dnf install git-lfs
# Arch Linux
sudo pacman -S git-lfs

# Register LFS hooks globally (once per machine)
git lfs install
bash
git clone [email protected]:amd/xdna-driver.git
cd 
# get code for submodules
git submodule update --init --recursive

Build

Prerequisite

  • If this is your first time building this module, follow below steps to resolve the dependencies (or at least look at the file content if you're not on a distro with apt-get)
bash
#requires root permissions to run the script
sudo su
cd 
./tools/amdxdna_deps.sh
# exit from root
exit

Steps to create release build DEB package (Ubuntu/Debian):

bash
cd /build

# If you do not have XRT installed yet:
cd xrt/build
./build.sh -npu -opt
# Then follow the installation guide in test

# Then build the xdna driver 
cd ../../build

# Start XDNA driver release build and create release DEB package
./build.sh -release

Follow the installation guide in the Test to install and test.

Steps to create release build packages (Arch Linux):

…

Follow the installation guide in the Test to install and test. Arch users are also advised to configure memory limits required for NPU access.

Note for Arch Linux users: The build system generates .tar.gz packages which are repackaged into proper Arch packages (.pkg.tar.zst) using the provided PKGBUILDs:

  • XRT packages: xrt/build/arch/ (PKGBUILD-xrt-base, PKGBUILD-xrt-npu)
  • AMDXDNA driver: build/arch/ (PKGBUILD-amdxdna-driver)
  • XDNA plugin: build/arch/ (PKGBUILD-xrt-plugin-amdxdna)

This ensures proper integration with pacman for installation, upgrades, and removal.

Driver in the plugin package

The kernel driver lives in drivers/accel/amdxdna/, mirrored from the Linux kernel staging tree.

./build.sh -release builds the driver and packages it into the plugin DEB:

  • amdxdna.ko — built from the upstream (staging) tree. DKMS compiles it on install and modprobe loads it automatically.

You will find xrt_plugin._--amdxdna.deb (Ubuntu/Debian) or xrt_plugin._--amdxdna.tar.gz (Arch Linux) in the Release/ folder. This package includes:

  • The .so library files, which will be installed into /opt/xilinx/xrt/lib folder
  • The XDNA driver source and DKMS script that build, install, and load amdxdna.ko on the target machine.
  • The firmware binary files, which will be installed to /usr/lib/firmware/amdnpu folder

Steps to create release build packages (Fedora)

bash
cd 

# Install dependencies (requires sudo)
sudo ./tools/amdxdna_deps.sh

# Get submodules
git submodule update --init --recursive

# Build XRT
cd xrt/build
./build.sh -npu -opt

# Build XDNA driver
cd ../../build
./build.sh -release

Follow the installation guide in the Test to install and test.

Test

If you haven't read System Requirements, double check it. Install the driver (if not already) and the plugin package generated during Build for your platform, then validate.

Ubuntu/Debian:

bash
sudo apt reinstall ./Release/xrt_plugin.2.19.0_ubuntu22.04-x86_64-amdxdna.deb

Arch Linux:

…

Note (Fedora): if ulimit -l still reports a low value (e.g. 8192) after setting the drop-in file above, Fedora's systemd --user may also need a higher memlock limit:

bash
sudo systemctl edit [email protected]

Add:

ini
[Service]
LimitMEMLOCK=infinity

Log out and log back in (or reboot), then verify:

bash
ulimit -l
xrt-smi examine

Q: xrt-smi enumerates the NPU, but commands abort (ERT_CMD_STATE_ABORT) or the mailbox times out right after load. What's wrong?

A: This is almost always a firmware/driver version mismatch — a stale NPU firmware (npu.sbin) left over from a previous or distro install does not match the loaded amdxdna.ko. The plugin package ships the matching firmware to /usr/lib/firmware/amdnpu//; make sure that copy is the one in use (re-install the plugin package, or remove a stale firmware you placed by hand), then reload the driver. Mixing a firmware version from one source with a driver from another is the common cause of post-load command aborts.

Q: The device enumerates, but telemetry/array queries fail with "Operation not supported" or EINVAL (e.g. GET_ARRAY, QUERY_TELEMETRY). Why?

A: Your XRT/plugin is newer than the loaded kernel driver. A distro in-tree amdxdna can predate ioctls that the current XRT SHIM issues, so those calls return EOPNOTSUPP/EINVAL while basic BO/exec paths still work. Use the driver built and shipped from this repo (the staging amdxdna.ko — see Driver in the plugin package, which implements the matching ioctls, rather than an older in-tree module.

Contributor Guidelines

  1. Read Getting Started
  2. Read System Requirements
  3. Run Linux checkpatch.pl before commit and create pull request, see Checkpatch

Checkpatch

  • There is a pre-commit script to run checkpatch.pl automatically.
bash
# How to setup the auto pre-commit check
cd /
cp tools/pre-commit .git/hooks/

git commit will reject the commit if error/warning is found, until you make checkpatch.pl happy.

  • There is shell script that scan all the source code in a folder
bash
cd /
./tools/codingsty_check.sh 

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言