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