Preface

This is the first edition of the CHERIoT Programmers' Guide. This book is intended as a companion to the CHERIoT Platform. The latest draft is published on the CHERIoT web site. The online version will include any errata from the first edition.

Acknowledgements

A few months ago, this book was less than half its current length. Completing this was supported by the UKRI Discribe Hub+, funded through the Economic and Social Research Council [ES/V003666/1].

The version that you are now reading has had some significant improvements in accuracy and structure thanks to some great feedback from technical reviewers Phil Day, Richard Edgar, Adam Finney, Hugo McNally. It was then copyedited by Amanda Robinson, who has done an excellent job in fixing my typos, missing words, baroque sentence structures and all of the places where I just forgot that sentences needed finishing. Any remaining errors, omissions, or poor explanations are my responsibility.

The cats on the cover represent safe, secure, compartmentalisation (what is safer or more secure than a cat in a box?). Each cat is in a separate, isolated, compartment, in the model for which CHERIoT was designed.

The cat photos were contributed by some wonderful people from the Fediverse. Starting at the top left, numbered left to right then top to bottom, the photo credits are:

1, 3, 5, 10:

Photographer: James (@chongliss@mastodon.ie), Cats: Jiji (1), Luna (3, 5), and Felix (10).

2, 11:

Photographer: Cassian Lodge (@cassolotl@eldritch.cafe), Cat: Rosa.

4:

Photographer: Marin Benčević (@marinbenc@sigmoid.social)

6:

Photographer: Asta Halkjær From (@ahfrom@fedi.ahfrom.synology.me), Cat: Betty Rambo.

7:

Photographer: Victor Zverovich (@vitaut@mastodon.social), Cat: Luna (no relation).

8:

Photographer: Michael McWilliams (@MichaelMcWilliams@mas.to), Cat: Scotchy.

9:

Photographer: jarkman (@jarkman@chaos.social), Cat: Jack.

12:

Photographer: Isaac Freund (@ifreund@hachyderm.io), Cat: Marzipan.

No generative AI was used in the creation of this image. No artist's work was appropriated without their consent.

Reading and using examples

Code listings in this book specify the file that they come from in the book's examples. You can find the examples in a stand-alone examples git repository on GitHub.

You can clone this repository with the following command:

$ git clone --branch first-edition 
	--recursive 
	https://github.com/CHERIoT-Platform/book-examples
Cloning into 'book-examples'...

This will clone exactly the version used in the first edition. If you check out the first-edition-update branch, then you will have a version that may not exactly match the listings in the book, but which has been updated to work with a newer version of the RTOS. Any differences in this branch will be listed in the errata section of the online edition of the book.

The examples are provided as a stand-alone repository containing a snapshot of the RTOS and network stack each as a git submodule. It provides a development container configuration (discussed in more detail in Section 3.2. Using the CHERIoT development container) that provides all of the tools required to build the examples. This is discussed in more detail in Chapter 3. Getting started writing CHERIoT software.

Example code in the book is pulled in from complete source files to ensure that everything that you see as a listing is valid code that will, at the very least, compile (and hopefully work). You should be able to build and run all of the example code yourself.

Listings have line numbers on the left. These are the line numbers in the file, so you can read the extracted listings in context.

When you read the files that contain these listings, you will see comments like // something#begin and // something#end. These are the markers for regions extracted and used in the book.

Syntax highlighting for this book is done by libclang (for C/C++) or TreeSitter (for Lua and Rego).