README.md

# Springbok Model Execution Repository

This project contains ML model codegen and execution libraries/examples. The
artifacts built from this project is targeted for RISC-V 32-bit baremetal machine
(Springbok).

## Prerequisite

If you get this project from Project Shodan manifest, you are all set. If not,
you need to have following projects as well to build the project successfully.

* [Springbok BSP](https://spacebeaker.googlesource.com/shodan/sw/vec): Under `<dir>/sw/vec`
* [IREE](https://github.com/google/iree): Under `<dir>/toolchain/iree`
* [Public ML models](https://spacebeaker.googlesource.com/shodan/ml-models-public): Under `<dir>/ml/ml-models-public`
* RISC-V 32-bit crosscompile toolchain

This project needs to be at `<dir>/sw/vec_iree`

## Code structure

* audio_prep: Audio preprocessing libarary
* build_tools: Utility scripts for the project
* cmake: CMake Macros for the project
* device: Device HAL driver library
* model_util: Runtime utility library for model execution
* native_log: BSP support for the Linux userspace emulation
* risp4ml: Vision preprocessing library (Reduced ISP for ML)
* samples: Codegen and execution of ML models based on IREE
  * simple_vec_mul: Point-wise vector multiplication examples
* ssd_postprocess: Vision postprocessing library for Single-Shot Detectors (SSD)
* vmvx_ukernel: Custom microkernel library for VMVX

## Build the project

If you are running from Project Shodan repo, you can build the artifacts with `m iree`.
If you download this project alone, you need to download/build IREE's host compiler,
then at the top level directory

```bash
  cmake -B <output dir> -G Ninja \
     -DCMAKE_TOOLCHAIN_FILE="$(realpath sw/vec_iree/cmake/riscv_iree.cmake)" \
     -DCMAKE_BUILD_TYPE=MinSizeRel \
     -DIREE_HOST_BIN_DIR="$(IREE_COMPILER_DIR)/install/bin" \
     -DRISCV_TOOLCHAIN_ROOT=$(TOOLCHAINRV32_PATH) \
     <dir>/sw/vec_iree
  cmake --build <output dir> --target all
```

## Run the executables

You can run QEMU or RENODE emulation with the built executables. In Shodan repo,
`qemu_sim_springbok` for QEMU emulation, and `sim_springbok` for Renode simulation.
Out-of-repo emulation is possible but require more steps.

## Test the executables

In Shodan, this project utilizes LLVM `lit` and `FileCheck` to test the ML
executable performance. The tests are defined in the *_test.run files under
`<output dir>`. To run the test, at the Shodan top level directory

```bash
lit --path <Filecheck dir> -a <output dir>
```

Filecheck in Debian testing is under `/usr/lib/llvm-11/bin`

Add `-D RUNNER=qemu` to enable the qemu tests.