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