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