| 1 |
// Copyright 2024 The Fuchsia Authors |
| 2 |
// |
| 3 |
// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0 |
| 4 |
// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT |
| 5 |
// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. |
| 6 |
// This file may not be copied, modified, or distributed except according to |
| 7 |
// those terms. |
| 8 |
|
| 9 |
#![allow(missing_copy_implementations, missing_debug_implementations)] |
| 10 |
|
| 11 |
//! The parameterized invariants of a [`Ptr`][super::Ptr]. |
| 12 |
//! |
| 13 |
//! Invariants are encoded as ([`Aliasing`], [`Alignment`], [`Validity`]) |
| 14 |
//! triples implementing the [`Invariants`] trait. |
| 15 |
|
| 16 |
/// The invariants of a [`Ptr`][super::Ptr]. |
| 17 |
pub trait Invariants: Sealed { |
| 18 |
type Aliasing: Aliasing; |
| 19 |
type Alignment: Alignment; |
| 20 |
type Validity: Validity; |
| 21 |
} |
| 22 |
|
| 23 |
impl<A: Aliasing, AA: Alignment, V: Validity> Invariants for (A, AA, V) { |
| 24 |
type Aliasing = A; |
| 25 |
type Alignment = AA; |
| 26 |
type Validity = V; |
| 27 |
} |
| 28 |
|
| 29 |
/// The aliasing invariant of a [`Ptr`][super::Ptr]. |
| 30 |
/// |
| 31 |
/// All aliasing invariants must permit reading from the bytes of a pointer's |
| 32 |
/// referent which are not covered by [`UnsafeCell`]s. |
| 33 |
/// |
| 34 |
/// [`UnsafeCell`]: core::cell::UnsafeCell |
| 35 |
pub trait Aliasing: Sealed { |
| 36 |
/// Is `Self` [`Exclusive`]? |
| 37 |
#[doc(hidden)] |
| 38 |
const IS_EXCLUSIVE: bool; |
| 39 |
} |
| 40 |
|
| 41 |
/// The alignment invariant of a [`Ptr`][super::Ptr]. |
| 42 |
pub trait Alignment: Sealed {} |
| 43 |
|
| 44 |
/// The validity invariant of a [`Ptr`][super::Ptr]. |
| 45 |
/// |
| 46 |
/// # Safety |
| 47 |
/// |
| 48 |
/// In this section, we will use `Ptr<T, V>` as a shorthand for `Ptr<T, I: |
| 49 |
/// Invariants<Validity = V>>` for brevity. |
| 50 |
/// |
| 51 |
/// Each `V: Validity` defines a set of bit values which may appear in the |
| 52 |
/// referent of a `Ptr<T, V>`, denoted `S(T, V)`. Each `V: Validity`, in its |
| 53 |
/// documentation, provides a definition of `S(T, V)` which must be valid for |
| 54 |
/// all `T: ?Sized`. Any `V: Validity` must guarantee that this set is only a |
| 55 |
/// function of the *bit validity* of the referent type, `T`, and not of any |
| 56 |
/// other property of `T`. As a consequence, given `V: Validity`, `T`, and `U` |
| 57 |
/// where `T` and `U` have the same bit validity, `S(V, T) = S(V, U)`. |
| 58 |
/// |
| 59 |
/// It is guaranteed that the referent of any `ptr: Ptr<T, V>` is a member of |
| 60 |
/// `S(T, V)`. Unsafe code must ensure that this guarantee will be upheld for |
| 61 |
/// any existing `Ptr`s or any `Ptr`s that that code creates. |
| 62 |
/// |
| 63 |
/// An important implication of this guarantee is that it restricts what |
| 64 |
/// transmutes are sound, where "transmute" is used in this context to refer to |
| 65 |
/// changing the referent type or validity invariant of a `Ptr`, as either |
| 66 |
/// change may change the set of bit values permitted to appear in the referent. |
| 67 |
/// In particular, the following are necessary (but not sufficient) conditions |
| 68 |
/// in order for a transmute from `src: Ptr<T, V>` to `dst: Ptr<U, W>` to be |
| 69 |
/// sound: |
| 70 |
/// - If `S(T, V) = S(U, W)`, then no restrictions apply; otherwise, |
| 71 |
/// - If `dst` permits mutation of its referent (e.g. via `Exclusive` aliasing |
| 72 |
/// or interior mutation under `Shared` aliasing), then it must hold that |
| 73 |
/// `S(T, V) ⊇ S(U, W)` - in other words, the transmute must not expand the |
| 74 |
/// set of allowed referent bit patterns. A violation of this requirement |
| 75 |
/// would permit using `dst` to write `x` where `x ∈ S(U, W)` but `x ∉ S(T, |
| 76 |
/// V)`, which would violate the guarantee that `src`'s referent may only |
| 77 |
/// contain values in `S(T, V)`. |
| 78 |
/// - If the referent may be mutated without going through `dst` while `dst` is |
| 79 |
/// live (e.g. via interior mutation on a `Shared`-aliased `Ptr` or `&` |
| 80 |
/// reference), then it must hold that `S(T, V) ⊆ S(U, W)` - in other words, |
| 81 |
/// the transmute must not shrink the set of allowed referent bit patterns. A |
| 82 |
/// violation of this requirement would permit using `src` or another |
| 83 |
/// mechanism (e.g. a `&` reference used to derive `src`) to write `x` where |
| 84 |
/// `x ∈ S(T, V)` but `x ∉ S(U, W)`, which would violate the guarantee that |
| 85 |
/// `dst`'s referent may only contain values in `S(U, W)`. |
| 86 |
pub unsafe trait Validity: Sealed {} |
| 87 |
|
| 88 |
/// An [`Aliasing`] invariant which is either [`Shared`] or [`Exclusive`]. |
| 89 |
/// |
| 90 |
/// # Safety |
| 91 |
/// |
| 92 |
/// Given `A: Reference`, callers may assume that either `A = Shared` or `A = |
| 93 |
/// Exclusive`. |
| 94 |
pub trait Reference: Aliasing + Sealed {} |
| 95 |
|
| 96 |
/// The `Ptr<'a, T>` adheres to the aliasing rules of a `&'a T`. |
| 97 |
/// |
| 98 |
/// The referent of a shared-aliased `Ptr` may be concurrently referenced by any |
| 99 |
/// number of shared-aliased `Ptr` or `&T` references, or by any number of |
| 100 |
/// `Ptr<U>` or `&U` references as permitted by `T`'s library safety invariants, |
| 101 |
/// and may not be concurrently referenced by any exclusively-aliased `Ptr`s or |
| 102 |
/// `&mut` references. The referent must not be mutated, except via |
| 103 |
/// [`UnsafeCell`]s, and only when permitted by `T`'s library safety invariants. |
| 104 |
/// |
| 105 |
/// [`UnsafeCell`]: core::cell::UnsafeCell |
| 106 |
pub enum Shared {} |
| 107 |
impl Aliasing for Shared { |
| 108 |
const IS_EXCLUSIVE: bool = false; |
| 109 |
} |
| 110 |
impl Reference for Shared {} |
| 111 |
|
| 112 |
/// The `Ptr<'a, T>` adheres to the aliasing rules of a `&'a mut T`. |
| 113 |
/// |
| 114 |
/// The referent of an exclusively-aliased `Ptr` may not be concurrently |
| 115 |
/// referenced by any other `Ptr`s or references, and may not be accessed (read |
| 116 |
/// or written) other than via this `Ptr`. |
| 117 |
pub enum Exclusive {} |
| 118 |
impl Aliasing for Exclusive { |
| 119 |
const IS_EXCLUSIVE: bool = true; |
| 120 |
} |
| 121 |
impl Reference for Exclusive {} |
| 122 |
|
| 123 |
/// It is unknown whether the pointer is aligned. |
| 124 |
pub enum Unaligned {} |
| 125 |
|
| 126 |
impl Alignment for Unaligned {} |
| 127 |
|
| 128 |
/// The referent is aligned: for `Ptr<T>`, the referent's address is a multiple |
| 129 |
/// of the `T`'s alignment. |
| 130 |
pub enum Aligned {} |
| 131 |
impl Alignment for Aligned {} |
| 132 |
|
| 133 |
/// Any bit pattern is allowed in the `Ptr`'s referent, including uninitialized |
| 134 |
/// bytes. |
| 135 |
pub enum Uninit {} |
| 136 |
// SAFETY: `Uninit`'s validity is well-defined for all `T: ?Sized`, and is not a |
| 137 |
// function of any property of `T` other than its bit validity (in fact, it's |
| 138 |
// not even a property of `T`'s bit validity, but this is more than we are |
| 139 |
// required to uphold). |
| 140 |
unsafe impl Validity for Uninit {} |
| 141 |
|
| 142 |
/// The byte ranges initialized in `T` are also initialized in the referent of a |
| 143 |
/// `Ptr<T>`. |
| 144 |
/// |
| 145 |
/// Formally: uninitialized bytes may only be present in `Ptr<T>`'s referent |
| 146 |
/// where they are guaranteed to be present in `T`. This is a dynamic property: |
| 147 |
/// if, at a particular byte offset, a valid enum discriminant is set, the |
| 148 |
/// subsequent bytes may only have uninitialized bytes as specified by the |
| 149 |
/// corresponding enum. |
| 150 |
/// |
| 151 |
/// Formally, given `len = size_of_val_raw(ptr)`, at every byte offset, `b`, in |
| 152 |
/// the range `[0, len)`: |
| 153 |
/// - If, in any instance `t: T` of length `len`, the byte at offset `b` in `t` |
| 154 |
/// is initialized, then the byte at offset `b` within `*ptr` must be |
| 155 |
/// initialized. |
| 156 |
/// - Let `c` be the contents of the byte range `[0, b)` in `*ptr`. Let `S` be |
| 157 |
/// the subset of valid instances of `T` of length `len` which contain `c` in |
| 158 |
/// the offset range `[0, b)`. If, in any instance of `t: T` in `S`, the byte |
| 159 |
/// at offset `b` in `t` is initialized, then the byte at offset `b` in `*ptr` |
| 160 |
/// must be initialized. |
| 161 |
/// |
| 162 |
/// Pragmatically, this means that if `*ptr` is guaranteed to contain an enum |
| 163 |
/// type at a particular offset, and the enum discriminant stored in `*ptr` |
| 164 |
/// corresponds to a valid variant of that enum type, then it is guaranteed |
| 165 |
/// that the appropriate bytes of `*ptr` are initialized as defined by that |
| 166 |
/// variant's bit validity (although note that the variant may contain another |
| 167 |
/// enum type, in which case the same rules apply depending on the state of |
| 168 |
/// its discriminant, and so on recursively). |
| 169 |
pub enum AsInitialized {} |
| 170 |
// SAFETY: `AsInitialized`'s validity is well-defined for all `T: ?Sized`, and |
| 171 |
// is not a function of any property of `T` other than its bit validity. |
| 172 |
unsafe impl Validity for AsInitialized {} |
| 173 |
|
| 174 |
/// The byte ranges in the referent are fully initialized. In other words, if |
| 175 |
/// the referent is `N` bytes long, then it contains a bit-valid `[u8; N]`. |
| 176 |
pub enum Initialized {} |
| 177 |
// SAFETY: `Initialized`'s validity is well-defined for all `T: ?Sized`, and is |
| 178 |
// not a function of any property of `T` other than its bit validity (in fact, |
| 179 |
// it's not even a property of `T`'s bit validity, but this is more than we are |
| 180 |
// required to uphold). |
| 181 |
unsafe impl Validity for Initialized {} |
| 182 |
|
| 183 |
/// The referent of a `Ptr<T>` is valid for `T`, upholding bit validity and any |
| 184 |
/// library safety invariants. |
| 185 |
pub enum Valid {} |
| 186 |
// SAFETY: `Valid`'s validity is well-defined for all `T: ?Sized`, and is not a |
| 187 |
// function of any property of `T` other than its bit validity. |
| 188 |
unsafe impl Validity for Valid {} |
| 189 |
|
| 190 |
/// # Safety |
| 191 |
/// |
| 192 |
/// `DT: CastableFrom<ST, SV, DV>` is sound if `SV = DV = Uninit` or `SV = DV = |
| 193 |
/// Initialized`. |
| 194 |
pub unsafe trait CastableFrom<ST: ?Sized, SV, DV> {} |
| 195 |
|
| 196 |
// SAFETY: `SV = DV = Uninit`. |
| 197 |
unsafe impl<ST: ?Sized, DT: ?Sized> CastableFrom<ST, Uninit, Uninit> for DT {} |
| 198 |
// SAFETY: `SV = DV = Initialized`. |
| 199 |
unsafe impl<ST: ?Sized, DT: ?Sized> CastableFrom<ST, Initialized, Initialized> for DT {} |
| 200 |
|
| 201 |
/// [`Ptr`](crate::Ptr) referents that permit unsynchronized read operations. |
| 202 |
/// |
| 203 |
/// `T: Read<A, R>` implies that a pointer to `T` with aliasing `A` permits |
| 204 |
/// unsynchronized read operations. This can be because `A` is [`Exclusive`] or |
| 205 |
/// because `T` does not permit interior mutation. |
| 206 |
/// |
| 207 |
/// # Safety |
| 208 |
/// |
| 209 |
/// `T: Read<A, R>` if either of the following conditions holds: |
| 210 |
/// - `A` is [`Exclusive`] |
| 211 |
/// - `T` implements [`Immutable`](crate::Immutable) |
| 212 |
/// |
| 213 |
/// As a consequence, if `T: Read<A, R>`, then any `Ptr<T, (A, ...)>` is |
| 214 |
/// permitted to perform unsynchronized reads from its referent. |
| 215 |
pub trait Read<A: Aliasing, R> {} |
| 216 |
|
| 217 |
impl<A: Aliasing, T: ?Sized + crate::Immutable> Read<A, BecauseImmutable> for T {} |
| 218 |
impl<T: ?Sized> Read<Exclusive, BecauseExclusive> for T {} |
| 219 |
|
| 220 |
/// Unsynchronized reads are permitted because only one live [`Ptr`](crate::Ptr) |
| 221 |
/// or reference may exist to the referent bytes at a time. |
| 222 |
#[derive(Copy, Clone, Debug)] |
| 223 |
#[doc(hidden)] |
| 224 |
pub enum BecauseExclusive {} |
| 225 |
|
| 226 |
/// Unsynchronized reads are permitted because no live [`Ptr`](crate::Ptr)s or |
| 227 |
/// references permit interior mutation. |
| 228 |
#[derive(Copy, Clone, Debug)] |
| 229 |
#[doc(hidden)] |
| 230 |
pub enum BecauseImmutable {} |
| 231 |
|
| 232 |
use sealed::Sealed; |
| 233 |
mod sealed { |
| 234 |
use super::*; |
| 235 |
|
| 236 |
pub trait Sealed {} |
| 237 |
|
| 238 |
impl Sealed for Shared {} |
| 239 |
impl Sealed for Exclusive {} |
| 240 |
|
| 241 |
impl Sealed for Unaligned {} |
| 242 |
impl Sealed for Aligned {} |
| 243 |
|
| 244 |
impl Sealed for Uninit {} |
| 245 |
impl Sealed for AsInitialized {} |
| 246 |
impl Sealed for Initialized {} |
| 247 |
impl Sealed for Valid {} |
| 248 |
|
| 249 |
impl<A: Sealed, AA: Sealed, V: Sealed> Sealed for (A, AA, V) {} |
| 250 |
|
| 251 |
impl Sealed for BecauseImmutable {} |
| 252 |
impl Sealed for BecauseExclusive {} |
| 253 |
} |