Teach transmute_{ref,mut}! to handle slice DSTs

This requires us to generalize our prior support for transmuting between
unsized types. In particular, we previously used the `SizeEq` trait to
denote that two types have equal sizes in the face of a cast operation
(in particular, that `*const T as *const U` preserves referent size). In
this commit, we add support for metadata fix-up, which means that we
support casts for which `*const T as *const U` does *not* preserve
referent size. Instead, we compute an affine function at compile time
and apply it at runtime - computing the destination type's metadata as a
function of the source metadata, `dst_meta = A + src_meta * B`. `A` and
`B` are computed at compile time.

We rename `SizeEq` to `SizeCompat`, and permit its `cast_from_raw`
method to perform a runtime metadata fix-up operation. We also relax the
safety post-condition to specify that `cast_from_raw` may return a
pointer with a smaller referent than that of its argument.

This second relaxation prepares us to support size truncating casts, for
example `&[u8] -> &[u16]` - given an odd number of `u8`s, the only way
to return a `&[u16]` is to "lose" the trailing `u8`. We generalize the
safety invariant on `TransmuteFrom` to support such casts.

Makes progress on #1817

Co-authored-by: Jack Wrenn <[email protected]>
gherrit-pr-id: Ib4bc62202e0b3b09d155333b525087f7aa8f02c2

Author: joshlf

src/doctests.rs

@@ -0,0 +1,125 @@
+// Copyright 2025 The Fuchsia Authors
+//
+// Licensed under the 2-Clause BSD License <LICENSE-BSD or
+// https://opensource.org/license/bsd-2-clause>, Apache License, Version 2.0
+// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
+// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
+// This file may not be copied, modified, or distributed except according to
+// those terms.
+
+#![cfg(feature = "derive")] // Required for derives on `SliceDst`
+#![allow(dead_code)]
+
+//! Our UI test framework, built on the `trybuild` crate, does not support
+//! testing for post-monomorphization errors. Instead, we use doctests, which
+//! are able to test for post-monomorphization errors.
+
+use crate::*;
+
+#[derive(KnownLayout, FromBytes, IntoBytes, Immutable)]
+#[repr(C)]
+#[allow(missing_debug_implementations, missing_copy_implementations)]
+pub struct SliceDst<T, U> {
+    pub t: T,
+    pub u: [U],
+}
+
+#[allow(clippy::must_use_candidate, clippy::missing_inline_in_public_items, clippy::todo)]
+impl<T: FromBytes + IntoBytes, U: FromBytes + IntoBytes> SliceDst<T, U> {
+    pub fn new() -> &'static SliceDst<T, U> {
+        todo!()
+    }
+
+    pub fn new_mut() -> &'static mut SliceDst<T, U> {
+        todo!()
+    }
+}
+
+/// `transmute_ref!` does not support transmuting from a type of smaller
+/// alignment to one of larger alignment.
+///
+/// ```compile_fail,E0080
+/// let increase_alignment: &u16 = zerocopy::transmute_ref!(&[0u8; 2]);
+/// ```
+///
+/// ```compile_fail,E0080
+/// let mut src = [0u8; 2];
+/// let increase_alignment: &mut u16 = zerocopy::transmute_mut!(&mut src);
+/// ```
+enum TransmuteRefMutAlignmentIncrease {}
+
+/// We require that the size of the destination type is not larger than the size
+/// of the source type.
+///
+/// ```compile_fail,E0080
+/// let increase_size: &[u8; 2] = zerocopy::transmute_ref!(&0u8);
+/// ```
+///
+/// ```compile_fail,E0080
+/// let mut src = 0u8;
+/// let increase_size: &mut [u8; 2] = zerocopy::transmute_mut!(&mut src);
+/// ```
+enum TransmuteRefMutSizeIncrease {}
+
+/// We require that the size of the destination type is not smaller than the
+/// size of the source type.
+///
+/// ```compile_fail,E0080
+/// let decrease_size: &u8 = zerocopy::transmute_ref!(&[0u8; 2]);
+/// ```
+///
+/// ```compile_fail,E0080
+/// let mut src = [0u8; 2];
+/// let decrease_size: &mut u8 = zerocopy::transmute_mut!(&mut src);
+/// ```
+enum TransmuteRefMutSizeDecrease {}
+
+/// It's not possible in the general case to increase the trailing slice offset
+/// during a reference transmutation - some pointer metadata values would not be
+/// supportable, and so such a transmutation would be fallible.
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &SliceDst<u8, u8> = SliceDst::new();
+/// let increase_offset: &SliceDst<[u8; 2], u8> = zerocopy::transmute_ref!(src);
+/// ```
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &mut SliceDst<u8, u8> = SliceDst::new_mut();
+/// let increase_offset: &mut SliceDst<[u8; 2], u8> = zerocopy::transmute_mut!(src);
+/// ```
+enum TransmuteRefMutDstOffsetIncrease {}
+
+/// Reference transmutes are not possible when the difference between the source
+/// and destination types' trailing slice offsets is not a multiple of the
+/// destination type's trailing slice element size.
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &SliceDst<[u8; 3], [u8; 2]> = SliceDst::new();
+/// let _: &SliceDst<[u8; 2], [u8; 2]> = zerocopy::transmute_ref!(src);
+/// ```
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &mut SliceDst<[u8; 3], [u8; 2]> = SliceDst::new_mut();
+/// let _: &mut SliceDst<[u8; 2], [u8; 2]> = zerocopy::transmute_mut!(src);
+/// ```
+enum TransmuteRefMutDstOffsetNotMultiple {}
+
+/// Reference transmutes are not possible when the source's trailing slice
+/// element size is not a multiple of the destination's.
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &SliceDst<(), [u8; 3]> = SliceDst::new();
+/// let _: &SliceDst<(), [u8; 2]> = zerocopy::transmute_ref!(src);
+/// ```
+///
+/// ```compile_fail,E0080
+/// use zerocopy::doctests::SliceDst;
+/// let src: &mut SliceDst<(), [u8; 3]> = SliceDst::new_mut();
+/// let _: &mut SliceDst<(), [u8; 2]> = zerocopy::transmute_mut!(src);
+/// ```
+enum TransmuteRefMutDstElemSizeNotMultiple {}

