diff --git a/docs/developing_iree/contributor_tips.md b/docs/developing_iree/contributor_tips.md index 03ddffc7cbde..19e4fd5e00c6 100644 --- a/docs/developing_iree/contributor_tips.md +++ b/docs/developing_iree/contributor_tips.md @@ -33,7 +33,7 @@ and create the PR from there. ```shell # From your existing git repo git remote rename origin upstream - git add remote origin git@github.com:/iree.git + git remote add origin git@github.com:/iree.git ``` b. If you haven't already cloned: diff --git a/docs/get_started/getting_started_linux_cmake_cross.md b/docs/get_started/getting_started_linux_cmake_cross.md new file mode 100644 index 000000000000..83c0defde853 --- /dev/null +++ b/docs/get_started/getting_started_linux_cmake_cross.md @@ -0,0 +1,125 @@ +# Getting Started on Linux with Cross-Compilation + + + +This guide walks through cross-compiling IREE core runtime towards the embedded +Linux platform. Cross-compiling IREE compilers is not supported at the moment. + +Cross-compilation involves both a *host* platform and a *target* platform. One +invokes compiler toolchains on the host platform to generate libraries and +executables that can be run on the target platform. + +The following steps will use aarch64 as the embedded platform. These steps has +been tested on Ubuntu 18.04. + +## Prerequisites + +### Set up host development environment + +The host platform should have been set up for developing IREE. Please make sure +you have followed the steps for +[Linux](./getting_started_linux_cmake.md). + +### Install GCC/G++-10 Cross Toolchain + +If Ubuntu version is eariler than Ubuntu 20.04, we need to add apt-repository +entry for newer gcc/g++. + +```shell +# Again, this is not required for Ubuntu 20.04 +$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test +$ sudo vi /etc/apt/sources.list + # add this line + deb http://de.archive.ubuntu.com/ubuntu groovy main +``` + +Install gcc/g++-10 + +```shell +$ sudo apt-get update +$ sudo apt install gcc-10 g++-10 +$ sudo apt install gcc-10-aarch64-linux-gnu g++-10-aarch64-linux-gnu +``` + +### Create CMake Cross-Toolchain File + +Create cmake cross-toolchain file. We use aarch64 as an example. + +```shell +$ vi aarch64-toolchain.cmake +``` + +Then copy-paste the following: + +```cmake +set(CMAKE_SYSTEM_NAME Linux) +set(CMAKE_SYSTEM_PROCESSOR aarch64) + +set(CMAKE_C_COMPILER "aarch64-linux-gnu-gcc-10") +set(CMAKE_CXX_COMPILER "aarch64-linux-gnu-g++-10") + +set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) +set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + +set(CMAKE_C_FLAGS "-march=armv8-a") +set(CMAKE_CXX_FLAGS "-march=armv8-a") +``` + +## Configure and Build + +### Configure on Linux + +```shell +$ cmake -G Ninja /path/to/iree \ + -DCMAKE_TOOLCHAIN_FILE=aarch64-toolchain.cmake \ + -B build-aarch64 \ + -DIREE_BUILD_COMPILER=OFF -DIREE_BUILD_SAMPLES=OFF \ + -DIREE_HOST_C_COMPILER=/usr/bin/gcc-10 \ + -DIREE_HOST_CXX_COMPILER=/usr/bin/g++-10 +``` + +### Build + +```shell +$ cmake --build build-aarch64/ +``` + +## Test on Embedded Device + +Translate a source MLIR into IREE module: + +```shell +# Assuming in IREE source root +$ build-aarch64/host/bin/iree-translate \ + -iree-mlir-to-vm-bytecode-module \ + -iree-hal-target-backends=vmla \ + iree/tools/test/simple.mlir \ + -o /tmp/simple-vmla.vmfb +``` + +Then copy the IREE runtime executable and module to the device: + +```shell +$ scp build-aarch64/iree/tools/iree-run-module ${device}:~ +$ scp /tmp/simple-vulkan.vmfb ${device}:~ +``` + +Log into device: + +```shell +$ ssh ${device} + +aarch64-ubuntu $ ./iree-run-module -driver=vmla \ + -input_file=simple-vmla.vmfb \ + -entry_function=abs \ + -inputs="i32=-5" + +EXEC @abs +i32=5 +``` \ No newline at end of file diff --git a/docs/get_started/getting_started_linux_qemu.md b/docs/get_started/getting_started_linux_qemu.md new file mode 100644 index 000000000000..06e8ac59327c --- /dev/null +++ b/docs/get_started/getting_started_linux_qemu.md @@ -0,0 +1,160 @@ +# Getting Started on Linux with Qemu-User + + + +This guide walks through using qemu-user to build the core compiler and runtime +parts of IREE towards the embedded linux platform. + +The following steps will use aarch64 as the embedded platform. These steps has +been tested on Ubuntu 18.04. It may take around 7 hours to build everything on +the x86 machines with 8 hardware threads running on 3.4 GHz + 16 GB RAM. + +## Prerequisites + +### Install Qemu User + +Install qemu-user to run aarch64 based rootfs (root file system). + +```shell +$ sudo apt install qemu-user-static +``` + +### Prepare AArch64 Based Ubuntu Rootfs + +Download aarch64 ubuntu-base rootfs from official site and use sudo to untar it +in ubuntu-18.04-arm64 foler. `sudo` is required here since there are special +device node files which need to be created under root permission. + +```shell +$ export ROOTFS=$PWD +$ wget http://cdimage.ubuntu.com/ubuntu-base/releases/18.04/release/ubuntu-base-18.04-base-arm64.tar.gz +$ mkdir ubuntu-18.04-arm64 && cd ubuntu-18.04-arm64 +$ sudo tar -xf ../ubuntu-base-18.04-base-arm64.tar.gz -C ./ +``` + +Copy `qemu-aarch64-static` to the aarch64 rootfs for executing aarch64 +binaries on the host x86. Copy `resolv.conf` to the aarch64 rootfs for network +access. + +```shell +$ sudo cp /usr/bin/qemu-aarch64-static $ROOTFS/usr/bin/ +$ sudo cp /etc/resolv.conf $ROOTFS/etc +``` + +### Prepare Folders Shared between Host and Rootfs + +It is very convenient to have some shared folders between the host and the +aarch64 rootfs, this example creates iree source and build folder on the host, +then bind it to the aarch64 rootfs. + +```shell +$ sudo mkdir -p $ROOTFS/path/to/iree +$ sudo mkdir -p $ROOTFS/path/to/iree-build +$ sudo mount --bind /path/to/iree $ROOTFS/path/to/iree +$ sudo mount --bind /path/to/iree-build $ROOTFS/path/to/iree-build +``` + +### Bind System Nodes to Aarch64 Rootfs, then Chroot + +Bind system nodes and start emulating aarch64 on host. + +```shell +$ sudo mount --bind /proc proc +$ sudo mount --bind /sys sys +$ sudo mount --bind /dev dev +$ sudo chroot $ROOTFS +``` + +## Setup Build Environment for Aarch64 Rootfs + +```shell +# apt-get update +# apt-get install build-essential wget python3 git ninja-build +``` + +### Install CMake + +IREE uses CMake version `>= 3.13`, default installed cmake for ubuntu 18.04 is +older than 3.13, so build and install newer version cmake for the aarch64 +rootfs. This example uses cmake 3.15.2. + +```shell +# wget https://github.com/Kitware/CMake/releases/download/v3.15.2/cmake-3.15.2.tar.gz +# tar -zxf cmake-3.15.2.tar.gz +# cd cmake-3.15.2 +# ./bootstrap +# make -j8 && sudo make install +``` + +### Install a Compiler + +We recommend Clang. GCC version `>= 9` is also supported. + +```shell +# wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/clang+llvm-10.0.0-aarch64-linux-gnu.tar.xz +# tar -xf clang+llvm-10.0.0-aarch64-linux-gnu.tar.xz +``` + +### [Optional] Prepare Vulkan + +Assume vulkan include and lib are available, then create a folder and copy +header and lib into this folder. + +```shell +# mkdir vulkan-sdk +# cp -r /path/to/vulkan/include vulkan-sdk +# cp -r /path/to/vulkan/lib vulkan-sdk +``` + +The vulkan-sdk folder struct +```shell +vulkan-sdk/ +├── include +│   └── vulkan +│   ├── vk_android_native_buffer +... +│   ├── vk_android_native_buffer.h +... +└── lib + └── libvulkan.so +``` + +### Build + +Build IREE with lld linker and experimental on. + +```shell +# export IREE_LLVMAOT_LINKER_PATH="$(which ld)" +# export VULKAN_SDK=/path/to/vulkan-sdk +# cmake -G Ninja /path/to/iree \ + -B /path/to/iree-build/build-aarch64 \ + -DIREE_BUILD_EXPERIMENTAL=ON \ + -DIREE_ENABLE_LLD=ON \ + -DCMAKE_C_COMPILER=./clang+llvm-10.0.0-aarch64-linux-gnu/bin/clang \ + -DCMAKE_CXX_COMPILER=./clang+llvm-10.0.0-aarch64-linux-gnu/bin/clang++ +# cmake --build /path/to/iree-build/build-aarch64 +``` + +## What's next? + +### Take a Look Around + +Check out the contents of the 'experimental test' build directory: + +```shell +# cd /path/to/iree-build/build-aarch64 +# ls experimental/ModelBuilder/test +``` + +Scp these tests and `third_party/llvm-project/llvm/lib/libvulkan-runtime-wrappers.so.12git` +to real device, then run it. + +```shell +$ ./bench-matmul-vector-jit +$ ./test-matmul-vulkan +``` diff --git a/scripts/prepare_doc_publication.py b/scripts/prepare_doc_publication.py index cc396dcd174f..0660815d6a90 100755 --- a/scripts/prepare_doc_publication.py +++ b/scripts/prepare_doc_publication.py @@ -51,6 +51,8 @@ def parse_arguments(): 'getting_started_linux_bazel.md': 'Linux with Bazel', 'getting_started_linux_cmake.md': 'Linux with CMake', 'getting_started_linux_vulkan.md': 'Linux with Vulkan', + 'getting_started_linux_qemu': 'Linux with Qemu' + 'getting_started_linux_cmake_cross.md': 'Linux with CMake Cross Compile', 'getting_started_windows_bazel.md': 'Windows with Bazel', 'getting_started_windows_cmake.md': 'Windows with CMake', 'getting_started_windows_vulkan.md': 'Windows with Vulkan', @@ -107,6 +109,8 @@ def parse_arguments(): 'getting_started_python.md': 10, 'generic_vulkan_env_setup.md': 11, 'cmake_options_and_variables.md': 12, + 'getting_started_linux_qemu.md': 13, + 'getting_started_linux_cmake_cross.md': 14, # Within 'Developing IREE' use explicit ordering. 'developer_overview.md': 1,