1// Copyright 2024 The Fuchsia Authors
2//
3// Licensed under the 2-Clause BSD License <LICENSE-BSD or
4// https://opensource.org/license/bsd-2-clause>, Apache License, Version 2.0
5// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
6// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
7// This file may not be copied, modified, or distributed except according to
8// those terms.
9
10use core::{mem, num::NonZeroUsize};
11
12use crate::util;
13
14/// The target pointer width, counted in bits.
15const POINTER_WIDTH_BITS: usize = mem::size_of::<usize>() * 8;
16
17/// The layout of a type which might be dynamically-sized.
18///
19/// `DstLayout` describes the layout of sized types, slice types, and "slice
20/// DSTs" - ie, those that are known by the type system to have a trailing slice
21/// (as distinguished from `dyn Trait` types - such types *might* have a
22/// trailing slice type, but the type system isn't aware of it).
23///
24/// Note that `DstLayout` does not have any internal invariants, so no guarantee
25/// is made that a `DstLayout` conforms to any of Rust's requirements regarding
26/// the layout of real Rust types or instances of types.
27#[doc(hidden)]
28#[allow(missing_debug_implementations, missing_copy_implementations)]
29#[cfg_attr(any(kani, test), derive(Copy, Clone, Debug, PartialEq, Eq))]
30pub struct DstLayout {
31 pub(crate) align: NonZeroUsize,
32 pub(crate) size_info: SizeInfo,
33}
34
35#[cfg_attr(any(kani, test), derive(Debug, PartialEq, Eq))]
36#[derive(Copy, Clone)]
37pub(crate) enum SizeInfo<E = usize> {
38 Sized { size: usize },
39 SliceDst(TrailingSliceLayout<E>),
40}
41
42#[cfg_attr(any(kani, test), derive(Debug, PartialEq, Eq))]
43#[derive(Copy, Clone)]
44pub(crate) struct TrailingSliceLayout<E = usize> {
45 // The offset of the first byte of the trailing slice field. Note that this
46 // is NOT the same as the minimum size of the type. For example, consider
47 // the following type:
48 //
49 // struct Foo {
50 // a: u16,
51 // b: u8,
52 // c: [u8],
53 // }
54 //
55 // In `Foo`, `c` is at byte offset 3. When `c.len() == 0`, `c` is followed
56 // by a padding byte.
57 pub(crate) offset: usize,
58 // The size of the element type of the trailing slice field.
59 pub(crate) elem_size: E,
60}
61
62impl SizeInfo {
63 /// Attempts to create a `SizeInfo` from `Self` in which `elem_size` is a
64 /// `NonZeroUsize`. If `elem_size` is 0, returns `None`.
65 #[allow(unused)]
66 const fn try_to_nonzero_elem_size(&self) -> Option<SizeInfo<NonZeroUsize>> {
67 Some(match *self {
68 SizeInfo::Sized { size: usize } => SizeInfo::Sized { size },
69 SizeInfo::SliceDst(TrailingSliceLayout { offset: usize, elem_size: usize }) => {
70 if let Some(elem_size: NonZero) = NonZeroUsize::new(elem_size) {
71 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size })
72 } else {
73 return None;
74 }
75 }
76 })
77 }
78}
79
80#[doc(hidden)]
81#[derive(Copy, Clone)]
82#[cfg_attr(test, derive(Debug))]
83#[allow(missing_debug_implementations)]
84pub enum CastType {
85 Prefix,
86 Suffix,
87}
88
89#[cfg_attr(test, derive(Debug))]
90pub(crate) enum MetadataCastError {
91 Alignment,
92 Size,
93}
94
95impl DstLayout {
96 /// The minimum possible alignment of a type.
97 const MIN_ALIGN: NonZeroUsize = match NonZeroUsize::new(1) {
98 Some(min_align) => min_align,
99 None => const_unreachable!(),
100 };
101
102 /// The maximum theoretic possible alignment of a type.
103 ///
104 /// For compatibility with future Rust versions, this is defined as the
105 /// maximum power-of-two that fits into a `usize`. See also
106 /// [`DstLayout::CURRENT_MAX_ALIGN`].
107 pub(crate) const THEORETICAL_MAX_ALIGN: NonZeroUsize =
108 match NonZeroUsize::new(1 << (POINTER_WIDTH_BITS - 1)) {
109 Some(max_align) => max_align,
110 None => const_unreachable!(),
111 };
112
113 /// The current, documented max alignment of a type \[1\].
114 ///
115 /// \[1\] Per <https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers>:
116 ///
117 /// The alignment value must be a power of two from 1 up to
118 /// 2<sup>29</sup>.
119 #[cfg(not(kani))]
120 #[cfg(not(target_pointer_width = "16"))]
121 pub(crate) const CURRENT_MAX_ALIGN: NonZeroUsize = match NonZeroUsize::new(1 << 28) {
122 Some(max_align) => max_align,
123 None => const_unreachable!(),
124 };
125
126 #[cfg(not(kani))]
127 #[cfg(target_pointer_width = "16")]
128 pub(crate) const CURRENT_MAX_ALIGN: NonZeroUsize = match NonZeroUsize::new(1 << 15) {
129 Some(max_align) => max_align,
130 None => const_unreachable!(),
131 };
132
133 /// Constructs a `DstLayout` for a zero-sized type with `repr_align`
134 /// alignment (or 1). If `repr_align` is provided, then it must be a power
135 /// of two.
136 ///
137 /// # Panics
138 ///
139 /// This function panics if the supplied `repr_align` is not a power of two.
140 ///
141 /// # Safety
142 ///
143 /// Unsafe code may assume that the contract of this function is satisfied.
144 #[doc(hidden)]
145 #[must_use]
146 #[inline]
147 pub const fn new_zst(repr_align: Option<NonZeroUsize>) -> DstLayout {
148 let align = match repr_align {
149 Some(align) => align,
150 None => Self::MIN_ALIGN,
151 };
152
153 const_assert!(align.get().is_power_of_two());
154
155 DstLayout { align, size_info: SizeInfo::Sized { size: 0 } }
156 }
157
158 /// Constructs a `DstLayout` which describes `T`.
159 ///
160 /// # Safety
161 ///
162 /// Unsafe code may assume that `DstLayout` is the correct layout for `T`.
163 #[doc(hidden)]
164 #[must_use]
165 #[inline]
166 pub const fn for_type<T>() -> DstLayout {
167 // SAFETY: `align` is correct by construction. `T: Sized`, and so it is
168 // sound to initialize `size_info` to `SizeInfo::Sized { size }`; the
169 // `size` field is also correct by construction.
170 DstLayout {
171 align: match NonZeroUsize::new(mem::align_of::<T>()) {
172 Some(align) => align,
173 None => const_unreachable!(),
174 },
175 size_info: SizeInfo::Sized { size: mem::size_of::<T>() },
176 }
177 }
178
179 /// Constructs a `DstLayout` which describes `[T]`.
180 ///
181 /// # Safety
182 ///
183 /// Unsafe code may assume that `DstLayout` is the correct layout for `[T]`.
184 pub(crate) const fn for_slice<T>() -> DstLayout {
185 // SAFETY: The alignment of a slice is equal to the alignment of its
186 // element type, and so `align` is initialized correctly.
187 //
188 // Since this is just a slice type, there is no offset between the
189 // beginning of the type and the beginning of the slice, so it is
190 // correct to set `offset: 0`. The `elem_size` is correct by
191 // construction. Since `[T]` is a (degenerate case of a) slice DST, it
192 // is correct to initialize `size_info` to `SizeInfo::SliceDst`.
193 DstLayout {
194 align: match NonZeroUsize::new(mem::align_of::<T>()) {
195 Some(align) => align,
196 None => const_unreachable!(),
197 },
198 size_info: SizeInfo::SliceDst(TrailingSliceLayout {
199 offset: 0,
200 elem_size: mem::size_of::<T>(),
201 }),
202 }
203 }
204
205 /// Like `Layout::extend`, this creates a layout that describes a record
206 /// whose layout consists of `self` followed by `next` that includes the
207 /// necessary inter-field padding, but not any trailing padding.
208 ///
209 /// In order to match the layout of a `#[repr(C)]` struct, this method
210 /// should be invoked for each field in declaration order. To add trailing
211 /// padding, call `DstLayout::pad_to_align` after extending the layout for
212 /// all fields. If `self` corresponds to a type marked with
213 /// `repr(packed(N))`, then `repr_packed` should be set to `Some(N)`,
214 /// otherwise `None`.
215 ///
216 /// This method cannot be used to match the layout of a record with the
217 /// default representation, as that representation is mostly unspecified.
218 ///
219 /// # Safety
220 ///
221 /// If a (potentially hypothetical) valid `repr(C)` Rust type begins with
222 /// fields whose layout are `self`, and those fields are immediately
223 /// followed by a field whose layout is `field`, then unsafe code may rely
224 /// on `self.extend(field, repr_packed)` producing a layout that correctly
225 /// encompasses those two components.
226 ///
227 /// We make no guarantees to the behavior of this method if these fragments
228 /// cannot appear in a valid Rust type (e.g., the concatenation of the
229 /// layouts would lead to a size larger than `isize::MAX`).
230 #[doc(hidden)]
231 #[must_use]
232 #[inline]
233 pub const fn extend(self, field: DstLayout, repr_packed: Option<NonZeroUsize>) -> Self {
234 use util::{max, min, padding_needed_for};
235
236 // If `repr_packed` is `None`, there are no alignment constraints, and
237 // the value can be defaulted to `THEORETICAL_MAX_ALIGN`.
238 let max_align = match repr_packed {
239 Some(max_align) => max_align,
240 None => Self::THEORETICAL_MAX_ALIGN,
241 };
242
243 const_assert!(max_align.get().is_power_of_two());
244
245 // We use Kani to prove that this method is robust to future increases
246 // in Rust's maximum allowed alignment. However, if such a change ever
247 // actually occurs, we'd like to be notified via assertion failures.
248 #[cfg(not(kani))]
249 {
250 const_debug_assert!(self.align.get() <= DstLayout::CURRENT_MAX_ALIGN.get());
251 const_debug_assert!(field.align.get() <= DstLayout::CURRENT_MAX_ALIGN.get());
252 if let Some(repr_packed) = repr_packed {
253 const_debug_assert!(repr_packed.get() <= DstLayout::CURRENT_MAX_ALIGN.get());
254 }
255 }
256
257 // The field's alignment is clamped by `repr_packed` (i.e., the
258 // `repr(packed(N))` attribute, if any) [1].
259 //
260 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers:
261 //
262 // The alignments of each field, for the purpose of positioning
263 // fields, is the smaller of the specified alignment and the alignment
264 // of the field's type.
265 let field_align = min(field.align, max_align);
266
267 // The struct's alignment is the maximum of its previous alignment and
268 // `field_align`.
269 let align = max(self.align, field_align);
270
271 let size_info = match self.size_info {
272 // If the layout is already a DST, we panic; DSTs cannot be extended
273 // with additional fields.
274 SizeInfo::SliceDst(..) => const_panic!("Cannot extend a DST with additional fields."),
275
276 SizeInfo::Sized { size: preceding_size } => {
277 // Compute the minimum amount of inter-field padding needed to
278 // satisfy the field's alignment, and offset of the trailing
279 // field. [1]
280 //
281 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers:
282 //
283 // Inter-field padding is guaranteed to be the minimum
284 // required in order to satisfy each field's (possibly
285 // altered) alignment.
286 let padding = padding_needed_for(preceding_size, field_align);
287
288 // This will not panic (and is proven to not panic, with Kani)
289 // if the layout components can correspond to a leading layout
290 // fragment of a valid Rust type, but may panic otherwise (e.g.,
291 // combining or aligning the components would create a size
292 // exceeding `isize::MAX`).
293 let offset = match preceding_size.checked_add(padding) {
294 Some(offset) => offset,
295 None => const_panic!("Adding padding to `self`'s size overflows `usize`."),
296 };
297
298 match field.size_info {
299 SizeInfo::Sized { size: field_size } => {
300 // If the trailing field is sized, the resulting layout
301 // will be sized. Its size will be the sum of the
302 // preceeding layout, the size of the new field, and the
303 // size of inter-field padding between the two.
304 //
305 // This will not panic (and is proven with Kani to not
306 // panic) if the layout components can correspond to a
307 // leading layout fragment of a valid Rust type, but may
308 // panic otherwise (e.g., combining or aligning the
309 // components would create a size exceeding
310 // `usize::MAX`).
311 let size = match offset.checked_add(field_size) {
312 Some(size) => size,
313 None => const_panic!("`field` cannot be appended without the total size overflowing `usize`"),
314 };
315 SizeInfo::Sized { size }
316 }
317 SizeInfo::SliceDst(TrailingSliceLayout {
318 offset: trailing_offset,
319 elem_size,
320 }) => {
321 // If the trailing field is dynamically sized, so too
322 // will the resulting layout. The offset of the trailing
323 // slice component is the sum of the offset of the
324 // trailing field and the trailing slice offset within
325 // that field.
326 //
327 // This will not panic (and is proven with Kani to not
328 // panic) if the layout components can correspond to a
329 // leading layout fragment of a valid Rust type, but may
330 // panic otherwise (e.g., combining or aligning the
331 // components would create a size exceeding
332 // `usize::MAX`).
333 let offset = match offset.checked_add(trailing_offset) {
334 Some(offset) => offset,
335 None => const_panic!("`field` cannot be appended without the total size overflowing `usize`"),
336 };
337 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size })
338 }
339 }
340 }
341 };
342
343 DstLayout { align, size_info }
344 }
345
346 /// Like `Layout::pad_to_align`, this routine rounds the size of this layout
347 /// up to the nearest multiple of this type's alignment or `repr_packed`
348 /// (whichever is less). This method leaves DST layouts unchanged, since the
349 /// trailing padding of DSTs is computed at runtime.
350 ///
351 /// In order to match the layout of a `#[repr(C)]` struct, this method
352 /// should be invoked after the invocations of [`DstLayout::extend`]. If
353 /// `self` corresponds to a type marked with `repr(packed(N))`, then
354 /// `repr_packed` should be set to `Some(N)`, otherwise `None`.
355 ///
356 /// This method cannot be used to match the layout of a record with the
357 /// default representation, as that representation is mostly unspecified.
358 ///
359 /// # Safety
360 ///
361 /// If a (potentially hypothetical) valid `repr(C)` type begins with fields
362 /// whose layout are `self` followed only by zero or more bytes of trailing
363 /// padding (not included in `self`), then unsafe code may rely on
364 /// `self.pad_to_align(repr_packed)` producing a layout that correctly
365 /// encapsulates the layout of that type.
366 ///
367 /// We make no guarantees to the behavior of this method if `self` cannot
368 /// appear in a valid Rust type (e.g., because the addition of trailing
369 /// padding would lead to a size larger than `isize::MAX`).
370 #[doc(hidden)]
371 #[must_use]
372 #[inline]
373 pub const fn pad_to_align(self) -> Self {
374 use util::padding_needed_for;
375
376 let size_info = match self.size_info {
377 // For sized layouts, we add the minimum amount of trailing padding
378 // needed to satisfy alignment.
379 SizeInfo::Sized { size: unpadded_size } => {
380 let padding = padding_needed_for(unpadded_size, self.align);
381 let size = match unpadded_size.checked_add(padding) {
382 Some(size) => size,
383 None => const_panic!("Adding padding caused size to overflow `usize`."),
384 };
385 SizeInfo::Sized { size }
386 }
387 // For DST layouts, trailing padding depends on the length of the
388 // trailing DST and is computed at runtime. This does not alter the
389 // offset or element size of the layout, so we leave `size_info`
390 // unchanged.
391 size_info @ SizeInfo::SliceDst(_) => size_info,
392 };
393
394 DstLayout { align: self.align, size_info }
395 }
396
397 /// Validates that a cast is sound from a layout perspective.
398 ///
399 /// Validates that the size and alignment requirements of a type with the
400 /// layout described in `self` would not be violated by performing a
401 /// `cast_type` cast from a pointer with address `addr` which refers to a
402 /// memory region of size `bytes_len`.
403 ///
404 /// If the cast is valid, `validate_cast_and_convert_metadata` returns
405 /// `(elems, split_at)`. If `self` describes a dynamically-sized type, then
406 /// `elems` is the maximum number of trailing slice elements for which a
407 /// cast would be valid (for sized types, `elem` is meaningless and should
408 /// be ignored). `split_at` is the index at which to split the memory region
409 /// in order for the prefix (suffix) to contain the result of the cast, and
410 /// in order for the remaining suffix (prefix) to contain the leftover
411 /// bytes.
412 ///
413 /// There are three conditions under which a cast can fail:
414 /// - The smallest possible value for the type is larger than the provided
415 /// memory region
416 /// - A prefix cast is requested, and `addr` does not satisfy `self`'s
417 /// alignment requirement
418 /// - A suffix cast is requested, and `addr + bytes_len` does not satisfy
419 /// `self`'s alignment requirement (as a consequence, since all instances
420 /// of the type are a multiple of its alignment, no size for the type will
421 /// result in a starting address which is properly aligned)
422 ///
423 /// # Safety
424 ///
425 /// The caller may assume that this implementation is correct, and may rely
426 /// on that assumption for the soundness of their code. In particular, the
427 /// caller may assume that, if `validate_cast_and_convert_metadata` returns
428 /// `Some((elems, split_at))`, then:
429 /// - A pointer to the type (for dynamically sized types, this includes
430 /// `elems` as its pointer metadata) describes an object of size `size <=
431 /// bytes_len`
432 /// - If this is a prefix cast:
433 /// - `addr` satisfies `self`'s alignment
434 /// - `size == split_at`
435 /// - If this is a suffix cast:
436 /// - `split_at == bytes_len - size`
437 /// - `addr + split_at` satisfies `self`'s alignment
438 ///
439 /// Note that this method does *not* ensure that a pointer constructed from
440 /// its return values will be a valid pointer. In particular, this method
441 /// does not reason about `isize` overflow, which is a requirement of many
442 /// Rust pointer APIs, and may at some point be determined to be a validity
443 /// invariant of pointer types themselves. This should never be a problem so
444 /// long as the arguments to this method are derived from a known-valid
445 /// pointer (e.g., one derived from a safe Rust reference), but it is
446 /// nonetheless the caller's responsibility to justify that pointer
447 /// arithmetic will not overflow based on a safety argument *other than* the
448 /// mere fact that this method returned successfully.
449 ///
450 /// # Panics
451 ///
452 /// `validate_cast_and_convert_metadata` will panic if `self` describes a
453 /// DST whose trailing slice element is zero-sized.
454 ///
455 /// If `addr + bytes_len` overflows `usize`,
456 /// `validate_cast_and_convert_metadata` may panic, or it may return
457 /// incorrect results. No guarantees are made about when
458 /// `validate_cast_and_convert_metadata` will panic. The caller should not
459 /// rely on `validate_cast_and_convert_metadata` panicking in any particular
460 /// condition, even if `debug_assertions` are enabled.
461 #[allow(unused)]
462 #[inline(always)]
463 pub(crate) const fn validate_cast_and_convert_metadata(
464 &self,
465 addr: usize,
466 bytes_len: usize,
467 cast_type: CastType,
468 ) -> Result<(usize, usize), MetadataCastError> {
469 // `debug_assert!`, but with `#[allow(clippy::arithmetic_side_effects)]`.
470 macro_rules! __const_debug_assert {
471 ($e:expr $(, $msg:expr)?) => {
472 const_debug_assert!({
473 #[allow(clippy::arithmetic_side_effects)]
474 let e = $e;
475 e
476 } $(, $msg)?);
477 };
478 }
479
480 // Note that, in practice, `self` is always a compile-time constant. We
481 // do this check earlier than needed to ensure that we always panic as a
482 // result of bugs in the program (such as calling this function on an
483 // invalid type) instead of allowing this panic to be hidden if the cast
484 // would have failed anyway for runtime reasons (such as a too-small
485 // memory region).
486 //
487 // TODO(#67): Once our MSRV is 1.65, use let-else:
488 // https://blog.rust-lang.org/2022/11/03/Rust-1.65.0.html#let-else-statements
489 let size_info = match self.size_info.try_to_nonzero_elem_size() {
490 Some(size_info) => size_info,
491 None => const_panic!("attempted to cast to slice type with zero-sized element"),
492 };
493
494 // Precondition
495 __const_debug_assert!(
496 addr.checked_add(bytes_len).is_some(),
497 "`addr` + `bytes_len` > usize::MAX"
498 );
499
500 // Alignment checks go in their own block to avoid introducing variables
501 // into the top-level scope.
502 {
503 // We check alignment for `addr` (for prefix casts) or `addr +
504 // bytes_len` (for suffix casts). For a prefix cast, the correctness
505 // of this check is trivial - `addr` is the address the object will
506 // live at.
507 //
508 // For a suffix cast, we know that all valid sizes for the type are
509 // a multiple of the alignment (and by safety precondition, we know
510 // `DstLayout` may only describe valid Rust types). Thus, a
511 // validly-sized instance which lives at a validly-aligned address
512 // must also end at a validly-aligned address. Thus, if the end
513 // address for a suffix cast (`addr + bytes_len`) is not aligned,
514 // then no valid start address will be aligned either.
515 let offset = match cast_type {
516 CastType::Prefix => 0,
517 CastType::Suffix => bytes_len,
518 };
519
520 // Addition is guaranteed not to overflow because `offset <=
521 // bytes_len`, and `addr + bytes_len <= usize::MAX` is a
522 // precondition of this method. Modulus is guaranteed not to divide
523 // by 0 because `align` is non-zero.
524 #[allow(clippy::arithmetic_side_effects)]
525 if (addr + offset) % self.align.get() != 0 {
526 return Err(MetadataCastError::Alignment);
527 }
528 }
529
530 let (elems, self_bytes) = match size_info {
531 SizeInfo::Sized { size } => {
532 if size > bytes_len {
533 return Err(MetadataCastError::Size);
534 }
535 (0, size)
536 }
537 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => {
538 // Calculate the maximum number of bytes that could be consumed
539 // - any number of bytes larger than this will either not be a
540 // multiple of the alignment, or will be larger than
541 // `bytes_len`.
542 let max_total_bytes =
543 util::round_down_to_next_multiple_of_alignment(bytes_len, self.align);
544 // Calculate the maximum number of bytes that could be consumed
545 // by the trailing slice.
546 //
547 // TODO(#67): Once our MSRV is 1.65, use let-else:
548 // https://blog.rust-lang.org/2022/11/03/Rust-1.65.0.html#let-else-statements
549 let max_slice_and_padding_bytes = match max_total_bytes.checked_sub(offset) {
550 Some(max) => max,
551 // `bytes_len` too small even for 0 trailing slice elements.
552 None => return Err(MetadataCastError::Size),
553 };
554
555 // Calculate the number of elements that fit in
556 // `max_slice_and_padding_bytes`; any remaining bytes will be
557 // considered padding.
558 //
559 // Guaranteed not to divide by zero: `elem_size` is non-zero.
560 #[allow(clippy::arithmetic_side_effects)]
561 let elems = max_slice_and_padding_bytes / elem_size.get();
562 // Guaranteed not to overflow on multiplication: `usize::MAX >=
563 // max_slice_and_padding_bytes >= (max_slice_and_padding_bytes /
564 // elem_size) * elem_size`.
565 //
566 // Guaranteed not to overflow on addition:
567 // - max_slice_and_padding_bytes == max_total_bytes - offset
568 // - elems * elem_size <= max_slice_and_padding_bytes == max_total_bytes - offset
569 // - elems * elem_size + offset <= max_total_bytes <= usize::MAX
570 #[allow(clippy::arithmetic_side_effects)]
571 let without_padding = offset + elems * elem_size.get();
572 // `self_bytes` is equal to the offset bytes plus the bytes
573 // consumed by the trailing slice plus any padding bytes
574 // required to satisfy the alignment. Note that we have computed
575 // the maximum number of trailing slice elements that could fit
576 // in `self_bytes`, so any padding is guaranteed to be less than
577 // the size of an extra element.
578 //
579 // Guaranteed not to overflow:
580 // - By previous comment: without_padding == elems * elem_size +
581 // offset <= max_total_bytes
582 // - By construction, `max_total_bytes` is a multiple of
583 // `self.align`.
584 // - At most, adding padding needed to round `without_padding`
585 // up to the next multiple of the alignment will bring
586 // `self_bytes` up to `max_total_bytes`.
587 #[allow(clippy::arithmetic_side_effects)]
588 let self_bytes =
589 without_padding + util::padding_needed_for(without_padding, self.align);
590 (elems, self_bytes)
591 }
592 };
593
594 __const_debug_assert!(self_bytes <= bytes_len);
595
596 let split_at = match cast_type {
597 CastType::Prefix => self_bytes,
598 // Guaranteed not to underflow:
599 // - In the `Sized` branch, only returns `size` if `size <=
600 // bytes_len`.
601 // - In the `SliceDst` branch, calculates `self_bytes <=
602 // max_toatl_bytes`, which is upper-bounded by `bytes_len`.
603 #[allow(clippy::arithmetic_side_effects)]
604 CastType::Suffix => bytes_len - self_bytes,
605 };
606
607 Ok((elems, split_at))
608 }
609}
610
611// TODO(#67): For some reason, on our MSRV toolchain, this `allow` isn't
612// enforced despite having `#![allow(unknown_lints)]` at the crate root, but
613// putting it here works. Once our MSRV is high enough that this bug has been
614// fixed, remove this `allow`.
615#[allow(unknown_lints)]
616#[cfg(test)]
617mod tests {
618 use super::*;
619
620 /// Tests of when a sized `DstLayout` is extended with a sized field.
621 #[allow(clippy::decimal_literal_representation)]
622 #[test]
623 fn test_dst_layout_extend_sized_with_sized() {
624 // This macro constructs a layout corresponding to a `u8` and extends it
625 // with a zero-sized trailing field of given alignment `n`. The macro
626 // tests that the resulting layout has both size and alignment `min(n,
627 // P)` for all valid values of `repr(packed(P))`.
628 macro_rules! test_align_is_size {
629 ($n:expr) => {
630 let base = DstLayout::for_type::<u8>();
631 let trailing_field = DstLayout::for_type::<elain::Align<$n>>();
632
633 let packs =
634 core::iter::once(None).chain((0..29).map(|p| NonZeroUsize::new(2usize.pow(p))));
635
636 for pack in packs {
637 let composite = base.extend(trailing_field, pack);
638 let max_align = pack.unwrap_or(DstLayout::CURRENT_MAX_ALIGN);
639 let align = $n.min(max_align.get());
640 assert_eq!(
641 composite,
642 DstLayout {
643 align: NonZeroUsize::new(align).unwrap(),
644 size_info: SizeInfo::Sized { size: align }
645 }
646 )
647 }
648 };
649 }
650
651 test_align_is_size!(1);
652 test_align_is_size!(2);
653 test_align_is_size!(4);
654 test_align_is_size!(8);
655 test_align_is_size!(16);
656 test_align_is_size!(32);
657 test_align_is_size!(64);
658 test_align_is_size!(128);
659 test_align_is_size!(256);
660 test_align_is_size!(512);
661 test_align_is_size!(1024);
662 test_align_is_size!(2048);
663 test_align_is_size!(4096);
664 test_align_is_size!(8192);
665 test_align_is_size!(16384);
666 test_align_is_size!(32768);
667 test_align_is_size!(65536);
668 test_align_is_size!(131072);
669 test_align_is_size!(262144);
670 test_align_is_size!(524288);
671 test_align_is_size!(1048576);
672 test_align_is_size!(2097152);
673 test_align_is_size!(4194304);
674 test_align_is_size!(8388608);
675 test_align_is_size!(16777216);
676 test_align_is_size!(33554432);
677 test_align_is_size!(67108864);
678 test_align_is_size!(33554432);
679 test_align_is_size!(134217728);
680 test_align_is_size!(268435456);
681 }
682
683 /// Tests of when a sized `DstLayout` is extended with a DST field.
684 #[test]
685 fn test_dst_layout_extend_sized_with_dst() {
686 // Test that for all combinations of real-world alignments and
687 // `repr_packed` values, that the extension of a sized `DstLayout`` with
688 // a DST field correctly computes the trailing offset in the composite
689 // layout.
690
691 let aligns = (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap());
692 let packs = core::iter::once(None).chain(aligns.clone().map(Some));
693
694 for align in aligns {
695 for pack in packs.clone() {
696 let base = DstLayout::for_type::<u8>();
697 let elem_size = 42;
698 let trailing_field_offset = 11;
699
700 let trailing_field = DstLayout {
701 align,
702 size_info: SizeInfo::SliceDst(TrailingSliceLayout { elem_size, offset: 11 }),
703 };
704
705 let composite = base.extend(trailing_field, pack);
706
707 let max_align = pack.unwrap_or(DstLayout::CURRENT_MAX_ALIGN).get();
708
709 let align = align.get().min(max_align);
710
711 assert_eq!(
712 composite,
713 DstLayout {
714 align: NonZeroUsize::new(align).unwrap(),
715 size_info: SizeInfo::SliceDst(TrailingSliceLayout {
716 elem_size,
717 offset: align + trailing_field_offset,
718 }),
719 }
720 )
721 }
722 }
723 }
724
725 /// Tests that calling `pad_to_align` on a sized `DstLayout` adds the
726 /// expected amount of trailing padding.
727 #[test]
728 fn test_dst_layout_pad_to_align_with_sized() {
729 // For all valid alignments `align`, construct a one-byte layout aligned
730 // to `align`, call `pad_to_align`, and assert that the size of the
731 // resulting layout is equal to `align`.
732 for align in (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap()) {
733 let layout = DstLayout { align, size_info: SizeInfo::Sized { size: 1 } };
734
735 assert_eq!(
736 layout.pad_to_align(),
737 DstLayout { align, size_info: SizeInfo::Sized { size: align.get() } }
738 );
739 }
740
741 // Test explicitly-provided combinations of unpadded and padded
742 // counterparts.
743
744 macro_rules! test {
745 (unpadded { size: $unpadded_size:expr, align: $unpadded_align:expr }
746 => padded { size: $padded_size:expr, align: $padded_align:expr }) => {
747 let unpadded = DstLayout {
748 align: NonZeroUsize::new($unpadded_align).unwrap(),
749 size_info: SizeInfo::Sized { size: $unpadded_size },
750 };
751 let padded = unpadded.pad_to_align();
752
753 assert_eq!(
754 padded,
755 DstLayout {
756 align: NonZeroUsize::new($padded_align).unwrap(),
757 size_info: SizeInfo::Sized { size: $padded_size },
758 }
759 );
760 };
761 }
762
763 test!(unpadded { size: 0, align: 4 } => padded { size: 0, align: 4 });
764 test!(unpadded { size: 1, align: 4 } => padded { size: 4, align: 4 });
765 test!(unpadded { size: 2, align: 4 } => padded { size: 4, align: 4 });
766 test!(unpadded { size: 3, align: 4 } => padded { size: 4, align: 4 });
767 test!(unpadded { size: 4, align: 4 } => padded { size: 4, align: 4 });
768 test!(unpadded { size: 5, align: 4 } => padded { size: 8, align: 4 });
769 test!(unpadded { size: 6, align: 4 } => padded { size: 8, align: 4 });
770 test!(unpadded { size: 7, align: 4 } => padded { size: 8, align: 4 });
771 test!(unpadded { size: 8, align: 4 } => padded { size: 8, align: 4 });
772
773 let current_max_align = DstLayout::CURRENT_MAX_ALIGN.get();
774
775 test!(unpadded { size: 1, align: current_max_align }
776 => padded { size: current_max_align, align: current_max_align });
777
778 test!(unpadded { size: current_max_align + 1, align: current_max_align }
779 => padded { size: current_max_align * 2, align: current_max_align });
780 }
781
782 /// Tests that calling `pad_to_align` on a DST `DstLayout` is a no-op.
783 #[test]
784 fn test_dst_layout_pad_to_align_with_dst() {
785 for align in (0..29).map(|p| NonZeroUsize::new(2usize.pow(p)).unwrap()) {
786 for offset in 0..10 {
787 for elem_size in 0..10 {
788 let layout = DstLayout {
789 align,
790 size_info: SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }),
791 };
792 assert_eq!(layout.pad_to_align(), layout);
793 }
794 }
795 }
796 }
797
798 // This test takes a long time when running under Miri, so we skip it in
799 // that case. This is acceptable because this is a logic test that doesn't
800 // attempt to expose UB.
801 #[test]
802 #[cfg_attr(miri, ignore)]
803 fn test_validate_cast_and_convert_metadata() {
804 #[allow(non_local_definitions)]
805 impl From<usize> for SizeInfo {
806 fn from(size: usize) -> SizeInfo {
807 SizeInfo::Sized { size }
808 }
809 }
810
811 #[allow(non_local_definitions)]
812 impl From<(usize, usize)> for SizeInfo {
813 fn from((offset, elem_size): (usize, usize)) -> SizeInfo {
814 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size })
815 }
816 }
817
818 fn layout<S: Into<SizeInfo>>(s: S, align: usize) -> DstLayout {
819 DstLayout { size_info: s.into(), align: NonZeroUsize::new(align).unwrap() }
820 }
821
822 /// This macro accepts arguments in the form of:
823 ///
824 /// layout(_, _).validate(_, _, _), Ok(Some((_, _)))
825 /// | | | | | | |
826 /// size ---------+ | | | | | |
827 /// align -----------+ | | | | |
828 /// addr ------------------------+ | | | |
829 /// bytes_len ----------------------+ | | |
830 /// cast_type -------------------------+ | |
831 /// elems ------------------------------------------+ |
832 /// split_at ------------------------------------------+
833 ///
834 /// `.validate` is shorthand for `.validate_cast_and_convert_metadata`
835 /// for brevity.
836 ///
837 /// Each argument can either be an iterator or a wildcard. Each
838 /// wildcarded variable is implicitly replaced by an iterator over a
839 /// representative sample of values for that variable. Each `test!`
840 /// invocation iterates over every combination of values provided by
841 /// each variable's iterator (ie, the cartesian product) and validates
842 /// that the results are expected.
843 ///
844 /// The final argument uses the same syntax, but it has a different
845 /// meaning:
846 /// - If it is `Ok(pat)`, then the pattern `pat` is supplied to
847 /// a matching assert to validate the computed result for each
848 /// combination of input values.
849 /// - If it is `Err(Some(msg) | None)`, then `test!` validates that the
850 /// call to `validate_cast_and_convert_metadata` panics with the given
851 /// panic message or, if the current Rust toolchain version is too
852 /// early to support panicking in `const fn`s, panics with *some*
853 /// message. In the latter case, the `const_panic!` macro is used,
854 /// which emits code which causes a non-panicking error at const eval
855 /// time, but which does panic when invoked at runtime. Thus, it is
856 /// merely difficult to predict the *value* of this panic. We deem
857 /// that testing against the real panic strings on stable and nightly
858 /// toolchains is enough to ensure correctness.
859 ///
860 /// Note that the meta-variables that match these variables have the
861 /// `tt` type, and some valid expressions are not valid `tt`s (such as
862 /// `a..b`). In this case, wrap the expression in parentheses, and it
863 /// will become valid `tt`.
864 macro_rules! test {
865 (
866 layout($size:tt, $align:tt)
867 .validate($addr:tt, $bytes_len:tt, $cast_type:tt), $expect:pat $(,)?
868 ) => {
869 itertools::iproduct!(
870 test!(@generate_size $size),
871 test!(@generate_align $align),
872 test!(@generate_usize $addr),
873 test!(@generate_usize $bytes_len),
874 test!(@generate_cast_type $cast_type)
875 ).for_each(|(size_info, align, addr, bytes_len, cast_type)| {
876 // Temporarily disable the panic hook installed by the test
877 // harness. If we don't do this, all panic messages will be
878 // kept in an internal log. On its own, this isn't a
879 // problem, but if a non-caught panic ever happens (ie, in
880 // code later in this test not in this macro), all of the
881 // previously-buffered messages will be dumped, hiding the
882 // real culprit.
883 let previous_hook = std::panic::take_hook();
884 // I don't understand why, but this seems to be required in
885 // addition to the previous line.
886 std::panic::set_hook(Box::new(|_| {}));
887 let actual = std::panic::catch_unwind(|| {
888 layout(size_info, align).validate_cast_and_convert_metadata(addr, bytes_len, cast_type)
889 }).map_err(|d| {
890 let msg = d.downcast::<&'static str>().ok().map(|s| *s.as_ref());
891 assert!(msg.is_some() || cfg!(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)), "non-string panic messages are not permitted when `--cfg zerocopy_panic_in_const_and_vec_try_reserve` is set");
892 msg
893 });
894 std::panic::set_hook(previous_hook);
895
896 assert!(
897 matches!(actual, $expect),
898 "layout({:?}, {}).validate_cast_and_convert_metadata({}, {}, {:?})" ,size_info, align, addr, bytes_len, cast_type
899 );
900 });
901 };
902 (@generate_usize _) => { 0..8 };
903 // Generate sizes for both Sized and !Sized types.
904 (@generate_size _) => {
905 test!(@generate_size (_)).chain(test!(@generate_size (_, _)))
906 };
907 // Generate sizes for both Sized and !Sized types by chaining
908 // specified iterators for each.
909 (@generate_size ($sized_sizes:tt | $unsized_sizes:tt)) => {
910 test!(@generate_size ($sized_sizes)).chain(test!(@generate_size $unsized_sizes))
911 };
912 // Generate sizes for Sized types.
913 (@generate_size (_)) => { test!(@generate_size (0..8)) };
914 (@generate_size ($sizes:expr)) => { $sizes.into_iter().map(Into::<SizeInfo>::into) };
915 // Generate sizes for !Sized types.
916 (@generate_size ($min_sizes:tt, $elem_sizes:tt)) => {
917 itertools::iproduct!(
918 test!(@generate_min_size $min_sizes),
919 test!(@generate_elem_size $elem_sizes)
920 ).map(Into::<SizeInfo>::into)
921 };
922 (@generate_fixed_size _) => { (0..8).into_iter().map(Into::<SizeInfo>::into) };
923 (@generate_min_size _) => { 0..8 };
924 (@generate_elem_size _) => { 1..8 };
925 (@generate_align _) => { [1, 2, 4, 8, 16] };
926 (@generate_opt_usize _) => { [None].into_iter().chain((0..8).map(Some).into_iter()) };
927 (@generate_cast_type _) => { [CastType::Prefix, CastType::Suffix] };
928 (@generate_cast_type $variant:ident) => { [CastType::$variant] };
929 // Some expressions need to be wrapped in parentheses in order to be
930 // valid `tt`s (required by the top match pattern). See the comment
931 // below for more details. This arm removes these parentheses to
932 // avoid generating an `unused_parens` warning.
933 (@$_:ident ($vals:expr)) => { $vals };
934 (@$_:ident $vals:expr) => { $vals };
935 }
936
937 const EVENS: [usize; 8] = [0, 2, 4, 6, 8, 10, 12, 14];
938 const ODDS: [usize; 8] = [1, 3, 5, 7, 9, 11, 13, 15];
939
940 // base_size is too big for the memory region.
941 test!(
942 layout(((1..8) | ((1..8), (1..8))), _).validate([0], [0], _),
943 Ok(Err(MetadataCastError::Size))
944 );
945 test!(
946 layout(((2..8) | ((2..8), (2..8))), _).validate([0], [1], Prefix),
947 Ok(Err(MetadataCastError::Size))
948 );
949 test!(
950 layout(((2..8) | ((2..8), (2..8))), _).validate([0x1000_0000 - 1], [1], Suffix),
951 Ok(Err(MetadataCastError::Size))
952 );
953
954 // addr is unaligned for prefix cast
955 test!(layout(_, [2]).validate(ODDS, _, Prefix), Ok(Err(MetadataCastError::Alignment)));
956 test!(layout(_, [2]).validate(ODDS, _, Prefix), Ok(Err(MetadataCastError::Alignment)));
957
958 // addr is aligned, but end of buffer is unaligned for suffix cast
959 test!(layout(_, [2]).validate(EVENS, ODDS, Suffix), Ok(Err(MetadataCastError::Alignment)));
960 test!(layout(_, [2]).validate(EVENS, ODDS, Suffix), Ok(Err(MetadataCastError::Alignment)));
961
962 // Unfortunately, these constants cannot easily be used in the
963 // implementation of `validate_cast_and_convert_metadata`, since
964 // `panic!` consumes a string literal, not an expression.
965 //
966 // It's important that these messages be in a separate module. If they
967 // were at the function's top level, we'd pass them to `test!` as, e.g.,
968 // `Err(TRAILING)`, which would run into a subtle Rust footgun - the
969 // `TRAILING` identifier would be treated as a pattern to match rather
970 // than a value to check for equality.
971 mod msgs {
972 pub(super) const TRAILING: &str =
973 "attempted to cast to slice type with zero-sized element";
974 pub(super) const OVERFLOW: &str = "`addr` + `bytes_len` > usize::MAX";
975 }
976
977 // casts with ZST trailing element types are unsupported
978 test!(layout((_, [0]), _).validate(_, _, _), Err(Some(msgs::TRAILING) | None),);
979
980 // addr + bytes_len must not overflow usize
981 test!(layout(_, _).validate([usize::MAX], (1..100), _), Err(Some(msgs::OVERFLOW) | None));
982 test!(layout(_, _).validate((1..100), [usize::MAX], _), Err(Some(msgs::OVERFLOW) | None));
983 test!(
984 layout(_, _).validate(
985 [usize::MAX / 2 + 1, usize::MAX],
986 [usize::MAX / 2 + 1, usize::MAX],
987 _
988 ),
989 Err(Some(msgs::OVERFLOW) | None)
990 );
991
992 // Validates that `validate_cast_and_convert_metadata` satisfies its own
993 // documented safety postconditions, and also a few other properties
994 // that aren't documented but we want to guarantee anyway.
995 fn validate_behavior(
996 (layout, addr, bytes_len, cast_type): (DstLayout, usize, usize, CastType),
997 ) {
998 if let Ok((elems, split_at)) =
999 layout.validate_cast_and_convert_metadata(addr, bytes_len, cast_type)
1000 {
1001 let (size_info, align) = (layout.size_info, layout.align);
1002 let debug_str = format!(
1003 "layout({:?}, {}).validate_cast_and_convert_metadata({}, {}, {:?}) => ({}, {})",
1004 size_info, align, addr, bytes_len, cast_type, elems, split_at
1005 );
1006
1007 // If this is a sized type (no trailing slice), then `elems` is
1008 // meaningless, but in practice we set it to 0. Callers are not
1009 // allowed to rely on this, but a lot of math is nicer if
1010 // they're able to, and some callers might accidentally do that.
1011 let sized = matches!(layout.size_info, SizeInfo::Sized { .. });
1012 assert!(!(sized && elems != 0), "{}", debug_str);
1013
1014 let resulting_size = match layout.size_info {
1015 SizeInfo::Sized { size } => size,
1016 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size }) => {
1017 let padded_size = |elems| {
1018 let without_padding = offset + elems * elem_size;
1019 without_padding + util::padding_needed_for(without_padding, align)
1020 };
1021
1022 let resulting_size = padded_size(elems);
1023 // Test that `validate_cast_and_convert_metadata`
1024 // computed the largest possible value that fits in the
1025 // given range.
1026 assert!(padded_size(elems + 1) > bytes_len, "{}", debug_str);
1027 resulting_size
1028 }
1029 };
1030
1031 // Test safety postconditions guaranteed by
1032 // `validate_cast_and_convert_metadata`.
1033 assert!(resulting_size <= bytes_len, "{}", debug_str);
1034 match cast_type {
1035 CastType::Prefix => {
1036 assert_eq!(addr % align, 0, "{}", debug_str);
1037 assert_eq!(resulting_size, split_at, "{}", debug_str);
1038 }
1039 CastType::Suffix => {
1040 assert_eq!(split_at, bytes_len - resulting_size, "{}", debug_str);
1041 assert_eq!((addr + split_at) % align, 0, "{}", debug_str);
1042 }
1043 }
1044 } else {
1045 let min_size = match layout.size_info {
1046 SizeInfo::Sized { size } => size,
1047 SizeInfo::SliceDst(TrailingSliceLayout { offset, .. }) => {
1048 offset + util::padding_needed_for(offset, layout.align)
1049 }
1050 };
1051
1052 // If a cast is invalid, it is either because...
1053 // 1. there are insufficent bytes at the given region for type:
1054 let insufficient_bytes = bytes_len < min_size;
1055 // 2. performing the cast would misalign type:
1056 let base = match cast_type {
1057 CastType::Prefix => 0,
1058 CastType::Suffix => bytes_len,
1059 };
1060 let misaligned = (base + addr) % layout.align != 0;
1061
1062 assert!(insufficient_bytes || misaligned);
1063 }
1064 }
1065
1066 let sizes = 0..8;
1067 let elem_sizes = 1..8;
1068 let size_infos = sizes
1069 .clone()
1070 .map(Into::<SizeInfo>::into)
1071 .chain(itertools::iproduct!(sizes, elem_sizes).map(Into::<SizeInfo>::into));
1072 let layouts = itertools::iproduct!(size_infos, [1, 2, 4, 8, 16, 32])
1073 .filter(|(size_info, align)| !matches!(size_info, SizeInfo::Sized { size } if size % align != 0))
1074 .map(|(size_info, align)| layout(size_info, align));
1075 itertools::iproduct!(layouts, 0..8, 0..8, [CastType::Prefix, CastType::Suffix])
1076 .for_each(validate_behavior);
1077 }
1078
1079 #[test]
1080 #[cfg(__ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS)]
1081 fn test_validate_rust_layout() {
1082 use crate::util::testutil::*;
1083 use core::{
1084 convert::TryInto as _,
1085 ptr::{self, NonNull},
1086 };
1087
1088 // This test synthesizes pointers with various metadata and uses Rust's
1089 // built-in APIs to confirm that Rust makes decisions about type layout
1090 // which are consistent with what we believe is guaranteed by the
1091 // language. If this test fails, it doesn't just mean our code is wrong
1092 // - it means we're misunderstanding the language's guarantees.
1093
1094 #[derive(Debug)]
1095 struct MacroArgs {
1096 offset: usize,
1097 align: NonZeroUsize,
1098 elem_size: Option<usize>,
1099 }
1100
1101 /// # Safety
1102 ///
1103 /// `test` promises to only call `addr_of_slice_field` on a `NonNull<T>`
1104 /// which points to a valid `T`.
1105 ///
1106 /// `with_elems` must produce a pointer which points to a valid `T`.
1107 fn test<T: ?Sized, W: Fn(usize) -> NonNull<T>>(
1108 args: MacroArgs,
1109 with_elems: W,
1110 addr_of_slice_field: Option<fn(NonNull<T>) -> NonNull<u8>>,
1111 ) {
1112 let dst = args.elem_size.is_some();
1113 let layout = {
1114 let size_info = match args.elem_size {
1115 Some(elem_size) => {
1116 SizeInfo::SliceDst(TrailingSliceLayout { offset: args.offset, elem_size })
1117 }
1118 None => SizeInfo::Sized {
1119 // Rust only supports types whose sizes are a multiple
1120 // of their alignment. If the macro created a type like
1121 // this:
1122 //
1123 // #[repr(C, align(2))]
1124 // struct Foo([u8; 1]);
1125 //
1126 // ...then Rust will automatically round the type's size
1127 // up to 2.
1128 size: args.offset + util::padding_needed_for(args.offset, args.align),
1129 },
1130 };
1131 DstLayout { size_info, align: args.align }
1132 };
1133
1134 for elems in 0..128 {
1135 let ptr = with_elems(elems);
1136
1137 if let Some(addr_of_slice_field) = addr_of_slice_field {
1138 let slc_field_ptr = addr_of_slice_field(ptr).as_ptr();
1139 // SAFETY: Both `slc_field_ptr` and `ptr` are pointers to
1140 // the same valid Rust object.
1141 #[allow(clippy::incompatible_msrv)]
1142 // Work around https://github.com/rust-lang/rust-clippy/issues/12280
1143 let offset: usize =
1144 unsafe { slc_field_ptr.byte_offset_from(ptr.as_ptr()).try_into().unwrap() };
1145 assert_eq!(offset, args.offset);
1146 }
1147
1148 // SAFETY: `ptr` points to a valid `T`.
1149 let (size, align) = unsafe {
1150 (mem::size_of_val_raw(ptr.as_ptr()), mem::align_of_val_raw(ptr.as_ptr()))
1151 };
1152
1153 // Avoid expensive allocation when running under Miri.
1154 let assert_msg = if !cfg!(miri) {
1155 format!("\n{:?}\nsize:{}, align:{}", args, size, align)
1156 } else {
1157 String::new()
1158 };
1159
1160 let without_padding =
1161 args.offset + args.elem_size.map(|elem_size| elems * elem_size).unwrap_or(0);
1162 assert!(size >= without_padding, "{}", assert_msg);
1163 assert_eq!(align, args.align.get(), "{}", assert_msg);
1164
1165 // This encodes the most important part of the test: our
1166 // understanding of how Rust determines the layout of repr(C)
1167 // types. Sized repr(C) types are trivial, but DST types have
1168 // some subtlety. Note that:
1169 // - For sized types, `without_padding` is just the size of the
1170 // type that we constructed for `Foo`. Since we may have
1171 // requested a larger alignment, `Foo` may actually be larger
1172 // than this, hence `padding_needed_for`.
1173 // - For unsized types, `without_padding` is dynamically
1174 // computed from the offset, the element size, and element
1175 // count. We expect that the size of the object should be
1176 // `offset + elem_size * elems` rounded up to the next
1177 // alignment.
1178 let expected_size =
1179 without_padding + util::padding_needed_for(without_padding, args.align);
1180 assert_eq!(expected_size, size, "{}", assert_msg);
1181
1182 // For zero-sized element types,
1183 // `validate_cast_and_convert_metadata` just panics, so we skip
1184 // testing those types.
1185 if args.elem_size.map(|elem_size| elem_size > 0).unwrap_or(true) {
1186 let addr = ptr.addr().get();
1187 let (got_elems, got_split_at) = layout
1188 .validate_cast_and_convert_metadata(addr, size, CastType::Prefix)
1189 .unwrap();
1190 // Avoid expensive allocation when running under Miri.
1191 let assert_msg = if !cfg!(miri) {
1192 format!(
1193 "{}\nvalidate_cast_and_convert_metadata({}, {})",
1194 assert_msg, addr, size,
1195 )
1196 } else {
1197 String::new()
1198 };
1199 assert_eq!(got_split_at, size, "{}", assert_msg);
1200 if dst {
1201 assert!(got_elems >= elems, "{}", assert_msg);
1202 if got_elems != elems {
1203 // If `validate_cast_and_convert_metadata`
1204 // returned more elements than `elems`, that
1205 // means that `elems` is not the maximum number
1206 // of elements that can fit in `size` - in other
1207 // words, there is enough padding at the end of
1208 // the value to fit at least one more element.
1209 // If we use this metadata to synthesize a
1210 // pointer, despite having a different element
1211 // count, we still expect it to have the same
1212 // size.
1213 let got_ptr = with_elems(got_elems);
1214 // SAFETY: `got_ptr` is a pointer to a valid `T`.
1215 let size_of_got_ptr = unsafe { mem::size_of_val_raw(got_ptr.as_ptr()) };
1216 assert_eq!(size_of_got_ptr, size, "{}", assert_msg);
1217 }
1218 } else {
1219 // For sized casts, the returned element value is
1220 // technically meaningless, and we don't guarantee any
1221 // particular value. In practice, it's always zero.
1222 assert_eq!(got_elems, 0, "{}", assert_msg)
1223 }
1224 }
1225 }
1226 }
1227
1228 macro_rules! validate_against_rust {
1229 ($offset:literal, $align:literal $(, $elem_size:literal)?) => {{
1230 #[repr(C, align($align))]
1231 struct Foo([u8; $offset]$(, [[u8; $elem_size]])?);
1232
1233 let args = MacroArgs {
1234 offset: $offset,
1235 align: $align.try_into().unwrap(),
1236 elem_size: {
1237 #[allow(unused)]
1238 let ret = None::<usize>;
1239 $(let ret = Some($elem_size);)?
1240 ret
1241 }
1242 };
1243
1244 #[repr(C, align($align))]
1245 struct FooAlign;
1246 // Create an aligned buffer to use in order to synthesize
1247 // pointers to `Foo`. We don't ever load values from these
1248 // pointers - we just do arithmetic on them - so having a "real"
1249 // block of memory as opposed to a validly-aligned-but-dangling
1250 // pointer is only necessary to make Miri happy since we run it
1251 // with "strict provenance" checking enabled.
1252 let aligned_buf = Align::<_, FooAlign>::new([0u8; 1024]);
1253 let with_elems = |elems| {
1254 let slc = NonNull::slice_from_raw_parts(NonNull::from(&aligned_buf.t), elems);
1255 #[allow(clippy::as_conversions)]
1256 NonNull::new(slc.as_ptr() as *mut Foo).unwrap()
1257 };
1258 let addr_of_slice_field = {
1259 #[allow(unused)]
1260 let f = None::<fn(NonNull<Foo>) -> NonNull<u8>>;
1261 $(
1262 // SAFETY: `test` promises to only call `f` with a `ptr`
1263 // to a valid `Foo`.
1264 let f: Option<fn(NonNull<Foo>) -> NonNull<u8>> = Some(|ptr: NonNull<Foo>| unsafe {
1265 NonNull::new(ptr::addr_of_mut!((*ptr.as_ptr()).1)).unwrap().cast::<u8>()
1266 });
1267 let _ = $elem_size;
1268 )?
1269 f
1270 };
1271
1272 test::<Foo, _>(args, with_elems, addr_of_slice_field);
1273 }};
1274 }
1275
1276 // Every permutation of:
1277 // - offset in [0, 4]
1278 // - align in [1, 16]
1279 // - elem_size in [0, 4] (plus no elem_size)
1280 validate_against_rust!(0, 1);
1281 validate_against_rust!(0, 1, 0);
1282 validate_against_rust!(0, 1, 1);
1283 validate_against_rust!(0, 1, 2);
1284 validate_against_rust!(0, 1, 3);
1285 validate_against_rust!(0, 1, 4);
1286 validate_against_rust!(0, 2);
1287 validate_against_rust!(0, 2, 0);
1288 validate_against_rust!(0, 2, 1);
1289 validate_against_rust!(0, 2, 2);
1290 validate_against_rust!(0, 2, 3);
1291 validate_against_rust!(0, 2, 4);
1292 validate_against_rust!(0, 4);
1293 validate_against_rust!(0, 4, 0);
1294 validate_against_rust!(0, 4, 1);
1295 validate_against_rust!(0, 4, 2);
1296 validate_against_rust!(0, 4, 3);
1297 validate_against_rust!(0, 4, 4);
1298 validate_against_rust!(0, 8);
1299 validate_against_rust!(0, 8, 0);
1300 validate_against_rust!(0, 8, 1);
1301 validate_against_rust!(0, 8, 2);
1302 validate_against_rust!(0, 8, 3);
1303 validate_against_rust!(0, 8, 4);
1304 validate_against_rust!(0, 16);
1305 validate_against_rust!(0, 16, 0);
1306 validate_against_rust!(0, 16, 1);
1307 validate_against_rust!(0, 16, 2);
1308 validate_against_rust!(0, 16, 3);
1309 validate_against_rust!(0, 16, 4);
1310 validate_against_rust!(1, 1);
1311 validate_against_rust!(1, 1, 0);
1312 validate_against_rust!(1, 1, 1);
1313 validate_against_rust!(1, 1, 2);
1314 validate_against_rust!(1, 1, 3);
1315 validate_against_rust!(1, 1, 4);
1316 validate_against_rust!(1, 2);
1317 validate_against_rust!(1, 2, 0);
1318 validate_against_rust!(1, 2, 1);
1319 validate_against_rust!(1, 2, 2);
1320 validate_against_rust!(1, 2, 3);
1321 validate_against_rust!(1, 2, 4);
1322 validate_against_rust!(1, 4);
1323 validate_against_rust!(1, 4, 0);
1324 validate_against_rust!(1, 4, 1);
1325 validate_against_rust!(1, 4, 2);
1326 validate_against_rust!(1, 4, 3);
1327 validate_against_rust!(1, 4, 4);
1328 validate_against_rust!(1, 8);
1329 validate_against_rust!(1, 8, 0);
1330 validate_against_rust!(1, 8, 1);
1331 validate_against_rust!(1, 8, 2);
1332 validate_against_rust!(1, 8, 3);
1333 validate_against_rust!(1, 8, 4);
1334 validate_against_rust!(1, 16);
1335 validate_against_rust!(1, 16, 0);
1336 validate_against_rust!(1, 16, 1);
1337 validate_against_rust!(1, 16, 2);
1338 validate_against_rust!(1, 16, 3);
1339 validate_against_rust!(1, 16, 4);
1340 validate_against_rust!(2, 1);
1341 validate_against_rust!(2, 1, 0);
1342 validate_against_rust!(2, 1, 1);
1343 validate_against_rust!(2, 1, 2);
1344 validate_against_rust!(2, 1, 3);
1345 validate_against_rust!(2, 1, 4);
1346 validate_against_rust!(2, 2);
1347 validate_against_rust!(2, 2, 0);
1348 validate_against_rust!(2, 2, 1);
1349 validate_against_rust!(2, 2, 2);
1350 validate_against_rust!(2, 2, 3);
1351 validate_against_rust!(2, 2, 4);
1352 validate_against_rust!(2, 4);
1353 validate_against_rust!(2, 4, 0);
1354 validate_against_rust!(2, 4, 1);
1355 validate_against_rust!(2, 4, 2);
1356 validate_against_rust!(2, 4, 3);
1357 validate_against_rust!(2, 4, 4);
1358 validate_against_rust!(2, 8);
1359 validate_against_rust!(2, 8, 0);
1360 validate_against_rust!(2, 8, 1);
1361 validate_against_rust!(2, 8, 2);
1362 validate_against_rust!(2, 8, 3);
1363 validate_against_rust!(2, 8, 4);
1364 validate_against_rust!(2, 16);
1365 validate_against_rust!(2, 16, 0);
1366 validate_against_rust!(2, 16, 1);
1367 validate_against_rust!(2, 16, 2);
1368 validate_against_rust!(2, 16, 3);
1369 validate_against_rust!(2, 16, 4);
1370 validate_against_rust!(3, 1);
1371 validate_against_rust!(3, 1, 0);
1372 validate_against_rust!(3, 1, 1);
1373 validate_against_rust!(3, 1, 2);
1374 validate_against_rust!(3, 1, 3);
1375 validate_against_rust!(3, 1, 4);
1376 validate_against_rust!(3, 2);
1377 validate_against_rust!(3, 2, 0);
1378 validate_against_rust!(3, 2, 1);
1379 validate_against_rust!(3, 2, 2);
1380 validate_against_rust!(3, 2, 3);
1381 validate_against_rust!(3, 2, 4);
1382 validate_against_rust!(3, 4);
1383 validate_against_rust!(3, 4, 0);
1384 validate_against_rust!(3, 4, 1);
1385 validate_against_rust!(3, 4, 2);
1386 validate_against_rust!(3, 4, 3);
1387 validate_against_rust!(3, 4, 4);
1388 validate_against_rust!(3, 8);
1389 validate_against_rust!(3, 8, 0);
1390 validate_against_rust!(3, 8, 1);
1391 validate_against_rust!(3, 8, 2);
1392 validate_against_rust!(3, 8, 3);
1393 validate_against_rust!(3, 8, 4);
1394 validate_against_rust!(3, 16);
1395 validate_against_rust!(3, 16, 0);
1396 validate_against_rust!(3, 16, 1);
1397 validate_against_rust!(3, 16, 2);
1398 validate_against_rust!(3, 16, 3);
1399 validate_against_rust!(3, 16, 4);
1400 validate_against_rust!(4, 1);
1401 validate_against_rust!(4, 1, 0);
1402 validate_against_rust!(4, 1, 1);
1403 validate_against_rust!(4, 1, 2);
1404 validate_against_rust!(4, 1, 3);
1405 validate_against_rust!(4, 1, 4);
1406 validate_against_rust!(4, 2);
1407 validate_against_rust!(4, 2, 0);
1408 validate_against_rust!(4, 2, 1);
1409 validate_against_rust!(4, 2, 2);
1410 validate_against_rust!(4, 2, 3);
1411 validate_against_rust!(4, 2, 4);
1412 validate_against_rust!(4, 4);
1413 validate_against_rust!(4, 4, 0);
1414 validate_against_rust!(4, 4, 1);
1415 validate_against_rust!(4, 4, 2);
1416 validate_against_rust!(4, 4, 3);
1417 validate_against_rust!(4, 4, 4);
1418 validate_against_rust!(4, 8);
1419 validate_against_rust!(4, 8, 0);
1420 validate_against_rust!(4, 8, 1);
1421 validate_against_rust!(4, 8, 2);
1422 validate_against_rust!(4, 8, 3);
1423 validate_against_rust!(4, 8, 4);
1424 validate_against_rust!(4, 16);
1425 validate_against_rust!(4, 16, 0);
1426 validate_against_rust!(4, 16, 1);
1427 validate_against_rust!(4, 16, 2);
1428 validate_against_rust!(4, 16, 3);
1429 validate_against_rust!(4, 16, 4);
1430 }
1431}
1432
1433#[cfg(kani)]
1434mod proofs {
1435 use core::alloc::Layout;
1436
1437 use super::*;
1438
1439 impl kani::Arbitrary for DstLayout {
1440 fn any() -> Self {
1441 let align: NonZeroUsize = kani::any();
1442 let size_info: SizeInfo = kani::any();
1443
1444 kani::assume(align.is_power_of_two());
1445 kani::assume(align < DstLayout::THEORETICAL_MAX_ALIGN);
1446
1447 // For testing purposes, we most care about instantiations of
1448 // `DstLayout` that can correspond to actual Rust types. We use
1449 // `Layout` to verify that our `DstLayout` satisfies the validity
1450 // conditions of Rust layouts.
1451 kani::assume(
1452 match size_info {
1453 SizeInfo::Sized { size } => Layout::from_size_align(size, align.get()),
1454 SizeInfo::SliceDst(TrailingSliceLayout { offset, elem_size: _ }) => {
1455 // `SliceDst`` cannot encode an exact size, but we know
1456 // it is at least `offset` bytes.
1457 Layout::from_size_align(offset, align.get())
1458 }
1459 }
1460 .is_ok(),
1461 );
1462
1463 Self { align: align, size_info: size_info }
1464 }
1465 }
1466
1467 impl kani::Arbitrary for SizeInfo {
1468 fn any() -> Self {
1469 let is_sized: bool = kani::any();
1470
1471 match is_sized {
1472 true => {
1473 let size: usize = kani::any();
1474
1475 kani::assume(size <= isize::MAX as _);
1476
1477 SizeInfo::Sized { size }
1478 }
1479 false => SizeInfo::SliceDst(kani::any()),
1480 }
1481 }
1482 }
1483
1484 impl kani::Arbitrary for TrailingSliceLayout {
1485 fn any() -> Self {
1486 let elem_size: usize = kani::any();
1487 let offset: usize = kani::any();
1488
1489 kani::assume(elem_size < isize::MAX as _);
1490 kani::assume(offset < isize::MAX as _);
1491
1492 TrailingSliceLayout { elem_size, offset }
1493 }
1494 }
1495
1496 #[kani::proof]
1497 fn prove_dst_layout_extend() {
1498 use crate::util::{max, min, padding_needed_for};
1499
1500 let base: DstLayout = kani::any();
1501 let field: DstLayout = kani::any();
1502 let packed: Option<NonZeroUsize> = kani::any();
1503
1504 if let Some(max_align) = packed {
1505 kani::assume(max_align.is_power_of_two());
1506 kani::assume(base.align <= max_align);
1507 }
1508
1509 // The base can only be extended if it's sized.
1510 kani::assume(matches!(base.size_info, SizeInfo::Sized { .. }));
1511 let base_size = if let SizeInfo::Sized { size } = base.size_info {
1512 size
1513 } else {
1514 unreachable!();
1515 };
1516
1517 // Under the above conditions, `DstLayout::extend` will not panic.
1518 let composite = base.extend(field, packed);
1519
1520 // The field's alignment is clamped by `max_align` (i.e., the
1521 // `packed` attribute, if any) [1].
1522 //
1523 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers:
1524 //
1525 // The alignments of each field, for the purpose of positioning
1526 // fields, is the smaller of the specified alignment and the
1527 // alignment of the field's type.
1528 let field_align = min(field.align, packed.unwrap_or(DstLayout::THEORETICAL_MAX_ALIGN));
1529
1530 // The struct's alignment is the maximum of its previous alignment and
1531 // `field_align`.
1532 assert_eq!(composite.align, max(base.align, field_align));
1533
1534 // Compute the minimum amount of inter-field padding needed to
1535 // satisfy the field's alignment, and offset of the trailing field.
1536 // [1]
1537 //
1538 // [1] Per https://doc.rust-lang.org/reference/type-layout.html#the-alignment-modifiers:
1539 //
1540 // Inter-field padding is guaranteed to be the minimum required in
1541 // order to satisfy each field's (possibly altered) alignment.
1542 let padding = padding_needed_for(base_size, field_align);
1543 let offset = base_size + padding;
1544
1545 // For testing purposes, we'll also construct `alloc::Layout`
1546 // stand-ins for `DstLayout`, and show that `extend` behaves
1547 // comparably on both types.
1548 let base_analog = Layout::from_size_align(base_size, base.align.get()).unwrap();
1549
1550 match field.size_info {
1551 SizeInfo::Sized { size: field_size } => {
1552 if let SizeInfo::Sized { size: composite_size } = composite.size_info {
1553 // If the trailing field is sized, the resulting layout will
1554 // be sized. Its size will be the sum of the preceding
1555 // layout, the size of the new field, and the size of
1556 // inter-field padding between the two.
1557 assert_eq!(composite_size, offset + field_size);
1558
1559 let field_analog =
1560 Layout::from_size_align(field_size, field_align.get()).unwrap();
1561
1562 if let Ok((actual_composite, actual_offset)) = base_analog.extend(field_analog)
1563 {
1564 assert_eq!(actual_offset, offset);
1565 assert_eq!(actual_composite.size(), composite_size);
1566 assert_eq!(actual_composite.align(), composite.align.get());
1567 } else {
1568 // An error here reflects that composite of `base`
1569 // and `field` cannot correspond to a real Rust type
1570 // fragment, because such a fragment would violate
1571 // the basic invariants of a valid Rust layout. At
1572 // the time of writing, `DstLayout` is a little more
1573 // permissive than `Layout`, so we don't assert
1574 // anything in this branch (e.g., unreachability).
1575 }
1576 } else {
1577 panic!("The composite of two sized layouts must be sized.")
1578 }
1579 }
1580 SizeInfo::SliceDst(TrailingSliceLayout {
1581 offset: field_offset,
1582 elem_size: field_elem_size,
1583 }) => {
1584 if let SizeInfo::SliceDst(TrailingSliceLayout {
1585 offset: composite_offset,
1586 elem_size: composite_elem_size,
1587 }) = composite.size_info
1588 {
1589 // The offset of the trailing slice component is the sum
1590 // of the offset of the trailing field and the trailing
1591 // slice offset within that field.
1592 assert_eq!(composite_offset, offset + field_offset);
1593 // The elem size is unchanged.
1594 assert_eq!(composite_elem_size, field_elem_size);
1595
1596 let field_analog =
1597 Layout::from_size_align(field_offset, field_align.get()).unwrap();
1598
1599 if let Ok((actual_composite, actual_offset)) = base_analog.extend(field_analog)
1600 {
1601 assert_eq!(actual_offset, offset);
1602 assert_eq!(actual_composite.size(), composite_offset);
1603 assert_eq!(actual_composite.align(), composite.align.get());
1604 } else {
1605 // An error here reflects that composite of `base`
1606 // and `field` cannot correspond to a real Rust type
1607 // fragment, because such a fragment would violate
1608 // the basic invariants of a valid Rust layout. At
1609 // the time of writing, `DstLayout` is a little more
1610 // permissive than `Layout`, so we don't assert
1611 // anything in this branch (e.g., unreachability).
1612 }
1613 } else {
1614 panic!("The extension of a layout with a DST must result in a DST.")
1615 }
1616 }
1617 }
1618 }
1619
1620 #[kani::proof]
1621 #[kani::should_panic]
1622 fn prove_dst_layout_extend_dst_panics() {
1623 let base: DstLayout = kani::any();
1624 let field: DstLayout = kani::any();
1625 let packed: Option<NonZeroUsize> = kani::any();
1626
1627 if let Some(max_align) = packed {
1628 kani::assume(max_align.is_power_of_two());
1629 kani::assume(base.align <= max_align);
1630 }
1631
1632 kani::assume(matches!(base.size_info, SizeInfo::SliceDst(..)));
1633
1634 let _ = base.extend(field, packed);
1635 }
1636
1637 #[kani::proof]
1638 fn prove_dst_layout_pad_to_align() {
1639 use crate::util::padding_needed_for;
1640
1641 let layout: DstLayout = kani::any();
1642
1643 let padded: DstLayout = layout.pad_to_align();
1644
1645 // Calling `pad_to_align` does not alter the `DstLayout`'s alignment.
1646 assert_eq!(padded.align, layout.align);
1647
1648 if let SizeInfo::Sized { size: unpadded_size } = layout.size_info {
1649 if let SizeInfo::Sized { size: padded_size } = padded.size_info {
1650 // If the layout is sized, it will remain sized after padding is
1651 // added. Its sum will be its unpadded size and the size of the
1652 // trailing padding needed to satisfy its alignment
1653 // requirements.
1654 let padding = padding_needed_for(unpadded_size, layout.align);
1655 assert_eq!(padded_size, unpadded_size + padding);
1656
1657 // Prove that calling `DstLayout::pad_to_align` behaves
1658 // identically to `Layout::pad_to_align`.
1659 let layout_analog =
1660 Layout::from_size_align(unpadded_size, layout.align.get()).unwrap();
1661 let padded_analog = layout_analog.pad_to_align();
1662 assert_eq!(padded_analog.align(), layout.align.get());
1663 assert_eq!(padded_analog.size(), padded_size);
1664 } else {
1665 panic!("The padding of a sized layout must result in a sized layout.")
1666 }
1667 } else {
1668 // If the layout is a DST, padding cannot be statically added.
1669 assert_eq!(padded.size_info, layout.size_info);
1670 }
1671 }
1672}
1673