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)