projects/linux·blob uaccess-cleanups · refs

2227 lines · 98.6 KiB

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
12use core::{mem, num::NonZeroUsize};
13
14use crate::util;
15
16/// The target pointer width, counted in bits.
17const 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)]
33pub 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)]
45pub(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)]
52pub(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
70impl 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))]
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)]
94pub enum CastType {
95 Prefix,
96 Suffix,
97}
98
99#[cfg_attr(test, derive(Debug))]
100pub(crate) enum MetadataCastError {
101 Alignment,
102 Size,
103}
104
105impl 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.
167 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]
185 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]
209 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]
233 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]`.
242 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]
280 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]
341 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]
492 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)]
521 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)]
529 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)]
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
757pub(crate) use cast_from::CastFrom;
758mod 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
799 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)]
1104mod tests {
1105 use super::*;
1106
1107 #[test]
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]
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]
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]
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]
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)]
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)]
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)]
1953mod proofs {
1954 use core::alloc::Layout;
1955
1956 use super::*;
1957
1958 impl kani::Arbitrary for DstLayout {
1959 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 {
1987 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 {
2004 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]
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]
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]
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]
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}