[1.95.0] Document provenance and its use in const eval

src/changelog.rst

@@ -163,6 +163,9 @@ Language changes in Rust 1.95.0
   - The target is outside the scope of the FLS.
 
 - `const-eval: be more consistent in the behavior of padding during typed copies <https://github.com/rust-lang/rust/pull/148967>`_
+
+  - TODO: Fill out once we settle on the rules.
+
 - `Const blocks are no longer evaluated to determine if expressions involving fallible operations can implicitly be constant-promoted <https://github.com/rust-lang/rust/pull/150557>`_
 
   - This implementation-specifc behavior is outside the scope of the FLS.

src/glossary.rst

@@ -1156,6 +1156,11 @@ A :dt:`derive macro` is a :t:`procedural macro` that consumes a stream of
 :t:`[token]s` and produces a stream of tokens, and is invoked via attribute
 :c:`derive`.
 
+derived pointer
+^^^^^^^^^^^^^^^
+
+A :dt:`derived pointer` is a :t:`pointer` obtained by :t:`borrowing`, copying a :t:`pointer`, loading a stored :t:`pointer`, performing :t:`pointer` arithmetic, or :t:`casting` a :t:`pointer`.
+
 destruction
 ^^^^^^^^^^^
 
@@ -3186,14 +3191,18 @@ opt-out trait bound
 An :dt:`opt-out trait bound` is a :t:`trait bound` with :s:`Punctuation` ``?``
 that nullifies an implicitly added :t:`trait bound`.
 
