Wrote some notes for the hackathon

hackathon.md

@@ -0,0 +1,94 @@
+# Hackathon Structured Lab Part 1
+
+## Orientation
+
+You are in the [`sonata-software`][] repository.
+This repository wraps the [`lowrisc/cheriot-rtos`][], adding some Sonata specific demonstration code on top of the CHERIoT stack.
+The [`lowrisc/cheriot-rtos`][], included in this repository as a submodule, is a fork of the upstream [`microsoft/cheriot-rtos`][].
+[`microsoft/cheriot-rtos`][] contains the CHERIoT software stack; it is well documented by the [CHERIoT Programmer's Guide][].
+*The [`lowrisc/cheriot-rtos`][] fork only exists to hold fresh patches that aren't quite ready to be upstreamed to [`microsoft/cheriot-rtos`][] but will be.*
+
+Other repositories of note:
+- [`sonata-system`][]: holds the Sonata system RTL and bootloader which come together to generate the bitstream.
+- [`sonata-rp2040`][]: The firmware that is running on the Sonata's RP2040 microcontroller.
+- [`CHERIoT-Platform/llvm-project`][]: The CHERIoT toolchain.
+- [`cheriot-audit`][]: A tool to explore and verify the relationships between CHERIoT RTOS components.
+
+For hardware documentation, see the [Sonata system book][].
+
+[`sonata-software`]: https://github.com/lowRISC/sonata-software
+[`lowrisc/cheriot-rtos`]: https://github.com/lowRISC/cheriot-rtos
+[`microsoft/cheriot-rtos`]: https://github.com/microsoft/cheriot-rtos
+[`sonata-system`]: https://github.com/lowRISC/sonata-system
+[`sonata-rp2040`]: https://github.com/newaetech/sonata-rp2040
+[`CHERIoT-Platform/llvm-project`]: https://github.com/CHERIoT-Platform/llvm-project
+[`cheriot-audit`]: https://github.com/CHERIoT-Platform/cheriot-audit
+[CHERIoT Programmer's Guide]: https://cheriot.org/book/
+[Sonata system book]: https://lowrisc.org/sonata-system/
+
+
+## The First Build and Load
+
+I'm going to assume you've run through the whole of the [`README.md`](README.md).
+In which case, you will have ran `xmake` and built the firmware images specified in [`xmake.lua`](xmake.lua), specifically by the *firmware* rules.
+Each of the firmware targets depends on *compartments*, declared with `add_deps`, and has a number of *threads*.
+For more information about these rules, see [`cheriot-rtos/README.md`](cheriot-rtos/README.md#building-firmware-images).
+
+The only thing this repository adds is a little post-link function, `convert_to_utf2`, that converts the ELF of the firmware image into a UF2 file which can be easily loaded onto the Sonata board.
+To do this, just copy the built UF2 to the `SONATA` drive which should have mounted when you plugged the board in.
+After doing this, you should see some flashing LEDs!
+
+```sh
+xmake
+cp build/cheriot/cheriot/release/sonata_simple_demo.uf2 /run/media/hugom/SONATA/
+sync
+```
+
+To see the UART console logs, attach to `/dev/ttyUSB2` at a Baud of 115200 with your favourite terminal.
+
+```sh
+picocom /dev/ttyUSB2 -b 115200 --imap lfcrlf
+```
+
+You should see:
+
+```
+bootloader: Loading software from flash...
+bootloader: Booting into program, hopefully.
+Led Walk Raw: Look pretty LEDs!
+```
+
+If you'd like get debug messages from the RTOS Core compartments, you can enable them with the following configuration flags.
+
+```sh
+xmake config --board=sonata --debug-scheduler=y \
+    --debug-locks=y --debug-cxxrt=y \
+    --debug-token_library=y --debug-allocator=y
+xmake build
+```
+
+You may need to run `rm -rf build/ .xmake/` to remove the debug messages from the configuration.
+
+
+## Learning about the CHERIoT RTOS
+
+The [CHERIoT Programmer's Guide] contains most of what a programmer would need to know to use the RTOS.
+It's rendered from [`cheriot-rtos/docs/`](cheriot-rtos/docs).
+
+The different boards supported can be found in [`cheriot-rtos/sdk/boards/`](cheriot-rtos/sdk/boards), of particular interest will be the Sonata's description in `sonata.json`.
+More on board descriptions can be found in [`cheriot-rtos/docs/BoardDescriptions.md`](cheriot-rtos/docs/BoardDescriptions.md).
+The structures the map onto the peripherals' memory and add functionality can be found in [`cheriot-rtos/sdk/include/platform/`](cheriot-rtos/sdk/include/platform/); the Sonata/Sunburst specific peripherals can be found in `sunburst/`.
+
+The examples in [`cheriot-rtos/examples`](cheriot-rtos/examples) provide a nice tour of the different ways compartments can interact.
+The following is shows how one can build an example to a UF2 file that can be loaded onto the board.
+
+```sh
+pushd cheriot-rtos/examples/04.temporal_safety/
+xmake -P .
+llvm-objcopy -Obinary build/cheriot/cheriot/release/temporal_safety /tmp/temporal_safety.bin
+uf2conv /tmp/temporal_safety.bin -b0x00101000 -co /tmp/temporal_safety.uf2
+popd
+```
+
+To explore the various utility libraries available, look through [`cheriot-rtos/sdk/include/`](cheriot-rtos/sdk/include/).
+When starting first starting to explore capabilities, the [`CHERI::Capability`](cheriot-rtos/sdk/include/cheri.hh) class is useful for pointer introspection.