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