doc: Update IREE related flow. Also fix doc formatting warnings. Change-Id: Ibcc80b08c93a53293c2057897e609de4f9c63d4d
diff --git a/GenerateAndInspectIREEExcutables.md b/GenerateAndInspectIREEExcutables.md index 61a9c41..0709c1b 100644 --- a/GenerateAndInspectIREEExcutables.md +++ b/GenerateAndInspectIREEExcutables.md
@@ -11,29 +11,29 @@ [iree-translate](https://github.com/google/iree/blob/main/iree/tools/iree-translate-main.cc) (generate the IREE bytecode modules). IREE codegen flow is based on LLVM and MLIR, so it utilizes the typical LLVM flags to define the machine targets. For -example, to generate the IREE bytecode module from mobilenetv2 MLIR: +example, to generate the IREE bytecode module from a vector multiply MLIR: -``` -RISCV_TOOLCHAIN_ROOT=${CACHE}/toolchain_iree/ \ -${OUT}/host/iree-build-host/install/bin/iree-translate \ +```bash +${OUT}/host/iree-compiler/install/bin/iree-translate \ -iree-input-type=mhlo \ -iree-mlir-to-vm-bytecode-module \ -iree-hal-target-backends=dylib-llvm-aot \ - -iree-llvm-target-triple=riscv64 \ - -iree-llvm-target-cpu=generic-rv64 \ - -iree-llvm-target-cpu-features="+m,+a,+f,+d,+c" \ - -iree-llvm-target-abi=lp64d \ - ${ROOTDIR}/ml/ml-models/mobilenetv2_iree.mlir \ - -o /tmp/mobilenetv2_iree-llvm_aot.vmfb + -iree-llvm-target-triple=riscv32-pc-linux-elf \ + -iree-llvm-target-cpu=generic-rv32 \ + -iree-llvm-target-cpu-features="+m,+f" \ + -iree-llvm-target-abi=lp32d \ + -iree-llvm-link-embedded=true \ + ${ROOTDIR}/toolchain/iree/iree/samples/simple_embedding/simple_embedding_test.mlir \ + -o /tmp/simple_mul-llvm_aot.vmfb ``` + With the options of: + * iree-hal-target-backends: The HAL device (library + dispatcher) target for the workload. In Shodan, the supported targets are: * dylib-llvm-aot: the dynamic library for LLVM ahead-of-time (AOT) compilation. * vmvx - * embedded-sync (WIP, not available now): embedded library for baremetal with - the synchronized executor. * iree-llvm-target-triple: The flag is populated to LLVM target triple. * iree-llvm-target-cpu: The flag populated to LLVM target cpu. It can be pre-defined cpu targets or the generic ones @@ -44,14 +44,15 @@ support. __For the vector extension, it can be enabled with "+experimental-v"__. * iree-llvm-target-abi: The flag is polulated to LLVM target abi. - -Some extra options: * iree-llvm-link-embedded: Generate the executable into a platform-agnostic ELF and use the ELF loader to load the library instead of using `dlopen` and `dlsym`. This creates the least overhead in the executable, and the simplest linker during codegen without dynamic library linkage; therefore, it will be the targeted path for Shodan. However, it is WIP and currently is not set as the default path. + +Some extra options: + * iree-llvm-keep-linker-artifacts: Aside from the generated bytecode flatbuffer (with [schema](https://github.com/google/iree/blob/main/iree/schemas/bytecode_module_def.fbs)), the intermediate linker is generated at `/tmp/<module_name>_linked_<hal_target>-xxxxxx.so`. @@ -63,14 +64,14 @@ * iree-llvm-debug-symbols: Add the debug information in the executable. Setting this to `false` at the production executable can reduce the workload size. -# Inspect IREE executables +## Inspect IREE executables To render the bytecode flatbuffer in a text file, the `iree-dump-module` tool can print out the content based on the descriptors in the schema, including the weights in the ML model. -``` -$ ${OUT}/host/iree-build-host/install/bin/iree-dump-module <vmfb file> +```bash +${OUT}/host/iree-compiler/install/bin/iree-dump-module <vmfb file> ``` With the linker artifact enabled, The `.so` file contends the dispatch functions @@ -78,10 +79,28 @@ retrieve the assembler content. For example, to render the executable (.text) segment -``` -$ ${CACHE}/toolchain_iree/bin/riscv64-unknown-linux-gnu-objdump -d <linker artifact> +```bash +${CACHE}/toolchain_iree_rv32imf/bin/riscv32-unknown-elf-objdump -d <linker artifact> ``` Note: - * If you use llvm-objdump to retrieve the assembler content, the RVV ISAs could + +* If you use llvm-objdump to retrieve the assembler content, the RVV ISAs could be rendered as unknown. + +## Inspect IREE IR lowering + +Use `iree-opt` to check the IR output + +```bash +${OUT}/host/iree-compiler/install/bin/iree-opt \ + -print-ir-after-all \ + -iree-transformation-pipeline \ + -iree-hal-target-backends=dylib-llvm-aot \ + -iree-llvm-target-triple=riscv32-pc-linux-elf \ + -iree-llvm-target-cpu=generic-rv32 \ + -iree-llvm-target-cpu-features="+m,+a,+f" \ + -iree-llvm-target-abi=lp32d \ + -iree-llvm-link-embedded=true \ + <MLIR input> +```
diff --git a/GettingStarted.md b/GettingStarted.md index 109a462..0aa1c02 100644 --- a/GettingStarted.md +++ b/GettingStarted.md
@@ -17,7 +17,7 @@ Now you need to pull down a copy of the `repo` tool from our public facing sites and add it to your path: -``` +```bash mkdir -p bin export PATH=$PATH:$HOME/bin curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo @@ -27,7 +27,7 @@ Make sure you've initialized git with your name and email address, and have configured it properly for fetching the sources: -``` +```bash git config --global user.name "Your Name" git config --global user.email "you@example.com" ``` @@ -36,7 +36,7 @@ new directory where you'd like it to live, and initialize `repo` with the current release branch. -``` +```bash repo init -u https://spacebeaker.googlesource.com/shodan/manifest -g default,internal repo sync -j$(nproc) ``` @@ -48,25 +48,25 @@ To setup the build system: -``` +```bash source build/setup.sh ``` Install the prerequisites: -``` +```bash m prereqs ``` Install the RISCV toolchain: -``` +```bash m tools ``` Install the instruction set simulator: -``` +```bash m sim ``` @@ -90,7 +90,7 @@ ### How to sync my local copy with latest? -``` +```bash repo sync -j$(nproc) ``` @@ -100,7 +100,7 @@ To upload a branch to gerrit for review, do this: -``` +```bash repo upload --re reviewer1,reviewer2 --cc email@host.com,email2@host2.com ``` @@ -111,7 +111,7 @@ and abandon and merge the changes into the repository. To make changes during the review process, make your changes to the files, then: -``` +```bash git add -A # To add the files you've changed git commit --amend # To update the previous change repo upload -t --re ${REVIEWER} --cc ${CC_LIST} # To upload the change to Gerrit for review @@ -121,41 +121,46 @@ Our layout is pretty simple: -#### hw/ +### hw/ Contains all of the source code and RTL required to build the Shodan hardware, as well as simulate it in Verilator. -#### build/ +### build/ Contains build scripts for the whole tree. This is effectively just an orchestration layer to make building the whole shebang easier. Each subtree may have its own build systems and have their own ways of building. -#### cicd/ +### cache/ + +The cached cross-compilation toolchain, including rust and RISC-V GCC/LLVM +toolchain. + +### cicd/ Contains continuous integration scripts and tooling for Jenkins, our CI/CD tool. -#### docs/ +### docs/ Lots of extra documentation (we hope) about how the repo is laid out, how the build system works, code reviews, licensing, etc. -#### manifest/ +### manifest/ The repo manifest used to glue all the git repositories together. -#### scripts/ +### scripts/ Contains utility scripts to help automate a few things. -#### sim/ +### sim/ Contains tools and src for simulation of the shodan hw. -#### toolchain/ +### toolchain/ -Contains the src to build the RISCV GCC/LLVM/QEMU toolchain, and +Contains the src to build the RISCV QEMU emulator, and [IREE](https://github/com/google/iree) toolchain for ML models. ## Start a simulation @@ -166,56 +171,53 @@ This alias is equivalent to the command: -``` +```bash mono cache/renode/Renode.exe ``` The configuration for the Shodan SoC is `sim/config/shodan.repl`, and an example of running zephyr on Shodan can be run as below: -``` +```bash include @sim/config/shodan_zephyr.resc start ``` ## Build and test ML artifacts -The ML executable is built with [IREE](https://github.com/google/iree) workflow. -The flow for RISCV 32-bit is still WIP, so you need to build the toolchain outside of the `m tools` -in the previous section. Eventually it will become part of the default toolchain. +The ML executable is built with [IREE](https://github.com/google/iree) workflow, +targeted to RISCV 32-bit bare-metal config. -The following instructions are the based on the -[getting started doc](https://google.github.io/iree/get-started/getting-started-riscv-cmake) -on IREE webpage but the GCC/LLVM toolchain are built from the source code. +To retrieve the IREE RISC-V toolchain and Renode emulator: -To build the IREE RISCV prerequisite toolchains: -``` -m toolchain_llvm -m qemu +```bash +m tools ``` To build the IREE targets: -``` + +```bash m iree ``` -To run the toy example (abs(-10)) for testing: -``` -bash scripts/run-iree.sh +The IREE compiler sits in `out/host/iree_compiler`, while the runtime library/example +sits in `out/springbok_iree`. +To run the toy example (four-element vector element-wise multiplication) for +testing: + +```bash +sim_springbok out/springbok_iree/iree/iree/samples/simple_embedding/simple_embedded_embedded_sync ``` The output should be shown as: -``` -I .../iree/tools/utils/vm_util.cc:258] Creating driver and device for 'dylib'... -Error in cpuinfo: processor architecture is not supported in cpuinfo -EXEC @abs -I .../iree/tools/utils/vm_util.cc:201] result[0]: Buffer<sint32[]> -EXEC @abs i32=10 -Smoke test passed +```bash +(machine-0) 18:05:23.6463 [INFO] cpu2: simprint: "simple_embedding done", 0 (0x0) +18:05:23.6475 [INFO] cpu2: simprint: "main returned: ", 0 (0x0) ``` -The test is also checked at the end of `m iree` + +(Enter quit to exit the Renode simulation) ## More Information - - [Information on how to use repo](https://go/repo) +- [Information on how to use repo](https://go/repo)