IRON is an open-source & close-to-metal Python API enabling fast and efficient execution on AMD Ryzen™ AI NPUs. It relies on language bindings around the MLIR-AIE dialect.

The IRON Python API for Ryzen™ AI NPUs is described in the following paper:

E. Hunhoff, J. Melber, K. Denolf, A. Bisca, S. Bayliss, S. Neuendorffer, J. Fifield, J. Lo, P. Vasireddy, P. James-Roxby, E. Keller. "Efficiency, Expressivity, and Extensibility in a Close-to-Metal NPU Programming Interface". In 33rd IEEE International Symposium On Field-Programmable Custom Computing Machines, May 2025.

Use this dashboard to quickly check the status of each kernel and locate relevant setup, build, and usage information.

These instructions will guide you through everything required for building and executing a program on the Ryzen™ AI NPU, starting from a fresh bare-bones Ubuntu 24.04 or Ubuntu 24.10 install.

Be sure you have the latest BIOS on your laptop or mini-PC that enables the NPU. See here.

If starting from Ubuntu 24.04 you may need to update the Linux kernel to 6.11+ by installing the Hardware Enablement (HWE) stack:

sudo apt update
sudo apt install --install-recommends linux-generic-hwe-24.04
sudo reboot

1. Install XDNA™ Driver and XRT:

   Instructions from mlir-aie repository

2. Install the packages needed for IRON and MLIR-AIE:

   # Python versions 3.10, 3.12 and 3.13 are currently supported by our wheels
   sudo apt install \
   build-essential clang clang-14 lld lld-14 cmake ninja-build python3-venv python3-pip

3. Setup a virtual environment and activate it:

   python3 -m venv ironenv
   source ironenv/bin/activate
   python3 -m pip install --upgrade pip

4. Source XRT (installed in step 1):

   source /opt/xilinx/xrt/setup.sh

5. Install required Python packages (from requirements.txt):

   MLIR_PYTHON_EXTRAS_SET_VERSION="0.0.8.3" HOST_MLIR_PYTHON_PACKAGE_PREFIX="aie" pip install -r requirements.txt

6. To test your installation, you can try to build and run the example below:

   cmake -B build
   cmake --build build --target silu_1_cols_1_channels_2048_tile_2048_run

Note: On a fresh install, if you get CMake Error: Could not find CMAKE_ROOT !!!, just deactivate and reactivate your python environment.

NOTE: Be sure the XRT setup script has been sourced: source /opt/xilinx/xrt/setup.sh

IRON is a CMake-based project. To configure the project, run:

cmake -B build

To build all designs, use:

cmake --build build

To test all the designs, use the following python script:

./scripts/run_tests.py --iter 1

You can select a single test to run using the --select flag.

Targets are listed when running cmake -B build with the following syntax:

Registering Executable: <TARGET_NAME>

If you want to build only a specific design, run:

# Example: cmake --build build --target silu_4_cols_1_channels_2048_tile_512
cmake --build build --target <TARGET_NAME>

You can also test an individual (or a selection of multiple) test(s) using the same script:

./scripts/run_tests.py --select <TARGET_ONE> --select <TARGET_TWO>

Additionally a target to build & run is made available under the <TARGET_NAME>_run symbol.

cmake --build build --target silu_4_cols_1_channels_2048_tile_512_run

To ensure your code passes CI linting checks before pushing, install the pre-push hook:

cp scripts/hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

The hook will run the same linting checks as CI:

• License checks (reuse)
• Python formatting (black)
• C++ formatting (clang-format)

To bypass the hook if needed: git push --no-verify

Copyright© 2025 Advanced Micro Devices, Inc