rust/kernel/ptr.rs

// SPDX-License-Identifier: GPL-2.0

//! Types and functions to work with pointers and addresses.

pub mod projection;
pub use crate::project_pointer as project;

use core::mem::{
    align_of,
    size_of, //
};
use core::num::NonZero;

use crate::{
    const_assert,
    num::FromConst, //
};

/// Type representing an alignment, which is always a power of two.
///
/// It is used to validate that a given value is a valid alignment, and to perform masking and
/// alignment operations.
///
/// This is a temporary substitute for the [`Alignment`] nightly type from the standard library,
/// and to be eventually replaced by it.
///
/// [`Alignment`]: https://github.com/rust-lang/rust/issues/102070
///
/// # Invariants
///
/// An alignment is always a power of two.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Alignment(NonZero<usize>);

impl Alignment {
    /// Validates that `ALIGN` is a power of two at build-time, and returns an [`Alignment`] of the
    /// same value.
    ///
    /// A build error is triggered if `ALIGN` is not a power of two.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// let v = Alignment::new::<16>();
    /// assert_eq!(v.as_usize(), 16);
    /// ```
    #[inline(always)]
    pub const fn new<const ALIGN: usize>() -> Self {
        const_assert!(
            ALIGN.is_power_of_two(),
            "Provided alignment is not a power of two."
        );

        // INVARIANT: `align` is a power of two.
        // SAFETY: `align` is a power of two, and thus non-zero.
        Self(unsafe { NonZero::new_unchecked(ALIGN) })
    }

    /// Validates that `align` is a power of two at runtime, and returns an
    /// [`Alignment`] of the same value.
    ///
    /// Returns [`None`] if `align` is not a power of two.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// assert_eq!(Alignment::new_checked(16), Some(Alignment::new::<16>()));
    /// assert_eq!(Alignment::new_checked(15), None);
    /// assert_eq!(Alignment::new_checked(1), Some(Alignment::new::<1>()));
    /// assert_eq!(Alignment::new_checked(0), None);
    /// ```
    #[inline(always)]
    pub const fn new_checked(align: usize) -> Option<Self> {
        if align.is_power_of_two() {
            // INVARIANT: `align` is a power of two.
            // SAFETY: `align` is a power of two, and thus non-zero.
            Some(Self(unsafe { NonZero::new_unchecked(align) }))
        } else {
            None
        }
    }

    /// Returns the alignment of `T`.
    ///
    /// This is equivalent to [`align_of`], but with the return value provided as an [`Alignment`].
    #[inline(always)]
    pub const fn of<T>() -> Self {
        // This cannot panic since alignments are always powers of two.
        //
        // We unfortunately cannot use `new` as it would require the `generic_const_exprs` feature.
        const { Alignment::new_checked(align_of::<T>()).unwrap() }
    }

    /// Returns this alignment as a [`usize`].
    ///
    /// It is guaranteed to be a power of two.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// assert_eq!(Alignment::new::<16>().as_usize(), 16);
    /// ```
    #[inline(always)]
    pub const fn as_usize(self) -> usize {
        self.as_nonzero().get()
    }

    /// Returns this alignment as a [`NonZero`].
    ///
    /// It is guaranteed to be a power of two.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// assert_eq!(Alignment::new::<16>().as_nonzero().get(), 16);
    /// ```
    #[inline(always)]
    pub const fn as_nonzero(self) -> NonZero<usize> {
        // Allow the compiler to know that the value is indeed a power of two. This can help
        // optimize some operations down the line, like e.g. replacing divisions by bit shifts.
        if !self.0.is_power_of_two() {
            // SAFETY: Per the invariants, `self.0` is always a power of two so this block will
            // never be reached.
            unsafe { core::hint::unreachable_unchecked() }
        }
        self.0
    }

    /// Returns the base-2 logarithm of the alignment.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// assert_eq!(Alignment::of::<u8>().log2(), 0);
    /// assert_eq!(Alignment::new::<16>().log2(), 4);
    /// ```
    #[inline(always)]
    pub const fn log2(self) -> u32 {
        self.0.ilog2()
    }

    /// Returns the mask for this alignment.
    ///
    /// This is equivalent to `!(self.as_usize() - 1)`.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::Alignment;
    ///
    /// assert_eq!(Alignment::new::<0x10>().mask(), !0xf);
    /// ```
    #[inline(always)]
    pub const fn mask(self) -> usize {
        // No underflow can occur as the alignment is guaranteed to be a power of two, and thus is
        // non-zero.
        !(self.as_usize() - 1)
    }
}

