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