docs:getting_started: Update the getting started doc with e2e simulation
Also add more details on the repo structure.
Change-Id: Id311235509759930c86135236cfd9ba2da15646d
diff --git a/GettingStarted.md b/GettingStarted.md
index 485a0ab..989dc5d 100644
--- a/GettingStarted.md
+++ b/GettingStarted.md
@@ -2,8 +2,8 @@
This is Project Shodan, a project to research the fusion of novel hardware and
software architectures to produce a low-power, ambient AI core. For more
-information, see our internal site at
-[sites/cerebrahardware/shodan](https://sites.google.com/corp/google.com/cerebrahardware/shodan).
+information, see our
+[internal site](https://sites.google.com/corp/google.com/cerebrahardware/projects/current-projects/shodan).
## Developing in this Codebase
@@ -58,18 +58,12 @@
m prereqs
```
-Install the RISCV toolchain:
+Install the tools used for development:
```bash
m tools
```
-Install the instruction set simulator:
-
-```bash
-m sim
-```
-
## Day-to-day Development Workflow
In general, working with repo is relatively simple:
@@ -121,11 +115,6 @@
Our layout is pretty simple:
-### hw/
-
-Contains all of the source code and RTL required to build the Shodan
-hardware, as well as simulate it in Verilator.
-
### build/
Contains build scripts for the whole tree. This is effectively just an
@@ -146,6 +135,27 @@
Lots of extra documentation (we hope) about how the repo is laid out, how the
build system works, code reviews, licensing, etc.
+### hw/
+
+Contains all of the source code and RTL required to build the Shodan
+hardware, as well as simulate it in Verilator.
+
+#### opentitan
+
+Security core.
+
+#### ibex
+
+System management controller (SMC).
+
+#### springbok
+
+Vector core for ML acceleration.
+
+### kata/
+
+Operating system software for the SMC; including seL4 kernel & CAmkES framework, and custom CAmkES components that support Shodan (or maybe KataOS) applications.
+
### manifest/
The repo manifest used to glue all the git repositories together.
@@ -156,44 +166,46 @@
### sim/
-Contains tools and src for simulation of the shodan hw.
+Contains tools and src for simulators (Renode and Verilator) of the shodan system.
+
+### sw/
+
+Contains the source code of applications running in all shodan cores.
+
+#### libtock-rs
+
+**TODO**: add more details
+
+#### multihart_boot_rom
+
+Bootstrap for System Management Controller, Security Core, and Vector Core. This is the first software to run after reset; it does low-level hardware setup and starts TockOs (SC) and seL4 (SMC).
+
+#### pigweed
+
+pigweed frameworks. Currently it is used for vector core functional tests.
+
+#### tock
+
+The operating system running on the Security Core.
+
+#### vec
+
+Springbok 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.
### toolchain/
Contains the src to build the RISCV QEMU emulator, and
[IREE](https://github/com/google/iree) toolchain for ML models.
-## Start a simulation
-
-The simulator used for Shodan is [Renode](https://renode.io/).
-After building and installing the simulator it can be run
-by using the alias `renode`.
-
-This alias is equivalent to the command:
-
-```bash
-mono cache/renode/Renode.exe
-```
-
-The configuration for the Shodan SoC is `sim/config/shodan.repl`,
-and an example of running zephyr on Shodan can be run as below:
-
-```bash
-include @sim/config/shodan_zephyr.resc
-start
-```
-
-## Build and test ML artifacts
+## Build and Test ML Artifacts
The ML executable is built with [IREE](https://github.com/google/iree) workflow,
targeted to RISCV 32-bit bare-metal config.
-To retrieve the IREE RISC-V toolchain and Renode emulator:
-
-```bash
-m tools
-```
-
To build the IREE targets:
```bash
@@ -218,6 +230,82 @@
(Enter quit to exit the Renode simulation)
+## Running The Full Shodan System Simulation
+
+The simulator used for Shodan is [Renode](https://renode.io/). The configuration for the Shodan system is `sim/config/shodan_all.repl`, while and starting script is in `sim/config/shodan_all.resc`
+
+To run the full system simulation, build the default target:
+
+```bash
+m
+```
+
+After all the artifacts are bulit, the Renode simulation session automatically starts, and you should see the secured core and SMC booted
+
+```bash
+19:14:43.6741 [INFO] uart0: OpenTitan initialisation complete. Entering main loop
+19:14:43.9188 [INFO] uart3: Booting all finished, dropped to user space
+19:14:48.8965 [INFO] uart3: kata_allocator::init: start_addr 0x1c8858 size 16384
+19:14:48.9079 [INFO] uart3: kata_debug_console::run
+19:14:48.9137 [INFO] uart3: kata_shell::DebugConsole::repl()
+```
+
+At this point, you should be able to connect to the SMC debug console.
+
+### Setting Up Debug Console Communication
+
+Install socat to your machine
+
+```bash
+sudo apt install socat
+```
+
+In a new shell session, launch the debug console with
+
+```bash
+scripts/kshell.sh
+```
+
+You will see the kataOS prompt showing up when you hit `enter`. Use `ctrl-c` to leave the console.
+
+### Connecting to Renode Console
+
+Renode has its own console to control the emulation environment. You can connect to it by
+
+```bash
+telnet localhost 1234
+```
+
+For example, you can check the core status
+
+```bash
+(matcha) cpu1 IsHalted
+False
+```
+
+or stop the whole emulation with
+
+```bash
+(matcha) quit
+```
+
+### Launch ML Job on the Vector Core
+
+You can launch the ML workload execution by communicating through the debug console
+
+```bash
+KATA_PROMPT> test_mlexecute
+```
+
+and you should see
+
+```bash
+19:31:01.0841 [INFO] uart3: KATA_PROMPT> test_mlexecute
+19:31:01.1057 [WARNING] cpu2: The debug mode now has no effect - connect a debugger, and switch to stepping mode.
+19:31:01.2934 [INFO] cpu2: simprint: "INFO |simple_vec_mul finished successfully", 0 (0x0)
+19:31:01.2945 [INFO] cpu2: simprint: "main returned: ", 0 (0x0)
+```
+
## More Information
- [Information on how to use repo](https://go/repo)
