Date: Fri, 26 Jun 2026 11:26:20 +0000 From: Brooks Davis <brooks@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 1366a87c9cb5 - main - memory_model(7): create and document pointer provenance Message-ID: <6a3e61dc.3a967.70c8f1c6@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by brooks: URL: https://cgit.FreeBSD.org/src/commit/?id=1366a87c9cb5ed47910636d17972f1bcad27fb9f commit 1366a87c9cb5ed47910636d17972f1bcad27fb9f Author: Brooks Davis <brooks@FreeBSD.org> AuthorDate: 2026-06-26 11:23:48 +0000 Commit: Brooks Davis <brooks@FreeBSD.org> CommitDate: 2026-06-26 11:26:11 +0000 memory_model(7): create and document pointer provenance Add a skeleton manpage intended to describe the FreeBSD memory model. To start out, add documentation of pointer provenance and a cross link to atomic(9). Provide some advice on preserving provenance in CHERI and reference more detailed discussions elsewere. Effort: CHERI upstreaming Reviewed by: kib, adrian, markj, emaste Sponsored by: Innovate UK Differential Revision: https://reviews.freebsd.org/D57812 --- share/man/man7/Makefile | 1 + share/man/man7/memory_model.7 | 121 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 6fd32da900e1..1462ad1da2a5 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -20,6 +20,7 @@ MAN= arch.7 \ hostname.7 \ intro.7 \ maclabel.7 \ + memory_model.7 \ mitigations.7 \ named_attribute.7 \ operator.7 \ diff --git a/share/man/man7/memory_model.7 b/share/man/man7/memory_model.7 new file mode 100644 index 000000000000..488f84763613 --- /dev/null +++ b/share/man/man7/memory_model.7 @@ -0,0 +1,121 @@ +.\"- +.\" Copyright (c) 2026 Capabilities Limited +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This software was developed by Capabilities Limited with funding from +.\" Innovate UK and the Department for Science, Innovation and Technology +.\" for the adoption and diffusion of CHERI technology under project +.\" 10168042 (“CheriBSD feature extraction, maturity, and testing”). +.\" +.Dd June 26, 2026 +.Dt MEMORY_MODEL 7 +.Os +.Sh NAME +.Nm memory model +.Nd Overview of the memory model +.Sh DESCRIPTION +Description of the memory model implemented by +.Fx . +.Ss Introduction +This document covers various aspects of the memory model implemented by +.Fx Ns 's +supported architectures, compilers, and language runtimes. +Some aspects are currently documented elsewhere, particularly in +.Xr atomic 9 . +.Ss Pointer Provenance +On the surface, pointers are integer addresses within a (usually +virtual) address space. +In systems programming languages, pointers also have provenance which +indicates where and when the pointer can access memory. +Compilers use provenance information to perform alias analysis to +justify optimizations. +.Pp +On CHERI targets, the bounds, permissions, and validity tag of +capabilities make some aspects of provenance concrete. +CHERI capabilities may only be derived from other capabilities and are +subject to monotonicity guarantees. +Specifically, no manipulation of a CHERI capability can produce a +capability with more permissions than the original. +.Pp +Developers must take care to ensure that pointer provenance is not lost +unless intended. +Specifically: +.Bl -dash +.It +When copying or manipulating pointers, use pointer types +.Pq e.g., Vt char * , +.Vt intptr_t , +or +.Vt uintptr_t +to preserve provenance. +Other integer types do not preserve provenance. +.It +Ensure that expressions using +.Vt intptr_t +or +.Vt uintptr_t +have a single, clear source of provenance. +E.g., when adding two variables of type +.Vt intptr_t +cast the one that is an offset to +.Vt size_t . +.It +Ensure that pointers are stored at their natural alignment. +This is required by CHERI, and accessing an object through an improperly +aligned pointer is undefined behavior in C. +.It +Cast pointers to a provenance-free type such as +.Vt ptraddr_t +when the address of a pointer is desired without provenance. +.It +Avoid manipulating pointer addresses such that they fall outside of the +underlying allocation except one past the end as permitted by ISO C. +Taking pointers further out of bounds +.Pq even temporarily +is undefined behavior in the C standard. +In practice CHERI capabilities may be taken some distance out of bounds, +but if taken too far out of bounds, the validity tag will be stripped. +.El +.Pp +Developers must also take care not to leak valid pointers across address +space boundaries. +Specifically: +.Bl -dash +.It +Copy objects containing pointers with provenance-perserving APIs such +as: +.Xr copyinptr 9 , +.Xr copyoutptr 9 , +.Xr memcpy 3 , +and +.Xr memmove 3 . +.It +Copy objects that should not contain pointers using +non-provenance-preserving APIs such as: +.Xr copyin 9 , +.Xr copyout 9 , +.Xr memcpy_data 9 , +and +.Xr memmove_data 9 . +.El +.Pp +For practical advice on adapting to CHERI C/C++'s notion of provenance, see the +.Lk https://ctsrd-cheri.github.io/cheri-c-programming/ CHERI C/C++ Programming Guide . +A provenance-aware memory object model of C is documented in +ISO/IEC TS 6010:2025: +.Dq Programming languages – A Provenance-aware memory object model for C +which can be read in draft form as WG14 paper +.Lk https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3057.pdf N3057 . +Further background on provenance in systems programming languages can +be found in the Rust RFC +.Lk https://rust-lang.github.io/rfcs/3559-rust-has-provenance.html 3559-rust-has-provenance . +.Sh SEE ALSO +.Xr arch 7 , +.Xr atomic 9 +.Sh AUTHORS +This software and this manual page were developed by Capabilities +Limited with funding from Innovate UK and the Department for Science, +Innovation and Technology for the adoption and diffusion of CHERI +technology under project 10168042 +.Pq Do CheriBSD feature extraction, maturity, and testing Dc .home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a3e61dc.3a967.70c8f1c6>