Debian Codegraph @

.cargo/vendor/zerocopy/src/pointer/invariant.rs

raw
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 }