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.
