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

• Introduction
• System Requirements
• 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
• Linux Kernel: v6.8 with IOMMU SVA support (see below)
• Installed XRT base package
  • 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.

Important: IOMMU SVA in Linux kernel support is required.

You need to manually build 6.8 Linux kernel packages by following below steps.

The 6.8 Linux kernel with SVA source code can be downloaded from iommu_sva_part4_v6_v6.8_rc2 on https://github.com/AMDESE/linux

# Assuming you have knowledge of kernel compile, this just refreshing up a few key points.

git clone --branch iommu_sva_part4_v6_v6.8_rc2 [email protected]:AMDESE/linux.git 
cd linux/

# 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

# Use below command to build kernel packages. Once build is done, DEB packages are at the parent directory of <your_build_dir>
make ARCH=x86 O=<your_build_dir> bindeb-pkg -j4

This repository has src/xrt as a git submodule. The path to XRT is set up to clone as ssh, so you need a public key registered with your GitHub.com account.

% git clone [email protected]: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.

sudo su 	#requires root permissions to run the script
cd <root-of-source-tree>
./tools/amdxdna_deps.sh
exit  		#exit from root

cd <root-of-source-tree>/build

# Start release build
./build.sh -release

# Create DEB package for existed release or debug build.
./build.sh -package

You will find "xrt_plugin*-amdxdna.deb" in Release/ folder. This package includes below content:

• The .so library files, which will be install to /opt/xilinx/xrt/libs folder
• The XDNA driver and DKMS script, which build, install and load amdxdna.ko driver when install DEB package on target machine
• The firmware binary files, which will be installed to /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 (test xclbins can be found under /lib/firwmare/amdnpu/<deviceID>/validate.xclbin
./example_build/example_noop_test <path-to-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: Yes. For example, if you have 6.6-rc1 linux header install on your build machine. Run ./build.sh [-debug|-release] -kernel_ver 6.6-rc1

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==p to enable XDNA_DBG() globally.

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: In amdxdna driver, it will not directly use the xclbin passed from application. Instead, it loads verified xclbin from /lib/firmware/amdnpu/ directory. The driver will check if the UUID of the xclbin from application and firmware directory matched. If this match process failed, you will see this error.

A: Yes. Make sure you have root privilege of the system. Follow below steps,

# Assume you already have xrt_plugin DEB package installed
# You need root privilege to install firmware
sudo bash

source /opt/xilinx/xrt/setup.sh

# List supported device(s)
/opt/xilinx/xrt/amdxdna/setup_xclbin_firmware.sh -list

# Assume adding an unsigned xclbin on Phoenix, run
/opt/xilinx/xrt/amdxdna/setup_xclbin_firmware.sh -dev Phoenix -xclbin <test>.xclbin

# When xrt_plugin package is removed, it will be automaticlly cleaned up.
# User is able to setup multiple xclbins. But if setup two xclbins with the same file name,
# the previous one will be overwritten.

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

There is a pre-commit script for this purpose.

cp amd-aie/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.