This repository is for the AMD XDNA™️ Driver (amdxdna.ko) for Linux®️ and XRT SHIM library development.
- Introduction
- System Requirements
- Linux compilation and installation
- Clone
- Build
- Test
- Q&A
- Contributor Guidelines
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.
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 😉
- Operating System:
- Ubuntu >= 22.04
- Arch Linux
- 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 (<root-of-source-tree>/xrt
) - Refer to https://github.com/Xilinx/XRT for more detailed information.
- To make sure the XRT base package works with the plug-in package, better build it from
Since Linux v6.10 offically 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.
# Assuming you have knowledge of kernel compilation,
# this is just refreshing up a few key points.
# Clone Linux source code from your favorite repository, for example
git clone --depth=1 --branch v6.10 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
# Usually, when people compile kernel from source code, they use current config
cp /boot/config-`uname -r` <your_build_dir>/.config # (Option step, if you know how to do it better)
# Open <your_build_dir>/.config and add "CONFIG_DRM_ACCEL=y" #Required by XDNA Driver
# Or run instead
scripts/config --file .config --enable DRM_ACCEL
scripts/config --file .config --enable AMD_IOMMU # Option step, if you know this is not set
# Use below command to build kernel packages. Once build is done, DEB packages are at the parent directory of <your_build_dir>
make -j `nproc` bindeb-pkg
# The exact names will depend on your configuration
sudo apt reinstall ../linux-headers-6.10.0_6.10.0-1_amd64.deb ../linux-image-6.10.0_6.10.0-1_amd64.deb ../linux-libc-dev_6.10.0-1_amd64.deb
git clone git@github.com:amd/xdna-driver.git
cd <root-of-source-tree>
# get code for submodules
git submodule update --init --recursive
- 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)
#requires root permissions to run the script
sudo su
cd <root-of-source-tree>
./tools/amdxdna_deps.sh
# exit from root
exit
cd <root-of-source-tree>/build
# If you do not have XRT installed yet:
cd xrt/build
./build.sh -npu -opt
# To adapt according to your OS & version
sudo apt reinstall ./Release/xrt_202510.2.19.0_22.04-amd64-npu.deb
cd ../../build
# Start XDNA driver release build
./build.sh -release
# Create DEB package for existed release or debug build.
./build.sh -package
# To adapt according to your OS & version
sudo apt reinstall ./Release/xrt_plugin.2.19.0_ubuntu22.04-x86_64-amdxdna.deb
You will find xrt_plugin\*-amdxdna.deb
in Release/ folder. This package includes:
- The
.so
library files, which will be installed into/opt/xilinx/xrt/lib
folder - The XDNA driver and DKMS script, which build, install and load
amdxdna.ko
driver when installing the .DEB package on target machine - The firmware binary files, which will be installed to
/usr/lib/firmware/amdnpu
folder
If you haven't read System Requirements, double check it.
source /opt/xilinx/xrt/setup.sh
cd <root-of-source-tree>/build
# Build the test program
./build.sh -example
# Run the test
./example_build/example_noop_test ../tools/bins/1502_00/validate.xclbin
A: We have debug version of library, which is compiled with -g
option. You can run ./build.sh -debug
or ./build.sh
.
To create a debug DEB package, run ./build.sh -package
afterward.
A: XDNA_DBG() relies on Linux's CONFIG_DYNAMIC_DEBUG framework, see Linux's dynamic debug howto page for details.
TL;DR, run sudo insmod amdxdna.ko dyndbg=+pf
to enable XDNA_DBG() globally, where +pf means enable debug printing and print the function name.
A: Create a debug DEB package, see above question. Then install debug DEB package in your environment. This time, you will have more verbose log. Share this log with us.
A: You can use NPU to accelerate ML inference. But NPU is not designed for ML training.
A: There is no limit for BO size from the XRT and NPU device. An application can fail to allocate a huge BO, once it hits the Linux resource limit. In our test, the "max locked memory" is the key. You can follow below steps to check and change configure.
ulimit -l # The result is in kbytes
# Open /etc/security/limits.conf, add below two lines.
# * soft memlock <max-size-in-kbytes>
# * hard memlock <max-size-in-kbytes>
#
# See comments of the file for the meaning of each column.
# Reboot the machine, then check if the limite is changed
ulimit -l
- Read Getting Started
- Read System Requirements
- Run Linux checkpatch.pl before commit and create pull request, see Checkpatch
There is a pre-commit script for this purpose.
cp xdna-driver/tools/pre-commit <root-of-source-tree>/.git/hooks/
git commit
will reject the commit if error/warning is found, until you make checkpatch.pl
happy.