Skip to content

Commit 62efd99

Browse files
hunhoffefifield
hunhoffe
and
fifield
authored
Docs and small updates for xrt build infrastructure (Xilinx#588)
* Add python packages that are needed to run xrt ninja/lit tests to requirements.txt * Ignore additional build artifact files * Start to update some build documentation * ryzen docs fix typo, fix building broken links * Fixed incorrect path in ryzen build instructions * Fix one more minor typo --------- Co-authored-by: Jeff Fifield <[email protected]>
1 parent b816f05 commit 62efd99

File tree

5 files changed

+211
-106
lines changed

5 files changed

+211
-106
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,17 @@ vck5000_aie_base_graph_hw.ltx
1818
vck5000_aie_base_graph_hw.xsa.link_summary
1919
Work
2020
build
21+
build-xrt
2122
install
23+
install-xrt
2224
platform_repo
2325
myproj
2426
sw_comp
2527
sd_card
2628
sysroot
2729
components
2830
air_project
31+
sandbox
2932

3033
# build results
3134
libadf.a

‎docs/building.md

Lines changed: 3 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,8 @@
11
# Building AIR Tools and Runtime
22

3-
## Running on the VCK5000
4-
5-
The first step required for running on the VCK5000 is building the hardware platform and loading it on your device. We provide a platform repository titled [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) which contains instructions on how to compile and load the platform, driver, and firmware on your VCK5000. Then, the AIR tools must be installed by following the [Building external projects on X86](#building-external-projects-on-X86) and [Environment setup](#environment-setup) instructions. Then, the [AIR PCIe driver](https://github.com/Xilinx/ROCm-air-platforms/tree/main/driver) from [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) must be compiled and installed. Now you are ready to run tests using AIR on the VCK5000! For example, go to [Test 13](test/13_mb_add_one) and run `make` followed by `sudo ./test.elf` to run the application.
6-
7-
8-
## Prerequisites
9-
10-
**mlir-air** is built and tested on Ubuntu 20.04 with the following packages installed:
11-
```
12-
cmake 3.20.6
13-
clang/llvm 10+
14-
lld
15-
python 3.8.x
16-
ninja 1.10.0
17-
Xilinx Vitis 2021.2
18-
libelf
19-
```
20-
21-
In addition the following packages maybe useful:
22-
23-
```
24-
25-
Xilinx Vivado 2021.2/2022.1
26-
Xilinx Vitis 2021.2/2022.1
27-
Xilinx aienginev2 library from https://github.com/Xilinx/embeddedsw
28-
29-
```
30-
Vivado and Vitis are used to build the platforms for available Xilinx cards with AIEs (VCK5000). Vitis also contains the AIE single core compiler xchesscc. The aienginev2 library is a driver backend used to configure the AIE array and used in building the AIR runtime. The aietools single core compiler and aienginev2 library are required to build binaries that run on AIE hardware.
31-
32-
NOTE: using the Vitis recommended settings64.sh script to set up your environement can cause tool conflicts. Setup your environment in the following order for aietools and Vitis:
33-
34-
```
35-
export PATH=$PATH:<Vitis_install_path>/Vitis/2022.2/aietools/bin:<Vitis_install_path>/Vitis/2022.2/bin
36-
```
37-
38-
NOTE: that you do not need the above additional Xilinx packages to make use of the AIR compiler passes.
39-
40-
Building mlir-air requires several other open source packages:
41-
- [mlir](https://github.com/llvm/llvm-project/tree/main/mlir)
42-
- [mlir-aie](https://github.com/Xilinx/mlir-aie)
43-
- [Xilinx cmakeModules](https://github.com/Xilinx/cmakeModules). Note that this is installed as a submodule of mlir-aie.
44-
45-
In order to build and run on PCIe cards, you first have to build and install the aienginev2 library. We chose to install the library in /opt/xaiengine but it is not required for the tools to be installed there. Just ensure that when building mlir-aie and mlir-air, that you point to the directory in which the aienginev2 library was installed.
46-
47-
```
48-
git clone https://github.com/stephenneuendorffer/aie-rt
49-
cd aie-rt
50-
git checkout phoenix_v2023.2
51-
cd driver/src
52-
make -f Makefile.Linux CFLAGS="-D__AIEAMDAIR__"
53-
sudo cp -r ../include /opt/aiengine/
54-
sudo cp libxaiengine.so* /opt/xaiengine/lib/
55-
export LD_LIBRARY_PATH=/opt/xaiengine/lib:${LD_LIBRARY_PATH}
56-
```
57-
58-
## Building external projects on X86
59-
60-
The mlir-air repository should be cloned locally before beginning.
61-
62-
First, run utils/setup_python_packages.sh to setup the prerequisite python packages. This script creates and installs the python packages listed in utils/requirements.txt in a virtual python environment called 'sandbox'.
63-
64-
```
65-
source utils/setup_python_packages.sh
66-
```
67-
68-
Next, clone and build LLVM, with MLIR enabled. In addition, we make some common build optimizations to use a linker ('lld' or 'gold') other than 'ld' (which tends to be quite slow on large link jobs) and to link against libLLVM.so and libClang so. You may find that other options are also useful. Note that due to changing MLIR APIs, only a particular revision is expected to work.
69-
70-
Run the following to clone and build llvm:
71-
72-
```
73-
cd mlir-air
74-
./utils/clone-llvm.sh
75-
./utils/build-llvm-local.sh llvm
76-
```
77-
78-
Next, clone and build MLIR-AIE with paths to llvm, aienginev2, and cmakeModules repositories. Note that in the following commands, we assume that the aienginev2 library is installed in /opt/xaiengine as directed in the `Prerequisites` section. If the aienginev2 library was installed elsewhere, be sure that the 4th argument to build mlir-aie points to that location.
79-
80-
```
81-
./utils/clone-mlir-aie.sh
82-
./utils/build-mlir-aie-local.sh llvm mlir-aie/cmake/modulesXilinx /opt/xaiengine mlir-aie
83-
```
84-
85-
Next, we must install our experimental ROCm runtime (ROCr) which allows us to communicate with the AIEs. The [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) repository contains documentation on how to install ROCr. Run the following script to clone the ROCm-air-platforms repository:
86-
87-
```
88-
./utils/clone-rocm-air-platforms.sh
89-
```
90-
91-
Use the following command to build the AIR tools to compile on x86 for PCIe cards (VCK5000). Make sure that ${ROCM\_ROOT} is pointing to your local ROCm install:
92-
93-
```
94-
./utils/build-mlir-air-pcie.sh llvm/ mlir-aie/cmake/modulesXilinx/ mlir-aie/ /opt/xaiengine ${ROCM_ROOT}/lib/cmake/hsa-runtime64/ ${ROCM_ROOT}/lib/cmake/hsakmt/
95-
```
96-
97-
The PCIe AIR runtime requires the use of the [AIR PCIe kernel driver](https://github.com/Xilinx/ROCm-air-platforms/tree/main/driver). The driver directory in the [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) repository contains documentation on how to compile and load the AIR PCIe kernel driver.
98-
99-
## Environment setup
100-
101-
Set up your environment to use the tools you just built with the following commands:
102-
103-
```
104-
export PATH=/path/to/mlir-air/install/bin:${PATH}
105-
export PYTHONPATH=/path/to/mlir-air/install/python:${PYTHONPATH}
106-
export LD_LIBRARY_PATH=/path/to/install/mlir-air/lib:/opt/xaiengine/lib:${LD_LIBRARY_PATH}
107-
export PATH=/path/to/mlir-air/install-pcie/bin:${PATH}
108-
```
3+
There are currently two documented way to build, run, and test AIR:
4+
* [Getting Started and Running on VCK5000](buildingVCK5000.md)
5+
* [Getting Started and Running on Linux Ryzen™ AI](buildingRyzenLin.md)
1096

1107
-----
1118

‎docs/buildingRyzenLin.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Getting Started and Running on Linux Ryzen™ AI
2+
3+
## Environment
4+
5+
The [MLIR-AIE](https://github.com/Xilinx/mlir-aie) repo maintains instructions on how to install dependencies and configure your environment. Follow the instructions [here](https://github.com/Xilinx/mlir-aie/blob/main/docs/buildHostLin.md). It is not necessary to follow the final steps for cloning/building/running MLIR-AIE itself.
6+
7+
## Prerequisites
8+
9+
Building MLIR-AIR several other open source packages:
10+
- [mlir](https://github.com/llvm/llvm-project/tree/main/mlir)
11+
- [mlir-aie](https://github.com/Xilinx/mlir-aie)
12+
- [Xilinx cmakeModules](https://github.com/Xilinx/cmakeModules). Note that this is installed as a submodule of MLIR-AIE
13+
- [libXAIE](https://github.com/jnider/aie-rt.git)
14+
15+
These prerequisitives can be installed with some helpful scripts found in the ```utils``` directory in the process described below.
16+
17+
First, clone the MLIR-AIR repo:
18+
```bash
19+
git clone https://github.com/Xilinx/mlir-air.git
20+
cd mlir-air
21+
```
22+
23+
Next, run ```utils/setup_python_packages.sh``` to setup the prerequisite python packages. This script creates and installs the python packages listed in [utils/requirements.txt](utils/requirements.txt) in a virtual python environment called ```sandbox```.
24+
25+
```bash
26+
source utils/setup_python_packages.sh
27+
```
28+
29+
Next, clone and build LLVM, with MLIR enabled. In addition, we make some common build optimizations to use a linker ('lld' or 'gold') other than 'ld' (which tends to be quite slow on large link jobs) and to link against libLLVM.so and libClang so. You may find that other options are also useful. Note that due to changing MLIR APIs, only a particular revision is expected to work.
30+
31+
Run the following to clone and build llvm:
32+
33+
```bash
34+
./utils/clone-llvm.sh
35+
./utils/build-llvm-local.sh llvm
36+
```
37+
38+
Next, clone and build the aienginev2 module.
39+
```bash
40+
./utils/github-clone-build-libxaie.sh
41+
```
42+
43+
Next, clone and build MLIR-AIE with paths to llvm, aienginev2, and cmakeModules repositories.
44+
```bash
45+
./utils/clone-mlir-aie.sh
46+
./utils/build-mlir-aie-local.sh llvm mlir-aie/cmake/modulesXilinx aienginev2 mlir-aie
47+
```
48+
49+
After this step, you are ready to build MLIR-AIR!
50+
51+
## Building
52+
53+
To build MLIR-AIR provide the paths to llvm, cmakeMoudles, and xrt (here, we assume it is installed in ```/opt/xilinx/xrt```):
54+
```bash
55+
./utils/build-mlir-air-xrt.sh llvm mlir-aie/cmake/modulesXilinx mlir-aie aienginev2 /opt/xilinx/xrt
56+
```
57+
58+
## Environment
59+
60+
To setup your environment after building:
61+
```bash
62+
source utils/env_setup.sh install-xrt/ mlir-aie/install/ llvm/install/
63+
```
64+
65+
Note that if you are starting a new enviroment (say be creating a new terminal sometime after building), restore your environment with:
66+
```bash
67+
source utils/env_setup.sh install-xrt/ mlir-aie/install/ llvm/install/
68+
source sandbox/bin/activate
69+
```
70+
71+
## Testing
72+
73+
Some tests for MLIR-AIR are provided. Run them as demonstrated below:
74+
75+
```bash
76+
cd mlir-air/build-xrt
77+
ninja install
78+
ninja check-air-cpp
79+
ninja check-air-mlir
80+
ninja check-air-python
81+
82+
# These are the ones in test/xrt, and this is about equivalent to `ninja check-air-e2e` if you set the LIT_OPS env var appropriately
83+
lit -sv --time-tests --show-unsupported --show-excluded --timeout 600 -j5 test/xrt
84+
85+
# Run an individual test
86+
lit -sv test/xrt/01_air_to_npu
87+
```
88+
89+
-----
90+
91+
<p align="center">Copyright&copy; 2022 Advanced Micro Devices, Inc.</p>

‎docs/buildingVCK5000.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Getting Started and Running on VCK5000
2+
3+
The first step required for running on the VCK5000 is building the hardware platform and loading it on your device. We provide a platform repository titled [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) which contains instructions on how to compile and load the platform, driver, and firmware on your VCK5000. Then, the AIR tools must be installed by following the [Building external projects on X86](#building-external-projects-on-X86) and [Environment setup](#environment-setup) instructions. Then, the [AIR PCIe driver](https://github.com/Xilinx/ROCm-air-platforms/tree/main/driver) from [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) must be compiled and installed. Now you are ready to run tests using AIR on the VCK5000! For example, go to [Test 13](test/13_mb_add_one) and run `make` followed by `sudo ./test.elf` to run the application.
4+
5+
6+
## Prerequisites
7+
8+
**mlir-air** is built and tested on Ubuntu 20.04 with the following packages installed:
9+
```
10+
cmake 3.20.6
11+
clang/llvm 10+
12+
lld
13+
python 3.8.x
14+
ninja 1.10.0
15+
Xilinx Vitis 2021.2
16+
libelf
17+
```
18+
19+
In addition the following packages maybe useful:
20+
21+
```
22+
23+
Xilinx Vivado 2021.2/2022.1
24+
Xilinx Vitis 2021.2/2022.1
25+
Xilinx aienginev2 library from https://github.com/Xilinx/embeddedsw
26+
27+
```
28+
Vivado and Vitis are used to build the platforms for available Xilinx cards with AIEs (VCK5000). Vitis also contains the AIE single core compiler xchesscc. The aienginev2 library is a driver backend used to configure the AIE array and used in building the AIR runtime. The aietools single core compiler and aienginev2 library are required to build binaries that run on AIE hardware.
29+
30+
NOTE: using the Vitis recommended settings64.sh script to set up your environement can cause tool conflicts. Setup your environment in the following order for aietools and Vitis:
31+
32+
```
33+
export PATH=$PATH:<Vitis_install_path>/Vitis/2022.2/aietools/bin:<Vitis_install_path>/Vitis/2022.2/bin
34+
```
35+
36+
NOTE: that you do not need the above additional Xilinx packages to make use of the AIR compiler passes.
37+
38+
Building mlir-air requires several other open source packages:
39+
- [mlir](https://github.com/llvm/llvm-project/tree/main/mlir)
40+
- [mlir-aie](https://github.com/Xilinx/mlir-aie)
41+
- [Xilinx cmakeModules](https://github.com/Xilinx/cmakeModules). Note that this is installed as a submodule of mlir-aie.
42+
43+
In order to build and run on PCIe cards, you first have to build and install the aienginev2 library. We chose to install the library in /opt/xaiengine but it is not required for the tools to be installed there. Just ensure that when building mlir-aie and mlir-air, that you point to the directory in which the aienginev2 library was installed.
44+
45+
```
46+
git clone https://github.com/stephenneuendorffer/aie-rt
47+
cd aie-rt
48+
git checkout phoenix_v2023.2
49+
cd driver/src
50+
make -f Makefile.Linux CFLAGS="-D__AIEAMDAIR__"
51+
sudo cp -r ../include /opt/aiengine/
52+
sudo cp libxaiengine.so* /opt/xaiengine/lib/
53+
export LD_LIBRARY_PATH=/opt/xaiengine/lib:${LD_LIBRARY_PATH}
54+
```
55+
56+
## Building external projects on X86
57+
58+
The mlir-air repository should be cloned locally before beginning.
59+
60+
First, run utils/setup_python_packages.sh to setup the prerequisite python packages. This script creates and installs the python packages listed in utils/requirements.txt in a virtual python environment called 'sandbox'.
61+
62+
```
63+
source utils/setup_python_packages.sh
64+
```
65+
66+
Next, clone and build LLVM, with MLIR enabled. In addition, we make some common build optimizations to use a linker ('lld' or 'gold') other than 'ld' (which tends to be quite slow on large link jobs) and to link against libLLVM.so and libClang so. You may find that other options are also useful. Note that due to changing MLIR APIs, only a particular revision is expected to work.
67+
68+
Run the following to clone and build llvm:
69+
70+
```
71+
cd mlir-air
72+
./utils/clone-llvm.sh
73+
./utils/build-llvm-local.sh llvm
74+
```
75+
76+
Next, clone and build MLIR-AIE with paths to llvm, aienginev2, and cmakeModules repositories. Note that in the following commands, we assume that the aienginev2 library is installed in /opt/xaiengine as directed in the `Prerequisites` section. If the aienginev2 library was installed elsewhere, be sure that the 4th argument to build mlir-aie points to that location.
77+
78+
```
79+
./utils/clone-mlir-aie.sh
80+
./utils/build-mlir-aie-local.sh llvm mlir-aie/cmake/modulesXilinx /opt/xaiengine mlir-aie
81+
```
82+
83+
Next, we must install our experimental ROCm runtime (ROCr) which allows us to communicate with the AIEs. The [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) repository contains documentation on how to install ROCr. Run the following script to clone the ROCm-air-platforms repository:
84+
85+
```
86+
./utils/clone-rocm-air-platforms.sh
87+
```
88+
89+
Use the following command to build the AIR tools to compile on x86 for PCIe cards (VCK5000). Make sure that ${ROCM\_ROOT} is pointing to your local ROCm install:
90+
91+
```
92+
./utils/build-mlir-air-pcie.sh llvm/ mlir-aie/cmake/modulesXilinx/ mlir-aie/ /opt/xaiengine ${ROCM_ROOT}/lib/cmake/hsa-runtime64/ ${ROCM_ROOT}/lib/cmake/hsakmt/
93+
```
94+
95+
The PCIe AIR runtime requires the use of the [AIR PCIe kernel driver](https://github.com/Xilinx/ROCm-air-platforms/tree/main/driver). The driver directory in the [ROCm-air-platforms](https://github.com/Xilinx/ROCm-air-platforms) repository contains documentation on how to compile and load the AIR PCIe kernel driver.
96+
97+
## Environment setup
98+
99+
Set up your environment to use the tools you just built with the following commands:
100+
101+
```
102+
export PATH=/path/to/mlir-air/install/bin:${PATH}
103+
export PYTHONPATH=/path/to/mlir-air/install/python:${PYTHONPATH}
104+
export LD_LIBRARY_PATH=/path/to/install/mlir-air/lib:/opt/xaiengine/lib:${LD_LIBRARY_PATH}
105+
export PATH=/path/to/mlir-air/install-pcie/bin:${PATH}
106+
```
107+
108+
-----
109+
110+
<p align="center">Copyright&copy; 2022 Advanced Micro Devices, Inc.</p>

‎utils/requirements.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
PyYAML>=5.3.1, <=6.0.1
2+
aiofiles
3+
filelock==3.13.1
4+
lit
15
joblib
26
ipykernel
37
psutil

0 commit comments

Comments
 (0)