Skip to content

Getting Started

Jump to bottom
Nirvedh Meshram edited this page Mar 19, 2024 · 7 revisions

Contents

  1. Prerequisites
  2. Build IREE with IREE-AMD-AIE plugin
  3. Build MLIR-AIE
  4. Build XRT
  5. Matrix Multiplication Example

Prerequisites

IREE and MLIR-AIE can be built from source using CMake. We also recommend the Ninja CMake generator and the clang compiler.

  1. Install a compiler/linker (typically "clang" and "lld" package).
  2. Install CMake
  3. Install Ninja

On Ubuntu:

sudo apt install cmake ninja-build clang lld

The generation of AI Engine program binaries require AMD Vitis software. Vitis installation instructions can be found at AMD website. We recommend Vitis version 2023.2. Prerequisites of Vitis on Ubuntu can be found at AMD website.

Build IREE with IREE-AMD-AIE plugin

Use Git to clone the IREE repository and initialize its submodules:

git clone https://github.com/openxla/iree.git
cd iree
git submodule update --init
cd ..

Also clone the IREE-AMD-AIE patch and initialize its submodules:

git clone https://github.com/nod-ai/iree-amd-aie.git
cd iree-amd-aie
git submodule update --init
python3 sync_deps.py
cd ..

A recommended CMake workflow is:

cd iree
cmake -G Ninja -B ../iree-build/ -S . \
   -DCMAKE_C_COMPILER=clang \
   -DCMAKE_CXX_COMPILER=clang++ \
   -DCMAKE_BUILD_TYPE=Debug \
   -DIREE_HAL_DRIVER_METAL=OFF \
   -DIREE_TARGET_BACKEND_ROCM=OFF \
   -DIREE_CMAKE_PLUGIN_PATHS="../iree-amd-aie" \
   -DCMAKE_C_COMPILER_LAUNCHER=ccache \
   -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
   -DCMAKE_INSTALL_PREFIX="../iree-install" \
   -DIREE_ENABLE_LLD=ON

Build MLIR-AIE

clone the MLIR-AIE repository and initialize its submodules:

git clone https://github.com/Xilinx/mlir-aie.git
cd mlir-aie
git submodule update --init

Load the Vitis 2023.2 installation into your environment PATH:

export PATH=$PATH:<Vitis_install_path>/Vitis/2023.2/aietools/bin:<Vitis_install_path>/Vitis/2023.2/bin
export VITIS=<Vitis_install_path>/Vitis/2023.2
export XILINX_VITIS=<Vitis_install_path>/Vitis/2023.2

The cmake and python packages prerequisites can be satisfied by sourcing the utils/setup_python_packages.sh script under a virtual environment created using the virtualenv tool.

The standalone installation of MLIR-AIE requires its own compiled LLVM:

./utils/clone-llvm.sh
./utils/build--llvm-local.sh

Build the MLIR-AIE tool using the recommended CMake workflow:

./utils/build-mlir-aie.sh <llvm dir>/<build dir>

Build XRT

Instructions on building XRT can be found on this website.

Matrix Multiplication Example

The simplest end-to-end example of IREE-AMD-AIE is compiling a matrix multiplication.

cd iree-amd-aie/tests/samples
<iree install dir>/bin/iree-compile --iree-hal-target-backends=amd-aie --compile-to=executable-sources \
    ./matmul_fill_static_i32.mlir | <iree install dir>/bin/iree-opt \
    --pass-pipeline="builtin.module(hal.executable(hal.executable.variant(iree-hal-translate-target-executable-variants{target=amd-aie})))" \
    --iree-codegen-transform-dialect-library=./matmul_fill_spec_pad.mlir > iree-aie.mlir

Copy over the builtin.module operation with its entire body into a new file named aie.mlir.

<mlir-aie install dir>/bin/aiecc.py --no-aiesim --aie-generate-cdo --aie-generate-ipu --no-compile-host \
    --xclbin-name=final.xclbin --ipu-insts-name=insts.txt ./aie.mlir

There are two key output files that shall get generated: the .xclbin binary file and the .txt IPU instructions in assembly. Copy this two files to a machine with the IPU hardware and IPU driver installed.

"Sign" an XCLBIN: This is something you need to do for every xclbin you build. An unsigned version needs to exist in /lib/firmware/amdaie/ in order for the xclbin to work properly. Currently, for 1502. You must generate this unsigned xclbin using the setup_xclbin_firmware.sh shell script as root.

# Assume you already have xrt_plugin amdaie DEB package installed

ls /lib/firmware/amdaie
# Look at the sub directories name that indicate your target device

sudo bash
source /opt/xilinx/xrt/setup.sh
# Assume adding an unsigned xclbin on Phoenix, run
/opt/xilinx/xrt/amdaie/setup_xclbin_firmware.sh -dev Phoenix -xclbin <your test>.xclbin

# <your test>_unsigned.xclbin will be added into /lib/firmware/amdaie/<version>/ and symbolic link will create.
# When xrt_plugin package is removed, it will automatically cleanup.

Build the host code: We recommend building the host code using clang. An example host code template can be found in MLIR-AIR examples directory.

clang ./test.cpp -o test.exe -std=c++11 -Wall -I<xrt dir>/include \
    -lrt -lstdc++ -luuid  -lboost_program_options -lboost_filesystem \
    -lprotobuf -lxrt_hwemu -lxrt_coreutil -lxdp_core -L<xrt dir>/lib

Run the test design:

.\<testName>.exe -x <xclbinName>.xclbin -k MLIR_AIE -i <instsName>.txt
Clone this wiki locally