Building the AMD XDNA Linux driver and its XRT plugin package

What the repository actually produces

This is not an application repository. It holds the AMD XDNA driver (amdxdna.ko) for Linux and the development tree for the XRT SHIM library, and the deliverable is a distributable plugin package rather than a binary you can download.

The README states the purpose plainly: the repository is for supporting XRT on AMD XDNA devices, and from it you can build an XRT plugin DEB package. On a machine that has an XDNA device and both the XRT base package and this plugin package installed, the XDNA device becomes usable on Linux.

The kernel driver lives in drivers/accel/amdxdna/ and is mirrored from the Linux kernel staging tree. That single fact shapes most of the practical experience of building it. A release build produces amdxdna.ko from that upstream tree, and DKMS compiles the module on install and modprobe loads it automatically. The plugin package also carries the .so library files installed into the /opt/xilinx/xrt/lib folder, the driver source and DKMS script, and the firmware binaries installed to /usr/lib/firmware/amdnpu.

The top-level layout backs this up: drivers/, src/, include/, build/, CMake/, tools/, test/, plus an xrt submodule and a vtd submodule.

The kernel decides whether you need this at all

Whether you must build anything depends heavily on your distribution, and the README walks through the cases. Ubuntu 25.04 ships Linux kernel 6.14, which already incorporates the amdxdna driver for AMD NPUs, so the kernel module side is covered. The XRT SHIM library is still needed from this repository even there, which is the detail that catches people out.

Ubuntu 24.10 includes kernel 6.11, which the README says meets the requirements for the driver. Ubuntu 24.04 users may need to update the kernel to 6.11 through the Hardware Enablement stack, because 6.10 is the stated minimum.

On Ubuntu 22.04 the story is longer. Linux 6.10 is where AMD IOMMU SVA is officially supported upstream, so the driver can work against upstream kernel source, but only if CONFIG_AMD_IOMMU and CONFIG_DRM_ACCEL are set. If they are not, the README says plainly that the system is not good for the XDNA driver.

The kernel requirement carries a permanent caveat. The README notes that due to a Linux API change the XDNA driver does not always keep supporting older kernel versions, and the stated floor for all of this is v6.10 or above. Arch Linux and Fedora 44 or above are also listed as supported operating systems.

Cloning needs Git LFS and two submodules

The vtd submodule stores binary archives through Git LFS, so Git LFS has to be installed and its hooks registered before you clone, or before you update submodules. The README walks through the installation for Ubuntu/Debian, Fedora/RHEL and Arch, then registers the hooks globally once per machine.

The clone itself is short. Install and configure LFS first, then take the source tree and pull in the submodules:

git clone [email protected]:amd/xdna-driver.git
cd <root-of-source-tree>
git submodule update --init --recursive

Two details deserve attention. The clone URL is the SSH form, so the operation needs a configured GitHub key rather than anonymous HTTPS access. And the recursive submodule update matters for more than tidiness, because the XRT base package is expected to come from the xrt submodule inside this same tree. The README advises building XRT from that submodule to make sure it works with the plugin package, pointing at the Xilinx/XRT repository for the finer details.

If you already have XRT installed system wide, the README notes that this base package is still a prerequisite, and the plugin build has a branch for the case where XRT is not installed yet.

Building on Ubuntu and Debian runs a dependency script as root

The first build of the module has an extra step. The README calls it a prerequisite and describes resolving dependencies with a script under tools/, which requires root permissions, on the grounds that not every distribution uses apt-get and the file itself is worth reading if you are elsewhere.

sudo su
cd <root-of-source-tree>
./tools/amdxdna_deps.sh
exit

After dependencies are resolved, the Ubuntu and Debian path builds XRT first, because the plugin depends on the base package, then builds the driver itself:

cd xrt/build
./build.sh -npu -opt
cd ../../build
./build.sh -release

The -npu and -opt flags select the NPU-oriented XRT build. The release build is what packages the driver, and the result lands in the Release/ folder as xrt_plugin.<version>_<distro-version>-<arch>-amdxdna.deb. The README then points you at the test and installation instructions for that package.

