Add the documentation for IREE codegen/objdump process
Change-Id: Ib3c8947da1a62697db5f1f9c85fa4cbb4fafb2ff
diff --git a/GenerateAndInspectIREEExcutables.md b/GenerateAndInspectIREEExcutables.md
new file mode 100644
index 0000000..61a9c41
--- /dev/null
+++ b/GenerateAndInspectIREEExcutables.md
@@ -0,0 +1,87 @@
+# Generate and Inspect IREE Executables
+
+In this doc, we explain the process of generating the IREE executables and
+inspecting the excutables with various tools.
+
+## Generate IREE executables
+
+IREE's main codegen tools are
+[iree-opt](https://github.com/google/iree/blob/main/iree/tools/iree-opt-main.cc)
+(generate MLIR representations) and
+[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:
+
+```
+RISCV_TOOLCHAIN_ROOT=${CACHE}/toolchain_iree/ \
+${OUT}/host/iree-build-host/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
+
+```
+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
+([link](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/RISCVTargetParser.def)).
+* iree-llvm-target-cpu-features: The flag is populated to LLVM target features for
+extra CPU extensions. For RISC-V, it can include the typical ISA extensions,
+such as multiplication/division, atomic, floating point, and compression ISA
+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.
+* 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`.
+(the exact path is printed in the stdout).
+* riscv-v-vector-bits-min and riscv-v-fixed-length-vector-lmul-max: If the
+vector extension is enabled in `iree-llvm-target-cpu-features`, the RVV VLS
+(vector length specific) code will be generated with the vector length specified
+by these two options.
+* 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
+
+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>
+```
+
+With the linker artifact enabled, The `.so` file contends the dispatch functions
+of the workload, and the user can use the objdump in the RISC-V toolchain to
+retrieve the assembler content. For example, to render the executable (.text)
+segment
+
+```
+$ ${CACHE}/toolchain_iree/bin/riscv64-unknown-linux-gnu-objdump -d <linker artifact>
+```
+
+Note:
+ * If you use llvm-objdump to retrieve the assembler content, the RVV ISAs could
+ be rendered as unknown.
diff --git a/GettingStarted.md b/GettingStarted.md
index 972c556..109a462 100644
--- a/GettingStarted.md
+++ b/GettingStarted.md
@@ -208,7 +208,6 @@
```
I .../iree/tools/utils/vm_util.cc:258] Creating driver and device for 'dylib'...
Error in cpuinfo: processor architecture is not supported in cpuinfo
-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
