| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <DBUIVGA74QX5.2KDKFG809YZ0A@nvidia.com>
Date: Tue, 05 Aug 2025 22:18:56 +0900
From: "Alexandre Courbot" <acourbot@...dia.com>
To: "Daniel Almeida" <daniel.almeida@...labora.com>
Cc: "Miguel Ojeda" <ojeda@...nel.org>, "Alex Gaynor"
<alex.gaynor@...il.com>, "Boqun Feng" <boqun.feng@...il.com>, "Gary Guo"
<gary@...yguo.net>, Björn Roy Baron
<bjorn3_gh@...tonmail.com>, "Benno Lossin" <lossin@...nel.org>, "Andreas
Hindborg" <a.hindborg@...nel.org>, "Alice Ryhl" <aliceryhl@...gle.com>,
"Trevor Gross" <tmgross@...ch.edu>, "Danilo Krummrich" <dakr@...nel.org>,
<linux-kernel@...r.kernel.org>, <rust-for-linux@...r.kernel.org>,
<nouveau@...ts.freedesktop.org>
Subject: Re: [PATCH v2 2/4] rust: add `Alignment` type
On Tue Aug 5, 2025 at 12:47 AM JST, Daniel Almeida wrote:
<snip>
>> +/// [`align_down!`] macros.
>> +///
>> +/// Heavily inspired by the [`Alignment`] nightly feature from the Rust standard library, and
>> +/// hopefully to be eventually replaced by it.
>
> It’s a bit hard to parse this.
>
> Also, I wonder if we should standardize some syntax for TODOs so we can parse
> them using a script? This way we can actually keep track and perhaps pipe them
> to our GitHub page as “good first issues” or just regular issues.
>
> I guess a simple "// TODO: “ here will do, for example.
FWIW, in Nova we tag each TODO items with a 4-letter identifier (i.e.
`TODO[ABCD]:` that is defined in our `todo.rst` file. This makes
grepping all the sites relevant to a given item easy.
>
>> +///
>> +/// [`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` cannot be asserted to be 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(align: usize) -> Self {
>> + build_assert!(align.is_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.
>> + ///
>> + /// [`None`] is returned if `align` was 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`.
>> + #[inline(always)]
>> + pub const fn of<T>() -> Self {
>> + // INVARIANT: `align_of` always returns a power of 2.
>> + Self(unsafe { NonZero::new_unchecked(align_of::<T>()) })
>> + }
>
>> +
>> + /// 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 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> {
>> + 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 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 the mask corresponding 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 {
>> + // INVARIANT: `self.as_usize()` is guaranteed to be a power of two (i.e. non-zero), thus
>> + // `1` can safely be substracted from it.
>> + self.as_usize() - 1
>> + }
>> +
>> + /// Aligns `value` down to this alignment.
>> + ///
>> + /// If the alignment contained in `self` is too large for `T`, then `0` is returned, which
>> + /// is correct as it is also the result that would have been returned if it did.
>
> I half get this, but still: If it did what?
I also stumbled while re-reading this sentence. :) Fixed.
Powered by blists - more mailing lists