Skip to content

linux-getting-started.md

Latest commit

 

History

History
164 lines (119 loc) · 4.62 KB

linux-getting-started.md

File metadata and controls

164 lines (119 loc) · 4.62 KB

Linux Getting Started Guide

This guide will help you get started with FastFlowLM on Linux, including setup for various distributions and NPU (Neural Processing Unit) support.

Supported Distributions

  • Ubuntu 24.04 LTS
  • Ubuntu 25.10
  • Arch Linux
  • Other (Generic Linux)

Prerequisites

  • amdxdna driver (included in kernel 7.0+, or via amdxdna-dkms)
  • NPU firmware version 1.1.0.0 or later
  • Python 3.8+
  • XRT stack from AMD

System Preparation

Ubuntu (24.04, 25.10)

1. Add the AMD XRT PPA (Required for NPU/XDNA)

The AMD XRT stack is a prerequisite for NPU support. Add AMD's PPA:

sudo add-apt-repository ppa:lemonade-team/stable
sudo apt update

See lemonade-team/stable PPA for details.

2. Install XRT and NPU Drivers

sudo apt install libxrt-npu2 amdxdna-dkms

3. Reboot

sudo reboot

4. Install FastFlowLM

sudo apt install ./fastflowlm*.deb

5. (NPU) Check memlock limit

  • Run: 
    ulimit -l
  • If not unlimited, add to /etc/security/limits.conf: 
    *    soft    memlock    unlimited
*    hard    memlock    unlimited
  • Reboot system

Arch Linux

Arch requires both the kernel-side amdxdna driver and the XRT userspace plugin. flm validate can see the NPU through /dev/accel/accel0, but flm run uses XRT (xrt::device(0)), so both layers must be working.

1. Install the runtime packages

sudo pacman -Syu
sudo pacman -S linux-headers linux-firmware-other xrt xrt-plugin-amdxdna

Install amdxdna-dkms from the AUR using your preferred AUR workflow, then rebuild the module for the running kernel if needed:

sudo dkms autoinstall -k "$(uname -r)"
sudo depmod -a
sudo reboot

If you need to rebuild a specific DKMS version, check dkms status and use that version explicitly.

If you run a non-default kernel, install the matching headers package instead, for example linux-zen-headers for linux-zen.

2. Confirm the DKMS driver is selected

After rebooting, make sure modinfo resolves to the DKMS module rather than the in-tree kernel module:

modinfo -F filename amdxdna

Expected output should contain updates/dkms, for example:

/lib/modules/6.19.13-arch1-1/updates/dkms/amdxdna.ko.zst

If it points under kernel/drivers/accel/amdxdna/, the stock kernel driver is still being used. Recheck matching headers, the DKMS build status, sudo depmod -a, and reboot.

3. Confirm XRT sees the NPU

xrt-smi examine

The output should list an NPU under the device table. If flm validate succeeds but flm run fails with No such device with index '0', XRT usually cannot see the NPU. Confirm xrt-plugin-amdxdna is installed and that xrt-smi examine lists the device before trying flm run again.

4. Firmware note for Linux 6.19

Some Arch linux-firmware-other versions include both npu.sbin.1.0.0.63.zst and npu.sbin.1.1.2.64.zst for 17f0_10. On the stock 6.19 in-tree amdxdna driver, forcing npu.sbin.zst to the 1.1 firmware can make the NPU disappear because the driver expects the older firmware protocol. The DKMS driver can use the protocol-7 firmware through npu_7.sbin.zst.

In short: if 1.1 firmware breaks probing on stock 6.19, do not keep forcing the npu.sbin.zst symlink. Use amdxdna-dkms or a kernel with the newer amdxdna driver, then verify flm validate reports firmware version 1.1.x.

Building from Source

  1. Ensure all required development packages are installed:

    sudo apt install ninja
sudo apt install libavformat-dev  libavutil-dev libavcodec-dev libswresample-dev libswscale-dev libxrt-dev uuid-dev libdrm-dev

  2. Clone the repository and pull all submodules:

    git clone --recursive https://github.com/FastFlowLM/FastFlowLM.git
cd FastFlowLM

  3. Build:

    cd src
cmake --preset linux-default
cd build
cmake --build . -j$(nproc)
sudo cmake --install .

Validating NPU Setup

To validate your NPU setup, run:

flm validate

You should see output similar to:

[Linux]  Kernel: 7.0.0-rc1-00052-g27936bfca73d
[Linux]  NPU: /dev/accel/accel0
[Linux]  NPU FW Version: 1.1.2.64
[Linux]  Memlock Limit: infinity

If validation passes but running a model fails, check XRT separately:

xrt-smi examine

flm validate uses the kernel DRM device directly, while flm run uses XRT. On Linux, a passing validation does not guarantee XRT can open device index 0.