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
- A Docker image
- Pre-built binaries and libraries shipped as a compressed tar archive named cheri-rel-volumes-20210817.tar.gz
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.
- Install the Docker image from Docker Hub:
docker pull ctsrd/cheribuild-docker:cheri-rel-20210817
- Check to see that the docker image loaded correctly with
docker image lswhich should show an image named
- 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.
- Unpack the tar file with
tar xf cheri-rel-volumes-20210817.tar.gz; you should now see a
cheri/directory which has
output/directories, among others, within it
- Change directory into
- From within the
cheri/cheribuilddirectory execute the following command:
./cheribuild.py docker-adduserwhich 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
directory. For example, to run the Morello version of the software
you would execute:
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 can be run from outside the
cheri/cheribuild directory, but for simplicity these notes assume
your current directory is
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:
To run the software release after the FVP has been installed use:
For more information on Arm's Morello and their FVP please refer to the following pages:
Building the System from Sources
The released software includes a configuration file in
cheribuild/docker-cheribuild.json that has the release
cheri-rel-20210817 embedded in it for the relevant
repositories. Whenever you use the
program from within your
cheribuild directory this
configuration file is used.
For a clean build from sources it is best to remove everything
rm -rf output/* build/*
To rebuild the system from sources use one of the following commands:
./docker-cheribuild.py --include-dependencies run-riscv64-purecap
./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
|cheri-rel-20210817||Summer 2021||Release with support for Arm's Morello and 64-bit CHERI-RISC-V|