# IRON / MLIR-AIE **A close-to-metal Python API for programming AMD Ryzen™ AI NPUs, built on an open-source MLIR-based compiler toolchain.** [![Build](https://img.shields.io/github/actions/workflow/status/Xilinx/mlir-aie/buildAndTestPythons.yml?branch=main&label=build&cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/actions/workflows/buildAndTestPythons.yml) [![Latest tag](https://img.shields.io/github/v/tag/Xilinx/mlir-aie?sort=semver&label=release&cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/tags) [![License](https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20exception-blue)](LICENSE) [![Contributors](https://img.shields.io/github/contributors/Xilinx/mlir-aie?cacheSeconds=86400)](https://github.com/Xilinx/mlir-aie/graphs/contributors) [![Discord](https://img.shields.io/badge/Discord-ROCm--NPU-5865F2?logo=discord&logoColor=white)](https://discord.gg/UbXzGdXsR5) 📖 **[Documentation](https://xilinx.github.io/mlir-aie/)** · 🚀 **[Programming Guide](programming_guide/)** · 🐍 **[Python API](https://xilinx.github.io/mlir-aie/api/)** · 💡 **[Examples](programming_examples/)** Write Python. Run it on the NPU. IRON compiles your Python design straight to the AI Engine array inside AMD Ryzen™ AI processors — you control tile placement, data movement, and vectorized compute, with nothing hidden behind a framework. Built for researchers and performance engineers pushing the NPU on everything from machine learning to digital signal processing, IRON *complements* mainstream inference tooling like the [AMD Ryzen™ AI Software Platform](https://github.com/amd/RyzenAI-SW/) rather than replacing it. ```python import aie.iron as iron from aie.iron import ObjectFifo, Program, Runtime, Worker from aie.iron.controlflow import range_ import numpy as np data_ty = np.ndarray[(1024,), np.dtype[np.int32]] @iron.jit def vector_add_one(a_in, b_out): of_in = ObjectFifo(data_ty, name="in") # host → compute tile of_out = ObjectFifo(data_ty, name="out") # compute tile → host def core_fn(of_in, of_out): # runs on one AIE core a = of_in.acquire(1) b = of_out.acquire(1) for i in range_(1024): b[i] = a[i] + 1 of_in.release(1); of_out.release(1) w = Worker(core_fn, [of_in.cons(), of_out.prod()]) def sequence(a, b, in_h, out_h): in_h.fill(a) out_h.drain(b, wait=True) rt = Runtime(sequence, [data_ty, data_ty, of_in.prod(), of_out.cons()]) return Program(iron.get_current_device(), rt, workers=[w]).resolve_program() a = iron.arange(1024, dtype=np.int32, device="npu") b = iron.zeros(1024, dtype=np.int32, device="npu") vector_add_one(a, b) # JIT-compiles on first call, runs on the NPU, caches after ``` `@iron.jit` compiles the design to an `xclbin` + instruction stream via the LLVM/MLIR-based [Peano](https://github.com/Xilinx/llvm-aie) compiler and runs it on the attached NPU. New to the concepts? Start with the [Programming Guide](programming_guide/) or the [Mini Tutorial](programming_guide/mini_tutorial/).

More about the toolchain

