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 or Kelvin).

## 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`
*   [Kelvin BSP](https://spacebeaker.googlesource.com/shodan/sw/kelvin): Under
    `<dir>/sw/kelvin`
*   [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
    *   branch_mul: Branch multiplication example
    *   microbenchmarks: Currently only contain a convolution 1x1 example
    *   simple_vec_mul: Point-wise vector multiplication examples
*   ssd_postprocess: Vision postprocessing library for Single-Shot Detectors
    (SSD)
*   ukernel: Custom microkernel library for VMVX and LLVM

## 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 go to the top level directory.

For Springbok

```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
```

For Kelvin

```bash
  cmake -B <output dir> -G Ninja \
     -DCMAKE_TOOLCHAIN_FILE="$(realpath sw/vec_iree/cmake/riscv_iree_gcc.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 RENODE emulation with the built executables. In Shodan repo,
`sim_springbok` for Renode simulation on Springbok; `sim_kelvin` for Renode
simulation on Kelvin. Out-of-repo emulation is possible but requires 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-16/bin`

Default is renode tests for Springbok. Add`-D RUNNER=kelvin` to enable renode
tests for Kelvin. Add`-D RUNNER=kelvin_hw` to enable renode tests for Kelvin HW.