Last edited on 20231108.

CHERIoT

These are notes I wrote while experimenting with CHERIoT.

Setting up the development environment

In order to compile programs to run on the CHERIoT platform, we need to set up the necessary compilation toolchain. The easiest way is to use a devcontainer within VSCode.

After installing VSCode, Docker and the devcontainer extension, locally cloneAs the repository contains submodules, don't forget the --recurse option when cloning: git clone --recurse https://github.com/microsoft/cheriot-rtos the CHERIoT RTOS repository and open it in VSCode. The dev container should then automatically install the necessary bits. It is then possible to navigate inside the container by opening the terminal (Ctrl + ` within VSCode).

Running the CHERIoT RTOS examples should then be as simple as

$ cd cheriot-rtos/examples/01.hello_world/
$ xmake config --sdk=/cheriot-tools/ --board=ibex-safe-simulator
$ xmake run

Synthesizing CHERIoT Ibex on an FPGA

The CHERIoT platform is based on a modified RISC-V Ibex processor, it is possible to synthesize the CPU on a Digilent Arty A7-100T.

Xilinx Vivado will be necessary to interact with the board. CHERIoT-safe provides a script for building bitfiles for the FPGA. We can then use Vivado to transfer the bitfile on the board.

However, in order to produce a suitable bitfile, firmware images are needed. Suitable ones are provided here. When transfered on the FPGA, this should print out a simple hello world over UART. This can be observed using screen /dev/ttyUSB1 115200115200 corresponds to the baud rate for communicating over UART. for instance.

As far as I understand, the firmware image is composed of two hex files, namely cpu0_irom.vhx and cpu0_iram.vhx. The IROM file contains the ROM bootloader code, it is thus sufficient for it to just contain a single jump instruction that branches to the start of IRAM which contains the actual code to run. For instance, CHERIoT-RTOS' run-ibex-safe-sim.sh script produces an IROM that contains a single jal x0, 262016 instruction which basically corresponds to an unconditional jump PC := PC + 262016. This offset is due to the fact that the IRAM base is located at 0x40000 offset from the IROM base. There are 32 nop instructions before the jal instruction thus occupying 128 bytes, and 128 + 262016 = 262144 = 0x40000.I am only speculating and have no idea whether this is actually correct.

CHERIoT-safe provides an example of how to build the aforementioned bare metal hello world. The build_fpga_test.sh script needs to be updated to point at the compilation tools, doing that inside of a container should be easier.

It is also possible to compile the RTOS examples so that they can run directly on the board, but it is currently necessary to use the arty-a7 branch of the repository.

$ cd cheriot-rtos/examples/01.hello_world/
$ xmake config --sdk=/cheriot-tools/ --board=ibex-arty-a7-100
[...]
$ xmake
[...]
$ cd build/cheriot/cheriot/release/
$ ../../../../../../scripts/run-ibex-safe-sim.sh hello_world

There should now be a firmware/ folder which can then be used to build a bitfile.