This repository contains an [MLIR-based](https://mlir.llvm.org/) toolchain for AI Engine-enabled devices, such as [AMD Ryzen™ AI](https://www.amd.com/en/products/processors/consumer/ryzen-ai.html) and [Versal™](https://www.xilinx.com/products/technology/ai-engine.html). It generates low-level configurations for the AI Engine portion of these devices. AI Engines are organized as a spatial array of tiles, where each tile contains AI Engine cores and/or memories. The spatial array is connected by stream switches that route data between tiles, scheduled by their programmable Data Movement Accelerators (DMAs). The repository provides MLIR representations at multiple levels of abstraction to target AI Engine devices, enabling compilers and developers to program cores and describe data movement and array connectivity. The [Peano](https://github.com/Xilinx/llvm-aie) component extends LLVM with the AI Engine processor as a target architecture, enabling integration with compiler frontends such as `clang`. Developers can use the [AIE API header library](https://xilinx.github.io/aie_api/topics.html) to write efficient vectorized AIE core code in C++ that Peano compiles. IRON 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](https://arxiv.org/abs/2504.18430)". In 33rd IEEE International Symposium On Field-Programmable Custom Computing Machines, May 2025.

## Ryzen™ AI host setup | Host | Start here | | --- | --- | | Linux (Ubuntu) | [Continue with the Linux setup below](#getting-started-for-amd-ryzen-ai-on-linux) | | Linux (non-Ubuntu) | [Non-Ubuntu Linux Setup](docs/buildHostLinNonUbuntu.md) | | Windows 11 | [Native Windows Setup](docs/buildHostWinNative.md) | | Windows via WSL | [Windows via WSL Setup](docs/buildHostWin.md) | ## Getting Started for AMD Ryzen™ AI on Linux 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. > **NOTE:** If you are using a different Linux distribution, see the [non-Ubuntu build guide](docs/buildHostLinNonUbuntu.md). Please be aware that building for distributions other than Ubuntu is experimental. Support may vary. ## Prerequisites ### BIOS Settings - Be sure you have the latest BIOS on your laptop or mini-PC that enables the NPU. See [here](#update-bios). - Turn off SecureBoot (Allows for unsigned drivers to be installed): `BIOS → Security → Secure boot → Disable` ### Linux Kernel Ensure your system is running Linux kernel **6.17 or newer** before installing these packages. On Ubuntu 24.04 you can verify this with: ```bash uname -r ``` If your kernel is older than 6.17, upgrade it using your distribution's kernel update mechanism -- on Ubuntu: ```bash sudo apt update sudo apt install --install-recommends linux-generic-hwe-24.04 sudo reboot ``` ### Install the XDNA™ Driver and XRT #### Install from upstream packages (Ubuntu 24.04 with Linux 6.17+) Install the XDNA driver and XRT from the AMD PPA: > The packaged XRT only supports Python 3.12 for `pyxrt` ```bash sudo add-apt-repository ppa:amd-team/xrt sudo apt update sudo apt install libxrt2 libxrt-npu2 libxrt-dev libxrt-utils libxrt-utils-npu amdxdna-dkms sudo reboot ``` > Make sure you are in the `render` group to access the NPU: > > ```bash > sudo usermod -aG render $USER > ``` > > You may need to logout and log back in after modifying user groups. > If you are on a different Linux distribution or kernel not supported by the upstream packages, see [Build from source](#alternative-build-xdna-driver-and-xrt-from-source) below. For non-Ubuntu distros (Arch, Void, Fedora-from-source, …) or kernels that already ship the in-tree `amdxdna` driver (Linux ≥ 6.14), see the [non-Ubuntu build guide](docs/buildHostLinNonUbuntu.md). Verify the NPU device is present: ```bash xrt-smi examine ``` > At the bottom of the output you should see: > ``` > Devices present > BDF : Name > ------------------------------------ > [0000:66:00.1] : NPU Strix > ``` ### Install IRON and MLIR-AIE Prerequisites Install the following packages needed for MLIR-AIE: ```bash # Python versions 3.11, 3.12, 3.13, and 3.14 are currently supported by our wheels sudo apt install \ build-essential clang clang-14 lld lld-14 cmake ninja-build python3-venv python3-pip uuid-dev ``` (Optional) Install opencv which is needed for vision programming examples: ```bash sudo apt install libopencv-dev python3-opencv ``` ## Install IRON for AMD Ryzen™ AI AIE Application Development ### From Pre-Built Binaries (Wheels) Set up and source a Python virtual environment and install the IRON library (`mlir-aie` wheel), and per-core compiler ("peano", `llvm-aie` wheel). The following is the **quickest path:** ````bash source utils/env_install.sh # one time / first time source utils/env_setup.sh # every time you open a new shell ```` This creates an environment named `ironenv` containing the toolchain. By default, the script will match the `mlir_aie` wheel associated with the currently checked-out release/commit of the repository. If it can't find a release for this commit, it will error, since trying to compile a version of the programming examples in this repository with a compiler wheel whose version does not exactly match very frequently leads to hard-to-debug errors. If you insist on using the latest available release from `main`, pass `--latest`. To manually install a different wheel, follow the manual instructions below. > *Tip:* The `utils/env_install.sh` script also works as an update script. ### From Source To build the compiler toolchain from source, you'll need additional dependencies. Install the requirements using: ````bash source utils/env_install.sh --dev # one time / first time source utils/env_setup.sh # every time you open a new shell ```` Then, build the compiler (`_from_wheels.sh` in this case refers to the LLVM installation being pulled from a wheel; MLIR-AIE links against LLVM, but will be built from source): ```bash ./utils/build-mlir-aie-from-wheels.sh ``` ### Manual Installation Steps Below steps replicate what the install script does.

Manual installation steps

1. Setup a virtual environment: ```bash python3 -m venv ironenv source ironenv/bin/activate python3 -m pip install --upgrade pip ``` 1. Install IRON library by installing the `mlir-aie` wheels: For installing the `mlir-aie` wheels, there are 3 options. Note that for whichever path you take, it is important to sync the `mlir-aie` wheels version, the GitHub repo commit, and the requirements versions. If you install from something other than the latest wheels, make sure you use the repo commit -- and installation instructions -- from that point in time. 1. **Latest:** For the latest wheels (not necessarily a release): ```bash # Install IRON library and mlir-aie from the latest wheel python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/latest-wheels-4 ``` 1. **Latest Release:** Alternatively, you can install the latest released version of `mlir-aie`. ```bash # Get the latest release version latest_tag_with_v=$(curl -s "https://api.github.com/repos/Xilinx/mlir-aie/releases/latest" | jq -r '.tag_name') latest_tag="${latest_tag_with_v#v}" # Install IRON library and mlir-aie from the latest stable release python3 -m pip install mlir_aie==${latest_tag} -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/${latest_tag_with_v} git checkout $latest_tag_with_v ``` 1. **Any Release:** You can install a specific version of `mlir-aie` from the release wheels. To see available versions, check out the [release page](https://github.com/Xilinx/mlir-aie/releases). ```bash # Install IRON library and mlir-aie from a specific release, # e.g., in the following command could be replaced with v1.1.3 python3 -m pip install mlir_aie -f https://github.com/Xilinx/mlir-aie/releases/expanded_assets/ git checkout ``` 1. Install the Peano compiler (the `llvm-aie` wheels) and dependencies: ```bash # Install Peano from the llvm-aie wheel, pinned to the tested nightly in # utils/peano-requirements.txt (the same pin CI uses; bumped by the update-peano # workflow). To grab the latest nightly instead, install `llvm-aie` directly # with `-f https://github.com/Xilinx/llvm-aie/releases/expanded_assets/nightly`. python3 -m pip install -r utils/peano-requirements.txt ``` 1. (Optional) Install Python packages required for development and testing: ```bash # Install Python requirements for development and testing python3 -m pip install -r python/requirements_dev.txt # Install the pre-commit and pre-push hooks defined in .pre-commit-config.yaml # (pre-push runs clang-format/black/ruff to catch formatting and lint issues before CI) pre-commit install ``` 1. Setup environment ```bash source utils/env_setup.sh ``` 1. (Optional) Install ML Python packages for ml programming examples: ```bash # Install Torch for ML examples python3 -m pip install -r python/requirements_ml.txt ``` 1. (Optional) Install Jupyter Notebook Python packages: ```bash # Install Jupyter Notebook python3 -m pip install -r python/requirements_notebook.txt # This creates an ipykernel (for use in notebooks) using the ironenv venv python3 -m ipykernel install --user --name ironenv # Only for Release v1.0 and non wheel-based installs: # The install generally captures in the $PYTHONPATH by the `env_setup.sh` script. # However, jupyter notebooks don't always get access to the PYTHONPATH (e.g., if they are run with # vscode) so we save the ${MLIR_AIE_INSTALL_DIR}/python in a .pth file in the site packages dir of the # ironenv venv; this allows the iron ipykernel to find the install dir regardless of if PYTHONPATH is # available or not. MLIR_AIE_INSTALL="$(pip show mlir_aie | grep ^Location: | awk '{print $2}')/mlir_aie" venv_site_packages="$(python3 -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')" echo "${MLIR_AIE_INSTALL}/python" > "$venv_site_packages/mlir-aie.pth" ```

## Run an IRON Design on the AMD Ryzen™ AI NPU on Linux The [programming examples](programming_examples/) use either of two entry points. Most examples use standalone `@iron.jit` to compile, run, and verify directly from Python: ```bash cd programming_examples// python3 .py ``` Examples with a separate native host, explicit artifact builds, or multi-stage workflow have a `Makefile`. Follow the example's README for its supported targets, such as `make run` or `make run_py`. ## Learn more about NPU programming with IRON 1. Continue to the [IRON AIE Application Programming Guide](programming_guide) 1. Additional MLIR-AIE documentation is available on the [website](https://xilinx.github.io/mlir-aie/) 1. AIE API header library documentation for single-core AIE programming in C++ is available [here](https://xilinx.github.io/aie_api/topics.html) 1. If you are a university researcher or student and interested in trying these tools on our Ryzen™ AI AUP Cloud systems, please contact the [AMD University Program](mailto:aup@amd.com) 1. Have a question or want to talk with the team and other users? Join the [ROCm Discord](https://discord.gg/UbXzGdXsR5) and look for the **ROCm-NPU** channel ## Optional: Install AIETools > You may skip the Vitis™ installation step if you intend to only target AMD XDNA™/AIE-ML (AIE2) and AMD XDNA™ 2 (AIE2P) using our open-source single-core compiler [Peano](https://github.com/Xilinx/llvm-aie). Compiling with `xchesscc` is not supported without installing AMD Vitis™ AIE Essentials. 1. Install Vitis™ AIE Essentials from [Ryzen AI Software 1.3 Early Access](https://account.amd.com/en/member/ryzenai-sw-ea.html#tabs-a5e122f973-item-4757898120-tab). We will assume you use the installation directory, `/tools/ryzen_ai-1.3.0/vitis_aie_essentials`. > This is an early access lounge, you must register and be granted access at this time. 1. Download VAIML Installer for Linux based compilation: `ryzen_ai-1.3.0ea1.tgz` 1. Extract the required tools: ```bash tar -xzvf ryzen_ai-1.3.0ea1.tgz cd ryzen_ai-1.3.0 mkdir vitis_aie_essentials mv vitis_aie_essentials*.whl vitis_aie_essentials cd vitis_aie_essentials unzip vitis_aie_essentials*.whl ``` 1. Set up an AI Engine license. 1. Get a local license for AI Engine tools from [https://www.xilinx.com/getlicense](https://www.xilinx.com/getlicense). 1. Copy your license file (Xilinx.lic) to your preferred location, e.g. `/opt/Xilinx.lic`: 1. Setup your environment using the following script for Vitis™ for AIETools: ```bash #!/bin/bash ################################################################################# # Setup Vitis AIE Essentials ################################################################################# export AIETOOLS_ROOT=/tools/ryzen_ai-1.3.0/vitis_aie_essentials export PATH=$PATH:${AIETOOLS_ROOT}/bin export LM_LICENSE_FILE=/opt/Xilinx.lic ``` ## Alternative: Build XDNA™ Driver and XRT from source If the [upstream packages](#install-from-upstream-packages-ubuntu-2404-with-linux-617) do not support your kernel or distribution, you can build the driver and XRT from source: 1. Execute the scripted build process: > This script will install package dependencies, build the xdna-driver and xrt packages, and install them. *These steps require `sudo` access.* ```bash bash ./utils/build_drivers.sh ``` 1. Reboot as directed after the script exits. ```bash sudo reboot ``` 1. Check that the NPU is working if the device appears with xrt-smi: ```bash source /opt/xilinx/xrt/setup.sh xrt-smi examine ``` ## Troubleshooting ### Update BIOS Be sure you have the latest BIOS for your laptop or mini PC, this will ensure the NPU (sometimes referred to as IPU) is enabled in the system. You may need to manually enable the NPU: `Advanced → CPU Configuration → IPU` > **NOTE:** Some manufacturers only provide Windows executables to update the BIOS, please do this before installing Ubuntu. # Detailed Getting Started Guides and Documentation [IRON AIE Application Programming Guide](programming_guide) [Device Descriptions](docs/Devices.md) [AMD XDNA NPU Architecture Cheatsheet](skills/aie-code-creator/references/architecture.md) — device/tile layout, memory hierarchy, vector register widths, MMUL shapes and divisibility constraints, routing/placement limits, and per-tile performance ballparks [AIE C++ Kernel Intrinsics Cheatsheet](skills/aie-code-creator/references/kernel_intrinsics.md) — AIE API boilerplate, loop-pipelining annotations, vector load/store, MMUL usage, and common intrinsic quick-reference tables [Building mlir-aie tools from source](docs/Building.md) [MLIR Dialect and Compiler Documentation](https://xilinx.github.io/mlir-aie/) Interested in contributing MLIR-AIE? [Information for developers](CONTRIBUTING.md) -----