Published in June 2020 as Technical Report UCAM-CL-TR-947, this guide introduces CHERI C/C++ and capability-based pointers across CHERI-MIPS, CHERI-RISC-V, and Arm Morello. It explains pointer provenance, bounds, permissions, memory safety, and the changes needed to port conventional C/C++ software. Topics include the CheriABI POSIX environment, CHERI Clang/LLVM diagnostics, capability-management APIs, and custom memory-allocator design. The guidance draws on experience adapting FreeBSD userspace, PostgreSQL, and WebKit, and distinguishes implemented referential and spatial protections from experimental temporal-safety support.
Free preview text
The first 5 pages, shown as text so search engines and readers can find this document.
Page 1
Technical Report
Number 947
Computer Laboratory
UCAM-CL-TR-947
ISSN 1476-2986
CHERI C/C++ Programming Guide
Robert N. M. Watson, Alexander Richardson,
Brooks Davis, John Baldwin, David Chisnall,
Jessica Clarke, Nathaniel Filardo,
Simon W. Moore, Edward Napierala,
Peter Sewell, Peter G. Neumann
June 2020
15 JJ Thomson Avenue
Cambridge CB3 0FD
United Kingdom
phone +44 1223 763500
https://www.cl.cam.ac.uk/
3
Abstract
This document is a brief introduction to the CHERI C/C++ programming languages.
We explain the principles underlying these language variants, and their grounding in
CHERI’s multiple architectural instantiations: CHERI-MIPS, CHERI-RISC-V, and Arm’s
Morello. We describe the most commonly encountered differences between these dialects
and C/C++ on conventional architectures, and where existing software may require minor
changes. We document new compiler warnings and errors that may be experienced compil-
ing code with the CHERI Clang/LLVM compiler, and suggest how they may be addressed
through typically minor source-code changes. We explain how modest language exten-
sions allow selected software, such as memory allocators, to further refine permissions
and bounds on pointers. This guidance is based on our experience adapting the FreeBSD
operating-system userspace, and applications such as PostgreSQL and WebKit, to run in a
CHERI C/C++ capability-based programming environment. We conclude by recommend-
ing further reading.
5
1 Introduction
This document is a brief introduction to the CHERI C/C++ programming languages. We ex-
plain the principles underlying these language variants, and their grounding in CHERI’s mul-
tiple architectural instantiations: CHERI-MIPS, CHERI-RISC-V, and Arm’s Morello. We
describe the most commonly encountered differences between these dialects and C/C++ on
conventional architectures, and where existing software may require minor changes. We doc-
ument new compiler warnings and errors that may be experienced compiling code with the
CHERI Clang/LLVM compiler, and suggest how they may be addressed through typically
minor source-code changes. We explain how modest language extensions allow selected soft-
ware, such as memory allocators, to further refine permissions and bounds on pointers. This
guidance is based on our experience adapting the FreeBSD operating-system userspace, and
applications such as PostgreSQL and WebKit, to run in a CHERI C/C++ capability-based pro-
gramming environment. We conclude by recommending further reading.
1.1 Definitions
CHERI Clang/LLVM and LLD implement the following new language, code-generation, and
linkage models:
CHERI C/C++ are C/C++-language dialects tuned to requirements arising from implementing
all pointers using CHERI capabilities. This includes all explicit pointers (i.e., those
declared by the programmer) and all implied pointers (e.g., those used to access local
and global variables). For example, they diverge from C/C++ implementations on con-
ventional architectures by preventing pointers passed through integer type other than
uintptr_t and intptr_t from being dereferenced. New Application Programming
Interfaces (APIs) provide access to capability features of pointers, including getting and
setting their bounds, required by selected software such as memory allocators. The vast
majority of C/C++ source code we have encountered requires little or no modification to
be compiled as CHERI C/C++.
Pure-capability machine code is compiled code (or hand-written assembly) that utilizes
CHERI capabilities for all memory accesses – including loads, stores, and instruction
fetches – rather than integer addresses. Capabilities are used to implement pointers ex-
plicitly described in the source program, and also to implement implied pointers in the
C execution environment, such as those used for control flow. Pure-capability machine
code is not binary compatible with capability-unaware code using integer pointers, not
least due to the different size of the pointer data type.
While the focus of this document is CHERI C/C++, CHERI is an architectural feature able
to support other software use cases including other C/C++-language mappings into its features.
Another mapping is hybrid C/C++, in which only selected pointers are implemented using cap-
abilities, with the remainder implemented using integers. We have primarily used hybrid C in
systems software that bridges between environments executing pure-capability machine code
CHERI C/C++ Programming Guide: summary, contents and background
This guide helps you understand the scope of CHERI C/C++ Programming Guide before or alongside reading the original document. It is based on the catalogue record, credited creator, source, classification and topics shown on this page. It does not replace the original work and does not invent claims about passages that Doxxly cannot verify.
Summary and overview
CHERI C/C++ Programming Guide is a 33-page documentcredited to Rhea K. Vance. Published in June 2020 as Technical Report UCAM-CL-TR-947, this guide introduces CHERI C/C++ and capability-based pointers across CHERI-MIPS, CHERI-RISC-V, and Arm Morello. It explains pointer provenance, bounds, permissions, memory safety, and the changes needed to port conventional C/C++ software. Topics include the CheriABI POSIX environment, CHERI Clang/LLVM diagnostics, capability-management APIs, and custom memory-allocator design. The guidance draws on experience adapting FreeBSD userspace, PostgreSQL, and WebKit, and distinguishes implemented referential and spatial protections from experimental temporal-safety support. It appears in the Technology & Security collection, which groups it with other material that readers may use for comparison and further study.
The item can be approached in several ways. A reader looking for a quick orientation can begin with the free five-page preview, inspect the page structure and use the metadata to judge relevance. Someone undertaking deeper research can work through the complete file, search its indexed text, record useful page references and compare its treatment of CHERI, C/C++, Capability-based programming, Memory safety, Pointer provenance, CheriABI, CheriBSD, Clang/LLVM, Memory allocation, Technical report with the related resources linked below.
Rather than reducing the work to a single claim, this page treats it as a source that should be read in context. The title, creator, publication source, licence and format all help explain what kind of evidence it may offer. Readers should distinguish the original author's statements from Doxxly's catalogue description, and should cite the original edition when using the material in academic, professional or published work.
Key topics and reader takeaways
The catalogue connects this document with CHERI, C/C++, Capability-based programming, Memory safety, Pointer provenance, CheriABI, CheriBSD, Clang/LLVM, Memory allocation, Technical report. These terms offer practical entry points rather than a substitute for close reading. Start by identifying the definitions, examples, arguments, tables or visual explanations attached to each topic. Then note where the creator draws connections, makes distinctions or moves from background material to a conclusion, recommendation, calculation or narrative development.
A useful reading method is to separate description from interpretation. First record what the item actually presents: names, headings, figures, formulas, quotations or stated propositions. Next consider why those details matter within the whole work. Finally compare them with another source from the same subject area. This process helps turn a long digital file into evidence that can be evaluated rather than merely skimmed.
Table of contents and reading guide
The following is an editorial content guide based on the verified catalogue topics. It is not represented as the original author's formal table of contents. Use it to organise notes while moving through the 33 pages in the player.
Part 1
CHERI
Use this section of the reading guide to identify how CHERI appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 2
C/C++
Use this section of the reading guide to identify how C/C++ appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 3
Capability-based programming
Use this section of the reading guide to identify how Capability-based programming appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 4
Memory safety
Use this section of the reading guide to identify how Memory safety appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 5
Pointer provenance
Use this section of the reading guide to identify how Pointer provenance appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 6
CheriABI
Use this section of the reading guide to identify how CheriABI appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 7
CheriBSD
Use this section of the reading guide to identify how CheriBSD appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
Part 8
Clang/LLVM
Use this section of the reading guide to identify how Clang/LLVM appears in CHERI C/C++ Programming Guide, note important terms, and connect the subject to the wider purpose of the work.
When a heading in the original differs from this guide, follow the original heading in your citation. Page numbers can also vary between editions. Doxxly's direct page field is useful for navigation, but formal references should include the title, creator, source and edition details available in the file itself.
About Rhea K. Vance
Doxxly credits Rhea K. Vance as the author or creator of CHERI C/C++ Programming Guide. This page does not add an unverified biography, job title or institutional affiliation. The attribution is preserved so readers can distinguish the creator from the hosting library and follow the original record when an external author link is available.
Author context matters because a work reflects a particular purpose, audience and point of view. Before relying on the material, consider what the creator set out to explain, when the source was produced and whether later research or revised guidance should also be consulted. For literature and philosophy, compare translations and editions; for technical material, check whether a newer version has superseded the one shown here.
About the source organisation
The recorded source for this item is cl.cam.ac.uk. Doxxly provides access and discovery tools but does not claim to be the original publisher unless explicitly stated. Source links, creator attribution and the recorded Publicly available file collected for editorial review licence are displayed to help readers assess provenance and permitted use.
Provenance is especially important for reports, standards, presentations and working spreadsheets. Check the original source for amendments, supporting files and current policy. A trustworthy research workflow keeps the source URL with any notes or downloaded copy, verifies important figures against the original, and avoids treating an archived document as automatically current.
Begin with the title and opening pages, then use the guide above to decide whether to read sequentially or move to a particular topic. The Doxxly player provides previous and next navigation, a direct page field, zoom steps, fit-to-width and fit-to-page modes, rotation and fullscreen. These controls are useful when a page contains small type, a wide table, an image, a scanned layout or a dense sequence of notes.
The first five pages are open to every visitor. A plan unlocks the complete item and full-document search. Search is best used for distinctive names, technical terms or short phrases; broad words can produce too many possible contexts. When you find a useful passage, read the surrounding pages so that a sentence, chart or formula is not separated from its explanation.
If downloading is enabled, members can obtain the original PDF file. Keep the original format when formulas, slide sequencing, pagination or layout carries meaning. Respect the Publicly available file collected for editorial review terms displayed on this page, and use the rights-report link if you believe the attribution or availability needs review.
Research questions to consider
As you read CHERI C/C++ Programming Guide, ask which audience the creator addresses, what problem or idea organises the work, what evidence is presented, and which assumptions remain unstated. Note whether important terms are defined consistently and whether examples represent a broader pattern or a narrow case. For quantitative material, record units, time periods, formulas and data sources. For interpretive material, separate the creator's language from your own summary.
A second set of questions concerns relevance today. Which parts remain durable, which depend on their historical or institutional setting, and what would need confirmation from a newer source? Following the tags and the Technology & Security collection can reveal useful comparisons. Agreement between sources can strengthen confidence, while disagreement can point to changing definitions, methods, evidence or priorities.
Finally, decide what you need from the item: background knowledge, a quotation, a worked example, a model, a visual explanation or a starting bibliography. That purpose should guide the depth of reading and the notes you keep. Doxxly helps locate and navigate the source; careful interpretation remains the reader's responsibility.