CHERI Software Release: Summer 2021

CHERI software releases are made up of a Docker image and a compressed tar file which, together, can be used to build and test software without the need to build or rebuild the compiler, debugger or the operating system.

The current release supports software emulation of CHERI-extended 64-bit RISC-V and Arm's Morello ISAs.

What You Get

Installation

The CHERI software release can be installed and run on a recent version of macOS such as Big Sur (Intel only) or Ubuntu Linux version 18.04 or 20.04. The release may run on other Linux distributions but it has has been extensively tested on Ubuntu only. The installation uses Docker as the engine that builds software as well as executing the software with QEMU or Arm's FVP.

The following checklist includes all of the steps to install this release.

  1. Install the Docker image from Docker Hub: docker pull ctsrd/cheribuild-docker:cheri-rel-20210817
  2. Check to see that the docker image loaded correctly with docker image ls which should show an image named ctsrd/cheribuild-docker with tag cheri-rel-20210817
  3. Download cheri-rel-volumes-20210817.tar.gz which contains all the tools and resides outside your Docker image but which Docker accesses as a VOLUME.
  4. Unpack the tar file with tar xf cheri-rel-volumes-20210817.tar.gz; you should now see a cheri/ directory which has build/, cheribuild/ and output/ directories, among others, within it
  5. Change directory into cheri/cheribuild
  6. From within the cheri/cheribuild directory execute the following command: ./cheribuild.py docker-adduser which will add your current user name, uid and gid to the cheribuild-docker image

You should now be able to run the Docker image following the instructions in the next section.

Running the CHERI Software Stack with Docker

To run the software release using docker you will use the ./docker-cheribuild.py command from within the cheri/cheribuild directory. For example, to run the Morello version of the software you would execute:

./docker-cheribuild.py run-morello-purecap

After several minutes you will be presented with a login: prompt at which you can log in as root without a password. You are now running in a QEMU emulated version of CheriBSD on the Morello ISA.

Similarly for the CHERI-RISC-V version you would execute the following command:

./docker-cheribuild.py run-riscv64-purecap

Note that docker-cheribuild.py can be run from outside the cheri/cheribuild directory, but for simplicity these notes assume your current directory is cheri/cheribuild.

Using Arm's FVP

The CHERI Software Release cannot currently be shipped with Arm's FVP, which is a more accurate simulation of the Morello board than is available with the QEMU version shipped with this release. Each system has its advantages; the FVP is a more accurate simulation of the eventual underlying hardware and has seen more extensive testing and use of the architecture, whilst QEMU executes far faster.

Note: The default setting for Docker Desktop for macOS reserves 2GB of RAM. This is insufficent to run the FVP and leads to Connection closed by foreign host. errors when the FVP is killed. Increasing memory to 4GB in Preferences/Resources is sufficent for simple operations, more may be required.

To add the FVP to your software release execute the following command:

./docker-cheribuild.py install-morello-fvp

To run the software release after the FVP has been installed use:

./docker-cheribuild.py run-fvp-morello-purecap

For more information on Arm's Morello and their FVP please refer to the following pages:

Morello Project

Arm Ecosystem FVPs

Building the System from Sources

The released software includes a configuration file in cheribuild/docker-cheribuild.json that has the release tag cheri-rel-20210817 embedded in it for the relevant repositories. Whenever you use the ./docker-cheribuild.py program from within your cheribuild directory this configuration file is used.

For a clean build from sources it is best to remove everything under the build/ and output/ directories:

rm -rf output/* build/*

To rebuild the system from sources use one of the following commands:

./docker-cheribuild.py --include-dependencies run-riscv64-purecap

or

./docker-cheribuild.py --include-dependencies run-morello-purecap

For more information please read the following: Obtaining CheriBSD as well as the extensive help available within ./cheribuild.py.

Release Tags

Tag Name Notes
cheri-rel-20210817 Summer 2021 Release with support for Arm's Morello and 64-bit CHERI-RISC-V