Page MenuHomeFreeBSD
Files F161573519

D57812.id180525.diff
No OneTemporary
Actions

D57812.id180525.diff
View Options

diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
--- a/share/man/man7/arch.7
+++ b/share/man/man7/arch.7
@@ -24,7 +24,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd June 20, 2026
+.Dd June 24, 2026
.Dt ARCH 7
.Os
.Sh NAME
@@ -242,6 +242,95 @@
.Pp
.Sy time_t
is 8 bytes on all supported architectures except i386.
+.Ss Pointer provenance
+On the surface, pointers are integer addresses within a (usually
+virtual) address space.
+In systems programming languages, pointers also have provenance.
+Provenance is additional information about the underlying storage
+pointed to by the pointer.
+Compilers can and do differentiate pointers with the same address based
+on observed provenance.
+For example, a pointer pointing to one-past-the-end of an array could
+have the same address as another valid allocation and the compiler could
+act on this information.
+.Pp
+The bounds, permissions, and validity tag of CHERI capabilities make
+some aspects of provenance concrete.
+CHERI capabilities may only be derived from other capabilities and are
+subject to monotonicity guarantees.
+No manipulation of a CHERI capability can produce a capability with more
+permissions than the original except by deriving it from a separate
+capability with those permissions.
+Developers must take care to ensure that pointer provenance is not lost
+unless intended.
+This includes:
+.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 a an offset to
+.Vt size_t .
+.It
+Avoid manipulating pointer addresses such that they fall outside of the
+underlying allocation.
+This 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.
+.It
+Ensure that pointers are stored at their natural alignment.
+This is required by CHERI and direct access 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.
+.El
+.Pp
+Developers must also take care not to leak valid pointers across address
+space boundaries.
+.Bl -dash
+.It
+Using provenance-preserving APIs when copying objects containing pointer
+whose provenance should preserved.
+These include:
+.Xr copyinptr 9 ,
+.Xr copyoutptr 9 ,
+.Xr memcpy 3 ,
+.Xr memmove 3 ,
+and
+.Xr qsort 3 .
+.It
+Using non-provenance-perserving APIs when copying data without pointers.
+These include:
+.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 .
.Ss Endianness and Char Signedness
.Bl -column -offset indent "Architecture" "Endianness" "char Signedness" "wchar_t Signedness"
.It Sy Architecture Ta Sy Endianness Ta Sy char Signedness Ta Sy wchar_t Signedness

File Metadata

Mime Type
text/plain
Expires
Mon, Jul 6, 12:09 AM (3 h, 52 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34322345
Default Alt Text
D57812.id180525.diff (3 KB)

Event Timeline