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)
