Commit 3a1ec424 authored by Hsiu Che Yu's avatar Hsiu Che Yu Committed by Miguel Ojeda
Browse files

rust: num: bounded: mark __new as unsafe 

The `Bounded::__new()` constructor relies on the caller to ensure the
value can be represented within N bits. Failing to uphold this
requirement breaks the type invariant. Mark it as unsafe and document
this requirement in a Safety section to make the contract explicit.

Update all call sites to use unsafe blocks and change their comments
from `INVARIANT:` to `SAFETY:`, as they are now justifying unsafe
operations rather than establishing type invariants.

Fixes: 01e345e8 ("rust: num: add Bounded integer wrapping type")
Link: https://lore.kernel.org/all/aS1qC_ol2XEpZ44b@google.com/


Reported-by: default avatarMiguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1211


Signed-off-by: default avatarHsiu Che Yu <yu.whisper.personal@gmail.com>
Acked-by: default avatarAlexandre Courbot <acourbot@nvidia.com>
Link: https://patch.msgid.link/20251204033849.23480-1-yu.whisper.personal@gmail.com


Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 609db7e7

rust/kernel/num/bounded.rs

+19 −15
Original line number Diff line number Diff line
@@ -259,9 +259,9 @@ pub const fn new<const VALUE: $type>() -> Self { 
                    assert!(fits_within!(VALUE, $type, N));

                }



                // INVARIANT: `fits_within` confirmed that `VALUE` can be represented within

                // SAFETY: `fits_within` confirmed that `VALUE` can be represented within

                // `N` bits.

                Self::__new(VALUE)

                unsafe { Self::__new(VALUE) }

            }

        }

        )*
@@ -284,7 +284,11 @@ impl<T, const N: u32> Bounded<T, N> 
    ///

    /// The caller remains responsible for checking, either statically or dynamically, that `value`

    /// can be represented as a `T` using at most `N` bits.

    const fn __new(value: T) -> Self {

    ///

    /// # Safety

    ///

    /// The caller must ensure that `value` can be represented within `N` bits.

    const unsafe fn __new(value: T) -> Self {

        // Enforce the type invariants.

        const {

            // `N` cannot be zero.
@@ -328,8 +332,8 @@ const fn __new(value: T) -> Self { 
    /// ```

    pub fn try_new(value: T) -> Option<Self> {

        fits_within(value, N).then(|| {

            // INVARIANT: `fits_within` confirmed that `value` can be represented within `N` bits.

            Self::__new(value)

            // SAFETY: `fits_within` confirmed that `value` can be represented within `N` bits.

            unsafe { Self::__new(value) }

        })

    }
@@ -370,8 +374,8 @@ pub fn from_expr(expr: T) -> Self { 
            "Requested value larger than maximal representable value."

        );



        // INVARIANT: `fits_within` confirmed that `expr` can be represented within `N` bits.

        Self::__new(expr)

        // SAFETY: `fits_within` confirmed that `expr` can be represented within `N` bits.

        unsafe { Self::__new(expr) }

    }



    /// Returns the wrapped value as the backing type.
@@ -410,9 +414,9 @@ pub const fn extend<const M: u32>(self) -> Bounded<T, M> { 
            );

        }



        // INVARIANT: The value did fit within `N` bits, so it will all the more fit within

        // SAFETY: The value did fit within `N` bits, so it will all the more fit within

        // the larger `M` bits.

        Bounded::__new(self.0)

        unsafe { Bounded::__new(self.0) }

    }



    /// Attempts to shrink the number of bits usable for `self`.
@@ -466,9 +470,9 @@ pub fn cast<U>(self) -> Bounded<U, N> 
        // `U` and `T` have the same sign, hence this conversion cannot fail.

        let value = unsafe { U::try_from(self.get()).unwrap_unchecked() };



        // INVARIANT: Although the backing type has changed, the value is still represented within

        // SAFETY: Although the backing type has changed, the value is still represented within

        // `N` bits, and with the same signedness.

        Bounded::__new(value)

        unsafe { Bounded::__new(value) }

    }

}
@@ -944,9 +948,9 @@ impl<T, const N: u32> From<$type> for Bounded<T, N> 
            Self: AtLeastXBits<{ <$type as Integer>::BITS as usize }>,

        {

            fn from(value: $type) -> Self {

                // INVARIANT: The trait bound on `Self` guarantees that `N` bits is

                // SAFETY: The trait bound on `Self` guarantees that `N` bits is

                // enough to hold any value of the source type.

                Self::__new(T::from(value))

                unsafe { Self::__new(T::from(value)) }

            }

        }

        )*
@@ -1051,8 +1055,8 @@ impl<T, const N: u32> From<bool> for Bounded<T, N> 
    T: Integer + From<bool>,

{

    fn from(value: bool) -> Self {

        // INVARIANT: A boolean can be represented using a single bit, and thus fits within any

        // SAFETY: A boolean can be represented using a single bit, and thus fits within any

        // integer type for any `N` > 0.

        Self::__new(T::from(value))

        unsafe { Self::__new(T::from(value)) }

    }

}