Update docs for the latest kelvin integration Change-Id: I1681a23e431c91ad8c9ccf630b9b301dcfb1617b
diff --git a/GettingStarted.md b/GettingStarted.md index 154cd8b..80ab3f8 100644 --- a/GettingStarted.md +++ b/GettingStarted.md
@@ -240,9 +240,9 @@ System management controller (SMC). -#### springbok +#### kelvin(HW) -Vector core for ML acceleration. +RTL of the ML core for ML acceleration. ### cantrip/ @@ -259,15 +259,25 @@ ### sim/ -Contains tools and src for simulators (Renode and Verilator) of the shodan system. +Contains tools and src for simulators (Kelvin, Renode, and Verilator) of the +shodan system. ### sw/ Contains the source code of applications running in all shodan cores. +#### kelvin(SW) + +Kelvin ML core BSP, the TFLM optimized kernel, and the instruction functional +tests. + #### libtock-rs -**TODO**: add more details +TockOS library + +#### matcha + +The platform and application SW running on the secured core. #### multihart_boot_rom @@ -279,18 +289,23 @@ pigweed frameworks. Currently it is used for vector core functional tests. +#### tflite-micro + +TensorFlow Lite for Microcontroller framework for ML deployment. A fork for the +upstream project to support Kelvin vector instructions. + #### tock The operating system running on the Security Core. -#### vec +#### vec (deprecated) -Springbok BSP, as well as the RVV instruction functional tests. +Springbok ML core BSP, as well as the RVV instruction functional tests. #### vec_iree -Springbok IREE application. It builds IREE runtime applications for ML models -using IREE libraries and Spingbok BSP. +ML core IREE application. It builds IREE runtime applications for ML models +using IREE libraries and ML Core BSP. ### toolchain/ @@ -305,27 +320,28 @@ To build the IREE targets: ```bash -m iree_no_wmmu +m iree ``` The IREE compiler sits in `out/host/iree_compiler`, while the runtime library/example -sits in `out/springbok_iree_no_wmmu`. -To run the toy example (four-element vector element-wise multiplication) for -testing: +sits in `out/<ml core>_iree`. +To run the toy example (four-element vector element-wise multiplication) on +kelvin for testing: ```bash -sim_springbok out/springbok_iree_no_wmmu/sparrow_iree/samples/simple_vec_mul/simple_int_vec_mul_bytecode_static +sim_kelvin out/kelvin_iree/sparrow_iree/samples/simple_vec_mul/simple_int_vec_mul_bytecode_static ``` The output should be shown as: ```bash -21:27:11.0241 [INFO] cpu2: simprint: "INFO |simple_vec_mul finished successfully", 0 (0x0) -21:27:11.0248 [INFO] cpu2: simprint: "main returned: ", 0 (0x0) +Starting simulation +INFO |simple_int_vec_mul finished successfully +Program exits properly +Total cycles: 237101 +Simulation done: 0.070 sec ``` -(Enter `quit` or `q` to exit the Renode simulation) - ## Running The Full Shodan System Simulation The simulator used for Shodan is [Renode](https://renode.io/). The configuration @@ -393,7 +409,7 @@ (matcha) quit ``` -### Launch ML Job on the Vector Core +### Launch ML Job on the ML Core You can launch the ML workload execution by communicating through the debug console @@ -403,18 +419,10 @@ CANTRIP> builtins ``` -Install the embedded ML model app; for example, +Start the embedded ML model app; for example, ```bash -CANTRIP> install mobilenet_v1_emitc_static.model -``` - -and you should see model installed. - -You can then launch the ML job with `test_mlexecute anything <model name>` - -```bash -CANTRIP> test_mlexecute anything mobilenet_v1_emitc_static +CANTRIP> start mltest ``` with the Renode console log printed as @@ -422,8 +430,9 @@ ```bash 15:17:59.9864 [INFO] uart5: [output] cantrip_ml_coordinator::Load successful. ... -15:18:02.6868 [INFO] cpu2: simprint: "main returned: ", 0 (0x0) - +15:18:02.6868 [INFO] uart5: [output] [mltest]::Model completed: mask 0b0001 ms 0 +... +18:18:45.7710 [INFO] uart5: [output] [mltest]::DONE! ``` ## More Information
diff --git a/KelvinIssDebugging.md b/KelvinIssDebugging.md index bfb41c2..3306876 100644 --- a/KelvinIssDebugging.md +++ b/KelvinIssDebugging.md
@@ -36,13 +36,11 @@ ## Running Kelvin ISS with Renode Kelvin simulator can connect to renode and then be integrated with the full -`nexus` behavioral simulation framework. As the first step, It uses a rv32im -placeholder model running non-SIMD binaries so we can test the integrated -system behaviors +`nexus` behavioral simulation framework. It uses kelvin_sim as a library and a +`KelvinCPU` wrapper to connect to the `nexus` framework. -**NOTE: Running vector-op program in renode is not supported yet.** - -Running the Kelvin SW binary can be done with the following CLIs +Running the Kelvin SW binary in a single core setup can be done with the +following CLIs ```bash source build/setup.sh @@ -53,39 +51,12 @@ The `.bin` file is the binary blob of the loadable segment parsed by `cache/toolchain_kelvin/bin/riscv32-unknown-elf-objcopy`. It is the additional output from the Kelvin build rules from either the Bazel build or CMake build -after the `.elf` executables are built +after the `.elf` executables are built. -### Debug Kelvin SW via Renode + GDB +**NOTE: Renode + kelvin does not support debugger. To debug a Kelvin SW program, +please refer to the previous section.** -Like Cantrip debugging, Kelvin Renode ISS can also attached to GDB to debug the -SW, step through the program, and dump the register or memory content. - -At the first shell session, run - -```bash -source build/setup.sh - -sim_kelvin_renode <.bin file> debug -``` - -At the second shell session, run GDB as - -```bash -cache/toolchain/bin/riscv32-unknown-elf-gdb -ex "target remote: 3333" <elf path> -``` - -Notice we load the actual `.elf` executable here so we can get the symbols and -proper address. After the Renode GDBServer is attached to GDB, GDB will -automatically start the Renode simulation (without actually running the program) - -Set up the proper breakpoints on the GDB console then continue the execution, e.g., - -```bash -b main -continue -``` - -**Note**: Once GDB is attached to the Renode simuation, you can start stepping -the execution without `run` or set up the breakpoint at the entry of the -executable. In fact, the first breakpoint can be captured reliably if it is - ___after___ the entry address. +For e2e simulation, loading and running the Kelvin SW program is done via CantripOS +MlCoordinator. See +[Launch ML Job on the ML Core](../GettingStarted.md#launch-ml-job-on-the-ml-core) +for more information.