Skip to content

Commit

Permalink
Update README for latest version
Browse files Browse the repository at this point in the history
  • Loading branch information
@keryell
keryell committed Apr 12, 2024
1 parent a28393b commit f9f8ed3
Showing 1 changed file with 62 additions and 27 deletions.
89 changes: 62 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ This repository is for the AMD XDNA™️ Driver (amdxdna.ko) for Linux®️ and
## Table of Contents
- [Introduction](#introduction)
- [System Requirements](#system-requirements)
- [Linux compilation and installation](#linux-compilation-and-installation)
- [Clone](#clone)
- [Build](#build)
- [Test](#test)
Expand All @@ -19,66 +20,99 @@ 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
* 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 (<root-of-source-tree>/xrt)
* 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.

*Important*: IOMMU SVA in Linux kernel support is required.

## Linux compilation and installation

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
The 6.8 Linux kernel with SVA source code can be downloaded from _v6.8-iommu-sva-part4-v7_ on https://github.com/AMD-SW/linux
``` bash
# Assuming you have knowledge of kernel compile, this just refreshing up a few key points.
# Assuming you have knowledge of kernel compilation,
# this is just refreshing up a few key points.

git clone --branch iommu_sva_part4_v6_v6.8_rc2 [email protected]:AMDESE/linux.git
cd linux/
git clone --depth=1 --branch v6.8-iommu-sva-part4-v7 [email protected]:AMD-SW/linux
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
# 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

# Otherwise if you do not have a `.config` file modern enough, you can
# get one for Debian/Ubuntu with
https://gist.github.com/keryell/a0d0c020f81128d0f0071f16c9022000/raw/069d79a53fd20193ea4c9fa469d84ffc334229bb/.config

# 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
make -j `nproc` bindeb-pkg
# The exact names will depend on your configuration
sudo apt reinstall ../linux-headers-6.8.5+iommu-sva-part4-v7+_6.8.5-00095-g88132f705404-2_amd64.deb ../linux-image-6.8.5+iommu-sva-part4-v7+_6.8.5-00095-g88132f705404-2_amd64.deb ../linux-libc-dev_6.8.5-00095-g88132f705404-2_amd64.deb
```

## Clone
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.

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>
git clone [email protected]:amd/xdna-driver.git
cd <root-of-source-tree>
# get code for submodules
% git submodule update --init --recursive
git submodule update --init --recursive
```

## Build

### Prerequisite
* If this is your first time building this module, follow below steps to resolve the dependencies.

* If this is your first time building this module,
follow below steps to resolve the dependencies or at least look at
the file content
``` bash
sudo su #requires root permissions to run the script
#requires root permissions to run the script
sudo su
cd <root-of-source-tree>
./tools/amdxdna_deps.sh
exit #exit from root
# exit from root
exit
```

### Steps to create release build DEB package:

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

# Start release build
# If you do not have XRT installed yet:
cd xrt/build
./build.sh
# To adapt according to your OS & version
sudo apt reinstall ./Release/xrt_202410.2.17.0_23.10-amd64-xrt.deb ./Release/xrt_202410.2.17.0_23.10-amd64-xbflash2.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.17.0_ubuntu23.10-x86_64-amdxdna.deb
```
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
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

## Test

If you haven't read [System Requirements](#system-requirements), double check it.

``` bash
Expand All @@ -88,14 +122,15 @@ 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>
# Run the test
./example_build/example_noop_test ../tools/bins/1502_00/validate.xclbin
```

## Q&A
### Q: I want to debug my application, how to build library with '-g'?

A: We have debug version of library, which is compiled with '-g' option. You can run `./build.sh -debug` or `./build.sh`.
### Q: I want to debug my application, how to build library with `-g`?

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.

### Q: When build -release or -debug, can I specify linux kernel version different than currently running linux kernel?
Expand All @@ -104,7 +139,7 @@ A: Yes. For example, if you have 6.6-rc1 linux header install on your build mach

### Q: I'm developing amdxdna.ko driver module. How to enable XDNA_DBG() print?

A: XDNA_DBG() relies on Linux's CONFIG_DYNAMIC_DEBUG framework, see Linux's [dynamic debug howto page](https://www.kernel.org/doc/html/v6.5/admin-guide/dynamic-debug-howto.html) for details.
A: XDNA_DBG() relies on Linux's CONFIG_DYNAMIC_DEBUG framework, see Linux's [dynamic debug howto page](https://www.kernel.org/doc/html/v6.8/admin-guide/dynamic-debug-howto.html) 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.

### Q: When install XRT plugin DEB package, apt-get/dpkg tool failed. What to do next?
Expand All @@ -121,4 +156,4 @@ There is a pre-commit script for this purpose.
``` bash
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.
`git commit` will reject the commit if error/warning is found, until you make `checkpatch.pl` happy.

0 comments on commit f9f8ed3

Please sign in to comment.