From nobody Fri Jun 26 11:26:20 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4gmtfN31wgz6jLMl for ; Fri, 26 Jun 2026 11:26:20 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4gmtfN24gDz44Mx for ; Fri, 26 Jun 2026 11:26:20 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1782473180; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=v5JAm/IeYYRFaIzVwwIAmi1UmJCOSoDlR8Nwh9kWTOM=; b=BFVAbqS5HPlBxnZf8uNBqV3nsqhkLmgF+Sv5uFQ9HOlh9xEYa0L0FfipiiTf9TNjT8UpXG pPKdEKbxVcUkJdBxRKPvlcs+TGkIFXUd3xgHBKOmRPcXSe1B+eNmuGhC4M1Uoyja9Du3Ss NEaBmEqkQhfjm0qJC21i6YGBFI+Drzy5ZvopmNzeyB9uuBn+5XVp3WnNIvx+hh0VxMzwzI NpInh//7g39Mm8S1MytsCibPsp4j+9vCgZEHkVY91w+6PgCjuKzy7R6qOni4N0rkjLaJBy sPhgto4NjnDSQ0ry0aYLUCYuUfkGadoYkWTYIa+aQiE/Oa84T/yuZtwLncrtjw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1782473180; a=rsa-sha256; cv=none; b=WIJdZAU6LYvpAdKI7l9kqUdvBig2MDmWfEKdR6LLFwprArwXltKh+YYDHha7JuV9zTi0tx /KgkUs3Wxt58wePSuiB2uHbnTxjvGhzM/9WcpWuwGoNMfxT2b/UWRXfxsucv/c1uo2R3I5 lH+s4ccEscOLiYh8qK4gJVOQrZHHk4AcqeVzyAeYwTL3vf+/DkIN8UScxRkvXwJYgb/oqs 8xrsl5QMtmAkbe63Re8RvNaKIzwsQkrra5OPUhFixqf4PJZedMg3RLE1X7dnQm5z+VbHIt wOqxdawDdQMRjxRUmAkCHt0fXHV6VLDUTOD2TMSOGVB/pExnQizaPrWGhcrSSg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1782473180; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=v5JAm/IeYYRFaIzVwwIAmi1UmJCOSoDlR8Nwh9kWTOM=; b=uKnaB4Htv0R3TZ3wr9VG0zb4vPFrGgDZylgf5uA5twWp7Wltm6S7Z1bYjDM6cO+i2l9OAI GazBdgLoAgjZFebSwOOg4cDwp/GwvBoiGkzydf7F/u1UlUFPnDX3vSzcrzeXjkOX533Bud 2HFFS0h6spITrchvuFv2780WLXLk65PBJ3tkoOeqhWDmITQv/2j/FYqDdumjQciOIt9bco KKG5IaLSvCqMyEYXL9gKS3SgDLeQhVMEgXTCpLrdDmcG3yDt76fliBfN3kZiPhwXUrRpX1 WruKUKZRBjTi1xWF6DUnb1Q9GcX81MEcUeJa++JPYrViR6KkIZTQU/Wir5SEeA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4gmtfN0jZBzbMb for ; Fri, 26 Jun 2026 11:26:20 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3a967 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 26 Jun 2026 11:26:20 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Brooks Davis Subject: git: 1366a87c9cb5 - main - memory_model(7): create and document pointer provenance List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: brooks X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 1366a87c9cb5ed47910636d17972f1bcad27fb9f Auto-Submitted: auto-generated Date: Fri, 26 Jun 2026 11:26:20 +0000 Message-Id: <6a3e61dc.3a967.70c8f1c6@gitrepo.freebsd.org> The branch main has been updated by brooks: URL: https://cgit.FreeBSD.org/src/commit/?id=1366a87c9cb5ed47910636d17972f1bcad27fb9f commit 1366a87c9cb5ed47910636d17972f1bcad27fb9f Author: Brooks Davis AuthorDate: 2026-06-26 11:23:48 +0000 Commit: Brooks Davis 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 .