With a new set of folks in the DSbD cohort 6 just getting started with their Sonata boards I thought it might be useful to capture some of the things I’ve learnt in the last few months about the ecosystem.

Setting up a dev environment

The easiest and quickest way to get up and running is to use the dev container. I have a fairly strong aversion to installing new software on my base system, and this just requires that you have docker installed. Opening a repo with dev container support in VS code will ask you if you want to reopen in a container. Do that and in a few seconds you’re in a pre-built dev environment. Simples, to paraphrase a meerkat.

One word of warning though; cheriot and Sonata both use the “:latest” tag as the version of the docker image, so you won’t automatically get updates when they are released. If you’ve pulled an update to a repo and builds starts failing with no apparent reason it’s worth pulling the latest dev container image and relaunching the dev container. You can find the image name to pull in the .devcontainer/devcontainer.json file.

Which Repo do I use ?

The CHERIoT ecosystem is split across a number of git repositories, and makes extensive used of submodules to link them and other external code from other places such as FreeRTOS. There is no version or release tagging in the repos, so you can only tell how current a submodule is by comparing the commit hashes. Versioning will start with the CHERIoT 1.0 release, which you can track here. On the plus side the CI system and maintainers do a good job of keeping it all compatible, and any breaking changes are discussed in the Signal channel.

cheriot-rtos

CHERIoT-RTOS is the core of the system, and includes its own set of examples that provide a great introduction to the main CHERI features. You don’t even need any hardware to run them, as by default they build for one of the two emulator environments (sail and ibex-safe-simulator) that are included in the dev container. The ReadMe file in the examples directory has a good description of what each does and how to build the and run them. You can also build and run the examples on the Sonata board, but remember to also set up the terminal emulator in another window or you won’t see any output.

cheriot-network

This contains the code for the various compartments in the secure network stack, and includes examples for SNTP, HTTP, HTTPS, and MQTT using some public servers. Note though that this is really set up to be used as a submodule; there is no dev container support in here, and the examples will only build if this is cloned alongside cheriot-rtos.

It’s worth looking at the layout of the code in here and how it is pulled into the other examples as an template of how to create reusable compartments.

cheriot-demos

This contains examples that are more complete systems than the feature focused examples in cheriot-rtos. The current examples are:

  • HughTheLightbulb requires a Sonata board connected via ethernet to network with a DHCP server and access to pool.ntp.org and test.mosquitto.org. It then controls the RGB LEDs on the Sonata Board via MQTT and shows the CPU and heap usage on the LCD. Its main focus is on the fault isolation within the network stack, but it’s also a useful example of basic IO programming on the Sonata board.

  • Compartmentalisation runs on Sonata or Arty A7 boards, and shows how compartments can be used to create an isolation boundary around a JavaScript runtime. It also shows how to expose the MMIO operations to JS. There is also a version of this in cheriot-rtos/exercises that runs just in the ibex-safe-simulator.

  • Configuration-broker shows how the CHERIoT features can be used to create a system where configuration data can be received from an external source and securely and safely distributed to a number compartments with a simple and minimal trust model. It currently builds for the ibex-safe-simulator with a simulated set of inputs and configuration targets, but a Sonata based variant also using MQTT is coming soon.

It includes cheriot-rtos and cheriot-network as submodules, so you can also run all of the examples in those repos from here as well. The commits of the submodule lags a little bit behind the main repos, but is generally recent enough unless you want to live on the bleeding edge. I think this is a better place for most folks to start, especially if you want at some point to use the network stack. You can still run all of the examples, and buffered a bit from changes in rtos, have access to some basic examples of working Sonata, and if you create an interesting demo you’re all set to contribute it back.

sonata-software

If you want examples that provide a wider coverage of interacting with the Sonata hardware then this is the one to look at. It also has a dev container, but it’s different from the Cheriot-rtos one and it’s not clear if it is really supported or not. Lowrisc instead suggest using nix, and the startup guide in the repo will talk you though installing nix on your system first. The dev container seems to also provides a nix setup, although it’s not the easiest thing to use. I found for example that the default (nix-devshell) terminal wouldn’t launch and I had to select bash terminal instead, and within that run everything as root. This also has a submodule of cheriot-rtos, but it’s a fork that has a few Sonata changes waiting to be upstreamed.

Connecting up a Sonata Board

From zero to CHERIoT in two minutes with Sonata covers how to extend a dev container to include a Sonata board.

If you power up your Sonata board after opening VS Code, then you need to tell VS code to rebuild the dev container (Ctrl-Shift-P -> Dev Containers:Rebuild Container) to get it to re-establish the volume mount.

If you’re going to be running any of the cheriot-rtos examples with console output then you also need to run a terminal emulator such as picocom or putty on whichever tty / COM port the Sonata board is connected to.