Teach transmute_{ref,mut}! to handle slice DSTs (#2428)

We generalize our existing support in `util::macro_util`, now relying on
PMEs to detect when transmutes cannot be supported. In order to continue
to support sized reference transmutation in a `const` context, we use
the autoref specialization trick to fall back to our old (`const`-safe)
implementation when both the source and destination type are `Sized`.

The main challenge in generalizing this support is making a trait
implementation available conditional on a PME. We do this using the
`unsafe_with_size_eq!` helper macro, which introduces
`#[repr(transparent)]` wrapper types, `Src` and `Dst`. Internal to this
macro, we implement `SizeEq<Src<T>> for Dst<U>`, with the implementation
of `SizeEq::cast_from_raw` containing the PME logic for size equality.
The macro's caller must promise to only use the `Src` and `Dst` types
to wrap the `T` and `U` types for which this PME logic has been applied
(or else the `SizeEq` impl could "leak" to types for which it is
unsound).

In addition, we 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 generalize `SizeEq` to permit its `cast_from_raw` method to perform a
runtime metadata fix-up operation.

Makes progress on #1817


gherrit-pr-id: Ib4bc62202e0b3b09d155333b525087f7aa8f02c2

Co-authored-by: Jack Wrenn <[email protected]>

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!()
+    }
+}
+
+/// We require that the alignment of the destination type is not larger than the
+/// alignment of the source type.
+///
+/// ```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

@@ -173,40 +173,13 @@ const _: () = unsafe {
     })
 };
 
-// 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_eq!(str, [u8]);
 
 macro_rules! unsafe_impl_try_from_bytes_for_nonzero {
     ($($nonzero:ident[$prim:ty]),*) => {
         $(
             unsafe_impl!(=> TryFromBytes for $nonzero; |n| {
-                // SAFETY: The caller promises that this is sound.
-                unsafe impl pointer::SizeEq<$nonzero> for Unalign<$prim> {
-                    fn cast_from_raw(n: NonNull<$nonzero>) -> NonNull<Unalign<$prim>> {
-                        cast!(n)
-                    }
-                }
-                // SAFETY: The caller promises that this is sound.
-                unsafe impl pointer::SizeEq<Unalign<$prim>> for $nonzero {
-                    fn cast_from_raw(p: NonNull<Unalign<$prim>>) -> NonNull<$nonzero> {
-                        cast!(p)
-                    }
-                }
+                impl_size_eq!($nonzero, Unalign<$prim>);
 
                 let n = n.transmute::<Unalign<$prim>, invariant::Valid, _>();
                 $nonzero::new(n.read_unaligned().into_inner()).is_some()
@@ -423,8 +396,8 @@ mod atomics {
         ($($($tyvar:ident)? => $atomic:ty [$prim:ty]),*) => {{
             crate::util::macros::__unsafe();
 
-            use core::{cell::UnsafeCell, ptr::NonNull};
-            use crate::pointer::{TransmuteFrom, SizeEq, invariant::Valid};
+            use core::cell::UnsafeCell;
+            use crate::pointer::{PtrInner, SizeEq, TransmuteFrom, invariant::Valid};
 
             $(
                 // SAFETY: The caller promised that `$atomic` and `$prim` have
@@ -437,15 +410,20 @@ mod atomics {
                 // 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)
+                    #[inline]
+                    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.
+                // SAFETY: See previous safety comment.
                 unsafe impl<$($tyvar)?> SizeEq<$prim> for $atomic {
-                    fn cast_from_raw(p: NonNull<$prim>) -> NonNull<$atomic> {
-                        cast!(p)
+                    #[inline]
+                    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
@@ -457,14 +435,18 @@ mod atomics {
                 //   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)
+                    #[inline]
+                    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)
+                    #[inline]
+                    fn cast_from_raw(p: PtrInner<'_, UnsafeCell<$prim>>) -> PtrInner<'_, $atomic> {
+                        // SAFETY: See previous safety comment.
+                        unsafe { cast!(p) }
                     }
                 }