src/impls.rs

@@ -114,7 +114,7 @@ safety_comment! {
     });
 }
 
-impl_size_eq!(bool, u8);
+impl_size_compat!(bool, u8);
 
 safety_comment! {
     /// SAFETY:
@@ -145,7 +145,7 @@ safety_comment! {
     });
 }
 
-impl_size_eq!(char, Unalign<u32>);
+impl_size_compat!(char, Unalign<u32>);
 
 safety_comment! {
     /// SAFETY:
@@ -179,39 +179,13 @@ safety_comment! {
     });
 }
 
-// SAFETY: `str` and `[u8]` have the same layout [1].
-//
-// [1] Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#str-layout:
-//
-//   String slices are a UTF-8 representation of characters that have the same
-//   layout as slices of type `[u8]`.
-unsafe impl pointer::SizeEq<str> for [u8] {
-    fn cast_from_raw(s: NonNull<str>) -> NonNull<[u8]> {
-        cast!(s)
-    }
-}
-// SAFETY: See previous safety comment.
-unsafe impl pointer::SizeEq<[u8]> for str {
-    fn cast_from_raw(bytes: NonNull<[u8]>) -> NonNull<str> {
-        cast!(bytes)
-    }
-}
+impl_size_compat!(str, [u8]);
 
 macro_rules! unsafe_impl_try_from_bytes_for_nonzero {
     ($($nonzero:ident[$prim:ty]),*) => {
         $(
             unsafe_impl!(=> TryFromBytes for $nonzero; |n| {
-                unsafe impl pointer::SizeEq<$nonzero> for Unalign<$prim> {
-                    fn cast_from_raw(n: NonNull<$nonzero>) -> NonNull<Unalign<$prim>> {
-                        cast!(n)
-                    }
-                }
-                unsafe impl pointer::SizeEq<Unalign<$prim>> for $nonzero {
-                    fn cast_from_raw(p: NonNull<Unalign<$prim>>) -> NonNull<$nonzero> {
-                        cast!(p)
-                    }
-                }
-
+                impl_size_compat!($nonzero, Unalign<$prim>);
                 let n = n.transmute::<Unalign<$prim>, invariant::Valid, _>();
                 $nonzero::new(n.read_unaligned().into_inner()).is_some()
             });
@@ -429,58 +403,75 @@ mod atomics {
     macro_rules! unsafe_impl_transmute_from_for_atomic {
         ($($($tyvar:ident)? => $atomic:ty [$prim:ty]),*) => {
             const _: () = {
-                use core::{cell::UnsafeCell, ptr::NonNull};
-                use crate::pointer::{TransmuteFrom, SizeEq, invariant::Valid};
+                use core::{cell::UnsafeCell};
+                use crate::pointer::{TransmuteFrom, PtrInner, SizeCompat, invariant::Valid};
 
                 $(
                     #[allow(unused_unsafe)] // Force the caller to call this macro inside `safety_comment!`.
                     const _: () = unsafe {};
 
-                    // SAFETY: The caller promised that `$atomic` and `$prim` have
-                    // the same size and bit validity.
+                    // SAFETY: The caller promised that `$atomic` and `$prim`
+                    // have the same size and bit validity. As a result of size
+                    // equality, both impls of `SizeCompat::cast_from_raw`
+                    // preserve referent size exactly.
                     unsafe impl<$($tyvar)?> TransmuteFrom<$atomic, Valid, Valid> for $prim {}
-                    // SAFETY: The caller promised that `$atomic` and `$prim` have
-                    // the same size and bit validity.
+                    // SAFETY: The caller promised that `$atomic` and `$prim`
+                    // have the same size and bit validity. As a result of size
+                    // equality, both impls of `SizeCompat::cast_from_raw`
+                    // preserve referent size exactly.
                     unsafe impl<$($tyvar)?> TransmuteFrom<$prim, Valid, Valid> for $atomic {}
 
-                    // SAFETY: THe caller promised that `$atomic` and `$prim`
-                    // have the same size.
-                    unsafe impl<$($tyvar)?> SizeEq<$atomic> for $prim {
-                        fn cast_from_raw(a: NonNull<$atomic>) -> NonNull<$prim> {
-                            cast!(a)
+                    // SAFETY: See inline safety comment.
+                    unsafe impl<$($tyvar)?> SizeCompat<$atomic> for $prim {
+                        #[inline(always)]
+                        fn cast_from_raw(a: PtrInner<'_, $atomic>) -> PtrInner<'_, $prim> {
+                            // SAFETY: The caller promised that `$atomic` and `$prim`
+                            // have the same size. Thus, this cast preserves
+                            // address, referent size, and provenance.
+                            unsafe { cast!(a) }
                         }
                     }
-                    // SAFETY: THe caller promised that `$atomic` and `$prim`
-                    // have the same size.
-                    unsafe impl<$($tyvar)?> SizeEq<$prim> for $atomic {
-                        fn cast_from_raw(p: NonNull<$prim>) -> NonNull<$atomic> {
-                            cast!(p)
+                    // SAFETY: See previous safety comment.
+                    unsafe impl<$($tyvar)?> SizeCompat<$prim> for $atomic {
+                        #[inline(always)]
+                        fn cast_from_raw(p: PtrInner<'_, $prim>) -> PtrInner<'_, $atomic> {
+                            // SAFETY: See previous safety comment.
+                            unsafe { cast!(p) }
                         }
                     }
+
                     // SAFETY: The caller promised that `$atomic` and `$prim`
                     // have the same size. `UnsafeCell<T>` has the same size as
-                    // `T` [1].
+                    // `T` [1]. Thus, this cast preserves address, referent
+                    // size, and provenance.
                     //
                     // [1] Per https://doc.rust-lang.org/1.85.0/std/cell/struct.UnsafeCell.html#memory-layout:
                     //
                     //   `UnsafeCell<T>` has the same in-memory representation as
                     //   its inner type `T`. A consequence of this guarantee is that
                     //   it is possible to convert between `T` and `UnsafeCell<T>`.
-                    unsafe impl<$($tyvar)?> SizeEq<$atomic> for UnsafeCell<$prim> {
-                        fn cast_from_raw(a: NonNull<$atomic>) -> NonNull<UnsafeCell<$prim>> {
-                            cast!(a)
+                    unsafe impl<$($tyvar)?> SizeCompat<$atomic> for UnsafeCell<$prim> {
+                        #[inline(always)]
+                        fn cast_from_raw(a: PtrInner<'_, $atomic>) -> PtrInner<'_, UnsafeCell<$prim>> {
+                            // SAFETY: See previous safety comment.
+                            unsafe { cast!(a) }
                         }
                     }
                     // SAFETY: See previous safety comment.
-                    unsafe impl<$($tyvar)?> SizeEq<UnsafeCell<$prim>> for $atomic {
-                        fn cast_from_raw(p: NonNull<UnsafeCell<$prim>>) -> NonNull<$atomic> {
-                            cast!(p)
+                    unsafe impl<$($tyvar)?> SizeCompat<UnsafeCell<$prim>> for $atomic {
+                        #[inline(always)]
+                        fn cast_from_raw(p: PtrInner<'_, UnsafeCell<$prim>>) -> PtrInner<'_, $atomic> {
+                            // SAFETY: See previous safety comment.
+                            unsafe { cast!(p) }
                         }
                     }
 
                     // SAFETY: The caller promised that `$atomic` and `$prim`
                     // have the same bit validity. `UnsafeCell<T>` has the same
-                    // bit validity as `T` [1].
+                    // bit validity as `T` [1]. `UnsafeCell<T>` also has the
+                    // same size as `T` [1], and so both impls of
+                    // `SizeCompat::cast_from_raw` preserve referent size
+                    // exactly.
                     //
                     // [1] Per https://doc.rust-lang.org/1.85.0/std/cell/struct.UnsafeCell.html#memory-layout:
                     //