impl<const V: i128> FromConst<V> for Alignment {
    const VALUE: Self = match Alignment::new_checked(<usize as FromConst<V>>::VALUE) {
        Some(alignment) => alignment,
        None => panic!("constant is not a power of two"),
    };
}

/// Trait for items that can be aligned against an [`Alignment`].
pub trait Alignable: Sized {
    /// Aligns `self` down to `alignment`.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::{Alignable, Alignment};
    ///
    /// assert_eq!(0x2f_usize.align_down(Alignment::new::<0x10>()), 0x20);
    /// assert_eq!(0x30usize.align_down(Alignment::new::<0x10>()), 0x30);
    /// assert_eq!(0xf0u8.align_down(Alignment::new::<0x1000>()), 0x0);
    /// ```
    fn align_down(self, alignment: Alignment) -> Self;

    /// Aligns `self` up to `alignment`, returning `None` if aligning would result in an overflow.
    ///
    /// # Examples
    ///
    /// ```
    /// use kernel::ptr::{Alignable, Alignment};
    ///
    /// assert_eq!(0x4fusize.align_up(Alignment::new::<0x10>()), Some(0x50));
    /// assert_eq!(0x40usize.align_up(Alignment::new::<0x10>()), Some(0x40));
    /// assert_eq!(0x0usize.align_up(Alignment::new::<0x10>()), Some(0x0));
    /// assert_eq!(u8::MAX.align_up(Alignment::new::<0x10>()), None);
    /// assert_eq!(0x10u8.align_up(Alignment::new::<0x100>()), None);
    /// assert_eq!(0x0u8.align_up(Alignment::new::<0x100>()), Some(0x0));
    /// ```
    fn align_up(self, alignment: Alignment) -> Option<Self>;
}

/// Implement [`Alignable`] for unsigned integer types.
macro_rules! impl_alignable_uint {
    ($($t:ty),*) => {
        $(
        impl Alignable for $t {
            #[inline(always)]
            fn align_down(self, alignment: Alignment) -> Self {
                // The operands of `&` need to be of the same type so convert the alignment to
                // `Self`. This means we need to compute the mask ourselves.
                ::core::num::NonZero::<Self>::try_from(alignment.as_nonzero())
                    .map(|align| self & !(align.get() - 1))
                    // An alignment larger than `Self` always aligns down to `0`.
                    .unwrap_or(0)
            }

            #[inline(always)]
            fn align_up(self, alignment: Alignment) -> Option<Self> {
                let aligned_down = self.align_down(alignment);
                if self == aligned_down {
                    Some(aligned_down)
                } else {
                    Self::try_from(alignment.as_usize())
                        .ok()
                        .and_then(|align| aligned_down.checked_add(align))
                }
            }
        }
        )*
    };
}

impl_alignable_uint!(u8, u16, u32, u64, usize);

/// Trait to represent compile-time known size information.
///
/// This is a generalization of [`size_of`] that works for dynamically sized types.
pub trait KnownSize {
    /// Minimum size of this type known at compile-time.
    const MIN_SIZE: usize;

    /// Minimum alignment of this type known at compile-time.
    const MIN_ALIGN: Alignment;

    /// Get the size of an object of this type in bytes, with the metadata of the given pointer.
    fn size(p: *const Self) -> usize;
}

impl<T> KnownSize for T {
    const MIN_SIZE: usize = size_of::<T>();
    const MIN_ALIGN: Alignment = Alignment::of::<T>();

    #[inline(always)]
    fn size(_: *const Self) -> usize {
        size_of::<T>()
    }
}

impl<T> KnownSize for [T] {
    const MIN_SIZE: usize = 0;
    const MIN_ALIGN: Alignment = Alignment::of::<T>();

    #[inline(always)]
    fn size(p: *const Self) -> usize {
        p.len() * size_of::<T>()
    }
}

/// Aligns `value` up to `align`.
///
/// This is the const-compatible equivalent of [`Alignable::align_up`].
///
/// Returns [`None`] on overflow.
///
/// # Examples
///
/// ```
/// use kernel::{
///     ptr::{
///         const_align_up,
///         Alignment, //
///     },
///     sizes::SZ_4K, //
/// };
///
/// assert_eq!(const_align_up(0x4f, Alignment::new::<16>()), Some(0x50));
/// assert_eq!(const_align_up(0x40, Alignment::new::<16>()), Some(0x40));
/// assert_eq!(const_align_up(1, Alignment::new::<SZ_4K>()), Some(SZ_4K));
/// ```
#[inline(always)]
pub const fn const_align_up(value: usize, align: Alignment) -> Option<usize> {
    match value.checked_add(align.as_usize() - 1) {
        Some(v) => Some(v & align.mask()),
        None => None,
    }
}