-
 or-pattern
 ^^^^^^^^^^
 
 An :dt:`or-pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s them using character 0x7C (vertical line, i.e. ``|``).
 
 See :s:`Pattern`.
 
+original pointer
+^^^^^^^^^^^^^^^^
+
+An :dt:`original pointer` is a :t:`pointer` created via allocation.
+
 outer attribute
 ^^^^^^^^^^^^^^^
 
@@ -3411,7 +3420,7 @@ A :dt:`pointer` is a :t:`value` of a :t:`pointer type`.
 pointer type
 ^^^^^^^^^^^^
 
-A :dt:`pointer type` is a :t:`type` whose values indicate memory locations.
+A :dt:`pointer type` is either a :t:`raw pointer type` or a :t:`reference type`.
 
 positional register argument
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3476,6 +3485,11 @@ program entry point
 A :dt:`program entry point` is a :t:`function` that is invoked at the start of
 a Rust program.
 
+provenance
+^^^^^^^^^^
+
+:dt:`Provenance` is an optional property of :t:`[pointer]s` that restricts the memory locations the :t:`pointer` may access, the timespan during which the accesses may occur, and whether the accesses may read from or write to said memory locations.
+
 public visibility
 ^^^^^^^^^^^^^^^^^
 
@@ -3659,7 +3673,7 @@ See :s:`RawCStringLiteral`.
 raw pointer
 ^^^^^^^^^^^
 
-A :dt:`raw pointer` is a pointer of a :t:`raw pointer type`.
+A :dt:`raw pointer` is a :t:`value` of a :t:`raw pointer type`.
 
 raw pointer type
 ^^^^^^^^^^^^^^^^
@@ -5186,6 +5200,11 @@ context.
 
 See :s:`WeakKeyword`.
 
+well-formed pointer
+^^^^^^^^^^^^^^^^^^^
+
+A :dt:`well-formed pointer` is a :t:`pointer` where either no byte of the :t:`pointer` carries :t:`provenance`, or every byte of the :t:`pointer` is the corresponding byte of a single :t:`pointer` with :t:`provenance`.
+
 where clause
 ^^^^^^^^^^^^
 

src/types-and-traits.rst

@@ -939,6 +939,11 @@ A :t:`function item type` implements the :std:`core::ops::Fn` :t:`trait`, the :s
 Indirection Types
 -----------------
 
+.. rubric:: Legality Rules
+
+:dp:`fls_3qI8FXMsyk0f`
+A :t:`pointer type` is either a :t:`raw pointer type` or a :t:`reference type`.
+
 .. _fls_xztr1kebz8bo:
 
 Function Pointer Types
@@ -1028,13 +1033,14 @@ A :t:`mutable raw pointer type` is a :t:`raw pointer type` subject to
 An :t:`immutable raw pointer type` is a :t:`raw pointer type` subject to
 :t:`keyword` ``const``.
 
+:dp:`fls_c2Guy3fPYaUV`
+A :t:`raw pointer` is a :t:`value` of a :t:`raw pointer type`.
+
 :dp:`fls_hrum767l6dte`
-Comparing two :t:`[value]s` of :t:`[raw pointer type]s` compares the addresses
-of the :t:`[value]s`.
+Comparing two :t:`[raw pointer]s` compares the addresses of the :t:`[raw pointer]s`.
 
 :dp:`fls_k6ues2936pjq`
-Comparing a :t:`value` of a :t:`raw pointer type` to a :t:`value` of a
-:t:`dynamically sized type` compares the data being pointed to.
+Comparing a :t:`raw pointer` to a :t:`value` of a :t:`dynamically sized type` compares the data being pointed to.
 
 .. rubric:: Examples
 

src/unsafety.rst

@@ -23,7 +23,7 @@ An :t:`unsafe operation` is an operation that may result in
 The :t:`[unsafe operation]s` are:
 
 * :dp:`fls_jd1inwz7ulyw`
-  Dereferencing a :t:`value` of a :t:`raw pointer type`.
+  Dereferencing a :t:`raw pointer`.
 
 * :dp:`fls_3ra8s1v1vbek`
   Reading or writing an :t:`external static`.

src/values.rst

@@ -62,6 +62,39 @@ It is undefined behavior to create an :t:`allocated object` with :t:`memory
 size` ``size`` where ``size`` is greater than the architectures maximum
 :c:`isize` value.
 
+.. _fls_Dqk4eIvxHloY:
+
+Provenance
+----------
+
+.. rubric:: Legality Rules
+
+:dp:`fls_jriT46yWgIR0`
+A :t:`pointer` is a :t:`value` of a :t:`pointer type`.
+
+:dp:`fls_VWUlxTy0QF9d`
+An :t:`original pointer` is a :t:`pointer` created via allocation.
+
+:dp:`fls_kaPNJ7iIHPro`
+A :t:`derived pointer` is a :t:`pointer` obtained by :t:`borrowing`, copying a :t:`pointer`, loading a stored :t:`pointer`, performing :t:`pointer` arithmetic, or :t:`casting` a :t:`pointer`.
+
+:dp:`fls_5MkKtNL9oCsL`
+:t:`Provenance` is an optional property of :t:`[pointer]s` that restricts the memory locations the :t:`pointer` may access, the timespan during which the accesses may occur, and whether the accesses may read from or write to said memory locations.
+
+:dp:`fls_1NJhTBN1D2qv`
+An :t:`original pointer` carries :t:`provenance` over all or part of the :t:`allocated object` it was created from.
+
+:dp:`fls_wnJmQYT7iKQf`
+A :t:`derived pointer` inherits the :t:`provenance` of the :t:`pointer` it was created from, if any.
+
+:dp:`fls_ffh8mAkebORJ`
+A :t:`well-formed pointer` is a :t:`pointer` where either no byte of the :t:`pointer` carries :t:`provenance`, or every byte of the :t:`pointer` is the corresponding byte of a single :t:`pointer` with :t:`provenance`.
+
+.. rubric:: Undefined Behavior
+
+:dp:`fls_c3DaCLQEBpYQ`
+It is undefined behavior to access memory through a :t:`pointer` that does not have :t:`provenance` permitting the access.
+
 .. _fls_ixjc5jaamx84:
 
 Constants
@@ -107,9 +140,8 @@ A :t:`constant` shall have a :t:`constant initializer`, unless it is an
 The :t:`expression` of a :t:`constant initializer` shall be a
 :t:`constant expression`.
 
-:dp:`fls_deuo1pn8cjd6`
-The value of a :t:`constant` is determined by evaluating its
-:t:`constant initializer`.
+:dp:`fls_l1FOH8zt0XRZ`
+If the :t:`value` produced by evaluating a :t:`constant initializer` is or contains a :t:`pointer`, then each such :t:`pointer` shall be a non-dangling :t:`well-formed pointer`.
 
 .. rubric:: Dynamic Semantics
 
@@ -188,6 +220,9 @@ A :t:`static` shall have a :t:`static initializer`, unless it is an
 The :t:`expression` of a :t:`static initializer` shall be a
 :t:`constant expression`.
 
+:dp:`fls_37oocZVDne5Y`
+If the :t:`value` produced by evaluating a :t:`static initializer` is or contains a :t:`pointer`, then each such :t:`pointer` shall be a non-dangling :t:`well-formed pointer`.
+
 :dp:`fls_8dcldbvu7lav`
 A use of a :t:`static` is a :t:`place expression` referring to the unique
 location of the :t:`static`.