lowRISC · HU90m · Aug 31, 2024 · Aug 30, 2024 · Aug 30, 2024 · Aug 30, 2024
diff --git a/.clang-tidy b/.clang-tidy
@@ -1,7 +1,7 @@
 Checks:          'clang-diagnostic-*,-clang-diagnostic-error,google-readability-casting,readability-else-after-return,performance-unnecessary-copy-initialization,bugprone-use-after-move,modernize-use-nullptr,modernize-redundant-void-arg,modernize-return-braced-init-list,modernize-use-default-member-init,modernize-use-equals-default,modernize-use-equals-delete,modernize-use-nodiscard,modernize-use-override,cppcoreguidelines-avoid-goto,misc-unconventional-assign-operator,cppcoreguidelines-narrowing-conversions,bugprone-assert-side-effect,bugprone-bool-pointer-implicit-conversion,bugprone-copy-constructor-init,bugprone-forwarding-reference-overload,bugprone-macro-parentheses,bugprone-macro-repeated-side-effects,bugprone-move-forwarding-reference,bugprone-misplaced-widening-cast,bugprone-swapped-arguments,bugprone-undelegated-constructor,bugprone-unused-raii,cert-dcl21-cpp,llvm-namespace-comment,misc-static-assert,misc-redundant-expression,modernize-loop-convert,readability-non-const-parameter,readability-identifier-naming'
+WarningsAsErrors: '*'
 FormatStyle: file
 UseColor: true
-WarningsAsErrors: false
 CheckOptions:
     - key: readability-identifier-naming.StructCase
       value: CamelCase

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -37,6 +37,7 @@ jobs:
 
       - name: Build Software
         run: |
+          nix build -L .?submodules=1#sonata-exercises
           nix build -L .?submodules=1#sonata-examples
           nix build -L .?submodules=1#sonata-tests
 

diff --git a/.reuse/dep5 b/.reuse/dep5
@@ -2,11 +2,11 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 
 Files: *.lock
        README.md
-       **/README.md
-       hackathon.md
        .devcontainer/*.*
        scripts/rp2040_uf2/pgrm.bin
-       doc/*
+       doc/*.md
+       tests/*.md
+       scripts/**/*.md
 Copyright: lowRISC contributors
 License: Apache-2.0
 

diff --git a/README.md b/README.md
@@ -1,162 +1,43 @@
-# Overview
+# Sonata Software
 
