1 // SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT 2 3 // Copyright 2024 The Fuchsia Authors 4 // 5 // Licensed under the 2-Clause BSD License <LICENSE-BSD or 6 // https://opensource.org/license/bsd-2-clause>, Apache License, Version 2.0 7 // <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT 8 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. 9 // This file may not be copied, modified, or distributed except according to 10 // those terms. 11 12 use core::{mem, num::NonZeroUsize}; 13 14 use crate::util; 15 16 /// The target pointer width, counted in bits. 17 const POINTER_WIDTH_BITS: usize = mem::size_of::<usize>() * 8; 18 19 /// The layout of a type which might be dynamically-sized. 20 /// 21 /// `DstLayout` describes the layout of sized types, slice types, and "slice 22 /// DSTs" - ie, those that are known by the type system to have a trailing slice 23 /// (as distinguished from `dyn Trait` types - such types *might* have a 24 /// trailing slice type, but the type system isn't aware of it). 25 /// 26 /// Note that `DstLayout` does not have any internal invariants, so no guarantee 27 /// is made that a `DstLayout` conforms to any of Rust's requirements regarding 28 /// the layout of real Rust types or instances of types. 29 #[doc(hidden)] 30 #[allow(missing_debug_implementations, missing_copy_implementations)] 31 #[cfg_attr(any(kani, test), derive(Debug, PartialEq, Eq))] 32 #[derive(Copy, Clone)] 33 pub struct DstLayout { 34 pub(crate) align: NonZeroUsize, 35 pub(crate) size_info: SizeInfo, 36 // Is it guaranteed statically (without knowing a value's runtime metadata) 37 // that the top-level type contains no padding? This does *not* apply 38 // recursively - for example, `[(u8, u16)]` has `statically_shallow_unpadded 39 // = true` even though this type likely has padding inside each `(u8, u16)`. 40 pub(crate) statically_shallow_unpadded: bool, 41 } 42 43 #[cfg_attr(any(kani, test), derive(Debug, PartialEq, Eq))] 44 #[derive(Copy, Clone)] 45 pub(crate) enum SizeInfo<E = usize> { 46 Sized { size: usize }, 47 SliceDst(TrailingSliceLayout<E>), 48 } 49 50 #[cfg_attr(any(kani, test), derive(Debug, PartialEq, Eq))] 51 #[derive(Copy, Clone)] 52 pub(crate) struct TrailingSliceLayout<E = usize> { 53 // The offset of the first byte of the trailing slice field. Note that this 54 // is NOT the same as the minimum size of the type. For example, consider 55 // the following type: 56 // 57 // struct Foo { 58 // a: u16, 59 // b: u8, 60 // c: [u8], 61 // } 62 // 63 // In `Foo`, `c` is at byte offset 3. When `c.len() == 0`, `c` is followed 64 // by a padding byte. 65 pub(crate) offset: usize, 66 // The size of the element type of the trailing slice field. 67 pub(crate) elem_size: E, 68 } 69 70 impl SizeInfo { 71 /// Attempts to create a `SizeInfo` from `Self` in which `elem_size` is a 72 /// `NonZeroUsize`. If `elem_size` is 0, returns `None`. 73 #[allow(unused)] 74 const fn try_to_nonzero_elem_size(&self) -> Option<SizeInfo<NonZeroUsize>> { 75 Some(match *self { 76 SizeInfo::Sized { size } => SizeInfo::Sized { size }, 77 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => { 78 if let Some(elem_size) = NonZeroUsize::new(elem_size) { 79 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) 80 } else { 81 return None; 82 } 83 } 84 }) 85 } 86 } 87 88 #[doc(hidden)] 89 #[derive(Copy, Clone)] 90 #[cfg_attr(test, derive(Debug))] 91 #[allow(missing_debug_implementations)] 92 pub enum CastType { 93 Prefix, 94 Suffix, 95 } 96 97 #[cfg_attr(test, derive(Debug))] 98 pub(crate) enum MetadataCastError { 99 Alignment, 100 Size, 101 } 102 103 impl DstLayout { 104 /// The minimum possible alignment of a type. 105 const MIN_ALIGN: NonZeroUsize = match NonZeroUsize::new(1) { 106 Some(min_align) => min_align, 107 None => const_unreachable!(), 108 }; 109 110 /// The maximum theoretic possible alignment of a type. 111 /// 112 /// For compatibility with future Rust versions, this is defined as the 113 /// maximum power-of-two that fits into a `usize`. See also 114 /// [`DstLayout::CURRENT_MAX_ALIGN`]. 115 pub(crate) const THEORETICAL_MAX_ALIGN: NonZeroUsize = 116 match NonZeroUsize::new(1 << (POINTER_WIDTH_BITS - 1)) { 117 Some(max_align) => max_align, 118 None => const_unreachable!(), 119 }; 120 121 /// The current, documented max alignment of a type \[1\]. 122 /// 123 /// \[1\] Per <https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers>: 124 /// 125 /// The alignment value must be a power of two from 1 up to 126 /// 2<sup>29</sup>. 127 #[cfg(not(kani))] 128 #[cfg(not(target_pointer_width = "16"))] 129 pub(crate) const CURRENT_MAX_ALIGN: NonZeroUsize = match NonZeroUsize::new(1 << 28) { 130 Some(max_align) => max_align, 131 None => const_unreachable!(), 132 }; 133 134 #[cfg(not(kani))] 135 #[cfg(target_pointer_width = "16")] 136 pub(crate) const CURRENT_MAX_ALIGN: NonZeroUsize = match NonZeroUsize::new(1 << 15) { 137 Some(max_align) => max_align, 138 None => const_unreachable!(), 139 }; 140 141 /// The maximum size of an allocation \[1\]. 142 /// 143 /// \[1\] Per <https://doc.rust-lang.org/1.91.1/std/ptr/index.html#allocation>: 144 /// 145 /// For any allocation with base `address`, `size`, and a set of `addresses`, 146 /// the following are guaranteed: [..] 147 /// 148 /// - `size <= isize::MAX` 149 /// 150 #[allow(clippy::as_conversions)] 151 pub(crate) const MAX_SIZE: usize = isize::MAX as usize; 152 153 /// Assumes that this layout lacks static shallow padding. 154 /// 155 /// # Panics 156 /// 157 /// This method does not panic. 158 /// 159 /// # Safety 160 /// 161 /// If `self` describes the size and alignment of type that lacks static 162 /// shallow padding, unsafe code may assume that the result of this method 163 /// accurately reflects the size, alignment, and lack of static shallow 164 /// padding of that type. 165 const fn assume_shallow_unpadded(self) -> Self { 166 Self { statically_shallow_unpadded: true, ..self } 167 } 168 169 /// Constructs a `DstLayout` for a zero-sized type with `repr_align` 170 /// alignment (or 1). If `repr_align` is provided, then it must be a power 171 /// of two. 172 /// 173 /// # Panics 174 /// 175 /// This function panics if the supplied `repr_align` is not a power of two. 176 /// 177 /// # Safety 178 /// 179 /// Unsafe code may assume that the contract of this function is satisfied. 180 #[doc(hidden)] 181 #[must_use] 182 #[inline] 183 pub const fn new_zst(repr_align: Option<NonZeroUsize>) -> DstLayout { 184 let align = match repr_align { 185 Some(align) => align, 186 None => Self::MIN_ALIGN, 187 }; 188 189 const_assert!(align.get().is_power_of_two()); 190 191 DstLayout { 192 align, 193 size_info: SizeInfo::Sized { size: 0 }, 194 statically_shallow_unpadded: true, 195 } 196 } 197 198 /// Constructs a `DstLayout` which describes `T` and assumes `T` may contain 199 /// padding. 200 /// 201 /// # Safety 202 /// 203 /// Unsafe code may assume that `DstLayout` is the correct layout for `T`. 204 #[doc(hidden)] 205 #[must_use] 206 #[inline] 207 pub const fn for_type<T>() -> DstLayout { 208 // SAFETY: `align` is correct by construction. `T: Sized`, and so it is 209 // sound to initialize `size_info` to `SizeInfo::Sized { size }`; the 210 // `size` field is also correct by construction. `unpadded` can safely 211 // default to `false`. 212 DstLayout { 213 align: match NonZeroUsize::new(mem::align_of::<T>()) { 214 Some(align) => align, 215 None => const_unreachable!(), 216 }, 217 size_info: SizeInfo::Sized { size: mem::size_of::<T>() }, 218 statically_shallow_unpadded: false, 219 } 220 } 221 222 /// Constructs a `DstLayout` which describes a `T` that does not contain 223 /// padding. 224 /// 225 /// # Safety 226 /// 227 /// Unsafe code may assume that `DstLayout` is the correct layout for `T`. 228 #[doc(hidden)] 229 #[must_use] 230 #[inline] 231 pub const fn for_unpadded_type<T>() -> DstLayout { 232 Self::for_type::<T>().assume_shallow_unpadded() 233 } 234 235 /// Constructs a `DstLayout` which describes `[T]`. 236 /// 237 /// # Safety 238 /// 239 /// Unsafe code may assume that `DstLayout` is the correct layout for `[T]`. 240 pub(crate) const fn for_slice<T>() -> DstLayout { 241 // SAFETY: The alignment of a slice is equal to the alignment of its 242 // element type, and so `align` is initialized correctly. 243 // 244 // Since this is just a slice type, there is no offset between the 245 // beginning of the type and the beginning of the slice, so it is 246 // correct to set `offset: 0`. The `elem_size` is correct by 247 // construction. Since `[T]` is a (degenerate case of a) slice DST, it 248 // is correct to initialize `size_info` to `SizeInfo::SliceDst`. 249 DstLayout { 250 align: match NonZeroUsize::new(mem::align_of::<T>()) { 251 Some(align) => align, 252 None => const_unreachable!(), 253 }, 254 size_info: SizeInfo::SliceDst(TrailingSliceLayout { 255 offset: 0, 256 elem_size: mem::size_of::<T>(), 257 }), 258 statically_shallow_unpadded: true, 259 } 260 } 261 262 /// Constructs a complete `DstLayout` reflecting a `repr(C)` struct with the 263 /// given alignment modifiers and fields. 264 /// 265 /// This method cannot be used to match the layout of a record with the 266 /// default representation, as that representation is mostly unspecified. 267 /// 268 /// # Safety 269 /// 270 /// For any definition of a `repr(C)` struct, if this method is invoked with 271 /// alignment modifiers and fields corresponding to that definition, the 272 /// resulting `DstLayout` will correctly encode the layout of that struct. 273 /// 274 /// We make no guarantees to the behavior of this method when it is invoked 275 /// with arguments that cannot correspond to a valid `repr(C)` struct. 276 #[must_use] 277 #[inline] 278 pub const fn for_repr_c_struct( 279 repr_align: Option<NonZeroUsize>, 280 repr_packed: Option<NonZeroUsize>, 281 fields: &[DstLayout], 282 ) -> DstLayout { 283 let mut layout = DstLayout::new_zst(repr_align); 284 285 let mut i = 0; 286 #[allow(clippy::arithmetic_side_effects)] 287 while i < fields.len() { 288 #[allow(clippy::indexing_slicing)] 289 let field = fields[i]; 290 layout = layout.extend(field, repr_packed); 291 i += 1; 292 } 293 294 layout = layout.pad_to_align(); 295 296 // SAFETY: `layout` accurately describes the layout of a `repr(C)` 297 // struct with `repr_align` or `repr_packed` alignment modifications and 298 // the given `fields`. The `layout` is constructed using a sequence of 299 // invocations of `DstLayout::{new_zst,extend,pad_to_align}`. The 300 // documentation of these items vows that invocations in this manner 301 // will accurately describe a type, so long as: 302 // 303 // - that type is `repr(C)`, 304 // - its fields are enumerated in the order they appear, 305 // - the presence of `repr_align` and `repr_packed` are correctly accounted for. 306 // 307 // We respect all three of these preconditions above. 308 layout 309 } 310 311 /// Like `Layout::extend`, this creates a layout that describes a record 312 /// whose layout consists of `self` followed by `next` that includes the 313 /// necessary inter-field padding, but not any trailing padding. 314 /// 315 /// In order to match the layout of a `#[repr(C)]` struct, this method 316 /// should be invoked for each field in declaration order. To add trailing 317 /// padding, call `DstLayout::pad_to_align` after extending the layout for 318 /// all fields. If `self` corresponds to a type marked with 319 /// `repr(packed(N))`, then `repr_packed` should be set to `Some(N)`, 320 /// otherwise `None`. 321 /// 322 /// This method cannot be used to match the layout of a record with the 323 /// default representation, as that representation is mostly unspecified. 324 /// 325 /// # Safety 326 /// 327 /// If a (potentially hypothetical) valid `repr(C)` Rust type begins with 328 /// fields whose layout are `self`, and those fields are immediately 329 /// followed by a field whose layout is `field`, then unsafe code may rely 330 /// on `self.extend(field, repr_packed)` producing a layout that correctly 331 /// encompasses those two components. 332 /// 333 /// We make no guarantees to the behavior of this method if these fragments 334 /// cannot appear in a valid Rust type (e.g., the concatenation of the 335 /// layouts would lead to a size larger than `isize::MAX`). 336 #[doc(hidden)] 337 #[must_use] 338 #[inline] 339 pub const fn extend(self, field: DstLayout, repr_packed: Option<NonZeroUsize>) -> Self { 340 use util::{max, min, padding_needed_for}; 341 342 // If `repr_packed` is `None`, there are no alignment constraints, and 343 // the value can be defaulted to `THEORETICAL_MAX_ALIGN`. 344 let max_align = match repr_packed { 345 Some(max_align) => max_align, 346 None => Self::THEORETICAL_MAX_ALIGN, 347 }; 348 349 const_assert!(max_align.get().is_power_of_two()); 350 351 // We use Kani to prove that this method is robust to future increases 352 // in Rust's maximum allowed alignment. However, if such a change ever 353 // actually occurs, we'd like to be notified via assertion failures. 354 #[cfg(not(kani))] 355 { 356 const_debug_assert!(self.align.get() <= DstLayout::CURRENT_MAX_ALIGN.get()); 357 const_debug_assert!(field.align.get() <= DstLayout::CURRENT_MAX_ALIGN.get()); 358 if let Some(repr_packed) = repr_packed { 359 const_debug_assert!(repr_packed.get() <= DstLayout::CURRENT_MAX_ALIGN.get()); 360 } 361 } 362 363 // The field's alignment is clamped by `repr_packed` (i.e., the 364 // `repr(packed(N))` attribute, if any) [1]. 365 // 366 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers: 367 // 368 // The alignments of each field, for the purpose of positioning 369 // fields, is the smaller of the specified alignment and the alignment 370 // of the field's type. 371 let field_align = min(field.align, max_align); 372 373 // The struct's alignment is the maximum of its previous alignment and 374 // `field_align`. 375 let align = max(self.align, field_align); 376 377 let (interfield_padding, size_info) = match self.size_info { 378 // If the layout is already a DST, we panic; DSTs cannot be extended 379 // with additional fields. 380 SizeInfo::SliceDst(..) => const_panic!("Cannot extend a DST with additional fields."), 381 382 SizeInfo::Sized { size: preceding_size } => { 383 // Compute the minimum amount of inter-field padding needed to 384 // satisfy the field's alignment, and offset of the trailing 385 // field. [1] 386 // 387 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers: 388 // 389 // Inter-field padding is guaranteed to be the minimum 390 // required in order to satisfy each field's (possibly 391 // altered) alignment. 392 let padding = padding_needed_for(preceding_size, field_align); 393 394 // This will not panic (and is proven to not panic, with Kani) 395 // if the layout components can correspond to a leading layout 396 // fragment of a valid Rust type, but may panic otherwise (e.g., 397 // combining or aligning the components would create a size 398 // exceeding `isize::MAX`). 399 let offset = match preceding_size.checked_add(padding) { 400 Some(offset) => offset, 401 None => const_panic!("Adding padding to `self`'s size overflows `usize`."), 402 }; 403 404 ( 405 padding, 406 match field.size_info { 407 SizeInfo::Sized { size: field_size } => { 408 // If the trailing field is sized, the resulting layout 409 // will be sized. Its size will be the sum of the 410 // preceding layout, the size of the new field, and the 411 // size of inter-field padding between the two. 412 // 413 // This will not panic (and is proven with Kani to not 414 // panic) if the layout components can correspond to a 415 // leading layout fragment of a valid Rust type, but may 416 // panic otherwise (e.g., combining or aligning the 417 // components would create a size exceeding 418 // `usize::MAX`). 419 let size = match offset.checked_add(field_size) { 420 Some(size) => size, 421 None => const_panic!("`field` cannot be appended without the total size overflowing `usize`"), 422 }; 423 SizeInfo::Sized { size } 424 } 425 SizeInfo::SliceDst(TrailingSliceLayout { 426 offset: trailing_offset, 427 elem_size, 428 }) => { 429 // If the trailing field is dynamically sized, so too 430 // will the resulting layout. The offset of the trailing 431 // slice component is the sum of the offset of the 432 // trailing field and the trailing slice offset within 433 // that field. 434 // 435 // This will not panic (and is proven with Kani to not 436 // panic) if the layout components can correspond to a 437 // leading layout fragment of a valid Rust type, but may 438 // panic otherwise (e.g., combining or aligning the 439 // components would create a size exceeding 440 // `usize::MAX`). 441 let offset = match offset.checked_add(trailing_offset) { 442 Some(offset) => offset, 443 None => const_panic!("`field` cannot be appended without the total size overflowing `usize`"), 444 }; 445 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) 446 } 447 }, 448 ) 449 } 450 }; 451 452 let statically_shallow_unpadded = self.statically_shallow_unpadded 453 && field.statically_shallow_unpadded 454 && interfield_padding == 0; 455 456 DstLayout { align, size_info, statically_shallow_unpadded } 457 } 458 459 /// Like `Layout::pad_to_align`, this routine rounds the size of this layout 460 /// up to the nearest multiple of this type's alignment or `repr_packed` 461 /// (whichever is less). This method leaves DST layouts unchanged, since the 462 /// trailing padding of DSTs is computed at runtime. 463 /// 464 /// The accompanying boolean is `true` if the resulting composition of 465 /// fields necessitated static (as opposed to dynamic) padding; otherwise 466 /// `false`. 467 /// 468 /// In order to match the layout of a `#[repr(C)]` struct, this method 469 /// should be invoked after the invocations of [`DstLayout::extend`]. If 470 /// `self` corresponds to a type marked with `repr(packed(N))`, then 471 /// `repr_packed` should be set to `Some(N)`, otherwise `None`. 472 /// 473 /// This method cannot be used to match the layout of a record with the 474 /// default representation, as that representation is mostly unspecified. 475 /// 476 /// # Safety 477 /// 478 /// If a (potentially hypothetical) valid `repr(C)` type begins with fields 479 /// whose layout are `self` followed only by zero or more bytes of trailing 480 /// padding (not included in `self`), then unsafe code may rely on 481 /// `self.pad_to_align(repr_packed)` producing a layout that correctly 482 /// encapsulates the layout of that type. 483 /// 484 /// We make no guarantees to the behavior of this method if `self` cannot 485 /// appear in a valid Rust type (e.g., because the addition of trailing 486 /// padding would lead to a size larger than `isize::MAX`). 487 #[doc(hidden)] 488 #[must_use] 489 #[inline] 490 pub const fn pad_to_align(self) -> Self { 491 use util::padding_needed_for; 492 493 let (static_padding, size_info) = match self.size_info { 494 // For sized layouts, we add the minimum amount of trailing padding 495 // needed to satisfy alignment. 496 SizeInfo::Sized { size: unpadded_size } => { 497 let padding = padding_needed_for(unpadded_size, self.align); 498 let size = match unpadded_size.checked_add(padding) { 499 Some(size) => size, 500 None => const_panic!("Adding padding caused size to overflow `usize`."), 501 }; 502 (padding, SizeInfo::Sized { size }) 503 } 504 // For DST layouts, trailing padding depends on the length of the 505 // trailing DST and is computed at runtime. This does not alter the 506 // offset or element size of the layout, so we leave `size_info` 507 // unchanged. 508 size_info @ SizeInfo::SliceDst(_) => (0, size_info), 509 }; 510 511 let statically_shallow_unpadded = self.statically_shallow_unpadded && static_padding == 0; 512 513 DstLayout { align: self.align, size_info, statically_shallow_unpadded } 514 } 515 516 /// Produces `true` if `self` requires static padding; otherwise `false`. 517 #[must_use] 518 #[inline(always)] 519 pub const fn requires_static_padding(self) -> bool { 520 !self.statically_shallow_unpadded 521 } 522 523 /// Produces `true` if there exists any metadata for which a type of layout 524 /// `self` would require dynamic trailing padding; otherwise `false`. 525 #[must_use] 526 #[inline(always)] 527 pub const fn requires_dynamic_padding(self) -> bool { 528 // A `% self.align.get()` cannot panic, since `align` is non-zero. 529 #[allow(clippy::arithmetic_side_effects)] 530 match self.size_info { 531 SizeInfo::Sized { .. } => false, 532 SizeInfo::SliceDst(trailing_slice_layout) => { 533 // SAFETY: This predicate is formally proved sound by 534 // `proofs::prove_requires_dynamic_padding`. 535 trailing_slice_layout.offset % self.align.get() != 0 536 || trailing_slice_layout.elem_size % self.align.get() != 0 537 } 538 } 539 } 540 541 /// Validates that a cast is sound from a layout perspective. 542 /// 543 /// Validates that the size and alignment requirements of a type with the 544 /// layout described in `self` would not be violated by performing a 545 /// `cast_type` cast from a pointer with address `addr` which refers to a 546 /// memory region of size `bytes_len`. 547 /// 548 /// If the cast is valid, `validate_cast_and_convert_metadata` returns 549 /// `(elems, split_at)`. If `self` describes a dynamically-sized type, then 550 /// `elems` is the maximum number of trailing slice elements for which a 551 /// cast would be valid (for sized types, `elem` is meaningless and should 552 /// be ignored). `split_at` is the index at which to split the memory region 553 /// in order for the prefix (suffix) to contain the result of the cast, and 554 /// in order for the remaining suffix (prefix) to contain the leftover 555 /// bytes. 556 /// 557 /// There are three conditions under which a cast can fail: 558 /// - The smallest possible value for the type is larger than the provided 559 /// memory region 560 /// - A prefix cast is requested, and `addr` does not satisfy `self`'s 561 /// alignment requirement 562 /// - A suffix cast is requested, and `addr + bytes_len` does not satisfy 563 /// `self`'s alignment requirement (as a consequence, since all instances 564 /// of the type are a multiple of its alignment, no size for the type will 565 /// result in a starting address which is properly aligned) 566 /// 567 /// # Safety 568 /// 569 /// The caller may assume that this implementation is correct, and may rely 570 /// on that assumption for the soundness of their code. In particular, the 571 /// caller may assume that, if `validate_cast_and_convert_metadata` returns 572 /// `Some((elems, split_at))`, then: 573 /// - A pointer to the type (for dynamically sized types, this includes 574 /// `elems` as its pointer metadata) describes an object of size `size <= 575 /// bytes_len` 576 /// - If this is a prefix cast: 577 /// - `addr` satisfies `self`'s alignment 578 /// - `size == split_at` 579 /// - If this is a suffix cast: 580 /// - `split_at == bytes_len - size` 581 /// - `addr + split_at` satisfies `self`'s alignment 582 /// 583 /// Note that this method does *not* ensure that a pointer constructed from 584 /// its return values will be a valid pointer. In particular, this method 585 /// does not reason about `isize` overflow, which is a requirement of many 586 /// Rust pointer APIs, and may at some point be determined to be a validity 587 /// invariant of pointer types themselves. This should never be a problem so 588 /// long as the arguments to this method are derived from a known-valid 589 /// pointer (e.g., one derived from a safe Rust reference), but it is 590 /// nonetheless the caller's responsibility to justify that pointer 591 /// arithmetic will not overflow based on a safety argument *other than* the 592 /// mere fact that this method returned successfully. 593 /// 594 /// # Panics 595 /// 596 /// `validate_cast_and_convert_metadata` will panic if `self` describes a 597 /// DST whose trailing slice element is zero-sized. 598 /// 599 /// If `addr + bytes_len` overflows `usize`, 600 /// `validate_cast_and_convert_metadata` may panic, or it may return 601 /// incorrect results. No guarantees are made about when 602 /// `validate_cast_and_convert_metadata` will panic. The caller should not 603 /// rely on `validate_cast_and_convert_metadata` panicking in any particular 604 /// condition, even if `debug_assertions` are enabled. 605 #[allow(unused)] 606 #[inline(always)] 607 pub(crate) const fn validate_cast_and_convert_metadata( 608 &self, 609 addr: usize, 610 bytes_len: usize, 611 cast_type: CastType, 612 ) -> Result<(usize, usize), MetadataCastError> { 613 // `debug_assert!`, but with `#[allow(clippy::arithmetic_side_effects)]`. 614 macro_rules! __const_debug_assert { 615 ($e:expr $(, $msg:expr)?) => { 616 const_debug_assert!({ 617 #[allow(clippy::arithmetic_side_effects)] 618 let e = $e; 619 e 620 } $(, $msg)?); 621 }; 622 } 623 624 // Note that, in practice, `self` is always a compile-time constant. We 625 // do this check earlier than needed to ensure that we always panic as a 626 // result of bugs in the program (such as calling this function on an 627 // invalid type) instead of allowing this panic to be hidden if the cast 628 // would have failed anyway for runtime reasons (such as a too-small 629 // memory region). 630 // 631 // FIXME(#67): Once our MSRV is 1.65, use let-else: 632 // https://blog.rust-lang.org/2022/11/03/Rust-1.65.0.html#let-else-statements 633 let size_info = match self.size_info.try_to_nonzero_elem_size() { 634 Some(size_info) => size_info, 635 None => const_panic!("attempted to cast to slice type with zero-sized element"), 636 }; 637 638 // Precondition 639 __const_debug_assert!( 640 addr.checked_add(bytes_len).is_some(), 641 "`addr` + `bytes_len` > usize::MAX" 642 ); 643 644 // Alignment checks go in their own block to avoid introducing variables 645 // into the top-level scope. 646 { 647 // We check alignment for `addr` (for prefix casts) or `addr + 648 // bytes_len` (for suffix casts). For a prefix cast, the correctness 649 // of this check is trivial - `addr` is the address the object will 650 // live at. 651 // 652 // For a suffix cast, we know that all valid sizes for the type are 653 // a multiple of the alignment (and by safety precondition, we know 654 // `DstLayout` may only describe valid Rust types). Thus, a 655 // validly-sized instance which lives at a validly-aligned address 656 // must also end at a validly-aligned address. Thus, if the end 657 // address for a suffix cast (`addr + bytes_len`) is not aligned, 658 // then no valid start address will be aligned either. 659 let offset = match cast_type { 660 CastType::Prefix => 0, 661 CastType::Suffix => bytes_len, 662 }; 663 664 // Addition is guaranteed not to overflow because `offset <= 665 // bytes_len`, and `addr + bytes_len <= usize::MAX` is a 666 // precondition of this method. Modulus is guaranteed not to divide 667 // by 0 because `align` is non-zero. 668 #[allow(clippy::arithmetic_side_effects)] 669 if (addr + offset) % self.align.get() != 0 { 670 return Err(MetadataCastError::Alignment); 671 } 672 } 673 674 let (elems, self_bytes) = match size_info { 675 SizeInfo::Sized { size } => { 676 if size > bytes_len { 677 return Err(MetadataCastError::Size); 678 } 679 (0, size) 680 } 681 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => { 682 // Calculate the maximum number of bytes that could be consumed 683 // - any number of bytes larger than this will either not be a 684 // multiple of the alignment, or will be larger than 685 // `bytes_len`. 686 let max_total_bytes = 687 util::round_down_to_next_multiple_of_alignment(bytes_len, self.align); 688 // Calculate the maximum number of bytes that could be consumed 689 // by the trailing slice. 690 // 691 // FIXME(#67): Once our MSRV is 1.65, use let-else: 692 // https://blog.rust-lang.org/2022/11/03/Rust-1.65.0.html#let-else-statements 693 let max_slice_and_padding_bytes = match max_total_bytes.checked_sub(offset) { 694 Some(max) => max, 695 // `bytes_len` too small even for 0 trailing slice elements. 696 None => return Err(MetadataCastError::Size), 697 }; 698 699 // Calculate the number of elements that fit in 700 // `max_slice_and_padding_bytes`; any remaining bytes will be 701 // considered padding. 702 // 703 // Guaranteed not to divide by zero: `elem_size` is non-zero. 704 #[allow(clippy::arithmetic_side_effects)] 705 let elems = max_slice_and_padding_bytes / elem_size.get(); 706 // Guaranteed not to overflow on multiplication: `usize::MAX >= 707 // max_slice_and_padding_bytes >= (max_slice_and_padding_bytes / 708 // elem_size) * elem_size`. 709 // 710 // Guaranteed not to overflow on addition: 711 // - max_slice_and_padding_bytes == max_total_bytes - offset 712 // - elems * elem_size <= max_slice_and_padding_bytes == max_total_bytes - offset 713 // - elems * elem_size + offset <= max_total_bytes <= usize::MAX 714 #[allow(clippy::arithmetic_side_effects)] 715 let without_padding = offset + elems * elem_size.get(); 716 // `self_bytes` is equal to the offset bytes plus the bytes 717 // consumed by the trailing slice plus any padding bytes 718 // required to satisfy the alignment. Note that we have computed 719 // the maximum number of trailing slice elements that could fit 720 // in `self_bytes`, so any padding is guaranteed to be less than 721 // the size of an extra element. 722 // 723 // Guaranteed not to overflow: 724 // - By previous comment: without_padding == elems * elem_size + 725 // offset <= max_total_bytes 726 // - By construction, `max_total_bytes` is a multiple of 727 // `self.align`. 728 // - At most, adding padding needed to round `without_padding` 729 // up to the next multiple of the alignment will bring 730 // `self_bytes` up to `max_total_bytes`. 731 #[allow(clippy::arithmetic_side_effects)] 732 let self_bytes = 733 without_padding + util::padding_needed_for(without_padding, self.align); 734 (elems, self_bytes) 735 } 736 }; 737 738 __const_debug_assert!(self_bytes <= bytes_len); 739 740 let split_at = match cast_type { 741 CastType::Prefix => self_bytes, 742 // Guaranteed not to underflow: 743 // - In the `Sized` branch, only returns `size` if `size <= 744 // bytes_len`. 745 // - In the `SliceDst` branch, calculates `self_bytes <= 746 // max_toatl_bytes`, which is upper-bounded by `bytes_len`. 747 #[allow(clippy::arithmetic_side_effects)] 748 CastType::Suffix => bytes_len - self_bytes, 749 }; 750 751 Ok((elems, split_at)) 752 } 753 } 754 755 pub(crate) use cast_from::CastFrom; 756 mod cast_from { 757 use crate::*; 758 759 pub(crate) struct CastFrom<Dst: ?Sized> { 760 _never: core::convert::Infallible, 761 _marker: PhantomData<Dst>, 762 } 763 764 // SAFETY: The implementation of `Project::project` preserves the address 765 // of the referent – it only modifies pointer metadata. 766 unsafe impl<Src, Dst> crate::pointer::cast::Cast<Src, Dst> for CastFrom<Dst> 767 where 768 Src: KnownLayout + ?Sized, 769 Dst: KnownLayout + ?Sized, 770 { 771 } 772 773 // SAFETY: The implementation of `Project::project` preserves the size of 774 // the referent (see inline comments for a more detailed proof of this). 775 unsafe impl<Src, Dst> crate::pointer::cast::CastExact<Src, Dst> for CastFrom<Dst> 776 where 777 Src: KnownLayout + ?Sized, 778 Dst: KnownLayout + ?Sized, 779 { 780 } 781 782 // SAFETY: `project` produces a pointer which refers to the same referent 783 // bytes as its input, or to a subset of them (see inline comments for a 784 // more detailed proof of this). It does this using provenance-preserving 785 // operations. 786 unsafe impl<Src, Dst> crate::pointer::cast::Project<Src, Dst> for CastFrom<Dst> 787 where 788 Src: KnownLayout + ?Sized, 789 Dst: KnownLayout + ?Sized, 790 { 791 /// # PME 792 /// 793 /// Generates a post-monomorphization error if it is not possible to 794 /// implement soundly. 795 // 796 // FIXME(#1817): Support Sized->Unsized and Unsized->Sized casts 797 fn project(src: PtrInner<'_, Src>) -> *mut Dst { 798 /// The parameters required in order to perform a pointer cast from 799 /// `Src` to `Dst`. 800 /// 801 /// These are a compile-time function of the layouts of `Src` 802 /// and `Dst`. 803 /// 804 /// # Safety 805 /// 806 /// `Src`'s alignment must not be smaller than `Dst`'s alignment. 807 struct CastParams<Src: ?Sized, Dst: ?Sized> { 808 inner: CastParamsInner, 809 _src: PhantomData<Src>, 810 _dst: PhantomData<Dst>, 811 } 812 813 #[derive(Copy, Clone)] 814 enum CastParamsInner { 815 // At compile time (specifically, post-monomorphization time), 816 // we need to compute two things: 817 // - Whether, given *any* `*Src`, it is possible to construct a 818 // `*Dst` which addresses the same number of bytes (ie, 819 // whether, for any `Src` pointer metadata, there exists `Dst` 820 // pointer metadata that addresses the same number of bytes) 821 // - If this is possible, any information necessary to perform 822 // the `Src`->`Dst` metadata conversion at runtime. 823 // 824 // Assume that `Src` and `Dst` are slice DSTs, and define: 825 // - `S_OFF = Src::LAYOUT.size_info.offset` 826 // - `S_ELEM = Src::LAYOUT.size_info.elem_size` 827 // - `D_OFF = Dst::LAYOUT.size_info.offset` 828 // - `D_ELEM = Dst::LAYOUT.size_info.elem_size` 829 // 830 // We are trying to solve the following equation: 831 // 832 // D_OFF + d_meta * D_ELEM = S_OFF + s_meta * S_ELEM 833 // 834 // At runtime, we will be attempting to compute `d_meta`, given 835 // `s_meta` (a runtime value) and all other parameters (which 836 // are compile-time values). We can solve like so: 837 // 838 // D_OFF + d_meta * D_ELEM = S_OFF + s_meta * S_ELEM 839 // 840 // d_meta * D_ELEM = S_OFF - D_OFF + s_meta * S_ELEM 841 // 842 // d_meta = (S_OFF - D_OFF + s_meta * S_ELEM)/D_ELEM 843 // 844 // Since `d_meta` will be a `usize`, we need the right-hand side 845 // to be an integer, and this needs to hold for *any* value of 846 // `s_meta` (in order for our conversion to be infallible - ie, 847 // to not have to reject certain values of `s_meta` at runtime). 848 // This means that: 849 // 850 // - `s_meta * S_ELEM` must be a multiple of `D_ELEM` 851 // - Since this must hold for any value of `s_meta`, `S_ELEM` 852 // must be a multiple of `D_ELEM` 853 // - `S_OFF - D_OFF` must be a multiple of `D_ELEM` 854 // 855 // Thus, let `OFFSET_DELTA_ELEMS = (S_OFF - D_OFF)/D_ELEM` and 856 // `ELEM_MULTIPLE = S_ELEM/D_ELEM`. We can rewrite the above 857 // expression as: 858 // 859 // d_meta = (S_OFF - D_OFF + s_meta * S_ELEM)/D_ELEM 860 // 861 // d_meta = OFFSET_DELTA_ELEMS + s_meta * ELEM_MULTIPLE 862 // 863 // Thus, we just need to compute the following and confirm that 864 // they have integer solutions in order to both a) determine 865 // whether infallible `Src` -> `Dst` casts are possible and, b) 866 // pre-compute the parameters necessary to perform those casts 867 // at runtime. These parameters are encapsulated in 868 // `CastParams`, which acts as a witness that such infallible 869 // casts are possible. 870 /// The parameters required in order to perform an 871 /// unsized-to-unsized pointer cast from `Src` to `Dst` as 872 /// described above. 873 /// 874 /// # Safety 875 /// 876 /// `Src` and `Dst` must both be slice DSTs. 877 /// 878 /// `offset_delta_elems` and `elem_multiple` must be valid as 879 /// described above. 880 UnsizedToUnsized { offset_delta_elems: usize, elem_multiple: usize }, 881 882 /// The metadata of a `Dst` which has the same size as `Src: 883 /// Sized`. 884 /// 885 /// # Safety 886 /// 887 /// `Src: Sized` and `Dst` must be a slice DST. 888 /// 889 /// A raw `Dst` pointer with metadata `dst_meta` must address 890 /// `size_of::<Src>()` bytes. 891 SizedToUnsized { dst_meta: usize }, 892 893 /// The metadata of a `Dst` which has the same size as `Src: 894 /// Sized`. 895 /// 896 /// # Safety 897 /// 898 /// `Src` and `Dst` must both be `Sized` and `size_of::<Src>() 899 /// == size_of::<Dst>()`. 900 SizedToSized, 901 } 902 903 impl<Src: ?Sized, Dst: ?Sized> Copy for CastParams<Src, Dst> {} 904 impl<Src: ?Sized, Dst: ?Sized> Clone for CastParams<Src, Dst> { 905 fn clone(&self) -> Self { 906 *self 907 } 908 } 909 910 impl<Src: ?Sized, Dst: ?Sized> CastParams<Src, Dst> { 911 const fn try_compute( 912 src: &DstLayout, 913 dst: &DstLayout, 914 ) -> Option<CastParams<Src, Dst>> { 915 if src.align.get() < dst.align.get() { 916 return None; 917 } 918 919 let inner = match (src.size_info, dst.size_info) { 920 ( 921 SizeInfo::Sized { size: src_size }, 922 SizeInfo::Sized { size: dst_size }, 923 ) => { 924 if src_size != dst_size { 925 return None; 926 } 927 928 // SAFETY: We checked above that `src_size == 929 // dst_size`. 930 CastParamsInner::SizedToSized 931 } 932 (SizeInfo::Sized { size: src_size }, SizeInfo::SliceDst(dst)) => { 933 let offset_delta = if let Some(od) = src_size.checked_sub(dst.offset) { 934 od 935 } else { 936 return None; 937 }; 938 939 let dst_elem_size = if let Some(e) = NonZeroUsize::new(dst.elem_size) { 940 e 941 } else { 942 return None; 943 }; 944 945 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 946 // divide by zero. 947 #[allow(clippy::arithmetic_side_effects)] 948 let delta_mod_other_elem = offset_delta % dst_elem_size.get(); 949 950 if delta_mod_other_elem != 0 { 951 return None; 952 } 953 954 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 955 // divide by zero. 956 #[allow(clippy::arithmetic_side_effects)] 957 let dst_meta = offset_delta / dst_elem_size.get(); 958 959 // SAFETY: The preceding math ensures that a `Dst` 960 // with `dst_meta` addresses `src_size` bytes. 961 CastParamsInner::SizedToUnsized { dst_meta } 962 } 963 (SizeInfo::SliceDst(src), SizeInfo::SliceDst(dst)) => { 964 let offset_delta = if let Some(od) = src.offset.checked_sub(dst.offset) 965 { 966 od 967 } else { 968 return None; 969 }; 970 971 let dst_elem_size = if let Some(e) = NonZeroUsize::new(dst.elem_size) { 972 e 973 } else { 974 return None; 975 }; 976 977 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 978 // divide by zero. 979 #[allow(clippy::arithmetic_side_effects)] 980 let delta_mod_other_elem = offset_delta % dst_elem_size.get(); 981 982 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 983 // divide by zero. 984 #[allow(clippy::arithmetic_side_effects)] 985 let elem_remainder = src.elem_size % dst_elem_size.get(); 986 987 if delta_mod_other_elem != 0 988 || src.elem_size < dst.elem_size 989 || elem_remainder != 0 990 { 991 return None; 992 } 993 994 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 995 // divide by zero. 996 #[allow(clippy::arithmetic_side_effects)] 997 let offset_delta_elems = offset_delta / dst_elem_size.get(); 998 999 // PANICS: `dst_elem_size: NonZeroUsize`, so this won't 1000 // divide by zero. 1001 #[allow(clippy::arithmetic_side_effects)] 1002 let elem_multiple = src.elem_size / dst_elem_size.get(); 1003 1004 CastParamsInner::UnsizedToUnsized { 1005 // SAFETY: We checked above that this is an exact ratio. 1006 offset_delta_elems, 1007 // SAFETY: We checked above that this is an exact ratio. 1008 elem_multiple, 1009 } 1010 } 1011 _ => return None, 1012 }; 1013 1014 // SAFETY: We checked above that `src.align >= dst.align`. 1015 Some(CastParams { inner, _src: PhantomData, _dst: PhantomData }) 1016 } 1017 } 1018 1019 impl<Src: KnownLayout + ?Sized, Dst: KnownLayout + ?Sized> CastParams<Src, Dst> { 1020 /// # Safety 1021 /// 1022 /// `src_meta` describes a `Src` whose size is no larger than 1023 /// `isize::MAX`. 1024 /// 1025 /// The returned metadata describes a `Dst` of the same size as 1026 /// the original `Src`. 1027 #[inline(always)] 1028 unsafe fn cast_metadata( 1029 self, 1030 src_meta: Src::PointerMetadata, 1031 ) -> Dst::PointerMetadata { 1032 #[allow(unused)] 1033 use crate::util::polyfills::*; 1034 1035 let dst_meta = match self.inner { 1036 CastParamsInner::UnsizedToUnsized { offset_delta_elems, elem_multiple } => { 1037 let src_meta = src_meta.to_elem_count(); 1038 #[allow( 1039 unstable_name_collisions, 1040 clippy::multiple_unsafe_ops_per_block 1041 )] 1042 // SAFETY: `self` is a witness that the following 1043 // equation holds: 1044 // 1045 // D_OFF + d_meta * D_ELEM = S_OFF + s_meta * S_ELEM 1046 // 1047 // Since the caller promises that `src_meta` is 1048 // valid `Src` metadata, this math will not 1049 // overflow, and the returned value will describe a 1050 // `Dst` of the same size. 1051 unsafe { 1052 offset_delta_elems 1053 .unchecked_add(src_meta.unchecked_mul(elem_multiple)) 1054 } 1055 } 1056 CastParamsInner::SizedToUnsized { dst_meta } => dst_meta, 1057 CastParamsInner::SizedToSized => 0, 1058 }; 1059 Dst::PointerMetadata::from_elem_count(dst_meta) 1060 } 1061 } 1062 1063 trait Params<Src: ?Sized> { 1064 const CAST_PARAMS: CastParams<Src, Self>; 1065 } 1066 1067 impl<Src, Dst> Params<Src> for Dst 1068 where 1069 Src: KnownLayout + ?Sized, 1070 Dst: KnownLayout + ?Sized, 1071 { 1072 const CAST_PARAMS: CastParams<Src, Dst> = 1073 match CastParams::try_compute(&Src::LAYOUT, &Dst::LAYOUT) { 1074 Some(params) => params, 1075 None => const_panic!( 1076 "cannot `transmute_ref!` or `transmute_mut!` between incompatible types" 1077 ), 1078 }; 1079 } 1080 1081 let src_meta = <Src as KnownLayout>::pointer_to_metadata(src.as_ptr()); 1082 let params = <Dst as Params<Src>>::CAST_PARAMS; 1083 1084 // SAFETY: `src: PtrInner` guarantees that `src`'s referent is zero 1085 // bytes or lives in a single allocation, which means that it is no 1086 // larger than `isize::MAX` bytes [1]. 1087 // 1088 // [1] https://doc.rust-lang.org/1.92.0/std/ptr/index.html#allocation 1089 let dst_meta = unsafe { params.cast_metadata(src_meta) }; 1090 1091 <Dst as KnownLayout>::raw_from_ptr_len(src.as_non_null().cast(), dst_meta).as_ptr() 1092 } 1093 } 1094 } 1095 1096 // FIXME(#67): For some reason, on our MSRV toolchain, this `allow` isn't 1097 // enforced despite having `#![allow(unknown_lints)]` at the crate root, but 1098 // putting it here works. Once our MSRV is high enough that this bug has been 1099 // fixed, remove this `allow`. 1100 #[allow(unknown_lints)] 1101 #[cfg(test)] 1102 mod tests { 1103 use super::*; 1104 1105 #[test] 1106 fn test_dst_layout_for_slice() { 1107 let layout = DstLayout::for_slice::<u32>(); 1108 match layout.size_info { 1109 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => { 1110 assert_eq!(offset, 0); 1111 assert_eq!(elem_size, 4); 1112 } 1113 _ => panic!("Expected SliceDst"), 1114 } 1115 assert_eq!(layout.align.get(), 4); 1116 } 1117 1118 /// Tests of when a sized `DstLayout` is extended with a sized field. 1119 #[allow(clippy::decimal_literal_representation)] 1120 #[test] 1121 fn test_dst_layout_extend_sized_with_sized() { 1122 // This macro constructs a layout corresponding to a `u8` and extends it 1123 // with a zero-sized trailing field of given alignment `n`. The macro 1124 // tests that the resulting layout has both size and alignment `min(n, 1125 // P)` for all valid values of `repr(packed(P))`. 1126 macro_rules! test_align_is_size { 1127 ($n:expr) => { 1128 let base = DstLayout::for_type::<u8>(); 1129 let trailing_field = DstLayout::for_type::<elain::Align<$n>>(); 1130 1131 let packs = 1132 core::iter::once(None).chain((0..29).map(|p| NonZeroUsize::new(2usize.pow(p)))); 1133 1134 for pack in packs { 1135 let composite = base.extend(trailing_field, pack); 1136 let max_align = pack.unwrap_or(DstLayout::CURRENT_MAX_ALIGN); 1137 let align = $n.min(max_align.get()); 1138 assert_eq!( 1139 composite, 1140 DstLayout { 1141 align: NonZeroUsize::new(align).unwrap(), 1142 size_info: SizeInfo::Sized { size: align }, 1143 statically_shallow_unpadded: false, 1144 } 1145 ) 1146 } 1147 }; 1148 } 1149 1150 test_align_is_size!(1); 1151 test_align_is_size!(2); 1152 test_align_is_size!(4); 1153 test_align_is_size!(8); 1154 test_align_is_size!(16); 1155 test_align_is_size!(32); 1156 test_align_is_size!(64); 1157 test_align_is_size!(128); 1158 test_align_is_size!(256); 1159 test_align_is_size!(512); 1160 test_align_is_size!(1024); 1161 test_align_is_size!(2048); 1162 test_align_is_size!(4096); 1163 test_align_is_size!(8192); 1164 test_align_is_size!(16384); 1165 test_align_is_size!(32768); 1166 test_align_is_size!(65536); 1167 test_align_is_size!(131072); 1168 test_align_is_size!(262144); 1169 test_align_is_size!(524288); 1170 test_align_is_size!(1048576); 1171 test_align_is_size!(2097152); 1172 test_align_is_size!(4194304); 1173 test_align_is_size!(8388608); 1174 test_align_is_size!(16777216); 1175 test_align_is_size!(33554432); 1176 test_align_is_size!(67108864); 1177 test_align_is_size!(33554432); 1178 test_align_is_size!(134217728); 1179 test_align_is_size!(268435456); 1180 } 1181 1182 /// Tests of when a sized `DstLayout` is extended with a DST field. 1183 #[test] 1184 fn test_dst_layout_extend_sized_with_dst() { 1185 // Test that for all combinations of real-world alignments and 1186 // `repr_packed` values, that the extension of a sized `DstLayout`` with 1187 // a DST field correctly computes the trailing offset in the composite 1188 // layout. 1189 1190 let aligns = (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap()); 1191 let packs = core::iter::once(None).chain(aligns.clone().map(Some)); 1192 1193 for align in aligns { 1194 for pack in packs.clone() { 1195 let base = DstLayout::for_type::<u8>(); 1196 let elem_size = 42; 1197 let trailing_field_offset = 11; 1198 1199 let trailing_field = DstLayout { 1200 align, 1201 size_info: SizeInfo::SliceDst(TrailingSliceLayout { elem_size, offset: 11 }), 1202 statically_shallow_unpadded: false, 1203 }; 1204 1205 let composite = base.extend(trailing_field, pack); 1206 1207 let max_align = pack.unwrap_or(DstLayout::CURRENT_MAX_ALIGN).get(); 1208 1209 let align = align.get().min(max_align); 1210 1211 assert_eq!( 1212 composite, 1213 DstLayout { 1214 align: NonZeroUsize::new(align).unwrap(), 1215 size_info: SizeInfo::SliceDst(TrailingSliceLayout { 1216 elem_size, 1217 offset: align + trailing_field_offset, 1218 }), 1219 statically_shallow_unpadded: false, 1220 } 1221 ) 1222 } 1223 } 1224 } 1225 1226 /// Tests that calling `pad_to_align` on a sized `DstLayout` adds the 1227 /// expected amount of trailing padding. 1228 #[test] 1229 fn test_dst_layout_pad_to_align_with_sized() { 1230 // For all valid alignments `align`, construct a one-byte layout aligned 1231 // to `align`, call `pad_to_align`, and assert that the size of the 1232 // resulting layout is equal to `align`. 1233 for align in (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap()) { 1234 let layout = DstLayout { 1235 align, 1236 size_info: SizeInfo::Sized { size: 1 }, 1237 statically_shallow_unpadded: true, 1238 }; 1239 1240 assert_eq!( 1241 layout.pad_to_align(), 1242 DstLayout { 1243 align, 1244 size_info: SizeInfo::Sized { size: align.get() }, 1245 statically_shallow_unpadded: align.get() == 1 1246 } 1247 ); 1248 } 1249 1250 // Test explicitly-provided combinations of unpadded and padded 1251 // counterparts. 1252 1253 macro_rules! test { 1254 (unpadded { size: $unpadded_size:expr, align: $unpadded_align:expr } 1255 => padded { size: $padded_size:expr, align: $padded_align:expr }) => { 1256 let unpadded = DstLayout { 1257 align: NonZeroUsize::new($unpadded_align).unwrap(), 1258 size_info: SizeInfo::Sized { size: $unpadded_size }, 1259 statically_shallow_unpadded: false, 1260 }; 1261 let padded = unpadded.pad_to_align(); 1262 1263 assert_eq!( 1264 padded, 1265 DstLayout { 1266 align: NonZeroUsize::new($padded_align).unwrap(), 1267 size_info: SizeInfo::Sized { size: $padded_size }, 1268 statically_shallow_unpadded: false, 1269 } 1270 ); 1271 }; 1272 } 1273 1274 test!(unpadded { size: 0, align: 4 } => padded { size: 0, align: 4 }); 1275 test!(unpadded { size: 1, align: 4 } => padded { size: 4, align: 4 }); 1276 test!(unpadded { size: 2, align: 4 } => padded { size: 4, align: 4 }); 1277 test!(unpadded { size: 3, align: 4 } => padded { size: 4, align: 4 }); 1278 test!(unpadded { size: 4, align: 4 } => padded { size: 4, align: 4 }); 1279 test!(unpadded { size: 5, align: 4 } => padded { size: 8, align: 4 }); 1280 test!(unpadded { size: 6, align: 4 } => padded { size: 8, align: 4 }); 1281 test!(unpadded { size: 7, align: 4 } => padded { size: 8, align: 4 }); 1282 test!(unpadded { size: 8, align: 4 } => padded { size: 8, align: 4 }); 1283 1284 let current_max_align = DstLayout::CURRENT_MAX_ALIGN.get(); 1285 1286 test!(unpadded { size: 1, align: current_max_align } 1287 => padded { size: current_max_align, align: current_max_align }); 1288 1289 test!(unpadded { size: current_max_align + 1, align: current_max_align } 1290 => padded { size: current_max_align * 2, align: current_max_align }); 1291 } 1292 1293 /// Tests that calling `pad_to_align` on a DST `DstLayout` is a no-op. 1294 #[test] 1295 fn test_dst_layout_pad_to_align_with_dst() { 1296 for align in (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap()) { 1297 for offset in 0..10 { 1298 for elem_size in 0..10 { 1299 let layout = DstLayout { 1300 align, 1301 size_info: SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }), 1302 statically_shallow_unpadded: false, 1303 }; 1304 assert_eq!(layout.pad_to_align(), layout); 1305 } 1306 } 1307 } 1308 } 1309 1310 // This test takes a long time when running under Miri, so we skip it in 1311 // that case. This is acceptable because this is a logic test that doesn't 1312 // attempt to expose UB. 1313 #[test] 1314 #[cfg_attr(miri, ignore)] 1315 fn test_validate_cast_and_convert_metadata() { 1316 #[allow(non_local_definitions)] 1317 impl From<usize> for SizeInfo { 1318 fn from(size: usize) -> SizeInfo { 1319 SizeInfo::Sized { size } 1320 } 1321 } 1322 1323 #[allow(non_local_definitions)] 1324 impl From<(usize, usize)> for SizeInfo { 1325 fn from((offset, elem_size): (usize, usize)) -> SizeInfo { 1326 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) 1327 } 1328 } 1329 1330 fn layout<S: Into<SizeInfo>>(s: S, align: usize) -> DstLayout { 1331 DstLayout { 1332 size_info: s.into(), 1333 align: NonZeroUsize::new(align).unwrap(), 1334 statically_shallow_unpadded: false, 1335 } 1336 } 1337 1338 /// This macro accepts arguments in the form of: 1339 /// 1340 /// layout(_, _).validate(_, _, _), Ok(Some((_, _))) 1341 /// | | | | | | | 1342 /// size ---------+ | | | | | | 1343 /// align -----------+ | | | | | 1344 /// addr ------------------------+ | | | | 1345 /// bytes_len ----------------------+ | | | 1346 /// cast_type -------------------------+ | | 1347 /// elems ------------------------------------------+ | 1348 /// split_at ------------------------------------------+ 1349 /// 1350 /// `.validate` is shorthand for `.validate_cast_and_convert_metadata` 1351 /// for brevity. 1352 /// 1353 /// Each argument can either be an iterator or a wildcard. Each 1354 /// wildcarded variable is implicitly replaced by an iterator over a 1355 /// representative sample of values for that variable. Each `test!` 1356 /// invocation iterates over every combination of values provided by 1357 /// each variable's iterator (ie, the cartesian product) and validates 1358 /// that the results are expected. 1359 /// 1360 /// The final argument uses the same syntax, but it has a different 1361 /// meaning: 1362 /// - If it is `Ok(pat)`, then the pattern `pat` is supplied to 1363 /// a matching assert to validate the computed result for each 1364 /// combination of input values. 1365 /// - If it is `Err(Some(msg) | None)`, then `test!` validates that the 1366 /// call to `validate_cast_and_convert_metadata` panics with the given 1367 /// panic message or, if the current Rust toolchain version is too 1368 /// early to support panicking in `const fn`s, panics with *some* 1369 /// message. In the latter case, the `const_panic!` macro is used, 1370 /// which emits code which causes a non-panicking error at const eval 1371 /// time, but which does panic when invoked at runtime. Thus, it is 1372 /// merely difficult to predict the *value* of this panic. We deem 1373 /// that testing against the real panic strings on stable and nightly 1374 /// toolchains is enough to ensure correctness. 1375 /// 1376 /// Note that the meta-variables that match these variables have the 1377 /// `tt` type, and some valid expressions are not valid `tt`s (such as 1378 /// `a..b`). In this case, wrap the expression in parentheses, and it 1379 /// will become valid `tt`. 1380 macro_rules! test { 1381 ( 1382 layout($size:tt, $align:tt) 1383 .validate($addr:tt, $bytes_len:tt, $cast_type:tt), $expect:pat $(,)? 1384 ) => { 1385 itertools::iproduct!( 1386 test!(@generate_size $size), 1387 test!(@generate_align $align), 1388 test!(@generate_usize $addr), 1389 test!(@generate_usize $bytes_len), 1390 test!(@generate_cast_type $cast_type) 1391 ).for_each(|(size_info, align, addr, bytes_len, cast_type)| { 1392 // Temporarily disable the panic hook installed by the test 1393 // harness. If we don't do this, all panic messages will be 1394 // kept in an internal log. On its own, this isn't a 1395 // problem, but if a non-caught panic ever happens (ie, in 1396 // code later in this test not in this macro), all of the 1397 // previously-buffered messages will be dumped, hiding the 1398 // real culprit. 1399 let previous_hook = std::panic::take_hook(); 1400 // I don't understand why, but this seems to be required in 1401 // addition to the previous line. 1402 std::panic::set_hook(Box::new(|_| {})); 1403 let actual = std::panic::catch_unwind(|| { 1404 layout(size_info, align).validate_cast_and_convert_metadata(addr, bytes_len, cast_type) 1405 }).map_err(|d| { 1406 let msg = d.downcast::<&'static str>().ok().map(|s| *s.as_ref()); 1407 assert!(msg.is_some() || cfg!(no_zerocopy_panic_in_const_and_vec_try_reserve_1_57_0), "non-string panic messages are not permitted when usage of panic in const fn is enabled"); 1408 msg 1409 }); 1410 std::panic::set_hook(previous_hook); 1411 1412 assert!( 1413 matches!(actual, $expect), 1414 "layout({:?}, {}).validate_cast_and_convert_metadata({}, {}, {:?})" ,size_info, align, addr, bytes_len, cast_type 1415 ); 1416 }); 1417 }; 1418 (@generate_usize _) => { 0..8 }; 1419 // Generate sizes for both Sized and !Sized types. 1420 (@generate_size _) => { 1421 test!(@generate_size (_)).chain(test!(@generate_size (_, _))) 1422 }; 1423 // Generate sizes for both Sized and !Sized types by chaining 1424 // specified iterators for each. 1425 (@generate_size ($sized_sizes:tt | $unsized_sizes:tt)) => { 1426 test!(@generate_size ($sized_sizes)).chain(test!(@generate_size $unsized_sizes)) 1427 }; 1428 // Generate sizes for Sized types. 1429 (@generate_size (_)) => { test!(@generate_size (0..8)) }; 1430 (@generate_size ($sizes:expr)) => { $sizes.into_iter().map(Into::<SizeInfo>::into) }; 1431 // Generate sizes for !Sized types. 1432 (@generate_size ($min_sizes:tt, $elem_sizes:tt)) => { 1433 itertools::iproduct!( 1434 test!(@generate_min_size $min_sizes), 1435 test!(@generate_elem_size $elem_sizes) 1436 ).map(Into::<SizeInfo>::into) 1437 }; 1438 (@generate_fixed_size _) => { (0..8).into_iter().map(Into::<SizeInfo>::into) }; 1439 (@generate_min_size _) => { 0..8 }; 1440 (@generate_elem_size _) => { 1..8 }; 1441 (@generate_align _) => { [1, 2, 4, 8, 16] }; 1442 (@generate_opt_usize _) => { [None].into_iter().chain((0..8).map(Some).into_iter()) }; 1443 (@generate_cast_type _) => { [CastType::Prefix, CastType::Suffix] }; 1444 (@generate_cast_type $variant:ident) => { [CastType::$variant] }; 1445 // Some expressions need to be wrapped in parentheses in order to be 1446 // valid `tt`s (required by the top match pattern). See the comment 1447 // below for more details. This arm removes these parentheses to 1448 // avoid generating an `unused_parens` warning. 1449 (@$_:ident ($vals:expr)) => { $vals }; 1450 (@$_:ident $vals:expr) => { $vals }; 1451 } 1452 1453 const EVENS: [usize; 8] = [0, 2, 4, 6, 8, 10, 12, 14]; 1454 const ODDS: [usize; 8] = [1, 3, 5, 7, 9, 11, 13, 15]; 1455 1456 // base_size is too big for the memory region. 1457 test!( 1458 layout(((1..8) | ((1..8), (1..8))), _).validate([0], [0], _), 1459 Ok(Err(MetadataCastError::Size)) 1460 ); 1461 test!( 1462 layout(((2..8) | ((2..8), (2..8))), _).validate([0], [1], Prefix), 1463 Ok(Err(MetadataCastError::Size)) 1464 ); 1465 test!( 1466 layout(((2..8) | ((2..8), (2..8))), _).validate([0x1000_0000 - 1], [1], Suffix), 1467 Ok(Err(MetadataCastError::Size)) 1468 ); 1469 1470 // addr is unaligned for prefix cast 1471 test!(layout(_, [2]).validate(ODDS, _, Prefix), Ok(Err(MetadataCastError::Alignment))); 1472 test!(layout(_, [2]).validate(ODDS, _, Prefix), Ok(Err(MetadataCastError::Alignment))); 1473 1474 // addr is aligned, but end of buffer is unaligned for suffix cast 1475 test!(layout(_, [2]).validate(EVENS, ODDS, Suffix), Ok(Err(MetadataCastError::Alignment))); 1476 test!(layout(_, [2]).validate(EVENS, ODDS, Suffix), Ok(Err(MetadataCastError::Alignment))); 1477 1478 // Unfortunately, these constants cannot easily be used in the 1479 // implementation of `validate_cast_and_convert_metadata`, since 1480 // `panic!` consumes a string literal, not an expression. 1481 // 1482 // It's important that these messages be in a separate module. If they 1483 // were at the function's top level, we'd pass them to `test!` as, e.g., 1484 // `Err(TRAILING)`, which would run into a subtle Rust footgun - the 1485 // `TRAILING` identifier would be treated as a pattern to match rather 1486 // than a value to check for equality. 1487 mod msgs { 1488 pub(super) const TRAILING: &str = 1489 "attempted to cast to slice type with zero-sized element"; 1490 pub(super) const OVERFLOW: &str = "`addr` + `bytes_len` > usize::MAX"; 1491 } 1492 1493 // casts with ZST trailing element types are unsupported 1494 test!(layout((_, [0]), _).validate(_, _, _), Err(Some(msgs::TRAILING) | None),); 1495 1496 // addr + bytes_len must not overflow usize 1497 test!(layout(_, _).validate([usize::MAX], (1..100), _), Err(Some(msgs::OVERFLOW) | None)); 1498 test!(layout(_, _).validate((1..100), [usize::MAX], _), Err(Some(msgs::OVERFLOW) | None)); 1499 test!( 1500 layout(_, _).validate( 1501 [usize::MAX / 2 + 1, usize::MAX], 1502 [usize::MAX / 2 + 1, usize::MAX], 1503 _ 1504 ), 1505 Err(Some(msgs::OVERFLOW) | None) 1506 ); 1507 1508 // Validates that `validate_cast_and_convert_metadata` satisfies its own 1509 // documented safety postconditions, and also a few other properties 1510 // that aren't documented but we want to guarantee anyway. 1511 fn validate_behavior( 1512 (layout, addr, bytes_len, cast_type): (DstLayout, usize, usize, CastType), 1513 ) { 1514 if let Ok((elems, split_at)) = 1515 layout.validate_cast_and_convert_metadata(addr, bytes_len, cast_type) 1516 { 1517 let (size_info, align) = (layout.size_info, layout.align); 1518 let debug_str = format!( 1519 "layout({:?}, {}).validate_cast_and_convert_metadata({}, {}, {:?}) => ({}, {})", 1520 size_info, align, addr, bytes_len, cast_type, elems, split_at 1521 ); 1522 1523 // If this is a sized type (no trailing slice), then `elems` is 1524 // meaningless, but in practice we set it to 0. Callers are not 1525 // allowed to rely on this, but a lot of math is nicer if 1526 // they're able to, and some callers might accidentally do that. 1527 let sized = matches!(layout.size_info, SizeInfo::Sized { .. }); 1528 assert!(!(sized && elems != 0), "{}", debug_str); 1529 1530 let resulting_size = match layout.size_info { 1531 SizeInfo::Sized { size } => size, 1532 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => { 1533 let padded_size = |elems| { 1534 let without_padding = offset + elems * elem_size; 1535 without_padding + util::padding_needed_for(without_padding, align) 1536 }; 1537 1538 let resulting_size = padded_size(elems); 1539 // Test that `validate_cast_and_convert_metadata` 1540 // computed the largest possible value that fits in the 1541 // given range. 1542 assert!(padded_size(elems + 1) > bytes_len, "{}", debug_str); 1543 resulting_size 1544 } 1545 }; 1546 1547 // Test safety postconditions guaranteed by 1548 // `validate_cast_and_convert_metadata`. 1549 assert!(resulting_size <= bytes_len, "{}", debug_str); 1550 match cast_type { 1551 CastType::Prefix => { 1552 assert_eq!(addr % align, 0, "{}", debug_str); 1553 assert_eq!(resulting_size, split_at, "{}", debug_str); 1554 } 1555 CastType::Suffix => { 1556 assert_eq!(split_at, bytes_len - resulting_size, "{}", debug_str); 1557 assert_eq!((addr + split_at) % align, 0, "{}", debug_str); 1558 } 1559 } 1560 } else { 1561 let min_size = match layout.size_info { 1562 SizeInfo::Sized { size } => size, 1563 SizeInfo::SliceDst(TrailingSliceLayout { offset, .. }) => { 1564 offset + util::padding_needed_for(offset, layout.align) 1565 } 1566 }; 1567 1568 // If a cast is invalid, it is either because... 1569 // 1. there are insufficient bytes at the given region for type: 1570 let insufficient_bytes = bytes_len < min_size; 1571 // 2. performing the cast would misalign type: 1572 let base = match cast_type { 1573 CastType::Prefix => 0, 1574 CastType::Suffix => bytes_len, 1575 }; 1576 let misaligned = (base + addr) % layout.align != 0; 1577 1578 assert!(insufficient_bytes || misaligned); 1579 } 1580 } 1581 1582 let sizes = 0..8; 1583 let elem_sizes = 1..8; 1584 let size_infos = sizes 1585 .clone() 1586 .map(Into::<SizeInfo>::into) 1587 .chain(itertools::iproduct!(sizes, elem_sizes).map(Into::<SizeInfo>::into)); 1588 let layouts = itertools::iproduct!(size_infos, [1, 2, 4, 8, 16, 32]) 1589 .filter(|(size_info, align)| !matches!(size_info, SizeInfo::Sized { size } if size % align != 0)) 1590 .map(|(size_info, align)| layout(size_info, align)); 1591 itertools::iproduct!(layouts, 0..8, 0..8, [CastType::Prefix, CastType::Suffix]) 1592 .for_each(validate_behavior); 1593 } 1594 1595 #[test] 1596 #[cfg(__ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS)] 1597 fn test_validate_rust_layout() { 1598 use core::{ 1599 convert::TryInto as _, 1600 ptr::{self, NonNull}, 1601 }; 1602 1603 use crate::util::testutil::*; 1604 1605 // This test synthesizes pointers with various metadata and uses Rust's 1606 // built-in APIs to confirm that Rust makes decisions about type layout 1607 // which are consistent with what we believe is guaranteed by the 1608 // language. If this test fails, it doesn't just mean our code is wrong 1609 // - it means we're misunderstanding the language's guarantees. 1610 1611 #[derive(Debug)] 1612 struct MacroArgs { 1613 offset: usize, 1614 align: NonZeroUsize, 1615 elem_size: Option<usize>, 1616 } 1617 1618 /// # Safety 1619 /// 1620 /// `test` promises to only call `addr_of_slice_field` on a `NonNull<T>` 1621 /// which points to a valid `T`. 1622 /// 1623 /// `with_elems` must produce a pointer which points to a valid `T`. 1624 fn test<T: ?Sized, W: Fn(usize) -> NonNull<T>>( 1625 args: MacroArgs, 1626 with_elems: W, 1627 addr_of_slice_field: Option<fn(NonNull<T>) -> NonNull<u8>>, 1628 ) { 1629 let dst = args.elem_size.is_some(); 1630 let layout = { 1631 let size_info = match args.elem_size { 1632 Some(elem_size) => { 1633 SizeInfo::SliceDst(TrailingSliceLayout { offset: args.offset, elem_size }) 1634 } 1635 None => SizeInfo::Sized { 1636 // Rust only supports types whose sizes are a multiple 1637 // of their alignment. If the macro created a type like 1638 // this: 1639 // 1640 // #[repr(C, align(2))] 1641 // struct Foo([u8; 1]); 1642 // 1643 // ...then Rust will automatically round the type's size 1644 // up to 2. 1645 size: args.offset + util::padding_needed_for(args.offset, args.align), 1646 }, 1647 }; 1648 DstLayout { size_info, align: args.align, statically_shallow_unpadded: false } 1649 }; 1650 1651 for elems in 0..128 { 1652 let ptr = with_elems(elems); 1653 1654 if let Some(addr_of_slice_field) = addr_of_slice_field { 1655 let slc_field_ptr = addr_of_slice_field(ptr).as_ptr(); 1656 // SAFETY: Both `slc_field_ptr` and `ptr` are pointers to 1657 // the same valid Rust object. 1658 // Work around https://github.com/rust-lang/rust-clippy/issues/12280 1659 let offset: usize = 1660 unsafe { slc_field_ptr.byte_offset_from(ptr.as_ptr()).try_into().unwrap() }; 1661 assert_eq!(offset, args.offset); 1662 } 1663 1664 // SAFETY: `ptr` points to a valid `T`. 1665 #[allow(clippy::multiple_unsafe_ops_per_block)] 1666 let (size, align) = unsafe { 1667 (mem::size_of_val_raw(ptr.as_ptr()), mem::align_of_val_raw(ptr.as_ptr())) 1668 }; 1669 1670 // Avoid expensive allocation when running under Miri. 1671 let assert_msg = if !cfg!(miri) { 1672 format!("\n{:?}\nsize:{}, align:{}", args, size, align) 1673 } else { 1674 String::new() 1675 }; 1676 1677 let without_padding = 1678 args.offset + args.elem_size.map(|elem_size| elems * elem_size).unwrap_or(0); 1679 assert!(size >= without_padding, "{}", assert_msg); 1680 assert_eq!(align, args.align.get(), "{}", assert_msg); 1681 1682 // This encodes the most important part of the test: our 1683 // understanding of how Rust determines the layout of repr(C) 1684 // types. Sized repr(C) types are trivial, but DST types have 1685 // some subtlety. Note that: 1686 // - For sized types, `without_padding` is just the size of the 1687 // type that we constructed for `Foo`. Since we may have 1688 // requested a larger alignment, `Foo` may actually be larger 1689 // than this, hence `padding_needed_for`. 1690 // - For unsized types, `without_padding` is dynamically 1691 // computed from the offset, the element size, and element 1692 // count. We expect that the size of the object should be 1693 // `offset + elem_size * elems` rounded up to the next 1694 // alignment. 1695 let expected_size = 1696 without_padding + util::padding_needed_for(without_padding, args.align); 1697 assert_eq!(expected_size, size, "{}", assert_msg); 1698 1699 // For zero-sized element types, 1700 // `validate_cast_and_convert_metadata` just panics, so we skip 1701 // testing those types. 1702 if args.elem_size.map(|elem_size| elem_size > 0).unwrap_or(true) { 1703 let addr = ptr.addr().get(); 1704 let (got_elems, got_split_at) = layout 1705 .validate_cast_and_convert_metadata(addr, size, CastType::Prefix) 1706 .unwrap(); 1707 // Avoid expensive allocation when running under Miri. 1708 let assert_msg = if !cfg!(miri) { 1709 format!( 1710 "{}\nvalidate_cast_and_convert_metadata({}, {})", 1711 assert_msg, addr, size, 1712 ) 1713 } else { 1714 String::new() 1715 }; 1716 assert_eq!(got_split_at, size, "{}", assert_msg); 1717 if dst { 1718 assert!(got_elems >= elems, "{}", assert_msg); 1719 if got_elems != elems { 1720 // If `validate_cast_and_convert_metadata` 1721 // returned more elements than `elems`, that 1722 // means that `elems` is not the maximum number 1723 // of elements that can fit in `size` - in other 1724 // words, there is enough padding at the end of 1725 // the value to fit at least one more element. 1726 // If we use this metadata to synthesize a 1727 // pointer, despite having a different element 1728 // count, we still expect it to have the same 1729 // size. 1730 let got_ptr = with_elems(got_elems); 1731 // SAFETY: `got_ptr` is a pointer to a valid `T`. 1732 let size_of_got_ptr = unsafe { mem::size_of_val_raw(got_ptr.as_ptr()) }; 1733 assert_eq!(size_of_got_ptr, size, "{}", assert_msg); 1734 } 1735 } else { 1736 // For sized casts, the returned element value is 1737 // technically meaningless, and we don't guarantee any 1738 // particular value. In practice, it's always zero. 1739 assert_eq!(got_elems, 0, "{}", assert_msg) 1740 } 1741 } 1742 } 1743 } 1744 1745 macro_rules! validate_against_rust { 1746 ($offset:literal, $align:literal $(, $elem_size:literal)?) => {{ 1747 #[repr(C, align($align))] 1748 struct Foo([u8; $offset]$(, [[u8; $elem_size]])?); 1749 1750 let args = MacroArgs { 1751 offset: $offset, 1752 align: $align.try_into().unwrap(), 1753 elem_size: { 1754 #[allow(unused)] 1755 let ret = None::<usize>; 1756 $(let ret = Some($elem_size);)? 1757 ret 1758 } 1759 }; 1760 1761 #[repr(C, align($align))] 1762 struct FooAlign; 1763 // Create an aligned buffer to use in order to synthesize 1764 // pointers to `Foo`. We don't ever load values from these 1765 // pointers - we just do arithmetic on them - so having a "real" 1766 // block of memory as opposed to a validly-aligned-but-dangling 1767 // pointer is only necessary to make Miri happy since we run it 1768 // with "strict provenance" checking enabled. 1769 let aligned_buf = Align::<_, FooAlign>::new([0u8; 1024]); 1770 let with_elems = |elems| { 1771 let slc = NonNull::slice_from_raw_parts(NonNull::from(&aligned_buf.t), elems); 1772 #[allow(clippy::as_conversions)] 1773 NonNull::new(slc.as_ptr() as *mut Foo).unwrap() 1774 }; 1775 let addr_of_slice_field = { 1776 #[allow(unused)] 1777 let f = None::<fn(NonNull<Foo>) -> NonNull<u8>>; 1778 $( 1779 // SAFETY: `test` promises to only call `f` with a `ptr` 1780 // to a valid `Foo`. 1781 let f: Option<fn(NonNull<Foo>) -> NonNull<u8>> = Some(|ptr: NonNull<Foo>| unsafe { 1782 NonNull::new(ptr::addr_of_mut!((*ptr.as_ptr()).1)).unwrap().cast::<u8>() 1783 }); 1784 let _ = $elem_size; 1785 )? 1786 f 1787 }; 1788 1789 test::<Foo, _>(args, with_elems, addr_of_slice_field); 1790 }}; 1791 } 1792 1793 // Every permutation of: 1794 // - offset in [0, 4] 1795 // - align in [1, 16] 1796 // - elem_size in [0, 4] (plus no elem_size) 1797 validate_against_rust!(0, 1); 1798 validate_against_rust!(0, 1, 0); 1799 validate_against_rust!(0, 1, 1); 1800 validate_against_rust!(0, 1, 2); 1801 validate_against_rust!(0, 1, 3); 1802 validate_against_rust!(0, 1, 4); 1803 validate_against_rust!(0, 2); 1804 validate_against_rust!(0, 2, 0); 1805 validate_against_rust!(0, 2, 1); 1806 validate_against_rust!(0, 2, 2); 1807 validate_against_rust!(0, 2, 3); 1808 validate_against_rust!(0, 2, 4); 1809 validate_against_rust!(0, 4); 1810 validate_against_rust!(0, 4, 0); 1811 validate_against_rust!(0, 4, 1); 1812 validate_against_rust!(0, 4, 2); 1813 validate_against_rust!(0, 4, 3); 1814 validate_against_rust!(0, 4, 4); 1815 validate_against_rust!(0, 8); 1816 validate_against_rust!(0, 8, 0); 1817 validate_against_rust!(0, 8, 1); 1818 validate_against_rust!(0, 8, 2); 1819 validate_against_rust!(0, 8, 3); 1820 validate_against_rust!(0, 8, 4); 1821 validate_against_rust!(0, 16); 1822 validate_against_rust!(0, 16, 0); 1823 validate_against_rust!(0, 16, 1); 1824 validate_against_rust!(0, 16, 2); 1825 validate_against_rust!(0, 16, 3); 1826 validate_against_rust!(0, 16, 4); 1827 validate_against_rust!(1, 1); 1828 validate_against_rust!(1, 1, 0); 1829 validate_against_rust!(1, 1, 1); 1830 validate_against_rust!(1, 1, 2); 1831 validate_against_rust!(1, 1, 3); 1832 validate_against_rust!(1, 1, 4); 1833 validate_against_rust!(1, 2); 1834 validate_against_rust!(1, 2, 0); 1835 validate_against_rust!(1, 2, 1); 1836 validate_against_rust!(1, 2, 2); 1837 validate_against_rust!(1, 2, 3); 1838 validate_against_rust!(1, 2, 4); 1839 validate_against_rust!(1, 4); 1840 validate_against_rust!(1, 4, 0); 1841 validate_against_rust!(1, 4, 1); 1842 validate_against_rust!(1, 4, 2); 1843 validate_against_rust!(1, 4, 3); 1844 validate_against_rust!(1, 4, 4); 1845 validate_against_rust!(1, 8); 1846 validate_against_rust!(1, 8, 0); 1847 validate_against_rust!(1, 8, 1); 1848 validate_against_rust!(1, 8, 2); 1849 validate_against_rust!(1, 8, 3); 1850 validate_against_rust!(1, 8, 4); 1851 validate_against_rust!(1, 16); 1852 validate_against_rust!(1, 16, 0); 1853 validate_against_rust!(1, 16, 1); 1854 validate_against_rust!(1, 16, 2); 1855 validate_against_rust!(1, 16, 3); 1856 validate_against_rust!(1, 16, 4); 1857 validate_against_rust!(2, 1); 1858 validate_against_rust!(2, 1, 0); 1859 validate_against_rust!(2, 1, 1); 1860 validate_against_rust!(2, 1, 2); 1861 validate_against_rust!(2, 1, 3); 1862 validate_against_rust!(2, 1, 4); 1863 validate_against_rust!(2, 2); 1864 validate_against_rust!(2, 2, 0); 1865 validate_against_rust!(2, 2, 1); 1866 validate_against_rust!(2, 2, 2); 1867 validate_against_rust!(2, 2, 3); 1868 validate_against_rust!(2, 2, 4); 1869 validate_against_rust!(2, 4); 1870 validate_against_rust!(2, 4, 0); 1871 validate_against_rust!(2, 4, 1); 1872 validate_against_rust!(2, 4, 2); 1873 validate_against_rust!(2, 4, 3); 1874 validate_against_rust!(2, 4, 4); 1875 validate_against_rust!(2, 8); 1876 validate_against_rust!(2, 8, 0); 1877 validate_against_rust!(2, 8, 1); 1878 validate_against_rust!(2, 8, 2); 1879 validate_against_rust!(2, 8, 3); 1880 validate_against_rust!(2, 8, 4); 1881 validate_against_rust!(2, 16); 1882 validate_against_rust!(2, 16, 0); 1883 validate_against_rust!(2, 16, 1); 1884 validate_against_rust!(2, 16, 2); 1885 validate_against_rust!(2, 16, 3); 1886 validate_against_rust!(2, 16, 4); 1887 validate_against_rust!(3, 1); 1888 validate_against_rust!(3, 1, 0); 1889 validate_against_rust!(3, 1, 1); 1890 validate_against_rust!(3, 1, 2); 1891 validate_against_rust!(3, 1, 3); 1892 validate_against_rust!(3, 1, 4); 1893 validate_against_rust!(3, 2); 1894 validate_against_rust!(3, 2, 0); 1895 validate_against_rust!(3, 2, 1); 1896 validate_against_rust!(3, 2, 2); 1897 validate_against_rust!(3, 2, 3); 1898 validate_against_rust!(3, 2, 4); 1899 validate_against_rust!(3, 4); 1900 validate_against_rust!(3, 4, 0); 1901 validate_against_rust!(3, 4, 1); 1902 validate_against_rust!(3, 4, 2); 1903 validate_against_rust!(3, 4, 3); 1904 validate_against_rust!(3, 4, 4); 1905 validate_against_rust!(3, 8); 1906 validate_against_rust!(3, 8, 0); 1907 validate_against_rust!(3, 8, 1); 1908 validate_against_rust!(3, 8, 2); 1909 validate_against_rust!(3, 8, 3); 1910 validate_against_rust!(3, 8, 4); 1911 validate_against_rust!(3, 16); 1912 validate_against_rust!(3, 16, 0); 1913 validate_against_rust!(3, 16, 1); 1914 validate_against_rust!(3, 16, 2); 1915 validate_against_rust!(3, 16, 3); 1916 validate_against_rust!(3, 16, 4); 1917 validate_against_rust!(4, 1); 1918 validate_against_rust!(4, 1, 0); 1919 validate_against_rust!(4, 1, 1); 1920 validate_against_rust!(4, 1, 2); 1921 validate_against_rust!(4, 1, 3); 1922 validate_against_rust!(4, 1, 4); 1923 validate_against_rust!(4, 2); 1924 validate_against_rust!(4, 2, 0); 1925 validate_against_rust!(4, 2, 1); 1926 validate_against_rust!(4, 2, 2); 1927 validate_against_rust!(4, 2, 3); 1928 validate_against_rust!(4, 2, 4); 1929 validate_against_rust!(4, 4); 1930 validate_against_rust!(4, 4, 0); 1931 validate_against_rust!(4, 4, 1); 1932 validate_against_rust!(4, 4, 2); 1933 validate_against_rust!(4, 4, 3); 1934 validate_against_rust!(4, 4, 4); 1935 validate_against_rust!(4, 8); 1936 validate_against_rust!(4, 8, 0); 1937 validate_against_rust!(4, 8, 1); 1938 validate_against_rust!(4, 8, 2); 1939 validate_against_rust!(4, 8, 3); 1940 validate_against_rust!(4, 8, 4); 1941 validate_against_rust!(4, 16); 1942 validate_against_rust!(4, 16, 0); 1943 validate_against_rust!(4, 16, 1); 1944 validate_against_rust!(4, 16, 2); 1945 validate_against_rust!(4, 16, 3); 1946 validate_against_rust!(4, 16, 4); 1947 } 1948 } 1949 1950 #[cfg(kani)] 1951 mod proofs { 1952 use core::alloc::Layout; 1953 1954 use super::*; 1955 1956 impl kani::Arbitrary for DstLayout { 1957 fn any() -> Self { 1958 let align: NonZeroUsize = kani::any(); 1959 let size_info: SizeInfo = kani::any(); 1960 1961 kani::assume(align.is_power_of_two()); 1962 kani::assume(align < DstLayout::THEORETICAL_MAX_ALIGN); 1963 1964 // For testing purposes, we most care about instantiations of 1965 // `DstLayout` that can correspond to actual Rust types. We use 1966 // `Layout` to verify that our `DstLayout` satisfies the validity 1967 // conditions of Rust layouts. 1968 kani::assume( 1969 match size_info { 1970 SizeInfo::Sized { size } => Layout::from_size_align(size, align.get()), 1971 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size: _ }) => { 1972 // `SliceDst` cannot encode an exact size, but we know 1973 // it is at least `offset` bytes. 1974 Layout::from_size_align(offset, align.get()) 1975 } 1976 } 1977 .is_ok(), 1978 ); 1979 1980 Self { align: align, size_info: size_info, statically_shallow_unpadded: kani::any() } 1981 } 1982 } 1983 1984 impl kani::Arbitrary for SizeInfo { 1985 fn any() -> Self { 1986 let is_sized: bool = kani::any(); 1987 1988 match is_sized { 1989 true => { 1990 let size: usize = kani::any(); 1991 1992 kani::assume(size <= DstLayout::MAX_SIZE); 1993 1994 SizeInfo::Sized { size } 1995 } 1996 false => SizeInfo::SliceDst(kani::any()), 1997 } 1998 } 1999 } 2000 2001 impl kani::Arbitrary for TrailingSliceLayout { 2002 fn any() -> Self { 2003 let elem_size: usize = kani::any(); 2004 let offset: usize = kani::any(); 2005 2006 kani::assume(elem_size < DstLayout::MAX_SIZE); 2007 kani::assume(offset < DstLayout::MAX_SIZE); 2008 2009 TrailingSliceLayout { elem_size, offset } 2010 } 2011 } 2012 2013 #[kani::proof] 2014 fn prove_requires_dynamic_padding() { 2015 let layout: DstLayout = kani::any(); 2016 2017 let SizeInfo::SliceDst(size_info) = layout.size_info else { 2018 kani::assume(false); 2019 loop {} 2020 }; 2021 2022 let meta: usize = kani::any(); 2023 2024 let Some(trailing_slice_size) = size_info.elem_size.checked_mul(meta) else { 2025 // The `trailing_slice_size` exceeds `usize::MAX`; `meta` is invalid. 2026 kani::assume(false); 2027 loop {} 2028 }; 2029 2030 let Some(unpadded_size) = size_info.offset.checked_add(trailing_slice_size) else { 2031 // The `unpadded_size` exceeds `usize::MAX`; `meta`` is invalid. 2032 kani::assume(false); 2033 loop {} 2034 }; 2035 2036 if unpadded_size >= DstLayout::MAX_SIZE { 2037 // The `unpadded_size` exceeds `isize::MAX`; `meta` is invalid. 2038 kani::assume(false); 2039 loop {} 2040 } 2041 2042 let trailing_padding = util::padding_needed_for(unpadded_size, layout.align); 2043 2044 if !layout.requires_dynamic_padding() { 2045 assert!(trailing_padding == 0); 2046 } 2047 } 2048 2049 #[kani::proof] 2050 fn prove_dst_layout_extend() { 2051 use crate::util::{max, min, padding_needed_for}; 2052 2053 let base: DstLayout = kani::any(); 2054 let field: DstLayout = kani::any(); 2055 let packed: Option<NonZeroUsize> = kani::any(); 2056 2057 if let Some(max_align) = packed { 2058 kani::assume(max_align.is_power_of_two()); 2059 kani::assume(base.align <= max_align); 2060 } 2061 2062 // The base can only be extended if it's sized. 2063 kani::assume(matches!(base.size_info, SizeInfo::Sized { .. })); 2064 let base_size = if let SizeInfo::Sized { size } = base.size_info { 2065 size 2066 } else { 2067 unreachable!(); 2068 }; 2069 2070 // Under the above conditions, `DstLayout::extend` will not panic. 2071 let composite = base.extend(field, packed); 2072 2073 // The field's alignment is clamped by `max_align` (i.e., the 2074 // `packed` attribute, if any) [1]. 2075 // 2076 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers: 2077 // 2078 // The alignments of each field, for the purpose of positioning 2079 // fields, is the smaller of the specified alignment and the 2080 // alignment of the field's type. 2081 let field_align = min(field.align, packed.unwrap_or(DstLayout::THEORETICAL_MAX_ALIGN)); 2082 2083 // The struct's alignment is the maximum of its previous alignment and 2084 // `field_align`. 2085 assert_eq!(composite.align, max(base.align, field_align)); 2086 2087 // Compute the minimum amount of inter-field padding needed to 2088 // satisfy the field's alignment, and offset of the trailing field. 2089 // [1] 2090 // 2091 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers: 2092 // 2093 // Inter-field padding is guaranteed to be the minimum required in 2094 // order to satisfy each field's (possibly altered) alignment. 2095 let padding = padding_needed_for(base_size, field_align); 2096 let offset = base_size + padding; 2097 2098 // For testing purposes, we'll also construct `alloc::Layout` 2099 // stand-ins for `DstLayout`, and show that `extend` behaves 2100 // comparably on both types. 2101 let base_analog = Layout::from_size_align(base_size, base.align.get()).unwrap(); 2102 2103 match field.size_info { 2104 SizeInfo::Sized { size: field_size } => { 2105 if let SizeInfo::Sized { size: composite_size } = composite.size_info { 2106 // If the trailing field is sized, the resulting layout will 2107 // be sized. Its size will be the sum of the preceding 2108 // layout, the size of the new field, and the size of 2109 // inter-field padding between the two. 2110 assert_eq!(composite_size, offset + field_size); 2111 2112 let field_analog = 2113 Layout::from_size_align(field_size, field_align.get()).unwrap(); 2114 2115 if let Ok((actual_composite, actual_offset)) = base_analog.extend(field_analog) 2116 { 2117 assert_eq!(actual_offset, offset); 2118 assert_eq!(actual_composite.size(), composite_size); 2119 assert_eq!(actual_composite.align(), composite.align.get()); 2120 } else { 2121 // An error here reflects that composite of `base` 2122 // and `field` cannot correspond to a real Rust type 2123 // fragment, because such a fragment would violate 2124 // the basic invariants of a valid Rust layout. At 2125 // the time of writing, `DstLayout` is a little more 2126 // permissive than `Layout`, so we don't assert 2127 // anything in this branch (e.g., unreachability). 2128 } 2129 } else { 2130 panic!("The composite of two sized layouts must be sized.") 2131 } 2132 } 2133 SizeInfo::SliceDst(TrailingSliceLayout { 2134 offset: field_offset, 2135 elem_size: field_elem_size, 2136 }) => { 2137 if let SizeInfo::SliceDst(TrailingSliceLayout { 2138 offset: composite_offset, 2139 elem_size: composite_elem_size, 2140 }) = composite.size_info 2141 { 2142 // The offset of the trailing slice component is the sum 2143 // of the offset of the trailing field and the trailing 2144 // slice offset within that field. 2145 assert_eq!(composite_offset, offset + field_offset); 2146 // The elem size is unchanged. 2147 assert_eq!(composite_elem_size, field_elem_size); 2148 2149 let field_analog = 2150 Layout::from_size_align(field_offset, field_align.get()).unwrap(); 2151 2152 if let Ok((actual_composite, actual_offset)) = base_analog.extend(field_analog) 2153 { 2154 assert_eq!(actual_offset, offset); 2155 assert_eq!(actual_composite.size(), composite_offset); 2156 assert_eq!(actual_composite.align(), composite.align.get()); 2157 } else { 2158 // An error here reflects that composite of `base` 2159 // and `field` cannot correspond to a real Rust type 2160 // fragment, because such a fragment would violate 2161 // the basic invariants of a valid Rust layout. At 2162 // the time of writing, `DstLayout` is a little more 2163 // permissive than `Layout`, so we don't assert 2164 // anything in this branch (e.g., unreachability). 2165 } 2166 } else { 2167 panic!("The extension of a layout with a DST must result in a DST.") 2168 } 2169 } 2170 } 2171 } 2172 2173 #[kani::proof] 2174 #[kani::should_panic] 2175 fn prove_dst_layout_extend_dst_panics() { 2176 let base: DstLayout = kani::any(); 2177 let field: DstLayout = kani::any(); 2178 let packed: Option<NonZeroUsize> = kani::any(); 2179 2180 if let Some(max_align) = packed { 2181 kani::assume(max_align.is_power_of_two()); 2182 kani::assume(base.align <= max_align); 2183 } 2184 2185 kani::assume(matches!(base.size_info, SizeInfo::SliceDst(..))); 2186 2187 let _ = base.extend(field, packed); 2188 } 2189 2190 #[kani::proof] 2191 fn prove_dst_layout_pad_to_align() { 2192 use crate::util::padding_needed_for; 2193 2194 let layout: DstLayout = kani::any(); 2195 2196 let padded = layout.pad_to_align(); 2197 2198 // Calling `pad_to_align` does not alter the `DstLayout`'s alignment. 2199 assert_eq!(padded.align, layout.align); 2200 2201 if let SizeInfo::Sized { size: unpadded_size } = layout.size_info { 2202 if let SizeInfo::Sized { size: padded_size } = padded.size_info { 2203 // If the layout is sized, it will remain sized after padding is 2204 // added. Its sum will be its unpadded size and the size of the 2205 // trailing padding needed to satisfy its alignment 2206 // requirements. 2207 let padding = padding_needed_for(unpadded_size, layout.align); 2208 assert_eq!(padded_size, unpadded_size + padding); 2209 2210 // Prove that calling `DstLayout::pad_to_align` behaves 2211 // identically to `Layout::pad_to_align`. 2212 let layout_analog = 2213 Layout::from_size_align(unpadded_size, layout.align.get()).unwrap(); 2214 let padded_analog = layout_analog.pad_to_align(); 2215 assert_eq!(padded_analog.align(), layout.align.get()); 2216 assert_eq!(padded_analog.size(), padded_size); 2217 } else { 2218 panic!("The padding of a sized layout must result in a sized layout.") 2219 } 2220 } else { 2221 // If the layout is a DST, padding cannot be statically added. 2222 assert_eq!(padded.size_info, layout.size_info); 2223 } 2224 } 2225 } 2226