1.\"- 2.\" Copyright (c) 2026 Capabilities Limited 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.\" This software was developed by Capabilities Limited with funding from 7.\" Innovate UK and the Department for Science, Innovation and Technology 8.\" for the adoption and diffusion of CHERI technology under project 9.\" 10168042 (“CheriBSD feature extraction, maturity, and testing”). 10.\" 11.Dd June 26, 2026 12.Dt MEMORY_MODEL 7 13.Os 14.Sh NAME 15.Nm memory model 16.Nd Overview of the memory model 17.Sh DESCRIPTION 18Description of the memory model implemented by 19.Fx . 20.Ss Introduction 21This document covers various aspects of the memory model implemented by 22.Fx Ns 's 23supported architectures, compilers, and language runtimes. 24Some aspects are currently documented elsewhere, particularly in 25.Xr atomic 9 . 26.Ss Pointer Provenance 27On the surface, pointers are integer addresses within a (usually 28virtual) address space. 29In systems programming languages, pointers also have provenance which 30indicates where and when the pointer can access memory. 31Compilers use provenance information to perform alias analysis to 32justify optimizations. 33.Pp 34On CHERI targets, the bounds, permissions, and validity tag of 35capabilities make some aspects of provenance concrete. 36CHERI capabilities may only be derived from other capabilities and are 37subject to monotonicity guarantees. 38Specifically, no manipulation of a CHERI capability can produce a 39capability with more permissions than the original. 40.Pp 41Developers must take care to ensure that pointer provenance is not lost 42unless intended. 43Specifically: 44.Bl -dash 45.It 46When copying or manipulating pointers, use pointer types 47.Pq e.g., Vt char * , 48.Vt intptr_t , 49or 50.Vt uintptr_t 51to preserve provenance. 52Other integer types do not preserve provenance. 53.It 54Ensure that expressions using 55.Vt intptr_t 56or 57.Vt uintptr_t 58have a single, clear source of provenance. 59E.g., when adding two variables of type 60.Vt intptr_t 61cast the one that is an offset to 62.Vt size_t . 63.It 64Ensure that pointers are stored at their natural alignment. 65This is required by CHERI, and accessing an object through an improperly 66aligned pointer is undefined behavior in C. 67.It 68Cast pointers to a provenance-free type such as 69.Vt ptraddr_t 70when the address of a pointer is desired without provenance. 71.It 72Avoid manipulating pointer addresses such that they fall outside of the 73underlying allocation except one past the end as permitted by ISO C. 74Taking pointers further out of bounds 75.Pq even temporarily 76is undefined behavior in the C standard. 77In practice CHERI capabilities may be taken some distance out of bounds, 78but if taken too far out of bounds, the validity tag will be stripped. 79.El 80.Pp 81Developers must also take care not to leak valid pointers across address 82space boundaries. 83Specifically: 84.Bl -dash 85.It 86Copy objects containing pointers with provenance-preserving APIs such 87as: 88.Xr copyinptr 9 , 89.Xr copyoutptr 9 , 90.Xr memcpy 3 , 91and 92.Xr memmove 3 . 93.It 94Copy objects that should not contain pointers using 95non-provenance-preserving APIs such as: 96.Xr copyin 9 , 97.Xr copyout 9 , 98.Xr memcpy_data 9 , 99and 100.Xr memmove_data 9 . 101.El 102.Pp 103For practical advice on adapting to CHERI C/C++'s notion of provenance, see the 104.Lk https://ctsrd-cheri.github.io/cheri-c-programming/ CHERI C/C++ Programming Guide . 105A provenance-aware memory object model of C is documented in 106ISO/IEC TS 6010:2025: 107.Dq Programming languages – A Provenance-aware memory object model for C 108which can be read in draft form as WG14 paper 109.Lk https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3057.pdf N3057 . 110Further background on provenance in systems programming languages can 111be found in the Rust RFC 112.Lk https://rust-lang.github.io/rfcs/3559-rust-has-provenance.html 3559-rust-has-provenance . 113.Sh SEE ALSO 114.Xr arch 7 , 115.Xr atomic 9 116.Sh AUTHORS 117This software and this manual page were developed by Capabilities 118Limited with funding from Innovate UK and the Department for Science, 119Innovation and Technology for the adoption and diffusion of CHERI 120technology under project 10168042 121.Pq Do CheriBSD feature extraction, maturity, and testing Dc . 122