// SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT//// Copyright 2023 The Fuchsia Authors//// Licensed under a BSD-style license <LICENSE-BSD>, 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. /// Unsafely implements trait(s) for a type.////// # Safety////// The trait impl must be sound.////// When implementing `TryFromBytes`:/// - If no `is_bit_valid` impl is provided, then it must be valid for///   `is_bit_valid` to unconditionally return `true`. In other words, it must///   be the case that any initialized sequence of bytes constitutes a valid///   instance of `$ty`./// - If an `is_bit_valid` impl is provided, then the impl of `is_bit_valid`///   must only return `true` if its argument refers to a valid `$ty`.macro_rules! unsafe_impl {    // Implement `$trait` for `$ty` with no bounds.    ($(#[$attr:meta])* $ty:ty: $trait:ident $(; |$candidate:ident| $is_bit_valid:expr)?) => {{        crate::util::macros::__unsafe();         $(#[$attr])*        // SAFETY: The caller promises that this is sound.        unsafe impl $trait for $ty {            unsafe_impl!(@method $trait $(; |$candidate| $is_bit_valid)?);        }    }};     // Implement all `$traits` for `$ty` with no bounds.    //    // The 2 arms under this one are there so we can apply    // N attributes for each one of M trait implementations.    // The simple solution of:    //    // ($(#[$attrs:meta])* $ty:ty: $($traits:ident),*) => {    //     $( unsafe_impl!( $(#[$attrs])* $ty: $traits ) );*    // }    //    // Won't work. The macro processor sees that the outer repetition    // contains both $attrs and $traits and expects them to match the same    // amount of fragments.    //    // To solve this we must:    // 1. Pack the attributes into a single token tree fragment we can match over.    // 2. Expand the traits.    // 3. Unpack and expand the attributes.    ($(#[$attrs:meta])* $ty:ty: $($traits:ident),*) => {        unsafe_impl!(@impl_traits_with_packed_attrs { $(#[$attrs])* } $ty: $($traits),*)    };     (@impl_traits_with_packed_attrs $attrs:tt $ty:ty: $($traits:ident),*) => {{        $( unsafe_impl!(@unpack_attrs $attrs $ty: $traits); )*    }};     (@unpack_attrs { $(#[$attrs:meta])* } $ty:ty: $traits:ident) => {        unsafe_impl!($(#[$attrs])* $ty: $traits);    };     // This arm is identical to the following one, except it contains a    // preceding `const`. If we attempt to handle these with a single arm, there    // is an inherent ambiguity between `const` (the keyword) and `const` (the    // ident match for `$tyvar:ident`).    //    // To explain how this works, consider the following invocation:    //    //   unsafe_impl!(const N: usize, T: ?Sized + Copy => Clone for Foo<T>);    //    // In this invocation, here are the assignments to meta-variables:    //    //   |---------------|------------|    //   | Meta-variable | Assignment |    //   |---------------|------------|    //   | $constname    |  N         |    //   | $constty      |  usize     |    //   | $tyvar        |  T         |    //   | $optbound     |  Sized     |    //   | $bound        |  Copy      |    //   | $trait        |  Clone     |    //   | $ty           |  Foo<T>    |    //   |---------------|------------|    //    // The following arm has the same behavior with the exception of the lack of    // support for a leading `const` parameter.    (        $(#[$attr:meta])*        const $constname:ident : $constty:ident $(,)?        $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*        => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {        unsafe_impl!(            @inner            $(#[$attr])*            @const $constname: $constty,            $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)*            => $trait for $ty $(; |$candidate| $is_bit_valid)?        );    };    (        $(#[$attr:meta])*        $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*        => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {{        unsafe_impl!(            @inner            $(#[$attr])*            $($tyvar $(: $(? $optbound +)* + $($bound +)*)?,)*            => $trait for $ty $(; |$candidate| $is_bit_valid)?        );    }};    (        @inner        $(#[$attr:meta])*        $(@const $constname:ident : $constty:ident,)*        $($tyvar:ident $(: $(? $optbound:ident +)* + $($bound:ident +)* )?,)*        => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {{        crate::util::macros::__unsafe();         $(#[$attr])*        #[allow(non_local_definitions)]        // SAFETY: The caller promises that this is sound.        unsafe impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?),* $(, const $constname: $constty,)*> $trait for $ty {            unsafe_impl!(@method $trait $(; |$candidate| $is_bit_valid)?);        }    }};     (@method TryFromBytes ; |$candidate:ident| $is_bit_valid:expr) => {        #[allow(clippy::missing_inline_in_public_items, dead_code)]        #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]        fn only_derive_is_allowed_to_implement_this_trait() {}         #[inline]        fn is_bit_valid<Alignment>($candidate: Maybe<'_, Self, Alignment>) -> bool        where            Alignment: crate::invariant::Alignment,        {            $is_bit_valid        }    };    (@method TryFromBytes) => {        #[allow(clippy::missing_inline_in_public_items)]        #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]        fn only_derive_is_allowed_to_implement_this_trait() {}        #[inline(always)]        fn is_bit_valid<Alignment>(_candidate: Maybe<'_, Self, Alignment>) -> bool        where            Alignment: crate::invariant::Alignment,        {            true        }    };    (@method $trait:ident) => {        #[allow(clippy::missing_inline_in_public_items, dead_code)]        #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]        fn only_derive_is_allowed_to_implement_this_trait() {}    };    (@method $trait:ident; |$_candidate:ident| $_is_bit_valid:expr) => {        compile_error!("Can't provide `is_bit_valid` impl for trait other than `TryFromBytes`");    };} /// Implements `$trait` for `$ty` where `$ty: TransmuteFrom<$repr>` (and/// vice-versa).////// Calling this macro is safe; the internals of the macro emit appropriate/// trait bounds which ensure that the given impl is sound.macro_rules! impl_for_transmute_from {    (        $(#[$attr:meta])*        $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?)?        => $trait:ident for $ty:ty [$repr:ty]    ) => {        const _: () = {            $(#[$attr])*            #[allow(non_local_definitions)]             // SAFETY: `is_trait<T, R>` (defined and used below) requires `T:            // TransmuteFrom<R>`, `R: TransmuteFrom<T>`, and `R: $trait`. It is            // called using `$ty` and `$repr`, ensuring that `$ty` and `$repr`            // have equivalent bit validity, and ensuring that `$repr: $trait`.            // The supported traits - `TryFromBytes`, `FromZeros`, `FromBytes`,            // and `IntoBytes` - are defined only in terms of the bit validity            // of a type. Therefore, `$repr: $trait` ensures that `$ty: $trait`            // is sound.            unsafe impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?)?> $trait for $ty {                #[allow(dead_code, clippy::missing_inline_in_public_items)]                #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]                fn only_derive_is_allowed_to_implement_this_trait() {                    use crate::pointer::{*, invariant::Valid};                     impl_for_transmute_from!(@assert_is_supported_trait $trait);                     fn is_trait<T, R>()                    where                        T: TransmuteFrom<R, Valid, Valid> + ?Sized,                        R: TransmuteFrom<T, Valid, Valid> + ?Sized,                        R: $trait,                    {                    }                     #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]                    fn f<$($tyvar $(: $(? $optbound +)* $($bound +)*)?)?>() {                        is_trait::<$ty, $repr>();                    }                }                 impl_for_transmute_from!(                    @is_bit_valid                    $(<$tyvar $(: $(? $optbound +)* $($bound +)*)?>)?                    $trait for $ty [$repr]                );            }        };    };    (@assert_is_supported_trait TryFromBytes) => {};    (@assert_is_supported_trait FromZeros) => {};    (@assert_is_supported_trait FromBytes) => {};    (@assert_is_supported_trait IntoBytes) => {};    (        @is_bit_valid        $(<$tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?>)?        TryFromBytes for $ty:ty [$repr:ty]    ) => {        #[inline(always)]        fn is_bit_valid<Alignment>(candidate: $crate::Maybe<'_, Self, Alignment>) -> bool        where            Alignment: $crate::invariant::Alignment,        {            // SAFETY: This macro ensures that `$repr` and `Self` have the same            // size and bit validity. Thus, a bit-valid instance of `$repr` is            // also a bit-valid instance of `Self`.            <$repr as TryFromBytes>::is_bit_valid(candidate.transmute::<_, _, BecauseImmutable>())        }    };    (        @is_bit_valid        $(<$tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?>)?        $trait:ident for $ty:ty [$repr:ty]    ) => {        // Trait other than `TryFromBytes`; no `is_bit_valid` impl.    };} /// Implements a trait for a type, bounding on each member of the power set of/// a set of type variables. This is useful for implementing traits for tuples/// or `fn` types.////// The last argument is the name of a macro which will be called in every/// `impl` block, and is expected to expand to the name of the type for which to/// implement the trait.////// For example, the invocation:/// ```ignore/// unsafe_impl_for_power_set!(A, B => Foo for type!(...))/// ```/// ...expands to:/// ```ignore/// unsafe impl       Foo for type!()     { ... }/// unsafe impl<B>    Foo for type!(B)    { ... }/// unsafe impl<A, B> Foo for type!(A, B) { ... }/// ```macro_rules! unsafe_impl_for_power_set {    (        $first:ident $(, $rest:ident)* $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)        $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {        unsafe_impl_for_power_set!(            $($rest),* $(-> $ret)? => $trait for $macro!(...)            $(; |$candidate| $is_bit_valid)?        );        unsafe_impl_for_power_set!(            @impl $first $(, $rest)* $(-> $ret)? => $trait for $macro!(...)            $(; |$candidate| $is_bit_valid)?        );    };    (        $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)        $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {        unsafe_impl_for_power_set!(            @impl $(-> $ret)? => $trait for $macro!(...)            $(; |$candidate| $is_bit_valid)?        );    };    (        @impl $($vars:ident),* $(-> $ret:ident)? => $trait:ident for $macro:ident!(...)        $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {        unsafe_impl!(            $($vars,)* $($ret)? => $trait for $macro!($($vars),* $(-> $ret)?)            $(; |$candidate| $is_bit_valid)?        );    };} /// Expands to an `Option<extern "C" fn>` type with the given argument types and/// return type. Designed for use with `unsafe_impl_for_power_set`.macro_rules! opt_extern_c_fn {    ($($args:ident),* -> $ret:ident) => { Option<extern "C" fn($($args),*) -> $ret> };} /// Expands to an `Option<unsafe extern "C" fn>` type with the given argument/// types and return type. Designed for use with `unsafe_impl_for_power_set`.macro_rules! opt_unsafe_extern_c_fn {    ($($args:ident),* -> $ret:ident) => { Option<unsafe extern "C" fn($($args),*) -> $ret> };} /// Expands to an `Option<fn>` type with the given argument types and return/// type. Designed for use with `unsafe_impl_for_power_set`.macro_rules! opt_fn {    ($($args:ident),* -> $ret:ident) => { Option<fn($($args),*) -> $ret> };} /// Expands to an `Option<unsafe fn>` type with the given argument types and/// return type. Designed for use with `unsafe_impl_for_power_set`.macro_rules! opt_unsafe_fn {    ($($args:ident),* -> $ret:ident) => { Option<unsafe fn($($args),*) -> $ret> };} // This `allow` is needed because, when testing, we export this macro so it can// be used in `doctests`.#[allow(rustdoc::private_intra_doc_links)]/// Implements trait(s) for a type or verifies the given implementation by/// referencing an existing (derived) implementation.////// This macro exists so that we can provide zerocopy-derive as an optional/// dependency and still get the benefit of using its derives to validate that/// our trait impls are sound.////// When compiling without `--cfg 'feature = "derive"` and without `--cfg test`,/// `impl_or_verify!` emits the provided trait impl. When compiling with either/// of those cfgs, it is expected that the type in question is deriving the/// traits instead. In this case, `impl_or_verify!` emits code which validates/// that the given trait impl is at least as restrictive as the the impl emitted/// by the custom derive. This has the effect of confirming that the impl which/// is emitted when the `derive` feature is disabled is actually sound (on the/// assumption that the impl emitted by the custom derive is sound).////// The caller is still required to provide a safety comment (e.g. using the/// `const _: () = unsafe` macro). The reason for this restriction is that,/// while `impl_or_verify!` can guarantee that the provided impl is sound when/// it is compiled with the appropriate cfgs, there is no way to guarantee that/// it is ever compiled with those cfgs. In particular, it would be possible to/// accidentally place an `impl_or_verify!` call in a context that is only ever/// compiled when the `derive` feature is disabled. If that were to happen,/// there would be nothing to prevent an unsound trait impl from being emitted./// Requiring a safety comment reduces the likelihood of emitting an unsound/// impl in this case, and also provides useful documentation for readers of the/// code.////// Finally, if a `TryFromBytes::is_bit_valid` impl is provided, it must adhere/// to the safety preconditions of [`unsafe_impl!`].////// ## Example////// ```rust,ignore/// // Note that these derives are gated by `feature = "derive"`/// #[cfg_attr(any(feature = "derive", test), derive(FromZeros, FromBytes, IntoBytes, Unaligned))]/// #[repr(transparent)]/// struct Wrapper<T>(T);////// const _: () = unsafe {///     /// SAFETY:///     /// `Wrapper<T>` is `repr(transparent)`, so it is sound to implement any///     /// zerocopy trait if `T` implements that trait.///     impl_or_verify!(T: FromZeros => FromZeros for Wrapper<T>);///     impl_or_verify!(T: FromBytes => FromBytes for Wrapper<T>);///     impl_or_verify!(T: IntoBytes => IntoBytes for Wrapper<T>);///     impl_or_verify!(T: Unaligned => Unaligned for Wrapper<T>);/// }/// ```#[cfg_attr(__ZEROCOPY_INTERNAL_USE_ONLY_DEV_MODE, macro_export)] // Used in `doctests.rs`#[doc(hidden)]macro_rules! impl_or_verify {    // The following two match arms follow the same pattern as their    // counterparts in `unsafe_impl!`; see the documentation on those arms for    // more details.    (        const $constname:ident : $constty:ident $(,)?        $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*        => $trait:ident for $ty:ty    ) => {        impl_or_verify!(@impl { unsafe_impl!(            const $constname: $constty, $($tyvar $(: $(? $optbound +)* $($bound +)*)?),* => $trait for $ty        ); });        impl_or_verify!(@verify $trait, {            impl<const $constname: $constty, $($tyvar $(: $(? $optbound +)* $($bound +)*)?),*> Subtrait for $ty {}        });    };    (        $($tyvar:ident $(: $(? $optbound:ident $(+)?)* $($bound:ident $(+)?)* )?),*        => $trait:ident for $ty:ty $(; |$candidate:ident| $is_bit_valid:expr)?    ) => {        impl_or_verify!(@impl { unsafe_impl!(            $($tyvar $(: $(? $optbound +)* $($bound +)*)?),* => $trait for $ty            $(; |$candidate| $is_bit_valid)?        ); });        impl_or_verify!(@verify $trait, {            impl<$($tyvar $(: $(? $optbound +)* $($bound +)*)?),*> Subtrait for $ty {}        });    };    (@impl $impl_block:tt) => {        #[cfg(not(any(feature = "derive", test)))]        { $impl_block };    };    (@verify $trait:ident, $impl_block:tt) => {        #[cfg(any(feature = "derive", test))]        {            // On some toolchains, `Subtrait` triggers the `dead_code` lint            // because it is implemented but never used.            #[allow(dead_code)]            trait Subtrait: $trait {}            $impl_block        };    };} /// Implements `KnownLayout` for a sized type.macro_rules! impl_known_layout {    ($(const $constvar:ident : $constty:ty, $tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {        $(impl_known_layout!(@inner const $constvar: $constty, $tyvar $(: ?$optbound)? => $ty);)*    };    ($($tyvar:ident $(: ?$optbound:ident)? => $ty:ty),* $(,)?) => {        $(impl_known_layout!(@inner , $tyvar $(: ?$optbound)? => $ty);)*    };    ($($(#[$attrs:meta])* $ty:ty),*) => { $(impl_known_layout!(@inner , => $(#[$attrs])* $ty);)* };    (@inner $(const $constvar:ident : $constty:ty)? , $($tyvar:ident $(: ?$optbound:ident)?)? => $(#[$attrs:meta])* $ty:ty) => {        const _: () = {            use core::ptr::NonNull;             #[allow(non_local_definitions)]            $(#[$attrs])*            // SAFETY: Delegates safety to `DstLayout::for_type`.            unsafe impl<$($tyvar $(: ?$optbound)?)? $(, const $constvar : $constty)?> KnownLayout for $ty {                #[allow(clippy::missing_inline_in_public_items)]                #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]                fn only_derive_is_allowed_to_implement_this_trait() where Self: Sized {}                 type PointerMetadata = ();                 // SAFETY: `CoreMaybeUninit<T>::LAYOUT` and `T::LAYOUT` are                // identical because `CoreMaybeUninit<T>` has the same size and                // alignment as `T` [1], and `CoreMaybeUninit` admits                // uninitialized bytes in all positions.                //                // [1] Per https://doc.rust-lang.org/1.81.0/std/mem/union.MaybeUninit.html#layout-1:                //                //   `MaybeUninit<T>` is guaranteed to have the same size,                //   alignment, and ABI as `T`                type MaybeUninit = core::mem::MaybeUninit<Self>;                 const LAYOUT: crate::DstLayout = crate::DstLayout::for_type::<$ty>();                 // SAFETY: `.cast` preserves address and provenance.                //                // FIXME(#429): Add documentation to `.cast` that promises that                // it preserves provenance.                #[inline(always)]                fn raw_from_ptr_len(bytes: NonNull<u8>, _meta: ()) -> NonNull<Self> {                    bytes.cast::<Self>()                }                 #[inline(always)]                fn pointer_to_metadata(_ptr: *mut Self) -> () {                }            }        };    };} /// Implements `KnownLayout` for a type in terms of the implementation of/// another type with the same representation.////// # Safety////// - `$ty` and `$repr` must have the same:///   - Fixed prefix size///   - Alignment///   - (For DSTs) trailing slice element size/// - It must be valid to perform an `as` cast from `*mut $repr` to `*mut $ty`,///   and this operation must preserve referent size (ie, `size_of_val_raw`).macro_rules! unsafe_impl_known_layout {    ($($tyvar:ident: ?Sized + KnownLayout =>)? #[repr($repr:ty)] $ty:ty) => {{        use core::ptr::NonNull;         crate::util::macros::__unsafe();         #[allow(non_local_definitions)]        // SAFETY: The caller promises that this is sound.        unsafe impl<$($tyvar: ?Sized + KnownLayout)?> KnownLayout for $ty {            #[allow(clippy::missing_inline_in_public_items, dead_code)]            #[cfg_attr(all(coverage_nightly, __ZEROCOPY_INTERNAL_USE_ONLY_NIGHTLY_FEATURES_IN_TESTS), coverage(off))]            fn only_derive_is_allowed_to_implement_this_trait() {}

Lines 1–500 of 1067. Load more