projects/linux·blob master · refs

1586 lines · 67.3 KiB

1// SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT
2//
3// Copyright 2023 The Fuchsia Authors
4//
5// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
6// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
7// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
8// This file may not be copied, modified, or distributed except according to
9// those terms.
10
11#![allow(missing_docs)]
12
13use core::{
14 fmt::{Debug, Formatter},
15 marker::PhantomData,
16};
17
18use crate::{
19 pointer::{
20 inner::PtrInner,
21 invariant::*,
22 transmute::{MutationCompatible, SizeEq, TransmuteFromPtr},
23 },
24 AlignmentError, CastError, CastType, KnownLayout, SizeError, TryFromBytes, ValidityError,
25};
26
27/// Module used to gate access to [`Ptr`]'s fields.
28mod def {
29 #[cfg(doc)]
30 use super::super::invariant;
31 use super::*;
32
33 /// A raw pointer with more restrictions.
34 ///
35 /// `Ptr<T>` is similar to [`NonNull<T>`], but it is more restrictive in the
36 /// following ways (note that these requirements only hold of non-zero-sized
37 /// referents):
38 /// - It must derive from a valid allocation.
39 /// - It must reference a byte range which is contained inside the
40 /// allocation from which it derives.
41 /// - As a consequence, the byte range it references must have a size
42 /// which does not overflow `isize`.
43 ///
44 /// Depending on how `Ptr` is parameterized, it may have additional
45 /// invariants:
46 /// - `ptr` conforms to the aliasing invariant of
47 /// [`I::Aliasing`](invariant::Aliasing).
48 /// - `ptr` conforms to the alignment invariant of
49 /// [`I::Alignment`](invariant::Alignment).
50 /// - `ptr` conforms to the validity invariant of
51 /// [`I::Validity`](invariant::Validity).
52 ///
53 /// `Ptr<'a, T>` is [covariant] in `'a` and invariant in `T`.
54 ///
55 /// [`NonNull<T>`]: core::ptr::NonNull
56 /// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
57 pub struct Ptr<'a, T, I>
58 where
59 T: ?Sized,
60 I: Invariants,
61 {
62 /// # Invariants
63 ///
64 /// 0. `ptr` conforms to the aliasing invariant of
65 /// [`I::Aliasing`](invariant::Aliasing).
66 /// 1. `ptr` conforms to the alignment invariant of
67 /// [`I::Alignment`](invariant::Alignment).
68 /// 2. `ptr` conforms to the validity invariant of
69 /// [`I::Validity`](invariant::Validity).
70 // SAFETY: `PtrInner<'a, T>` is covariant in `'a` and invariant in `T`.
71 ptr: PtrInner<'a, T>,
72 _invariants: PhantomData<I>,
73 }
74
75 impl<'a, T, I> Ptr<'a, T, I>
76 where
77 T: 'a + ?Sized,
78 I: Invariants,
79 {
80 /// Constructs a new `Ptr` from a [`PtrInner`].
81 ///
82 /// # Safety
83 ///
84 /// The caller promises that:
85 ///
86 /// 0. `ptr` conforms to the aliasing invariant of
87 /// [`I::Aliasing`](invariant::Aliasing).
88 /// 1. `ptr` conforms to the alignment invariant of
89 /// [`I::Alignment`](invariant::Alignment).
90 /// 2. `ptr` conforms to the validity invariant of
91 /// [`I::Validity`](invariant::Validity).
92 pub(crate) unsafe fn from_inner(ptr: PtrInner<'a, T>) -> Ptr<'a, T, I> {
93 // SAFETY: The caller has promised to satisfy all safety invariants
94 // of `Ptr`.
95 Self { ptr, _invariants: PhantomData }
96 }
97
98 /// Converts this `Ptr<T>` to a [`PtrInner<T>`].
99 ///
100 /// Note that this method does not consume `self`. The caller should
101 /// watch out for `unsafe` code which uses the returned value in a way
102 /// that violates the safety invariants of `self`.
103 #[inline]
104 #[must_use]
105 pub fn as_inner(&self) -> PtrInner<'a, T> {
106 self.ptr
107 }
108 }
109}
110
111#[allow(unreachable_pub)] // This is a false positive on our MSRV toolchain.
112pub use def::Ptr;
113
114/// External trait implementations on [`Ptr`].
115mod _external {
116 use super::*;
117
118 /// SAFETY: Shared pointers are safely `Copy`. `Ptr`'s other invariants
119 /// (besides aliasing) are unaffected by the number of references that exist
120 /// to `Ptr`'s referent. The notable cases are:
121 /// - Alignment is a property of the referent type (`T`) and the address,
122 /// both of which are unchanged
123 /// - Let `S(T, V)` be the set of bit values permitted to appear in the
124 /// referent of a `Ptr<T, I: Invariants<Validity = V>>`. Since this copy
125 /// does not change `I::Validity` or `T`, `S(T, I::Validity)` is also
126 /// unchanged.
127 ///
128 /// We are required to guarantee that the referents of the original `Ptr`
129 /// and of the copy (which, of course, are actually the same since they
130 /// live in the same byte address range) both remain in the set `S(T,
131 /// I::Validity)`. Since this invariant holds on the original `Ptr`, it
132 /// cannot be violated by the original `Ptr`, and thus the original `Ptr`
133 /// cannot be used to violate this invariant on the copy. The inverse
134 /// holds as well.
135 impl<'a, T, I> Copy for Ptr<'a, T, I>
136 where
137 T: 'a + ?Sized,
138 I: Invariants<Aliasing = Shared>,
139 {
140 }
141
142 /// SAFETY: See the safety comment on `Copy`.
143 impl<'a, T, I> Clone for Ptr<'a, T, I>
144 where
145 T: 'a + ?Sized,
146 I: Invariants<Aliasing = Shared>,
147 {
148 #[inline]
149 fn clone(&self) -> Self {
150 *self
151 }
152 }
153
154 impl<'a, T, I> Debug for Ptr<'a, T, I>
155 where
156 T: 'a + ?Sized,
157 I: Invariants,
158 {
159 #[inline]
160 fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
161 self.as_inner().as_non_null().fmt(f)
162 }
163 }
164}
165
166/// Methods for converting to and from `Ptr` and Rust's safe reference types.
167mod _conversions {
168 use super::*;
169 use crate::pointer::cast::{CastExact, CastSized, IdCast};
170
171 /// `&'a T` → `Ptr<'a, T>`
172 impl<'a, T> Ptr<'a, T, (Shared, Aligned, Valid)>
173 where
174 T: 'a + ?Sized,
175 {
176 /// Constructs a `Ptr` from a shared reference.
177 #[inline(always)]
178 pub fn from_ref(ptr: &'a T) -> Self {
179 let inner = PtrInner::from_ref(ptr);
180 // SAFETY:
181 // 0. `ptr`, by invariant on `&'a T`, conforms to the aliasing
182 // invariant of `Shared`.
183 // 1. `ptr`, by invariant on `&'a T`, conforms to the alignment
184 // invariant of `Aligned`.
185 // 2. `ptr`'s referent, by invariant on `&'a T`, is a bit-valid `T`.
186 // This satisfies the requirement that a `Ptr<T, (_, _, Valid)>`
187 // point to a bit-valid `T`. Even if `T` permits interior
188 // mutation, this invariant guarantees that the returned `Ptr`
189 // can only ever be used to modify the referent to store
190 // bit-valid `T`s, which ensures that the returned `Ptr` cannot
191 // be used to violate the soundness of the original `ptr: &'a T`
192 // or of any other references that may exist to the same
193 // referent.
194 unsafe { Self::from_inner(inner) }
195 }
196 }
197
198 /// `&'a mut T` → `Ptr<'a, T>`
199 impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)>
200 where
201 T: 'a + ?Sized,
202 {
203 /// Constructs a `Ptr` from an exclusive reference.
204 #[inline(always)]
205 pub fn from_mut(ptr: &'a mut T) -> Self {
206 let inner = PtrInner::from_mut(ptr);
207 // SAFETY:
208 // 0. `ptr`, by invariant on `&'a mut T`, conforms to the aliasing
209 // invariant of `Exclusive`.
210 // 1. `ptr`, by invariant on `&'a mut T`, conforms to the alignment
211 // invariant of `Aligned`.
212 // 2. `ptr`'s referent, by invariant on `&'a mut T`, is a bit-valid
213 // `T`. This satisfies the requirement that a `Ptr<T, (_, _,
214 // Valid)>` point to a bit-valid `T`. This invariant guarantees
215 // that the returned `Ptr` can only ever be used to modify the
216 // referent to store bit-valid `T`s, which ensures that the
217 // returned `Ptr` cannot be used to violate the soundness of the
218 // original `ptr: &'a mut T`.
219 unsafe { Self::from_inner(inner) }
220 }
221 }
222
223 /// `Ptr<'a, T>` → `&'a T`
224 impl<'a, T, I> Ptr<'a, T, I>
225 where
226 T: 'a + ?Sized,
227 I: Invariants<Alignment = Aligned, Validity = Valid>,
228 I::Aliasing: Reference,
229 {
230 /// Converts `self` to a shared reference.
231 // This consumes `self`, not `&self`, because `self` is, logically, a
232 // pointer. For `I::Aliasing = invariant::Shared`, `Self: Copy`, and so
233 // this doesn't prevent the caller from still using the pointer after
234 // calling `as_ref`.
235 #[allow(clippy::wrong_self_convention)]
236 #[inline]
237 #[must_use]
238 pub fn as_ref(self) -> &'a T {
239 let raw = self.as_inner().as_non_null();
240 // SAFETY: `self` satisfies the `Aligned` invariant, so we know that
241 // `raw` is validly-aligned for `T`.
242 #[cfg(miri)]
243 unsafe {
244 crate::util::miri_promise_symbolic_alignment(
245 raw.as_ptr().cast(),
246 core::mem::align_of_val_raw(raw.as_ptr()),
247 );
248 }
249 // SAFETY: This invocation of `NonNull::as_ref` satisfies its
250 // documented safety preconditions:
251 //
252 // 1. The pointer is properly aligned. This is ensured by-contract
253 // on `Ptr`, because the `I::Alignment` is `Aligned`.
254 //
255 // 2. If the pointer's referent is not zero-sized, then the pointer
256 // must be “dereferenceable” in the sense defined in the module
257 // documentation; i.e.:
258 //
259 // > The memory range of the given size starting at the pointer
260 // > must all be within the bounds of a single allocated object.
261 // > [2]
262 //
263 // This is ensured by contract on all `PtrInner`s.
264 //
265 // 3. The pointer must point to a validly-initialized instance of
266 // `T`. This is ensured by-contract on `Ptr`, because the
267 // `I::Validity` is `Valid`.
268 //
269 // 4. You must enforce Rust’s aliasing rules. This is ensured by
270 // contract on `Ptr`, because `I::Aliasing: Reference`. Either it
271 // is `Shared` or `Exclusive`. If it is `Shared`, other
272 // references may not mutate the referent outside of
273 // `UnsafeCell`s.
274 //
275 // [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_ref
276 // [2]: https://doc.rust-lang.org/std/ptr/index.html#safety
277 unsafe { raw.as_ref() }
278 }
279 }
280
281 impl<'a, T, I> Ptr<'a, T, I>
282 where
283 T: 'a + ?Sized,
284 I: Invariants,
285 I::Aliasing: Reference,
286 {
287 /// Reborrows `self`, producing another `Ptr`.
288 ///
289 /// Since `self` is borrowed mutably, this prevents any methods from
290 /// being called on `self` as long as the returned `Ptr` exists.
291 #[inline]
292 #[must_use]
293 #[allow(clippy::needless_lifetimes)] // Allows us to name the lifetime in the safety comment below.
294 pub fn reborrow<'b>(&'b mut self) -> Ptr<'b, T, I>
295 where
296 'a: 'b,
297 {
298 // SAFETY: The following all hold by invariant on `self`, and thus
299 // hold of `ptr = self.as_inner()`:
300 // 0. SEE BELOW.
301 // 1. `ptr` conforms to the alignment invariant of
302 // [`I::Alignment`](invariant::Alignment).
303 // 2. `ptr` conforms to the validity invariant of
304 // [`I::Validity`](invariant::Validity). `self` and the returned
305 // `Ptr` permit the same bit values in their referents since they
306 // have the same referent type (`T`) and the same validity
307 // (`I::Validity`). Thus, regardless of what mutation is
308 // permitted (`Exclusive` aliasing or `Shared`-aliased interior
309 // mutation), neither can be used to write a value to the
310 // referent which violates the other's validity invariant.
311 //
312 // For aliasing (0 above), since `I::Aliasing: Reference`,
313 // there are two cases for `I::Aliasing`:
314 // - For `invariant::Shared`: `'a` outlives `'b`, and so the
315 // returned `Ptr` does not permit accessing the referent any
316 // longer than is possible via `self`. For shared aliasing, it is
317 // sound for multiple `Ptr`s to exist simultaneously which
318 // reference the same memory, so creating a new one is not
319 // problematic.
320 // - For `invariant::Exclusive`: Since `self` is `&'b mut` and we
321 // return a `Ptr` with lifetime `'b`, `self` is inaccessible to
322 // the caller for the lifetime `'b` - in other words, `self` is
323 // inaccessible to the caller as long as the returned `Ptr`
324 // exists. Since `self` is an exclusive `Ptr`, no other live
325 // references or `Ptr`s may exist which refer to the same memory
326 // while `self` is live. Thus, as long as the returned `Ptr`
327 // exists, no other references or `Ptr`s which refer to the same
328 // memory may be live.
329 unsafe { Ptr::from_inner(self.as_inner()) }
330 }
331
332 /// Reborrows `self` as shared, producing another `Ptr` with `Shared`
333 /// aliasing.
334 ///
335 /// Since `self` is borrowed mutably, this prevents any methods from
336 /// being called on `self` as long as the returned `Ptr` exists.
337 #[inline]
338 #[must_use]
339 #[allow(clippy::needless_lifetimes)] // Allows us to name the lifetime in the safety comment below.
340 pub fn reborrow_shared<'b>(&'b mut self) -> Ptr<'b, T, (Shared, I::Alignment, I::Validity)>
341 where
342 'a: 'b,
343 {
344 // SAFETY: The following all hold by invariant on `self`, and thus
345 // hold of `ptr = self.as_inner()`:
346 // 0. SEE BELOW.
347 // 1. `ptr` conforms to the alignment invariant of
348 // [`I::Alignment`](invariant::Alignment).
349 // 2. `ptr` conforms to the validity invariant of
350 // [`I::Validity`](invariant::Validity). `self` and the returned
351 // `Ptr` permit the same bit values in their referents since they
352 // have the same referent type (`T`) and the same validity
353 // (`I::Validity`). Thus, regardless of what mutation is
354 // permitted (`Exclusive` aliasing or `Shared`-aliased interior
355 // mutation), neither can be used to write a value to the
356 // referent which violates the other's validity invariant.
357 //
358 // For aliasing (0 above), since `I::Aliasing: Reference`,
359 // there are two cases for `I::Aliasing`:
360 // - For `invariant::Shared`: `'a` outlives `'b`, and so the
361 // returned `Ptr` does not permit accessing the referent any
362 // longer than is possible via `self`. For shared aliasing, it is
363 // sound for multiple `Ptr`s to exist simultaneously which
364 // reference the same memory, so creating a new one is not
365 // problematic.
366 // - For `invariant::Exclusive`: Since `self` is `&'b mut` and we
367 // return a `Ptr` with lifetime `'b`, `self` is inaccessible to
368 // the caller for the lifetime `'b` - in other words, `self` is
369 // inaccessible to the caller as long as the returned `Ptr`
370 // exists. Since `self` is an exclusive `Ptr`, no other live
371 // references or `Ptr`s may exist which refer to the same memory
372 // while `self` is live. Thus, as long as the returned `Ptr`
373 // exists, no other references or `Ptr`s which refer to the same
374 // memory may be live.
375 unsafe { Ptr::from_inner(self.as_inner()) }
376 }
377 }
378
379 /// `Ptr<'a, T>` → `&'a mut T`
380 impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)>
381 where
382 T: 'a + ?Sized,
383 {
384 /// Converts `self` to a mutable reference.
385 #[allow(clippy::wrong_self_convention)]
386 #[inline]
387 #[must_use]
388 pub fn as_mut(self) -> &'a mut T {
389 let mut raw = self.as_inner().as_non_null();
390 // SAFETY: `self` satisfies the `Aligned` invariant, so we know that
391 // `raw` is validly-aligned for `T`.
392 #[cfg(miri)]
393 unsafe {
394 crate::util::miri_promise_symbolic_alignment(
395 raw.as_ptr().cast(),
396 core::mem::align_of_val_raw(raw.as_ptr()),
397 );
398 }
399 // SAFETY: This invocation of `NonNull::as_mut` satisfies its
400 // documented safety preconditions:
401 //
402 // 1. The pointer is properly aligned. This is ensured by-contract
403 // on `Ptr`, because the `ALIGNMENT_INVARIANT` is `Aligned`.
404 //
405 // 2. If the pointer's referent is not zero-sized, then the pointer
406 // must be “dereferenceable” in the sense defined in the module
407 // documentation; i.e.:
408 //
409 // > The memory range of the given size starting at the pointer
410 // > must all be within the bounds of a single allocated object.
411 // > [2]
412 //
413 // This is ensured by contract on all `PtrInner`s.
414 //
415 // 3. The pointer must point to a validly-initialized instance of
416 // `T`. This is ensured by-contract on `Ptr`, because the
417 // validity invariant is `Valid`.
418 //
419 // 4. You must enforce Rust’s aliasing rules. This is ensured by
420 // contract on `Ptr`, because the `ALIASING_INVARIANT` is
421 // `Exclusive`.
422 //
423 // [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_mut
424 // [2]: https://doc.rust-lang.org/std/ptr/index.html#safety
425 unsafe { raw.as_mut() }
426 }
427 }
428
429 /// `Ptr<'a, T>` → `Ptr<'a, U>`
430 impl<'a, T: ?Sized, I> Ptr<'a, T, I>
431 where
432 I: Invariants,
433 {
434 #[must_use]
435 #[inline(always)]
436 pub fn transmute<U, V, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)>
437 where
438 V: Validity,
439 U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, <U as SizeEq<T>>::CastFrom, R>
440 + SizeEq<T>
441 + ?Sized,
442 {
443 self.transmute_with::<U, V, <U as SizeEq<T>>::CastFrom, R>()
444 }
445
446 #[inline]
447 #[must_use]
448 pub fn transmute_with<U, V, C, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)>
449 where
450 V: Validity,
451 U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, C, R> + ?Sized,
452 C: CastExact<T, U>,
453 {
454 // SAFETY:
455 // - By `C: CastExact`, `C` preserves referent address, and so we
456 // don't need to consider projections in the following safety
457 // arguments.
458 // - If aliasing is `Shared`, then by `U: TransmuteFromPtr<T>`, at
459 // least one of the following holds:
460 // - `T: Immutable` and `U: Immutable`, in which case it is
461 // trivially sound for shared code to operate on a `&T` and `&U`
462 // at the same time, as neither can perform interior mutation
463 // - It is directly guaranteed that it is sound for shared code to
464 // operate on these references simultaneously
465 // - By `U: TransmuteFromPtr<T, I::Aliasing, I::Validity, C, V>`, it
466 // is sound to perform this transmute using `C`.
467 unsafe { self.project_transmute_unchecked::<_, _, C>() }
468 }
469
470 #[inline]
471 #[must_use]
472 pub fn recall_validity<V, R>(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)>
473 where
474 V: Validity,
475 T: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, IdCast, R>,
476 {
477 let ptr = self.transmute_with::<T, V, IdCast, R>();
478 // SAFETY: `self` and `ptr` have the same address and referent type.
479 // Therefore, if `self` satisfies `I::Alignment`, then so does
480 // `ptr`.
481 unsafe { ptr.assume_alignment::<I::Alignment>() }
482 }
483
484 /// Projects and/or transmutes to a different (unsized) referent type
485 /// without checking interior mutability.
486 ///
487 /// Callers should prefer [`cast`] or [`project`] where possible.
488 ///
489 /// [`cast`]: Ptr::cast
490 /// [`project`]: Ptr::project
491 ///
492 /// # Safety
493 ///
494 /// The caller promises that:
495 /// - If `I::Aliasing` is [`Shared`], it must not be possible for safe
496 /// code, operating on a `&T` and `&U`, with the referents of `self`
497 /// and `self.project_transmute_unchecked()`, respectively, to cause
498 /// undefined behavior.
499 /// - It is sound to project and/or transmute a pointer of type `T` with
500 /// aliasing `I::Aliasing` and validity `I::Validity` to a pointer of
501 /// type `U` with aliasing `I::Aliasing` and validity `V`. This is a
502 /// subtle soundness requirement that is a function of `T`, `U`,
503 /// `I::Aliasing`, `I::Validity`, and `V`, and may depend upon the
504 /// presence, absence, or specific location of `UnsafeCell`s in `T`
505 /// and/or `U`, and on whether interior mutation is ever permitted via
506 /// those `UnsafeCell`s. See [`Validity`] for more details.
507 #[inline]
508 #[must_use]
509 pub unsafe fn project_transmute_unchecked<U: ?Sized, V, P>(
510 self,
511 ) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)>
512 where
513 V: Validity,
514 P: crate::pointer::cast::Project<T, U>,
515 {
516 let ptr = self.as_inner().project::<_, P>();
517
518 // SAFETY:
519 //
520 // The following safety arguments rely on the fact that `P: Project`
521 // guarantees that `P` is a referent-preserving or -shrinking
522 // projection. Thus, `ptr` addresses a subset of the bytes of
523 // `*self`, and so certain properties that hold of `*self` also hold
524 // of `*ptr`.
525 //
526 // 0. `ptr` conforms to the aliasing invariant of `I::Aliasing`:
527 // - `Exclusive`: `self` is the only `Ptr` or reference which is
528 // permitted to read or modify the referent for the lifetime
529 // `'a`. Since we consume `self` by value, the returned pointer
530 // remains the only `Ptr` or reference which is permitted to
531 // read or modify the referent for the lifetime `'a`.
532 // - `Shared`: Since `self` has aliasing `Shared`, we know that
533 // no other code may mutate the referent during the lifetime
534 // `'a`, except via `UnsafeCell`s, and except as permitted by
535 // `T`'s library safety invariants. The caller promises that
536 // any safe operations which can be permitted on a `&T` and a
537 // `&U` simultaneously must be sound. Thus, no operations on a
538 // `&U` could violate `&T`'s library safety invariants, and
539 // vice-versa. Since any mutation via shared references outside
540 // of `UnsafeCell`s is unsound, this must be impossible using
541 // `&T` and `&U`.
542 // - `Inaccessible`: There are no restrictions we need to uphold.
543 // 1. `ptr` trivially satisfies the alignment invariant `Unaligned`.
544 // 2. The caller promises that the returned pointer satisfies the
545 // validity invariant `V` with respect to its referent type, `U`.
546 unsafe { Ptr::from_inner(ptr) }
547 }
548 }
549
550 /// `Ptr<'a, T, (_, _, _)>` → `Ptr<'a, Unalign<T>, (_, Aligned, _)>`
551 impl<'a, T, I> Ptr<'a, T, I>
552 where
553 I: Invariants,
554 {
555 /// Converts a `Ptr` an unaligned `T` into a `Ptr` to an aligned
556 /// `Unalign<T>`.
557 #[inline]
558 #[must_use]
559 pub fn into_unalign(
560 self,
561 ) -> Ptr<'a, crate::Unalign<T>, (I::Aliasing, Aligned, I::Validity)> {
562 // FIXME(#1359): This should be a `transmute_with` call.
563 // Unfortunately, to avoid blanket impl conflicts, we only implement
564 // `TransmuteFrom<T>` for `Unalign<T>` (and vice versa) specifically
565 // for `Valid` validity, not for all validity types.
566
567 // SAFETY:
568 // - By `CastSized: Cast`, `CastSized` preserves referent address,
569 // and so we don't need to consider projections in the following
570 // safety arguments.
571 // - Since `Unalign<T>` has the same layout as `T`, the returned
572 // pointer refers to `UnsafeCell`s at the same locations as
573 // `self`.
574 // - `Unalign<T>` promises to have the same bit validity as `T`. By
575 // invariant on `Validity`, the set of bit patterns allowed in the
576 // referent of a `Ptr<X, (_, _, V)>` is only a function of the
577 // validity of `X` and of `V`. Thus, the set of bit patterns
578 // allowed in the referent of a `Ptr<T, (_, _, I::Validity)>` is
579 // the same as the set of bit patterns allowed in the referent of
580 // a `Ptr<Unalign<T>, (_, _, I::Validity)>`. As a result, `self`
581 // and the returned `Ptr` permit the same set of bit patterns in
582 // their referents, and so neither can be used to violate the
583 // validity of the other.
584 let ptr = unsafe { self.project_transmute_unchecked::<_, _, CastSized>() };
585 ptr.bikeshed_recall_aligned()
586 }
587 }
588
589 impl<'a, T, I> Ptr<'a, T, I>
590 where
591 T: ?Sized,
592 I: Invariants<Validity = Valid>,
593 I::Aliasing: Reference,
594 {
595 /// Reads the referent.
596 #[must_use]
597 #[inline(always)]
598 pub fn read<R>(self) -> T
599 where
600 T: Copy,
601 T: Read<I::Aliasing, R>,
602 {
603 <I::Alignment as Alignment>::read(self)
604 }
605
606 /// Views the value as an aligned reference.
607 ///
608 /// This is only available if `T` is [`Unaligned`].
609 #[must_use]
610 #[inline]
611 pub fn unaligned_as_ref(self) -> &'a T
612 where
613 T: crate::Unaligned,
614 {
615 self.bikeshed_recall_aligned().as_ref()
616 }
617 }
618}
619
620/// State transitions between invariants.
621mod _transitions {
622 use super::*;
623 use crate::{
624 pointer::{cast::IdCast, transmute::TryTransmuteFromPtr},
625 ReadOnly,
626 };
627
628 impl<'a, T, I> Ptr<'a, T, I>
629 where
630 T: 'a + ?Sized,
631 I: Invariants,
632 {
633 /// Assumes that `self` satisfies the invariants `H`.
634 ///
635 /// # Safety
636 ///
637 /// The caller promises that `self` satisfies the invariants `H`.
638 unsafe fn assume_invariants<H: Invariants>(self) -> Ptr<'a, T, H> {
639 // SAFETY: The caller has promised to satisfy all parameterized
640 // invariants of `Ptr`. `Ptr`'s other invariants are satisfied
641 // by-contract by the source `Ptr`.
642 unsafe { Ptr::from_inner(self.as_inner()) }
643 }
644
645 /// Helps the type system unify two distinct invariant types which are
646 /// actually the same.
647 #[inline]
648 #[must_use]
649 pub fn unify_invariants<
650 H: Invariants<Aliasing = I::Aliasing, Alignment = I::Alignment, Validity = I::Validity>,
651 >(
652 self,
653 ) -> Ptr<'a, T, H> {
654 // SAFETY: The associated type bounds on `H` ensure that the
655 // invariants are unchanged.
656 unsafe { self.assume_invariants::<H>() }
657 }
658
659 /// Assumes that `self`'s referent is validly-aligned for `T` if
660 /// required by `A`.
661 ///
662 /// # Safety
663 ///
664 /// The caller promises that `self`'s referent conforms to the alignment
665 /// invariant of `T` if required by `A`.
666 #[inline]
667 pub(crate) unsafe fn assume_alignment<A: Alignment>(
668 self,
669 ) -> Ptr<'a, T, (I::Aliasing, A, I::Validity)> {
670 // SAFETY: The caller promises that `self`'s referent is
671 // well-aligned for `T` if required by `A` .
672 unsafe { self.assume_invariants() }
673 }
674
675 /// Checks the `self`'s alignment at runtime, returning an aligned `Ptr`
676 /// on success.
677 #[inline]
678 pub fn try_into_aligned(
679 self,
680 ) -> Result<Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)>, AlignmentError<Self, T>>
681 where
682 T: Sized,
683 {
684 if let Err(err) =
685 crate::util::validate_aligned_to::<_, T>(self.as_inner().as_non_null())
686 {
687 return Err(err.with_src(self));
688 }
689
690 // SAFETY: We just checked the alignment.
691 Ok(unsafe { self.assume_alignment::<Aligned>() })
692 }
693
694 /// Recalls that `self`'s referent is validly-aligned for `T`.
695 #[inline]
696 // FIXME(#859): Reconsider the name of this method before making it
697 // public.
698 #[must_use]
699 pub fn bikeshed_recall_aligned(self) -> Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)>
700 where
701 T: crate::Unaligned,
702 {
703 // SAFETY: The bound `T: Unaligned` ensures that `T` has no
704 // non-trivial alignment requirement.
705 unsafe { self.assume_alignment::<Aligned>() }
706 }
707
708 /// Assumes that `self`'s referent conforms to the validity requirement
709 /// of `V`.
710 ///
711 /// # Safety
712 ///
713 /// The caller promises that `self`'s referent conforms to the validity
714 /// requirement of `V`.
715 #[must_use]
716 #[inline]
717 pub unsafe fn assume_validity<V: Validity>(
718 self,
719 ) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)> {
720 // SAFETY: The caller promises that `self`'s referent conforms to
721 // the validity requirement of `V`.
722 unsafe { self.assume_invariants() }
723 }
724
725 /// A shorthand for `self.assume_validity<invariant::Initialized>()`.
726 ///
727 /// # Safety
728 ///
729 /// The caller promises to uphold the safety preconditions of
730 /// `self.assume_validity<invariant::Initialized>()`.
731 #[must_use]
732 #[inline]
733 pub unsafe fn assume_initialized(
734 self,
735 ) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Initialized)> {
736 // SAFETY: The caller has promised to uphold the safety
737 // preconditions.
738 unsafe { self.assume_validity::<Initialized>() }
739 }
740
741 /// A shorthand for `self.assume_validity<Valid>()`.
742 ///
743 /// # Safety
744 ///
745 /// The caller promises to uphold the safety preconditions of
746 /// `self.assume_validity<Valid>()`.
747 #[must_use]
748 #[inline]
749 pub unsafe fn assume_valid(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)> {
750 // SAFETY: The caller has promised to uphold the safety
751 // preconditions.
752 unsafe { self.assume_validity::<Valid>() }
753 }
754
755 /// Checks that `self`'s referent is validly initialized for `T`,
756 /// returning a `Ptr` with `Valid` on success.
757 ///
758 /// # Panics
759 ///
760 /// This method will panic if
761 /// [`T::is_bit_valid`][TryFromBytes::is_bit_valid] panics.
762 ///
763 /// # Safety
764 ///
765 /// On error, unsafe code may rely on this method's returned
766 /// `ValidityError` containing `self`.
767 #[inline]
768 pub fn try_into_valid<R, S>(
769 mut self,
770 ) -> Result<Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)>, ValidityError<Self, T>>
771 where
772 T: TryFromBytes
773 + Read<I::Aliasing, R>
774 + TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid, IdCast, S>,
775 ReadOnly<T>: Read<I::Aliasing, R>,
776 I::Aliasing: Reference,
777 I: Invariants<Validity = Initialized>,
778 {
779 // This call may panic. If that happens, it doesn't cause any
780 // soundness issues, as we have not generated any invalid state
781 // which we need to fix before returning.
782 if T::is_bit_valid(self.reborrow().transmute::<_, _, _>().reborrow_shared()) {
783 // SAFETY: If `T::is_bit_valid`, code may assume that `self`
784 // contains a bit-valid instance of `T`. By `T:
785 // TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid>`, so
786 // long as `self`'s referent conforms to the `Valid` validity
787 // for `T` (which we just confirmed), then this transmute is
788 // sound.
789 Ok(unsafe { self.assume_valid() })
790 } else {
791 Err(ValidityError::new(self))
792 }
793 }
794
795 /// Forgets that `self`'s referent is validly-aligned for `T`.
796 #[inline]
797 #[must_use]
798 pub fn forget_aligned(self) -> Ptr<'a, T, (I::Aliasing, Unaligned, I::Validity)> {
799 // SAFETY: `Unaligned` is less restrictive than `Aligned`.
800 unsafe { self.assume_invariants() }
801 }
802 }
803}
804
805/// Casts of the referent type.
806#[cfg_attr(not(zerocopy_unstable_ptr), allow(unreachable_pub))]
807pub use _casts::TryWithError;
808mod _casts {
809 use core::cell::UnsafeCell;
810
811 use super::*;
812 use crate::{
813 pointer::cast::{AsBytesCast, Cast},
814 HasTag, ProjectField,
815 };
816
817 impl<'a, T, I> Ptr<'a, T, I>
818 where
819 T: 'a + ?Sized,
820 I: Invariants,
821 {
822 /// Casts to a different referent type without checking interior
823 /// mutability.
824 ///
825 /// Callers should prefer [`cast`][Ptr::cast] where possible.
826 ///
827 /// # Safety
828 ///
829 /// If `I::Aliasing` is [`Shared`], it must not be possible for safe
830 /// code, operating on a `&T` and `&U` with the same referent
831 /// simultaneously, to cause undefined behavior.
832 #[inline]
833 #[must_use]
834 pub unsafe fn cast_unchecked<U, C: Cast<T, U>>(
835 self,
836 ) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)>
837 where
838 U: 'a + CastableFrom<T, I::Validity, I::Validity> + ?Sized,
839 {
840 // SAFETY:
841 // - By `C: Cast`, `C` preserves the address of the referent.
842 // - If `I::Aliasing` is [`Shared`], the caller promises that it
843 // is not possible for safe code, operating on a `&T` and `&U`
844 // with the same referent simultaneously, to cause undefined
845 // behavior.
846 // - By `U: CastableFrom<T, I::Validity, I::Validity>`,
847 // `I::Validity` is either `Uninit` or `Initialized`. In both
848 // cases, the bit validity `I::Validity` has the same semantics
849 // regardless of referent type. In other words, the set of allowed
850 // referent values for `Ptr<T, (_, _, I::Validity)>` and `Ptr<U,
851 // (_, _, I::Validity)>` are identical. As a consequence, neither
852 // `self` nor the returned `Ptr` can be used to write values which
853 // are invalid for the other.
854 unsafe { self.project_transmute_unchecked::<_, _, C>() }
855 }
856
857 /// Casts to a different referent type.
858 #[inline]
859 #[must_use]
860 pub fn cast<U, C, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)>
861 where
862 T: MutationCompatible<U, I::Aliasing, I::Validity, I::Validity, R>,
863 U: 'a + ?Sized + CastableFrom<T, I::Validity, I::Validity>,
864 C: Cast<T, U>,
865 {
866 // SAFETY: Because `T: MutationCompatible<U, I::Aliasing, R>`, one
867 // of the following holds:
868 // - `T: Read<I::Aliasing>` and `U: Read<I::Aliasing>`, in which
869 // case one of the following holds:
870 // - `I::Aliasing` is `Exclusive`
871 // - `T` and `U` are both `Immutable`
872 // - It is sound for safe code to operate on `&T` and `&U` with the
873 // same referent simultaneously.
874 unsafe { self.cast_unchecked::<_, C>() }
875 }
876
877 #[inline(always)]
878 pub fn project<F, const VARIANT_ID: i128, const FIELD_ID: i128>(
879 mut self,
880 ) -> Result<Ptr<'a, T::Type, T::Invariants>, T::Error>
881 where
882 T: ProjectField<F, I, VARIANT_ID, FIELD_ID>,
883 I::Aliasing: Reference,
884 {
885 use crate::pointer::cast::Projection;
886 match T::is_projectable(self.reborrow().project_tag()) {
887 Ok(()) => {
888 let inner = self.as_inner();
889 let projected = inner.project::<_, Projection<F, VARIANT_ID, FIELD_ID>>();
890 // SAFETY: By `T: ProjectField<F, I, VARIANT_ID, FIELD_ID>`,
891 // for `self: Ptr<'_, T, I>` such that `T::is_projectable`
892 // (which we've verified in this match arm),
893 // `T::project(self.as_inner())` conforms to
894 // `T::Invariants`. The `projected` pointer satisfies these
895 // invariants because it is produced by way of an
896 // abstraction that is equivalent to
897 // `T::project(ptr.as_inner())`: by invariant on
898 // `PtrInner::project`, `projected` is guaranteed to address
899 // the subset of the bytes of `inner`'s referent addressed
900 // by `Projection::project(inner)`, and by invariant on
901 // `Projection`, `Projection::project` is implemented by
902 // delegating to an implementation of `HasField::project`.
903 Ok(unsafe { Ptr::from_inner(projected) })
904 }
905 Err(err) => Err(err),
906 }
907 }
908
909 #[must_use]
910 #[inline(always)]
911 pub(crate) fn project_tag(self) -> Ptr<'a, T::Tag, I>
912 where
913 T: HasTag,
914 {
915 // SAFETY: By invariant on `Self::ProjectToTag`, this is a sound
916 // projection.
917 let tag = unsafe { self.project_transmute_unchecked::<_, _, T::ProjectToTag>() };
918 // SAFETY: By invariant on `Self::ProjectToTag`, the projected
919 // pointer has the same alignment as `ptr`.
920 let tag = unsafe { tag.assume_alignment() };
921 tag.unify_invariants()
922 }
923
924 /// Attempts to transform the pointer, restoring the original on
925 /// failure.
926 ///
927 /// # Safety
928 ///
929 /// If `I::Aliasing != Shared`, then if `f` returns `Err(err)`, no copy
930 /// of `f`'s argument must exist outside of `err`.
931 #[inline(always)]
932 pub(crate) unsafe fn try_with_unchecked<U, J, E, F>(
933 self,
934 f: F,
935 ) -> Result<Ptr<'a, U, J>, E::Mapped>
936 where
937 U: 'a + ?Sized,
938 J: Invariants<Aliasing = I::Aliasing>,
939 E: TryWithError<Self>,
940 F: FnOnce(Ptr<'a, T, I>) -> Result<Ptr<'a, U, J>, E>,
941 {
942 let old_inner = self.as_inner();
943 #[rustfmt::skip]
944 let res = f(self).map_err(#[inline(always)] move |err: E| {
945 err.map(#[inline(always)] |src| {
946 drop(src);
947
948 // SAFETY:
949 // 0. Aliasing is either `Shared` or `Exclusive`:
950 // - If aliasing is `Shared`, then it cannot violate
951 // aliasing make another copy of this pointer (in fact,
952 // using `I::Aliasing = Shared`, we could have just
953 // cloned `self`).
954 // - If aliasing is `Exclusive`, then `f` is not allowed
955 // to make another copy of `self`. In `map_err`, we are
956 // consuming the only value in the returned `Result`.
957 // By invariant on `E: TryWithError<Self>`, that `err:
958 // E` only contains a single `Self` and no other
959 // non-ZST fields which could be `Ptr`s or references
960 // to `self`'s referent. By the same invariant, `map`
961 // consumes this single `Self` and passes it to this
962 // closure. Since `self` was, by invariant on
963 // `Exclusive`, the only `Ptr` or reference live for
964 // `'a` with this referent, and since we `drop(src)`
965 // above, there are no copies left, and so we are
966 // creating the only copy.
967 // 1. `self` conforms to `I::Aliasing` by invariant on
968 // `Ptr`, and `old_inner` has the same address, so it
969 // does too.
970 // 2. `f` could not have violated `self`'s validity without
971 // itself being unsound. Assuming that `f` is sound, the
972 // referent of `self` is still valid for `T`.
973 unsafe { Ptr::from_inner(old_inner) }
974 })
975 });
976 res
977 }
978
979 /// Attempts to transform the pointer, restoring the original on
980 /// failure.
981 #[inline(always)]
982 pub fn try_with<U, J, E, F>(self, f: F) -> Result<Ptr<'a, U, J>, E::Mapped>
983 where
984 U: 'a + ?Sized,
985 J: Invariants<Aliasing = I::Aliasing>,
986 E: TryWithError<Self>,
987 F: FnOnce(Ptr<'a, T, I>) -> Result<Ptr<'a, U, J>, E>,
988 I: Invariants<Aliasing = Shared>,
989 {
990 // SAFETY: `I::Aliasing = Shared`, so the safety condition does not
991 // apply.
992 unsafe { self.try_with_unchecked(f) }
993 }
994 }
995
996 /// # Safety
997 ///
998 /// `Self` only contains a single `Self::Inner`, and `Self::Mapped` only
999 /// contains a single `MappedInner`. Other than that, `Self` and
1000 /// `Self::Mapped` contain no non-ZST fields.
1001 ///
1002 /// `map` must pass ownership of `self`'s sole `Self::Inner` to `f`.
1003 pub unsafe trait TryWithError<MappedInner> {
1004 type Inner;
1005 type Mapped;
1006 fn map<F: FnOnce(Self::Inner) -> MappedInner>(self, f: F) -> Self::Mapped;
1007 }
1008
1009 impl<'a, T, I> Ptr<'a, T, I>
1010 where
1011 T: 'a + KnownLayout + ?Sized,
1012 I: Invariants,
1013 {
1014 /// Casts this pointer-to-initialized into a pointer-to-bytes.
1015 #[allow(clippy::wrong_self_convention)]
1016 #[must_use]
1017 #[inline]
1018 pub fn as_bytes<R>(self) -> Ptr<'a, [u8], (I::Aliasing, Aligned, Valid)>
1019 where
1020 [u8]: TransmuteFromPtr<T, I::Aliasing, I::Validity, Valid, AsBytesCast, R>,
1021 {
1022 self.transmute_with::<[u8], Valid, AsBytesCast, _>().bikeshed_recall_aligned()
1023 }
1024 }
1025
1026 impl<'a, T, I, const N: usize> Ptr<'a, [T; N], I>
1027 where
1028 T: 'a,
1029 I: Invariants,
1030 {
1031 /// Casts this pointer-to-array into a slice.
1032 #[allow(clippy::wrong_self_convention)]
1033 #[inline]
1034 #[must_use]
1035 pub fn as_slice(self) -> Ptr<'a, [T], I> {
1036 let slice = self.as_inner().as_slice();
1037 // SAFETY: Note that, by post-condition on `PtrInner::as_slice`,
1038 // `slice` refers to the same byte range as `self.as_inner()`.
1039 //
1040 // 0. Thus, `slice` conforms to the aliasing invariant of
1041 // `I::Aliasing` because `self` does.
1042 // 1. By the above lemma, `slice` conforms to the alignment
1043 // invariant of `I::Alignment` because `self` does.
1044 // 2. Since `[T; N]` and `[T]` have the same bit validity [1][2],
1045 // and since `self` and the returned `Ptr` have the same validity
1046 // invariant, neither `self` nor the returned `Ptr` can be used
1047 // to write a value to the referent which violates the other's
1048 // validity invariant.
1049 //
1050 // [1] Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout:
1051 //
1052 // An array of `[T; N]` has a size of `size_of::<T>() * N` and the
1053 // same alignment of `T`. Arrays are laid out so that the
1054 // zero-based `nth` element of the array is offset from the start
1055 // of the array by `n * size_of::<T>()` bytes.
1056 //
1057 // ...
1058 //
1059 // Slices have the same layout as the section of the array they
1060 // slice.
1061 //
1062 // [2] Per https://doc.rust-lang.org/1.81.0/reference/types/array.html#array-types:
1063 //
1064 // All elements of arrays are always initialized
1065 unsafe { Ptr::from_inner(slice) }
1066 }
1067 }
1068
1069 /// For caller convenience, these methods are generic over alignment
1070 /// invariant. In practice, the referent is always well-aligned, because the
1071 /// alignment of `[u8]` is 1.
1072 impl<'a, I> Ptr<'a, [u8], I>
1073 where
1074 I: Invariants<Validity = Valid>,
1075 {
1076 /// Attempts to cast `self` to a `U` using the given cast type.
1077 ///
1078 /// If `U` is a slice DST and pointer metadata (`meta`) is provided,
1079 /// then the cast will only succeed if it would produce an object with
1080 /// the given metadata.
1081 ///
1082 /// Returns `None` if the resulting `U` would be invalidly-aligned, if
1083 /// no `U` can fit in `self`, or if the provided pointer metadata
1084 /// describes an invalid instance of `U`. On success, returns a pointer
1085 /// to the largest-possible `U` which fits in `self`.
1086 ///
1087 /// # Safety
1088 ///
1089 /// The caller may assume that this implementation is correct, and may
1090 /// rely on that assumption for the soundness of their code. In
1091 /// particular, the caller may assume that, if `try_cast_into` returns
1092 /// `Some((ptr, remainder))`, then `ptr` and `remainder` refer to
1093 /// non-overlapping byte ranges within `self`, and that `ptr` and
1094 /// `remainder` entirely cover `self`. Finally:
1095 /// - If this is a prefix cast, `ptr` has the same address as `self`.
1096 /// - If this is a suffix cast, `remainder` has the same address as
1097 /// `self`.
1098 #[inline(always)]
1099 pub fn try_cast_into<U, R>(
1100 self,
1101 cast_type: CastType,
1102 meta: Option<U::PointerMetadata>,
1103 ) -> Result<
1104 (Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, Ptr<'a, [u8], I>),
1105 CastError<Self, U>,
1106 >
1107 where
1108 I::Aliasing: Reference,
1109 U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>,
1110 {
1111 let (inner, remainder) = self.as_inner().try_cast_into(cast_type, meta).map_err(
1112 #[inline(always)]
1113 |err| {
1114 err.map_src(
1115 #[inline(always)]
1116 |inner|
1117 // SAFETY: `PtrInner::try_cast_into` promises to return its
1118 // original argument on error, which was originally produced
1119 // by `self.as_inner()`, which is guaranteed to satisfy
1120 // `Ptr`'s invariants.
1121 unsafe { Ptr::from_inner(inner) },
1122 )
1123 },
1124 )?;
1125
1126 // SAFETY:
1127 // 0. Since `U: Read<I::Aliasing, _>`, either:
1128 // - `I::Aliasing` is `Exclusive`, in which case both `src` and
1129 // `ptr` conform to `Exclusive`
1130 // - `I::Aliasing` is `Shared` and `U` is `Immutable` (we already
1131 // know that `[u8]: Immutable`). In this case, neither `U` nor
1132 // `[u8]` permit mutation, and so `Shared` aliasing is
1133 // satisfied.
1134 // 1. `ptr` conforms to the alignment invariant of `Aligned` because
1135 // it is derived from `try_cast_into`, which promises that the
1136 // object described by `target` is validly aligned for `U`.
1137 // 2. By trait bound, `self` - and thus `target` - is a bit-valid
1138 // `[u8]`. `Ptr<[u8], (_, _, Valid)>` and `Ptr<_, (_, _,
1139 // Initialized)>` have the same bit validity, and so neither
1140 // `self` nor `res` can be used to write a value to the referent
1141 // which violates the other's validity invariant.
1142 let res = unsafe { Ptr::from_inner(inner) };
1143
1144 // SAFETY:
1145 // 0. `self` and `remainder` both have the type `[u8]`. Thus, they
1146 // have `UnsafeCell`s at the same locations. Type casting does
1147 // not affect aliasing.
1148 // 1. `[u8]` has no alignment requirement.
1149 // 2. `self` has validity `Valid` and has type `[u8]`. Since
1150 // `remainder` references a subset of `self`'s referent, it is
1151 // also a bit-valid `[u8]`. Thus, neither `self` nor `remainder`
1152 // can be used to write a value to the referent which violates
1153 // the other's validity invariant.
1154 let remainder = unsafe { Ptr::from_inner(remainder) };
1155
1156 Ok((res, remainder))
1157 }
1158
1159 /// Attempts to cast `self` into a `U`, failing if all of the bytes of
1160 /// `self` cannot be treated as a `U`.
1161 ///
1162 /// In particular, this method fails if `self` is not validly-aligned
1163 /// for `U` or if `self`'s size is not a valid size for `U`.
1164 ///
1165 /// # Safety
1166 ///
1167 /// On success, the caller may assume that the returned pointer
1168 /// references the same byte range as `self`.
1169 #[allow(unused)]
1170 #[inline(always)]
1171 pub fn try_cast_into_no_leftover<U, R>(
1172 self,
1173 meta: Option<U::PointerMetadata>,
1174 ) -> Result<Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, CastError<Self, U>>
1175 where
1176 I::Aliasing: Reference,
1177 U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>,
1178 [u8]: Read<I::Aliasing, R>,
1179 {
1180 // SAFETY: The provided closure returns the only copy of `slf`.
1181 unsafe {
1182 self.try_with_unchecked(
1183 #[inline(always)]
1184 |slf| match slf.try_cast_into(CastType::Prefix, meta) {
1185 Ok((slf, remainder)) => {
1186 if remainder.is_empty() {
1187 Ok(slf)
1188 } else {
1189 Err(CastError::Size(SizeError::<_, U>::new(())))
1190 }
1191 }
1192 Err(err) => Err(err.map_src(
1193 #[inline(always)]
1194 |_slf| (),
1195 )),
1196 },
1197 )
1198 }
1199 }
1200 }
1201
1202 impl<'a, T, I> Ptr<'a, UnsafeCell<T>, I>
1203 where
1204 T: 'a + ?Sized,
1205 I: Invariants<Aliasing = Exclusive>,
1206 {
1207 /// Converts this `Ptr` into a pointer to the underlying data.
1208 ///
1209 /// This call borrows the `UnsafeCell` mutably (at compile-time) which
1210 /// guarantees that we possess the only reference.
1211 ///
1212 /// This is like [`UnsafeCell::get_mut`], but for `Ptr`.
1213 ///
1214 /// [`UnsafeCell::get_mut`]: core::cell::UnsafeCell::get_mut
1215 #[must_use]
1216 #[inline(always)]
1217 pub fn get_mut(self) -> Ptr<'a, T, I> {
1218 // SAFETY: As described below, `UnsafeCell<T>` has the same size
1219 // as `T: ?Sized` (same static size or same DST layout). Thus,
1220 // `*const UnsafeCell<T> as *const T` is a size-preserving cast.
1221 define_cast!(unsafe { Cast<T: ?Sized> = UnsafeCell<T> => T });
1222
1223 // SAFETY:
1224 // - Aliasing is `Exclusive`, and so we are not required to promise
1225 // anything about the locations of `UnsafeCell`s.
1226 // - `UnsafeCell<T>` has the same bit validity as `T` [1].
1227 // Technically the term "representation" doesn't guarantee this,
1228 // but the subsequent sentence in the documentation makes it clear
1229 // that this is the intention.
1230 //
1231 // By invariant on `Validity`, since `T` and `UnsafeCell<T>` have
1232 // the same bit validity, then the set of values which may appear
1233 // in the referent of a `Ptr<T, (_, _, V)>` is the same as the set
1234 // which may appear in the referent of a `Ptr<UnsafeCell<T>, (_,
1235 // _, V)>`. Thus, neither `self` nor `ptr` may be used to write a
1236 // value to the referent which would violate the other's validity
1237 // invariant.
1238 //
1239 // [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout:
1240 //
1241 // `UnsafeCell<T>` has the same in-memory representation as its
1242 // inner type `T`. A consequence of this guarantee is that it is
1243 // possible to convert between `T` and `UnsafeCell<T>`.
1244 let ptr = unsafe { self.project_transmute_unchecked::<_, _, Cast>() };
1245
1246 // SAFETY: `UnsafeCell<T>` has the same alignment as `T` [1],
1247 // and so if `self` is guaranteed to be aligned, then so is the
1248 // returned `Ptr`.
1249 //
1250 // [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout:
1251 //
1252 // `UnsafeCell<T>` has the same in-memory representation as
1253 // its inner type `T`. A consequence of this guarantee is that
1254 // it is possible to convert between `T` and `UnsafeCell<T>`.
1255 let ptr = unsafe { ptr.assume_alignment::<I::Alignment>() };
1256 ptr.unify_invariants()
1257 }
1258 }
1259}
1260
1261/// Projections through the referent.
1262mod _project {
1263 use super::*;
1264
1265 impl<'a, T, I> Ptr<'a, [T], I>
1266 where
1267 T: 'a,
1268 I: Invariants,
1269 I::Aliasing: Reference,
1270 {
1271 /// Iteratively projects the elements `Ptr<T>` from `Ptr<[T]>`.
1272 #[inline]
1273 pub fn iter(self) -> impl Iterator<Item = Ptr<'a, T, I>> {
1274 // SAFETY:
1275 // 0. `elem` conforms to the aliasing invariant of `I::Aliasing`:
1276 // - `Exclusive`: `self` is consumed by value, and therefore
1277 // cannot be used to access the slice while any yielded
1278 // element `Ptr` is live. Each non-zero-sized element is a
1279 // disjoint byte range within the slice, and zero-sized
1280 // elements address no bytes, so distinct yielded element
1281 // `Ptr`s do not alias each other.
1282 // - `Shared`: It is sound for multiple shared `Ptr`s to exist
1283 // simultaneously which reference the same memory.
1284 // 1. `elem`, conditionally, conforms to the validity invariant of
1285 // `I::Alignment`. If `elem` is projected from data well-aligned
1286 // for `[T]`, `elem` will be valid for `T`.
1287 // 2. `elem` conforms to the validity invariant of `I::Validity`.
1288 // Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout:
1289 //
1290 // Slices have the same layout as the section of the array they
1291 // slice.
1292 //
1293 // Arrays are laid out so that the zero-based `nth` element of
1294 // the array is offset from the start of the array by `n *
1295 // size_of::<T>()` bytes. Thus, `elem` addresses a valid `T`
1296 // within the slice. Since `self` satisfies `I::Validity`, `elem`
1297 // also satisfies `I::Validity`.
1298 self.as_inner().iter().map(
1299 #[inline(always)]
1300 |elem| unsafe { Ptr::from_inner(elem) },
1301 )
1302 }
1303 }
1304
1305 #[allow(clippy::needless_lifetimes)]
1306 impl<'a, T, I> Ptr<'a, T, I>
1307 where
1308 T: 'a + ?Sized + KnownLayout<PointerMetadata = usize>,
1309 I: Invariants,
1310 {
1311 /// The number of slice elements in the object referenced by `self`.
1312 #[inline]
1313 #[must_use]
1314 pub fn len(&self) -> usize {
1315 self.as_inner().meta().get()
1316 }
1317
1318 /// Returns `true` if the slice pointer has a length of 0.
1319 #[inline]
1320 #[must_use]
1321 pub fn is_empty(&self) -> bool {
1322 self.len() == 0
1323 }
1324 }
1325}
1326
1327#[cfg(test)]
1328mod tests {
1329 use core::mem::{self, MaybeUninit};
1330
1331 use super::*;
1332 #[allow(unused)] // Needed on our MSRV, but considered unused on later toolchains.
1333 use crate::util::AsAddress;
1334 use crate::{pointer::BecauseImmutable, util::testutil::AU64, FromBytes, Immutable};
1335
1336 mod test_ptr_try_cast_into_soundness {
1337 use super::*;
1338
1339 // This test is designed so that if `Ptr::try_cast_into_xxx` are
1340 // buggy, it will manifest as unsoundness that Miri can detect.
1341
1342 // - If `size_of::<T>() == 0`, `N == 4`
1343 // - Else, `N == 4 * size_of::<T>()`
1344 //
1345 // Each test will be run for each metadata in `metas`.
1346 fn test<T, I, const N: usize>(metas: I)
1347 where
1348 T: ?Sized + KnownLayout + Immutable + FromBytes,
1349 I: IntoIterator<Item = Option<T::PointerMetadata>> + Clone,
1350 {
1351 let mut bytes = [MaybeUninit::<u8>::uninit(); N];
1352 let initialized = [MaybeUninit::new(0u8); N];
1353 for start in 0..=bytes.len() {
1354 for end in start..=bytes.len() {
1355 // Set all bytes to uninitialized other than those in
1356 // the range we're going to pass to `try_cast_from`.
1357 // This allows Miri to detect out-of-bounds reads
1358 // because they read uninitialized memory. Without this,
1359 // some out-of-bounds reads would still be in-bounds of
1360 // `bytes`, and so might spuriously be accepted.
1361 bytes = [MaybeUninit::<u8>::uninit(); N];
1362 let bytes = &mut bytes[start..end];
1363 // Initialize only the byte range we're going to pass to
1364 // `try_cast_from`.
1365 bytes.copy_from_slice(&initialized[start..end]);
1366
1367 let bytes = {
1368 let bytes: *const [MaybeUninit<u8>] = bytes;
1369 #[allow(clippy::as_conversions)]
1370 let bytes = bytes as *const [u8];
1371 // SAFETY: We just initialized these bytes to valid
1372 // `u8`s.
1373 unsafe { &*bytes }
1374 };
1375
1376 // SAFETY: The bytes in `slf` must be initialized.
1377 unsafe fn validate_and_get_len<
1378 T: ?Sized + KnownLayout + FromBytes + Immutable,
1379 >(
1380 slf: Ptr<'_, T, (Shared, Aligned, Initialized)>,
1381 ) -> usize {
1382 let t = slf.recall_validity().as_ref();
1383
1384 let bytes = {
1385 let len = mem::size_of_val(t);
1386 let t: *const T = t;
1387 // SAFETY:
1388 // - We know `t`'s bytes are all initialized
1389 // because we just read it from `slf`, which
1390 // points to an initialized range of bytes. If
1391 // there's a bug and this doesn't hold, then
1392 // that's exactly what we're hoping Miri will
1393 // catch!
1394 // - Since `T: FromBytes`, `T` doesn't contain
1395 // any `UnsafeCell`s, so it's okay for `t: T`
1396 // and a `&[u8]` to the same memory to be
1397 // alive concurrently.
1398 unsafe { core::slice::from_raw_parts(t.cast::<u8>(), len) }
1399 };
1400
1401 // This assertion ensures that `t`'s bytes are read
1402 // and compared to another value, which in turn
1403 // ensures that Miri gets a chance to notice if any
1404 // of `t`'s bytes are uninitialized, which they
1405 // shouldn't be (see the comment above).
1406 assert_eq!(bytes, vec![0u8; bytes.len()]);
1407
1408 mem::size_of_val(t)
1409 }
1410
1411 for meta in metas.clone().into_iter() {
1412 for cast_type in [CastType::Prefix, CastType::Suffix] {
1413 if let Ok((slf, remaining)) = Ptr::from_ref(bytes)
1414 .try_cast_into::<T, BecauseImmutable>(cast_type, meta)
1415 {
1416 // SAFETY: All bytes in `bytes` have been
1417 // initialized.
1418 let len = unsafe { validate_and_get_len(slf) };
1419 assert_eq!(remaining.len(), bytes.len() - len);
1420 #[allow(unstable_name_collisions)]
1421 let bytes_addr = bytes.as_ptr().addr();
1422 #[allow(unstable_name_collisions)]
1423 let remaining_addr = remaining.as_inner().as_ptr().addr();
1424 match cast_type {
1425 CastType::Prefix => {
1426 assert_eq!(remaining_addr, bytes_addr + len)
1427 }
1428 CastType::Suffix => assert_eq!(remaining_addr, bytes_addr),
1429 }
1430
1431 if let Some(want) = meta {
1432 let got =
1433 KnownLayout::pointer_to_metadata(slf.as_inner().as_ptr());
1434 assert_eq!(got, want);
1435 }
1436 }
1437 }
1438
1439 if let Ok(slf) = Ptr::from_ref(bytes)
1440 .try_cast_into_no_leftover::<T, BecauseImmutable>(meta)
1441 {
1442 // SAFETY: All bytes in `bytes` have been
1443 // initialized.
1444 let len = unsafe { validate_and_get_len(slf) };
1445 assert_eq!(len, bytes.len());
1446
1447 if let Some(want) = meta {
1448 let got = KnownLayout::pointer_to_metadata(slf.as_inner().as_ptr());
1449 assert_eq!(got, want);
1450 }
1451 }
1452 }
1453 }
1454 }
1455 }
1456
1457 #[derive(FromBytes, KnownLayout, Immutable)]
1458 #[repr(C)]
1459 struct SliceDst<T> {
1460 a: u8,
1461 trailing: [T],
1462 }
1463
1464 // Each test case becomes its own `#[test]` function. We do this because
1465 // this test in particular takes far, far longer to execute under Miri
1466 // than all of our other tests combined. Previously, we had these
1467 // execute sequentially in a single test function. We run Miri tests in
1468 // parallel in CI, but this test being sequential meant that most of
1469 // that parallelism was wasted, as all other tests would finish in a
1470 // fraction of the total execution time, leaving this test to execute on
1471 // a single thread for the remainder of the test. By putting each test
1472 // case in its own function, we permit better use of available
1473 // parallelism.
1474 macro_rules! test {
1475 ($test_name:ident: $ty:ty) => {
1476 #[test]
1477 #[allow(non_snake_case)]
1478 fn $test_name() {
1479 const S: usize = core::mem::size_of::<$ty>();
1480 const N: usize = if S == 0 { 4 } else { S * 4 };
1481 test::<$ty, _, N>([None]);
1482
1483 // If `$ty` is a ZST, then we can't pass `None` as the
1484 // pointer metadata, or else computing the correct trailing
1485 // slice length will panic.
1486 if S == 0 {
1487 test::<[$ty], _, N>([Some(0), Some(1), Some(2), Some(3)]);
1488 test::<SliceDst<$ty>, _, N>([Some(0), Some(1), Some(2), Some(3)]);
1489 } else {
1490 test::<[$ty], _, N>([None, Some(0), Some(1), Some(2), Some(3)]);
1491 test::<SliceDst<$ty>, _, N>([None, Some(0), Some(1), Some(2), Some(3)]);
1492 }
1493 }
1494 };
1495 ($ty:ident) => {
1496 test!($ty: $ty);
1497 };
1498 ($($ty:ident),*) => { $(test!($ty);)* }
1499 }
1500
1501 test!(empty_tuple: ());
1502 test!(u8, u16, u32, u64, usize, AU64);
1503 test!(i8, i16, i32, i64, isize);
1504 test!(f32, f64);
1505 }
1506
1507 #[test]
1508 fn test_try_cast_into_explicit_count() {
1509 macro_rules! test {
1510 ($ty:ty, $bytes:expr, $elems:expr, $expect:expr) => {{
1511 let bytes = [0u8; $bytes];
1512 let ptr = Ptr::from_ref(&bytes[..]);
1513 let res =
1514 ptr.try_cast_into::<$ty, BecauseImmutable>(CastType::Prefix, Some($elems));
1515 if let Some(expect) = $expect {
1516 let (ptr, _) = res.unwrap();
1517 assert_eq!(KnownLayout::pointer_to_metadata(ptr.as_inner().as_ptr()), expect);
1518 } else {
1519 let _ = res.unwrap_err();
1520 }
1521 }};
1522 }
1523
1524 #[derive(KnownLayout, Immutable)]
1525 #[repr(C)]
1526 struct ZstDst {
1527 u: [u8; 8],
1528 slc: [()],
1529 }
1530
1531 test!(ZstDst, 8, 0, Some(0));
1532 test!(ZstDst, 7, 0, None);
1533
1534 test!(ZstDst, 8, usize::MAX, Some(usize::MAX));
1535 test!(ZstDst, 7, usize::MAX, None);
1536
1537 #[derive(KnownLayout, Immutable)]
1538 #[repr(C)]
1539 struct Dst {
1540 u: [u8; 8],
1541 slc: [u8],
1542 }
1543
1544 test!(Dst, 8, 0, Some(0));
1545 test!(Dst, 7, 0, None);
1546
1547 test!(Dst, 9, 1, Some(1));
1548 test!(Dst, 8, 1, None);
1549
1550 // If we didn't properly check for overflow, this would cause the
1551 // metadata to overflow to 0, and thus the cast would spuriously
1552 // succeed.
1553 test!(Dst, 8, usize::MAX - 8 + 1, None);
1554 }
1555
1556 #[test]
1557 fn test_try_cast_into_no_leftover_restores_original_slice() {
1558 let bytes = [0u8; 4];
1559 let ptr = Ptr::from_ref(&bytes[..]);
1560 let res = ptr.try_cast_into_no_leftover::<[u8; 2], BecauseImmutable>(None);
1561 match res {
1562 Ok(_) => panic!("should have failed due to leftover bytes"),
1563 Err(CastError::Size(e)) => {
1564 assert_eq!(e.into_src().len(), 4, "Should return original slice length");
1565 }
1566 Err(e) => panic!("wrong error type: {:?}", e),
1567 }
1568 }
1569
1570 #[test]
1571 fn test_iter_exclusive_yields_disjoint_ptrs() {
1572 let mut arr = [0u8, 1, 2, 3];
1573
1574 {
1575 let mut iter = Ptr::from_mut(&mut arr[..]).iter();
1576 let first = iter.next().unwrap().as_mut();
1577 let second = iter.next().unwrap().as_mut();
1578
1579 *first = 10;
1580 *second = 20;
1581 *first = 30;
1582 }
1583
1584 assert_eq!(arr, [30, 20, 2, 3]);
1585 }
1586}