Note the ordering constraint embedded in the commands: the XRT build happens inside xrt/build, then the driver build happens one directory up, and the two are not interchangeable steps.

Arch Linux gets four PKGBUILDs instead of one DEB

Arch users get a different packaging route, and the README explains why. The build system generates .tar.gz packages that are repackaged into proper Arch packages (.pkg.tar.zst) using the PKGBUILDs in the tree. The plugin package for Arch is named xrt_plugin.<version>_-<arch>-amdxdna.tar.gz rather than the Debian package.

Four PKGBUILDs are involved, and their locations are spelled out: the XRT packages live in xrt/build/arch/ (PKGBUILD-xrt-base, PKGBUILD-xrt-npu), the AMDXDNA driver in build/arch/ (PKGBUILD-amdxdna-driver), and the XDNA plugin in build/arch/ (PKGBUILD-xrt-plugin-amdxdna).

makepkg -p PKGBUILD-xrt-base
makepkg -p PKGBUILD-xrt-npu
makepkg -p PKGBUILD-amdxdna-driver
makepkg -p PKGBUILD-xrt-plugin-amdxdna

The comments in the README add a dependency detail worth carrying over to any other distribution: the AMDXDNA driver is a separate package for the DKMS-based kernel module, and the plugin package depends on it. On Arch, the dependency script runs under sudo rather than inside a root shell, and the README additionally advises Arch users to configure the memory limits required for NPU access.

This repackaging exists so that pacman handles installation, upgrades and removal, which is the practical argument for doing it this way.

Where this route stops being the sensible one

There are clear cases where building this repository is wasted effort. If your distribution already ships a kernel with the amdxdna driver, the module half of the problem is solved, and the README says as much for Ubuntu 25.04. If you do not need the XRT SHIM library, there is little reason to build anything here at all.

There is also a cost to the mirroring arrangement. Because drivers/accel/amdxdna/ is mirrored from the Linux kernel staging tree, the source you build is by definition a copy of something in motion, and the README's warning about Linux API changes means a driver that worked against one kernel can fail against the next. DKMS will rebuild the module on install, so a kernel update triggers a rebuild of code that may not have kept up.

The dependency chain is the other friction point. Nothing works without the XRT base package, and the README asks you to build that from the xrt submodule rather than mixing in a distribution or vendor build, which means the build is not a single package install but a sequenced build of base package, driver and plugin. There is no binary release published on the repository to fall back on, so there is no shortcut if the source build fails.

A kernel built by hand is the last resort, not the first step

If CONFIG_DRM_ACCEL or CONFIG_AMD_IOMMU is missing on your kernel, the README describes building a kernel from source as a manual path. It assumes you already know how to compile a kernel and calls itself a refresh of a few key points, cloning the upstream source at tag v6.10, copying the running configuration into the build directory, enabling the required options, and producing Debian packages with a bindeb-pkg target.

The two option changes that matter are:

scripts/config --file .config --enable DRM_ACCEL
scripts/config --file .config --enable AMD_IOMMU # Option step, if you know this is not set

The README marks CONFIG_DRM_ACCEL as required by the XDNA driver and treats CONFIG_AMD_IOMMU as optional if you already know it is set. The kernel packages are then installed with apt reinstall, and the exact file names depend on your configuration.

This is the most expensive path in the whole flow: it replaces a driver build with a kernel build, it ties you to one upstream tag, and the resulting packages carry your own configuration choices. The README presents it for users who want to build a kernel manually, not as the default starting point for installing an NPU driver.

Editorial conclusion

This repository is the right tool if you need an XRT plugin package for an AMD NPU on a distribution whose kernel does not already carry a usable amdxdna module, and it is the wrong tool if your machine runs Ubuntu 25.04 or newer with a stock kernel that includes the driver and only needs the XRT SHIM library from this source. Before starting, confirm that your kernel is 6.10 or above with CONFIG_DRM_ACCEL and CONFIG_AMD_IOMMU enabled, build the XRT base package from the xrt submodule rather than from a distribution package, and remember that the driver is mirrored from the kernel staging tree, so the module you build today may not match the next kernel release.

Frequently asked questions

Official sources

1. amd/xdna-driver on GitHub
2. Issues
3. README