rust/zerocopy/src/pointer/mod.rs

// 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.

//! Abstractions over raw pointers.

#![allow(missing_docs)]

mod inner;
pub mod invariant;
mod ptr;
pub mod transmute;

pub use inner::PtrInner;
pub use invariant::{BecauseExclusive, BecauseImmutable, Read};
pub use ptr::{Ptr, TryWithError};
pub use transmute::*;

use crate::wrappers::ReadOnly;

/// A shorthand for a maybe-valid, maybe-aligned reference. Used as the argument
/// to [`TryFromBytes::is_bit_valid`].
///
/// [`TryFromBytes::is_bit_valid`]: crate::TryFromBytes::is_bit_valid
pub type Maybe<'a, T, Alignment = invariant::Unaligned> =
    Ptr<'a, ReadOnly<T>, (invariant::Shared, Alignment, invariant::Initialized)>;

/// Checks if the referent is zeroed.
pub(crate) fn is_zeroed<T, I>(ptr: Ptr<'_, T, I>) -> bool
where
    T: crate::Immutable + crate::KnownLayout,
    I: invariant::Invariants<Validity = invariant::Initialized>,
    I::Aliasing: invariant::Reference,
{
    ptr.as_bytes().as_ref().iter().all(
        #[inline(always)]
        |&byte| byte == 0,
    )
}

pub mod cast {
    use core::{marker::PhantomData, mem};

    use crate::{
        layout::{SizeInfo, TrailingSliceLayout},
        HasField, KnownLayout, PtrInner,
    };

    /// A pointer cast or projection.
    ///
    /// # Safety
    ///
    /// The implementation of `project` must satisfy its safety post-condition.
    pub unsafe trait Project<Src: ?Sized, Dst: ?Sized> {
        /// Projects a pointer from `Src` to `Dst`.
        ///
        /// Users should generally not call `project` directly, and instead
        /// should use high-level APIs like [`PtrInner::project`] or
        /// [`Ptr::project`].
        ///
        /// [`Ptr::project`]: crate::pointer::Ptr::project
        ///
        /// # Safety
        ///
        /// The returned pointer refers to a non-strict subset of the bytes of
        /// `src`'s referent, and has the same provenance as `src`.
        fn project(src: PtrInner<'_, Src>) -> *mut Dst;
    }

    /// A [`Project`] which preserves the address of the referent – a pointer
    /// cast.
    ///
    /// # Safety
    ///
    /// A `Cast` projection must preserve the address of the referent. It may
    /// shrink the set of referent bytes, and it may change the referent's type.
    pub unsafe trait Cast<Src: ?Sized, Dst: ?Sized>: Project<Src, Dst> {}

    /// A [`Cast`] which does not shrink the set of referent bytes.
    ///
    /// # Safety
    ///
    /// A `CastExact` projection must preserve the set of referent bytes.
    pub unsafe trait CastExact<Src: ?Sized, Dst: ?Sized>: Cast<Src, Dst> {}

    /// A no-op pointer cast.
    #[derive(Default, Copy, Clone)]
    #[allow(missing_debug_implementations)]
    pub struct IdCast;

    // SAFETY: `project` returns its argument unchanged, and so it is a
    // provenance-preserving projection which preserves the set of referent
    // bytes.
    unsafe impl<T: ?Sized> Project<T, T> for IdCast {
        #[inline(always)]
        fn project(src: PtrInner<'_, T>) -> *mut T {
            src.as_ptr()
        }
    }

    // SAFETY: The `Project::project` impl preserves referent address.
    unsafe impl<T: ?Sized> Cast<T, T> for IdCast {}

    // SAFETY: The `Project::project` impl preserves referent size.
    unsafe impl<T: ?Sized> CastExact<T, T> for IdCast {}

    /// A pointer cast which preserves or shrinks the set of referent bytes of
    /// a statically-sized referent.
    ///
    /// # Safety
    ///
    /// The implementation of [`Project`] uses a compile-time assertion to
    /// guarantee that `Dst` is no larger than `Src`. Thus, `CastSized` has a
    /// sound implementation of [`Project`] for all `Src` and `Dst` – the caller
    /// may pass any `Src` and `Dst` without being responsible for soundness.
    #[allow(missing_debug_implementations, missing_copy_implementations)]
    pub enum CastSized {}

    // SAFETY: By the `static_assert!`, `Dst` is no larger than `Src`,
    // and so all casts preserve or shrink the set of referent bytes. All
    // operations preserve provenance.
    unsafe impl<Src, Dst> Project<Src, Dst> for CastSized {
        #[inline(always)]
        fn project(src: PtrInner<'_, Src>) -> *mut Dst {
            static_assert!(Src, Dst => mem::size_of::<Src>() >= mem::size_of::<Dst>());
            src.as_ptr().cast::<Dst>()
        }
    }

    // SAFETY: The `Project::project` impl preserves referent address.
    unsafe impl<Src, Dst> Cast<Src, Dst> for CastSized {}

    /// A pointer cast which preserves the set of referent bytes of a
    /// statically-sized referent.
    ///
    /// # Safety
    ///
    /// The implementation of [`Project`] uses a compile-time assertion to
    /// guarantee that `Dst` has the same size as `Src`. Thus, `CastSizedExact`
    /// has a sound implementation of [`Project`] for all `Src` and `Dst` – the
    /// caller may pass any `Src` and `Dst` without being responsible for
    /// soundness.
    #[allow(missing_debug_implementations, missing_copy_implementations)]
    pub enum CastSizedExact {}

    // SAFETY: By the `static_assert!`, `Dst` has the same size as `Src`,
    // and so all casts preserve the set of referent bytes. All operations
    // preserve provenance.
    unsafe impl<Src, Dst> Project<Src, Dst> for CastSizedExact {
        #[inline(always)]
        fn project(src: PtrInner<'_, Src>) -> *mut Dst {
            static_assert!(Src, Dst => mem::size_of::<Src>() == mem::size_of::<Dst>());
            src.as_ptr().cast::<Dst>()
        }
    }

    // SAFETY: The `Project::project_raw` impl preserves referent address.
    unsafe impl<Src, Dst> Cast<Src, Dst> for CastSizedExact {}

    // SAFETY: By the `static_assert!`, `Project::project_raw` impl preserves
    // referent size.
    unsafe impl<Src, Dst> CastExact<Src, Dst> for CastSizedExact {}

    /// A pointer cast which preserves or shrinks the set of referent bytes of
    /// a dynamically-sized referent.
    ///
    /// # Safety
    ///
    /// The implementation of [`Project`] uses a compile-time assertion to
    /// guarantee that the cast preserves the set of referent bytes. Thus,
    /// `CastUnsized` has a sound implementation of [`Project`] for all `Src`
    /// and `Dst` – the caller may pass any `Src` and `Dst` without being
    /// responsible for soundness.
    #[allow(missing_debug_implementations, missing_copy_implementations)]
    pub enum CastUnsized {}

    // SAFETY: By the `static_assert!`, `Src` and `Dst` are either:
    // - Both sized and equal in size
    // - Both slice DSTs with the same trailing slice offset and element size
    //   and with align_of::<Src>() == align_of::<Dst>(). These ensure that any
    //   given pointer metadata encodes the same size for both `Src` and `Dst`
    //   (note that the alignment is required as it affects the amount of
    //   trailing padding). Thus, `project` preserves the set of referent bytes.
    unsafe impl<Src, Dst> Project<Src, Dst> for CastUnsized
    where
        Src: ?Sized + KnownLayout,
        Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
    {
        #[inline(always)]
        fn project(src: PtrInner<'_, Src>) -> *mut Dst {
            // FIXME: Do we want this to support shrinking casts as well? If so,
            // we'll need to remove the `CastExact` impl.
            static_assert!(Src: ?Sized + KnownLayout, Dst: ?Sized + KnownLayout => {
                let src = <Src as KnownLayout>::LAYOUT;
                let dst = <Dst as KnownLayout>::LAYOUT;
                match (src.size_info, dst.size_info) {
                    (SizeInfo::Sized { size: src_size }, SizeInfo::Sized { size: dst_size }) => src_size == dst_size,
                    (
                        SizeInfo::SliceDst(TrailingSliceLayout { offset: src_offset, elem_size: src_elem_size }),
                        SizeInfo::SliceDst(TrailingSliceLayout { offset: dst_offset, elem_size: dst_elem_size })
                    ) => src.align.get() == dst.align.get() && src_offset == dst_offset && src_elem_size == dst_elem_size,
                    _ => false,
                }
            });

            let metadata = Src::pointer_to_metadata(src.as_ptr());
            Dst::raw_from_ptr_len(src.as_non_null().cast::<u8>(), metadata).as_ptr()
        }
    }

    // SAFETY: The `Project::project` impl preserves referent address.
    unsafe impl<Src, Dst> Cast<Src, Dst> for CastUnsized
    where
        Src: ?Sized + KnownLayout,
        Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
    {
    }

    // SAFETY: By the `static_assert!` in `Project::project`, `Src` and `Dst`
    // are either:
    // - Both sized and equal in size
    // - Both slice DSTs with the same alignment, trailing slice offset, and
    //   element size. These ensure that any given pointer metadata encodes the
    //   same size for both `Src` and `Dst` (note that the alignment is required
    //   as it affects the amount of trailing padding).
    unsafe impl<Src, Dst> CastExact<Src, Dst> for CastUnsized
    where
        Src: ?Sized + KnownLayout,
        Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
    {
    }

    /// A field projection
    ///
    /// A `Projection` is a [`Project`] which implements projection by
    /// delegating to an implementation of [`HasField::project`].
    #[allow(missing_debug_implementations, missing_copy_implementations)]
    pub struct Projection<F: ?Sized, const VARIANT_ID: i128, const FIELD_ID: i128> {
        _never: core::convert::Infallible,
        _phantom: PhantomData<F>,
    }

    // SAFETY: `HasField::project` has the same safety post-conditions as
    // `Project::project`.
    unsafe impl<T: ?Sized, F, const VARIANT_ID: i128, const FIELD_ID: i128> Project<T, T::Type>
        for Projection<F, VARIANT_ID, FIELD_ID>
    where
        T: HasField<F, VARIANT_ID, FIELD_ID>,
    {
        #[inline(always)]
        fn project(src: PtrInner<'_, T>) -> *mut T::Type {
            T::project(src)
        }
    }

    // SAFETY: All `repr(C)` union fields exist at offset 0 within the union [1],
    // and so any union projection is actually a cast (ie, preserves address).
    //
    // [1] Per
    //     https://doc.rust-lang.org/1.92.0/reference/type-layout.html#reprc-unions,
    //     it's not *technically* guaranteed that non-maximally-sized fields
    //     are at offset 0, but it's clear that this is the intention of `repr(C)`
    //     unions. It says:
    //
    //     > A union declared with `#[repr(C)]` will have the same size and
    //     > alignment as an equivalent C union declaration in the C language for
    //     > the target platform.
    //
    //     Note that this only mentions size and alignment, not layout. However,
    //     C unions *do* guarantee that all fields start at offset 0. [2]
    //
    //     This is also reinforced by
    //     https://doc.rust-lang.org/1.92.0/reference/items/unions.html#r-items.union.fields.offset:
    //
    //     > Fields might have a non-zero offset (except when the C
    //     > representation is used); in that case the bits starting at the
    //     > offset of the fields are read
    //
    // [2] Per https://port70.net/~nsz/c/c11/n1570.html#6.7.2.1p16:
    //
    //     > The size of a union is sufficient to contain the largest of its
    //     > members. The value of at most one of the members can be stored in a
    //     > union object at any time. A pointer to a union object, suitably
    //     > converted, points to each of its members (or if a member is a
    //     > bit-field, then to the unit in which it resides), and vice versa.
    //
    // FIXME(https://github.com/rust-lang/unsafe-code-guidelines/issues/595):
    // Cite the documentation once it's updated.
    unsafe impl<T: ?Sized, F, const FIELD_ID: i128> Cast<T, T::Type>
        for Projection<F, { crate::REPR_C_UNION_VARIANT_ID }, FIELD_ID>
    where
        T: HasField<F, { crate::REPR_C_UNION_VARIANT_ID }, FIELD_ID>,
    {
    }

    /// A transitive sequence of projections.
    ///
    /// Given `TU: Project` and `UV: Project`, `TransitiveProject<_, TU, UV>` is
    /// a [`Project`] which projects by applying `TU` followed by `UV`.
    ///
    /// If `TU: Cast` and `UV: Cast`, then `TransitiveProject<_, TU, UV>: Cast`.
    #[allow(missing_debug_implementations)]
    pub struct TransitiveProject<U: ?Sized, TU, UV> {
        _never: core::convert::Infallible,
        _projections: PhantomData<(TU, UV)>,
        // On our MSRV (1.56), the debuginfo for a tuple containing both an
        // uninhabited type and a DST causes an ICE. We split `U` from `TU` and
        // `UV` to avoid this situation.
        _u: PhantomData<U>,
    }

    // SAFETY: Since `TU::project` and `UV::project` are each
    // provenance-preserving operations which preserve or shrink the set of
    // referent bytes, so is their composition.
    unsafe impl<T, U, V, TU, UV> Project<T, V> for TransitiveProject<U, TU, UV>
    where
        T: ?Sized,
        U: ?Sized,
        V: ?Sized,
        TU: Project<T, U>,
        UV: Project<U, V>,
    {
        #[inline(always)]
        fn project(t: PtrInner<'_, T>) -> *mut V {
            t.project::<_, TU>().project::<_, UV>().as_ptr()
        }
    }

    // SAFETY: Since the `Project::project` impl delegates to `TU::project` and
    // `UV::project`, and since `TU` and `UV` are `Cast`, the `Project::project`
    // impl preserves the address of the referent.
    unsafe impl<T, U, V, TU, UV> Cast<T, V> for TransitiveProject<U, TU, UV>
    where
        T: ?Sized,
        U: ?Sized,
        V: ?Sized,
        TU: Cast<T, U>,
        UV: Cast<U, V>,
    {
    }

    // SAFETY: Since the `Project::project` impl delegates to `TU::project` and
    // `UV::project`, and since `TU` and `UV` are `CastExact`, the `Project::project`
    // impl preserves the set of referent bytes.
    unsafe impl<T, U, V, TU, UV> CastExact<T, V> for TransitiveProject<U, TU, UV>
    where
        T: ?Sized,
        U: ?Sized,
        V: ?Sized,
        TU: CastExact<T, U>,
        UV: CastExact<U, V>,
    {
    }

    /// A cast from `T` to `[u8]`.
    #[allow(missing_copy_implementations, missing_debug_implementations)]
    pub struct AsBytesCast;

    // SAFETY: `project` constructs a pointer with the same address as `src`
    // and with a referent of the same size as `*src`. It does this using
    // provenance-preserving operations.
    //
    // FIXME(https://github.com/rust-lang/unsafe-code-guidelines/issues/594):
    // Technically, this proof assumes that `*src` is contiguous (the same is
    // true of other proofs in this codebase). Is this guaranteed anywhere?
    unsafe impl<T: ?Sized + KnownLayout> Project<T, [u8]> for AsBytesCast {
        #[inline(always)]
        fn project(src: PtrInner<'_, T>) -> *mut [u8] {
            let bytes = match T::size_of_val_raw(src.as_non_null()) {
                Some(bytes) => bytes,
                // SAFETY: `KnownLayout::size_of_val_raw` promises to always
                // return `Some` so long as the resulting size fits in a
                // `usize`. By invariant on `PtrInner`, `src` refers to a range
                // of bytes whose size fits in an `isize`, which implies that it
                // also fits in a `usize`.
                None => unsafe { core::hint::unreachable_unchecked() },
            };

            core::ptr::slice_from_raw_parts_mut(src.as_ptr().cast::<u8>(), bytes)
        }
    }

    // SAFETY: The `Project::project` impl preserves referent address.
    unsafe impl<T: ?Sized + KnownLayout> Cast<T, [u8]> for AsBytesCast {}

    // SAFETY: The `Project::project` impl preserves the set of referent bytes.
    unsafe impl<T: ?Sized + KnownLayout> CastExact<T, [u8]> for AsBytesCast {}

    /// A cast from any type to `()`.
    #[allow(missing_copy_implementations, missing_debug_implementations)]
    pub struct CastToUnit;

    // SAFETY: The `project` implementation projects to a subset of its
    // argument's referent using provenance-preserving operations.
    unsafe impl<T: ?Sized> Project<T, ()> for CastToUnit {
        #[inline(always)]
        fn project(src: PtrInner<'_, T>) -> *mut () {
            src.as_ptr().cast::<()>()
        }
    }

    // SAFETY: The `project` implementation preserves referent address.
    unsafe impl<T: ?Sized> Cast<T, ()> for CastToUnit {}
}