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