-This repository contains software, build flows and examples for the Sonata System (https://github.com/lowRISC/sonata-system).
+This repository contains software, build flows and examples for the [Sonata System][].
 
-If you want to use the web-based environment start at [Use a web-based environment](#use-a-web-based-environment). For local setups only Windows requires specific instructions, Nix handles everything you need on Linux and OSX. So if you're not using Windows jump straight to [Installing Nix](#installing-nix).
+[sonata system]: https://github.com/lowRISC/sonata-system
 
-## Windows Specific Setup
+For a guide on how to get up and running on building software for the sonata board see the [getting started guide][].
+After you are all set up, take a look at the [hardware access control exercise][].
 
-To obtain a Linux environment on Windows, you can choose to start a virtual machine or use Windows Subsystem for Linux (WSL).
+[getting started guide]: ./doc/getting-started.md
+[hardware access control exercise]: ./exercises/hardware_access_control/README.md
 
-Microsoft provides a detailed guide on how to install WSL: https://learn.microsoft.com/en-us/windows/wsl/install. For latest systems this would just be a single command:
-```bat
-wsl --install
-```
-You might need to enable virtualisation in the BIOS if it's not enabled by default.
+## Orientation
 
-If you are running the command without admin privileges, user account control (UAC) popups will appear a few times asking to allow changes to be made to the device.
-Click "yes" to approve.
+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 [`CHERIoT-Platform/cheriot-rtos`][].
+[`CHERIoT-Platform/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 [`CHERIoT-Platform/cheriot-rtos`][] but will be.*
 
-After the command's completion, it should say that Ubuntu is installed. Reboot your machine to make these changes effective.
+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.
+- [`CHERIoT-Platform/book`][]: The source of the [CHERIoT Programmer's Guide][].
 
-After rebooting, Ubuntu should be available in your start menu.
-Click it to start. For the first time, it would prompt you to select a Unix username and password.
-Follow the Linux (Ubuntu) steps for the rest of this guide.
+For hardware documentation, see the [Sonata system book][].
 
-> ℹ️ If you have installed your WSL a long time ago, systemd may not have been enabled by default.
-> It is recommended to use enable systemd.
-> See https://learn.microsoft.com/en-us/windows/wsl/systemd.
+[`sonata-software`]: https://github.com/lowRISC/sonata-software
+[`lowrisc/cheriot-rtos`]: https://github.com/lowRISC/cheriot-rtos
+[`CHERIoT-Platform/cheriot-rtos`]: https://github.com/CHERIoT-Platform/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-Platform/book`]: https://github.com/CHERIoT-Platform/book
+[CHERIoT Programmer's Guide]: https://cheriot.org/book/
+[Sonata system book]: https://lowrisc.org/sonata-system/
 
-## Installing Nix
-
-The Nix package manager is used to create reproducible builds and consistent development environments.
-Nix is required to follow the instructions below.
-We recommend installing Nix with the Determinate Systems' [`nix-installer`](https://github.com/DeterminateSystems/nix-installer):
-
-```sh
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-```
-
-For more indepth instructions, follow the guide on [the zero to nix site](https://zero-to-nix.com/start/install).
-
-*If you've downloaded nix through another method, make sure the experimental features ["flakes"](https://nixos.wiki/wiki/Flakes) and ["nix-command"](https://nixos.wiki/wiki/Nix_command) are enabled.*
-
-*To use Nix from the terminal you'll need to open up a new terminal for it to be added to your path.*
-
-*To obtain a Linux environment on Windows, you can choose to start a virtual machine or use Windows Subsystem for Linux (WSL). Microsoft provides [a detailed guide on how to install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).*
-
-### Setup Cache
-
-Nix will build everything from source, which can take quite some time unless you have access to cached binaries.
-To make use of the lowRISC cache so you don't have to rebuild binaries yourself, you'll need to make sure you're a trusted user.
-To do this, you will need to add your user to the trusted users in `/etc/nix/nix.conf`, e.g. `trusted-users = root username`. *You can also add all users from a certain group instead of a single user by using an `@` symbol before the group name, e.g. `@sudo` or `@wheel`.*
-
-> ℹ️ For Ubuntu users (including WSL users), this means adding this line to the `/etc/nix/nix.conf`:
-> ```
-> trusted-users = root @sudo
-> ```
-> 
-> You'll need to restart the nix-daemon afterwards for the change to be picked up.
-> ```sh
-> sudo systemctl restart nix-daemon
-> ```
-
-> ℹ️ For OSX users, this means adding this line to the `/etc/nix/nix.conf`:
-> ```
-> trusted-users = root @admin
-> ```
-> 
-> You then need to restart your Mac for the changes to take effect.
-
-## Enter the CHERIoT development environment
-
-Running the following will put you in a shell environment with all the applications needed to build the CHERIoT RTOS.
-
-```sh
-# Enter the shell with
-nix develop github:lowRISC/sonata-software
-# Exit the shell with
-exit
-```
-
-These applications are layered on top of your usual environment. You can see what was added with `echo $PATH`.
-
-```
-do you want to allow configuration setting 'extra-substituters' to be set to 'https://nix-cache.lowrisc.org/public/' (y/N)? y
-do you want to permanently mark this value as trusted (y/N)? y
-do you want to allow configuration setting 'extra-trusted-public-keys' to be set to 'nix-cache.lowrisc.org-public-1:O6JLD0yXzaJDPiQW1meVu32JIDViuaPtGDfjlOopU7o=' (y/N)? y
-do you want to permanently mark this value as trusted (y/N)? y
-warning: ignoring untrusted substituter 'https://nix-cache.lowrisc.org/public/', you are not a trusted user.
-```
-
-There is also an environment with the sonata simulator included:
-```
-nix develop .#env-with-sim
-sonata-simulator --help
-```
-
-If you see the warning that substituter is ignored, cancel the process with Ctrl+C and check to see that [trusted-users is setup properly](#Linux). Nix can and will build everything from source if it can't find a cached version, so letting it continue will cause LLVM-Cheriot to be built from scratch on your machine.
-
-## Use a web-based environment
-
-A [Github Codespaces](https://github.com/features/codespaces) web-based development environment is available.
-As codespaces provides a limited amount of free compute and storage (60 hours per month) a local environment is likely preferred for serious development however the codespace offers an excellent way to test out Sonata development with minimal friction.
-
-To use it you will need a (free) github account, you can sign-up at [https://github.com/signup](https://github.com/signup) if you need one.
-
-To create the codespace go to the sonata-software repository https://github.com/lowrisc/sonata-software, click on '<> Code' and choose the 'Codespaces' tab. You should see a green 'Create codespace on main' button. Click this and a codespace will be setup.
-
-It'll take a few minutes to create, and you will eventually see a vscode UI. In the bottom panel (which has the terminal) you'll see a + icon in the top right of the panel. Click this and you should see a new terminal open that gives the prompt 'Sonata /workspaces/sonata-software>'. This is the same shell environment you get with the local setup described above.
-
-You can now follow the first build instructions below but you don't need to checkout the repository (the github codespace has done that for you).
-
-You have a limited allowance for running codespaces. To avoid running out you can delete or stop your codespace from [https://github.com/codespaces](https://github.com/codespaces). Click the three horizontal dots next to the codespace name and choose either 'Delete' or 'Stop Codespace'.
-
-## Your first build
-
-Checkout this repository (not required under github codespaces) and cd into it:
-```sh
-git clone --recurse-submodule \
-    https://github.com/lowRISC/sonata-software.git
-cd sonata-software
-```
-
-Configure and run build:
-
-```sh
-xmake -P examples
-```
-
-After running this you should see the build run to completion and report success, the critical lines indicating a successful build are:
-
-```sh
-Converted to uf2, output size: 74752, start address: 0x101000
-Wrote 74752 bytes to build/cheriot/cheriot/release/sonata_simple_demo.uf2
-[100%]: build ok, spent 6.827s
-```
-
-*Note, the output size may differ.*
-
-## Next steps
-
-The [lab from the recent hackathon](hackathon.md) gives a good introduction to some CHERIoT RTOS features and how to develop CHERIoT RTOS applications for Sonata.
-
-## Running with the simulator
-
-When using the `env-with-sim` environment (see above) a Sonata simulator binary is available.
-The `scripts/run_sim.sh` script can be used to run it against a binary, e.g. to run the binary built above in the simulator:
-
-```sh
-./scripts/run_sim.sh build/cheriot/cheriot/release/sonata_simple_demo
-```
-
-UART output can be seen in the uart0.log file.
-This can be observed using `tail -f` which will monitor the file and output as soon as something is written to the UART.
-Note with the simulator running in the foreground this will need to be run in another terminal
-
-```sh
-tail -f uart0.log
-```
 
 ## License
 

diff --git a/SUMMARY.md b/SUMMARY.md
@@ -0,0 +1,15 @@
+<!--
+Copyright lowRISC Contributors.
+SPDX-License-Identifier: Apache-2.0
+-->
+# Sonata Software
+
+[Introduction](./README.md)
+
+- [Getting started](./doc/getting-started.md)
+  - [Running Sonata Software](./doc/guide/running-software.md)
+
+- [Exploring the CHERIoT RTOS](./doc/exploring-cheriot-rtos.md)
+
+- [Exercises](./exercises/README.md)
+  - [Hardware Access Control Exercise](./exercises/hardware_access_control/README.md)
diff --git a/book.toml b/book.toml
@@ -0,0 +1,12 @@
+# Copyright lowRISC Contributors.
+# SPDX-License-Identifier: Apache-2.0
+
+[book]
+language = "en"
+multilingual = false
+src = "."
+title = "Sonata Software"
+
+[output.html]
+git-repository-url = "https://github.com/lowRISC/sonata-software"
+edit-url-template = "https://github.com/lowRISC/sonata-software/edit/main/{path}"
diff --git a/doc/exploring-cheriot-rtos.md b/doc/exploring-cheriot-rtos.md
@@ -0,0 +1,49 @@
+# Exploring CHERIoT RTOS
+## CHERIoT RTOS Orientation
+All the software in this repository runs on the CHERIoT RTOS, which is pulled into this repository as a submodule at [`cheriot-rtos`].
+The [CHERIoT Programmer's Guide] contains most of what a programmer would need to know to use the RTOS.
+
+[`cheriot-rtos`]: ../cheriot-rtos
+[CHERIoT Programmer's Guide]: https://cheriot.org/book/
+
+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 drivers (structures that map onto a peripherals' MMIO) 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/` within the aforementioned directory.
+
+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.
+
+## Build System
+
+The CHERIoT RTOS uses [xmake][] as it's build system.
+The main rules you'll use are *compartment* and *library*, for creating compartments and libraries, as well as the *firmware* rule for creating a firmware image.
+Documentation on these can be found in the CHERIoT RTOS' readme under '[building firmware images][]'.
+For examples of using these rules, look at a root `xmake.lua` file, such as [`examples/xmake.lua`], and in the subdirectories it includes with the `includes` function.
+*Note, we run an additional `convert_to_uf2` function on our firmware images to create UF2 files in this repository.*
+
+[xmake]: https://xmake.io/
+[building firmware images]: ../cheriot-rtos/README.md#building-firmware-images
+[`examples/xmake.lua`]: ../examples/xmake.lua
+
+
+## Building an upstream CHERIoT RTOS example
+
+The examples in [`cheriot-rtos/examples`](../cheriot-rtos/examples) provide a nice tour of the different ways compartments can interact.
+These can be built by pointing xmake to the example one wants to build, as shown below.
+
+```sh
+# Run from the root of the sonata-software repository
+xmake -P cheriot-rtos/examples/05.sealing/
+```
+
+### Where's my UF2
+
+If you've followed the '[running software on the FPGA]' guide, you'll expect UF2 files as part of the build artefacts but these aren't automatically created in the [`cheriot-rtos`][] repository.
+Thankfully, this repository includes a `./scripts/elf-to-uf2.sh` script that converts an ELF into a firmware a UF2 file.
+
+[running software on the FPGA]: ./guide/running-software.md#running-on-the-sonata-fpga
+
+```sh
+xmake -P cheriot-rtos/examples/05.sealing/
+./scripts/elf-to-uf2.sh build/cheriot/cheriot/release/sealing
+```
diff --git a/doc/getting-started.md b/doc/getting-started.md
@@ -91,7 +91,7 @@ do you want to permanently mark this value as trusted (y/N)? y
 warning: ignoring untrusted substituter 'https://nix-cache.lowrisc.org/public/', you are not a trusted user.
 ```
 
-If you see the warning that substituter is ignored, cancel the process with Ctrl+C and check to see that [trusted-users is setup properly](#Setup-Cache). Nix can and will build everything from source if it can't find a cached version, so letting it continue will cause LLVM-Cheriot to be built from scratch on your machine.
+If you see the warning that substituter is ignored, cancel the process with Ctrl+C and check to see that [trusted-users is setup properly](#setup-cache). Nix can and will build everything from source if it can't find a cached version, so letting it continue will cause LLVM-Cheriot to be built from scratch on your machine.
 
 
 ## Your first build

diff --git a/doc/guide/running-software.md b/doc/guide/running-software.md
@@ -0,0 +1,59 @@
+# Running Sonata Software
+
+One can either run software [on the sonata FPGA board](#running-on-the-sonata-fpga)
+or [in the sonata simulator](#running-in-the-simulator).
+
+## Running in the simulator
+
+In the [getting started guide][], you entered the default environment with `nix develop`.
+Because you now want to use the simulator, you will want to enter the environment that includes the simulator with the following.
+
+```sh
+nix develop .#env-with-sim
+```
+
+[getting started guide]: ../getting-started.md
+
+This will pull the simulator into your path as `sonata-simulator`.
+There's a convenience script, `scripts/run_sim.sh`, for calling the simulator.
+One simply points the script to a built ELF file and it will run the firmware in the simulator.
+*The ELF file is the build artefact with the same name as the firmware image and no extension.*
+Note, the simulator will never terminate, so you will have to <kbd>Ctrl</kbd>+<kbd>C</kbd> to terminate the simulator.
+
+```sh
+./scripts/run_sim.sh build/cheriot/cheriot/release/sonata_simple_demo
+```
+
+UART output can be seen in the `uart0.log` file, which should appear in the directory the simulator was run from.
+This can be observed using `tail -f` which will monitor the file and output as soon as something is written to the UART.
+Note with the simulator running in the foreground this will need to be run in another terminal
+
+```sh
+tail -f uart0.log
+```
+
+## Running on the Sonata FPGA
+
+Any builds of software in this repository will also produce a UF2 file containing the built firmware.
+When the Sonata FPGA is plugged into the computer, it should show up as a drive called 'SONATA'.
+On my computer, it can be found at `/run/media/$USER/SONATA`.
+One just needs to copy the built UF2 file onto this drive for it to be loaded and run.
+
+```sh
+cp build/cheriot/cheriot/release/sonata_simple_demo.uf2 "/run/media/$USER/SONATA/"
+sync # This `sync` command is rarely necessary
+```
+
+To see the UART console logs, attach to `/dev/ttyUSB2` at a Baud of 921,600 with your favourite terminal.
+
+```sh
+picocom /dev/ttyUSB2 -b 921600 --imap lfcrlf
+```
+
+When running the `sonata_simple_demo.uf2`, you should see the following console output as well as some flashing LEDs and LCD activity.
+
+```
+bootloader: Loading software from flash...
+bootloader: Booting into program, hopefully.
+Led Walk Raw: Look pretty LEDs!
+```
diff --git a/examples/all/gpiolib.hh b/examples/all/gpiolib.hh