Alignment operations are very common in the kernel. Since they are
always performed using a power of two value, enforcing this invariant
through a dedicated type leads to less bugs and can lead to improved
generated code.
Introduce the `Alignment` type, inspired by the nightly Rust feature of
the same name. It provides the same interface as its upstream namesake,
while extending it with `align_up` and `align_down` operations that are
usable on any integer type.
Signed-off-by: Alexandre Courbot <acourbot at nvidia.com>
---
rust/kernel/lib.rs | 1 +
rust/kernel/ptr.rs | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 214 insertions(+)
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index
2955f65da1278dd4cba1e4272ff178b8211a892c..0e66b55cde66ee1b274862cd78ad465a572dc5d9
100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -100,6 +100,7 @@
pub mod platform;
pub mod prelude;
pub mod print;
+pub mod ptr;
pub mod rbtree;
pub mod revocable;
pub mod security;
diff --git a/rust/kernel/ptr.rs b/rust/kernel/ptr.rs
new file mode 100644
index
0000000000000000000000000000000000000000..6d941db58944619ea5b05676af06981a3ceaaca8
--- /dev/null
+++ b/rust/kernel/ptr.rs
@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Types and functions to work with pointers and addresses.
+
+use core::fmt::Debug;
+use core::num::NonZero;
+use core::ops::{BitAnd, Not};
+
+use crate::build_assert;
+use crate::num::CheckedAdd;
+
+/// Type representing an alignment, which is always a power of two.
+///
+/// It be used to validate that a given value is a valid alignment, and to
perform masking and
+/// align down/up operations. The alignment operations are done using the
[`align_up!`] and
+/// [`align_down!`] macros.
+///
+/// Heavily inspired by the [`Alignment`] nightly feature from the Rust
standard library, and
+/// hopefully 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` 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.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::ptr::Alignment;
+ ///
+ /// assert_eq!(Alignment::new(0x10).align_down(0x2f), 0x20);
+ /// assert_eq!(Alignment::new(0x10).align_down(0x30), 0x30);
+ /// assert_eq!(Alignment::new(0x1000).align_down(0xf0u8), 0x0);
+ /// ```
+ #[inline(always)]
+ pub fn align_down<T>(self, value: T) -> T
+ where
+ T: TryFrom<usize> + BitAnd<Output = T> + Not<Output =
T> + Default,
+ {
+ T::try_from(self.mask())
+ .map(|mask| value & !mask)
+ .unwrap_or(T::default())
+ }
+
+ /// Aligns `value` up to this alignment, returning `None` if aligning
pushes the result above
+ /// the limits of `value`'s type.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::ptr::Alignment;
+ ///
+ /// assert_eq!(Alignment::new(0x10).align_up(0x4f), Some(0x50));
+ /// assert_eq!(Alignment::new(0x10).align_up(0x40), Some(0x40));
+ /// assert_eq!(Alignment::new(0x10).align_up(0x0), Some(0x0));
+ /// assert_eq!(Alignment::new(0x10).align_up(u8::MAX), None);
+ /// assert_eq!(Alignment::new(0x100).align_up(0x10u8), None);
+ /// assert_eq!(Alignment::new(0x100).align_up(0x0u8), Some(0x0));
+ /// ```
+ #[inline(always)]
+ pub fn align_up<T>(self, value: T) -> Option<T>
+ where
+ T: TryFrom<usize>
+ + BitAnd<Output = T>
+ + Not<Output = T>
+ + Default
+ + PartialEq
+ + Copy
+ + CheckedAdd,
+ {
+ let aligned_down = self.align_down(value);
+ if value == aligned_down {
+ Some(aligned_down)
+ } else {
+ T::try_from(self.as_usize())
+ .ok()
+ .and_then(|align| aligned_down.checked_add(align))
+ }
+ }
+}
--
2.50.1
On Mon, Aug 4, 2025 at 1:45?PM Alexandre Courbot <acourbot at nvidia.com> wrote:> > +/// align down/up operations. The alignment operations are done using the [`align_up!`] and > +/// [`align_down!`] macros.These intra-doc links don't work (they are not macros in this version at least).> + /// 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>()) })Missing safety comment (`CLIPPY=1` spots it). Also, cannot we use `new()` here? i.e. the value will be known at compile-time.> + 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() } > + }I guess this one is here to help optimize users after they inline the cal? Is there a particular case you noticed? i.e. it may be worth mentioning it.> + 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 > + }I am not sure why there is `// INVARIANT` here, since we are not creating a new `Self`. I guess by "safely" you are trying to say there is no overflow risk -- I would be explicit and avoid "safe", since it is safe to overflow. Typo: subtracted Cheers, Miguel
On Mon Aug 4, 2025 at 4:17 PM CEST, Miguel Ojeda wrote:> On Mon, Aug 4, 2025 at 1:45?PM Alexandre Courbot <acourbot at nvidia.com> wrote: >> + 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() } >> + } > > I guess this one is here to help optimize users after they inline the > cal? Is there a particular case you noticed? i.e. it may be worth > mentioning it.I suggested this in the previous version [1]. For example, it optimizes division to only be a left shift. [1]: https://lore.kernel.org/all/DBL1ZGZCSJF3.29HNS9BSN89C6 at kernel.org --- Cheers, Benno
Hi Alex,> On 4 Aug 2025, at 08:45, Alexandre Courbot <acourbot at nvidia.com> wrote: > > Alignment operations are very common in the kernel. Since they are > always performed using a power of two value, enforcing this invariant > through a dedicated type leads to less bugs and can lead to improved > generated code. > > Introduce the `Alignment` type, inspired by the nightly Rust feature of > the same name. It provides the same interface as its upstream namesake, > while extending it with `align_up` and `align_down` operations that are > usable on any integer type. > > Signed-off-by: Alexandre Courbot <acourbot at nvidia.com> > --- > rust/kernel/lib.rs | 1 + > rust/kernel/ptr.rs | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 214 insertions(+) > > diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs > index 2955f65da1278dd4cba1e4272ff178b8211a892c..0e66b55cde66ee1b274862cd78ad465a572dc5d9 100644 > --- a/rust/kernel/lib.rs > +++ b/rust/kernel/lib.rs > @@ -100,6 +100,7 @@ > pub mod platform; > pub mod prelude; > pub mod print; > +pub mod ptr; > pub mod rbtree; > pub mod revocable; > pub mod security; > diff --git a/rust/kernel/ptr.rs b/rust/kernel/ptr.rs > new file mode 100644 > index 0000000000000000000000000000000000000000..6d941db58944619ea5b05676af06981a3ceaaca8 > --- /dev/null > +++ b/rust/kernel/ptr.rs > @@ -0,0 +1,213 @@ > +// SPDX-License-Identifier: GPL-2.0 > + > +//! Types and functions to work with pointers and addresses. > + > +use core::fmt::Debug; > +use core::num::NonZero; > +use core::ops::{BitAnd, Not}; > + > +use crate::build_assert; > +use crate::num::CheckedAdd; > + > +/// Type representing an alignment, which is always a power of two. > +/// > +/// It be used to validate that a given value is a valid alignment, and to perform masking and > +/// align down/up operations. The alignment operations are done using the [`align_up!`] andNit: I?d go with ?align up or align down operations? instead of using a slash.> +/// [`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.> +/// > +/// [`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?> + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::ptr::Alignment; > + /// > + /// assert_eq!(Alignment::new(0x10).align_down(0x2f), 0x20); > + /// assert_eq!(Alignment::new(0x10).align_down(0x30), 0x30); > + /// assert_eq!(Alignment::new(0x1000).align_down(0xf0u8), 0x0); > + /// ``` > + #[inline(always)] > + pub fn align_down<T>(self, value: T) -> T > + where > + T: TryFrom<usize> + BitAnd<Output = T> + Not<Output = T> + Default, > + { > + T::try_from(self.mask()) > + .map(|mask| value & !mask) > + .unwrap_or(T::default()) > + } > + > + /// Aligns `value` up to this alignment, returning `None` if aligning pushes the result above > + /// the limits of `value`'s type. > + /// > + /// # Examples > + /// > + /// ``` > + /// use kernel::ptr::Alignment; > + /// > + /// assert_eq!(Alignment::new(0x10).align_up(0x4f), Some(0x50)); > + /// assert_eq!(Alignment::new(0x10).align_up(0x40), Some(0x40)); > + /// assert_eq!(Alignment::new(0x10).align_up(0x0), Some(0x0)); > + /// assert_eq!(Alignment::new(0x10).align_up(u8::MAX), None); > + /// assert_eq!(Alignment::new(0x100).align_up(0x10u8), None); > + /// assert_eq!(Alignment::new(0x100).align_up(0x0u8), Some(0x0)); > + /// ``` > + #[inline(always)] > + pub fn align_up<T>(self, value: T) -> Option<T> > + where > + T: TryFrom<usize> > + + BitAnd<Output = T> > + + Not<Output = T> > + + Default > + + PartialEq > + + Copy > + + CheckedAdd, > + { > + let aligned_down = self.align_down(value); > + if value == aligned_down { > + Some(aligned_down) > + } else { > + T::try_from(self.as_usize()) > + .ok() > + .and_then(|align| aligned_down.checked_add(align)) > + } > + } > +} > > -- > 2.50.1 > >Everything else looks fine, IMHO. ? Daniel
On Mon Aug 4, 2025 at 11:17 PM JST, Miguel Ojeda wrote:> On Mon, Aug 4, 2025 at 1:45?PM Alexandre Courbot <acourbot at nvidia.com> wrote: >> >> +/// align down/up operations. The alignment operations are done using the [`align_up!`] and >> +/// [`align_down!`] macros. > > These intra-doc links don't work (they are not macros in this version at least).Oops, these are remnants of some previous attempt at making this work, which I could swear I removed. That and the sentence's grammar as a whole is incorrect. Let me rework this.> >> + /// 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>()) }) > > Missing safety comment (`CLIPPY=1` spots it). > > Also, cannot we use `new()` here? i.e. the value will be known at compile-time.We can indeed! Brilliant.> >> + 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() } >> + } > > I guess this one is here to help optimize users after they inline the > cal? Is there a particular case you noticed? i.e. it may be worth > mentioning it.This was a suggestion from Benno [1], to give more hints to the compiler. Let me add a comment to justify its presence. [1] https://lore.kernel.org/rust-for-linux/DBL1ZGZCSJF3.29HNS9BSN89C6 at kernel.org/> >> + 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 >> + } > > I am not sure why there is `// INVARIANT` here, since we are not > creating a new `Self`.> > I guess by "safely" you are trying to say there is no overflow risk -- > I would be explicit and avoid "safe", since it is safe to overflow.I just wanted to justify that we cannot substract from 0. Maybe an `unchecked_sub` would be better here? The `unsafe` block would also justify the safety comment. ... mmm actually that would be `checked_sub().unwrap_unchecked()`, since `unchecked_sub` appeared in Rust 1.79.