This patchset was part of the Nova FWSEC-FRTS submission [1], but has been extracted as it was not very visible there, and seems to require more discussion that the Nova code. I hope that presenting it separately will help make it converge towards something that can be merged. The motivation for this new module is to provide numerical functions not supported (or not optimally supported for the kernel use-cases) by Rust core. One example is how kernel code often aligns addresses or length to some power-of-two. While Rust has `next_multiple_of` that provides the same result, it also supports non-power-of-two values and is thus not as efficient as the simple substract-and-mask operation that can be done with a power of two. Another missing operation is `last_set_bit` (`fls` in the C code), which is again commonly used in the kernel but has no equivalent yet in Rust core. This patchset introduces these two features available: - A `PowerOfTwo` newtype for unsigned integers with `align_down` and `align_up` operations optimized for the kernel. The newtype ensures that these operations cannot be used with a non-power-of-two, which would yield an incorrect result. - A set of `last_set_bit` const functions for unsigned integers types. The last patch makes use of these features in the Nova driver, as was originally done in the patchset. It requires the v6 of the patch series [2] to be applied. [1] https://lore.kernel.org/rust-for-linux/DANP9ATT1T5W.1KP4992E26FTP at nvidia.com/ [2] https://lore.kernel.org/rust-for-linux/20250619-nova-frts-v6-0-ecf41ef99252 at nvidia.com/ Changes since split from the nova-core series: - Rename `fls` to `last_set_bit`, - Generate per-type doctests, - Add invariants section to `PowerOfTwo`. - Do not use reference to `self` in `PowerOfTwo` methods since it implements `Copy`, - Use #[derive] where possible instead of implementing traits manually, - Remove `Deref` and `Borrow` implementations. Signed-off-by: Alexandre Courbot <acourbot at nvidia.com> --- Alexandre Courbot (3): rust: add `num` module with `PowerOfTwo` type rust: num: add the `last_set_bit` operation nova-core: use `num` module Documentation/gpu/nova/core/todo.rst | 15 --- drivers/gpu/nova-core/falcon/hal/ga102.rs | 4 +- drivers/gpu/nova-core/fb.rs | 6 +- drivers/gpu/nova-core/firmware/fwsec.rs | 7 +- drivers/gpu/nova-core/vbios.rs | 4 +- rust/kernel/lib.rs | 1 + rust/kernel/num.rs | 201 ++++++++++++++++++++++++++++++ 7 files changed, 211 insertions(+), 27 deletions(-) --- base-commit: c7864f7ab73417e352d8d00e46d3e9e6a228c5ab change-id: 20250620-num-9420281c02c7 Best regards, -- Alexandre Courbot <acourbot at nvidia.com>
Alexandre Courbot
2025-Jun-20 13:14 UTC
[PATCH 1/3] rust: add `num` module with `PowerOfTwo` type
Introduce the `num` module, featuring the `PowerOfTwo` unsigned wrapper that guarantees (at build-time or runtime) that a value is a power of two. Such a property is often useful to maintain. In the context of the kernel, powers of two are often used to align addresses or sizes up and down, or to create masks. These operations are provided by this type. It is introduced to be first used by the nova-core driver. Signed-off-by: Alexandre Courbot <acourbot at nvidia.com> --- rust/kernel/lib.rs | 1 + rust/kernel/num.rs | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 6b4774b2b1c37f4da1866e993be6230bc6715841..2955f65da1278dd4cba1e4272ff178b8211a892c 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -89,6 +89,7 @@ pub mod mm; #[cfg(CONFIG_NET)] pub mod net; +pub mod num; pub mod of; #[cfg(CONFIG_PM_OPP)] pub mod opp; diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs new file mode 100644 index 0000000000000000000000000000000000000000..6ecff037893dd25420a6369ea0cd6adbe3460b29 --- /dev/null +++ b/rust/kernel/num.rs @@ -0,0 +1,163 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Numerical and binary utilities for primitive types. + +use crate::build_assert; +use core::fmt::Debug; +use core::hash::Hash; + +/// An unsigned integer which is guaranteed to be a power of 2. +/// +/// # Invariants +/// +/// The stored value is guaranteed to be a power of two. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[repr(transparent)] +pub struct PowerOfTwo<T>(T); + +macro_rules! power_of_two_impl { + ($($t:ty),+) => { + $( + impl PowerOfTwo<$t> { + /// Validates that `v` is a power of two at build-time, and returns it wrapped into + /// [`PowerOfTwo`]. + /// + /// A build error is triggered if `v` cannot be asserted to be a power of two. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!("let v = PowerOfTwo::<", stringify!($t), ">::new(16);")] + /// assert_eq!(v.value(), 16); + /// ``` + #[inline(always)] + pub const fn new(v: $t) -> Self { + build_assert!(v.count_ones() == 1); + Self(v) + } + + /// Validates that `v` is a power of two at runtime, and returns it wrapped into + /// [`PowerOfTwo`]. + /// + /// [`None`] is returned if `v` was not a power of two. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::try_new(16), Some(PowerOfTwo::<", + stringify!($t), + ">::new(16)));" + )] + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::try_new(15), None);" + )] + /// ``` + #[inline(always)] + pub const fn try_new(v: $t) -> Option<Self> { + match v.count_ones() { + 1 => Some(Self(v)), + _ => None, + } + } + + /// Returns the value of this instance. + /// + /// It is guaranteed to be a power of two. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!("let v = PowerOfTwo::<", stringify!($t), ">::new(16);")] + /// assert_eq!(v.value(), 16); + /// ``` + #[inline(always)] + pub const fn value(self) -> $t { + self.0 + } + + /// Returns the mask corresponding to `self.value() - 1`. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!("let v = PowerOfTwo::<", stringify!($t), ">::new(0x10);")] + /// assert_eq!(v.mask(), 0xf); + /// ``` + #[inline(always)] + pub const fn mask(self) -> $t { + self.0.wrapping_sub(1) + } + + /// Aligns `self` down to `alignment`. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::new(0x10).align_down(0x2f), 0x20);" + )] + /// ``` + #[inline(always)] + pub const fn align_down(self, value: $t) -> $t { + value & !self.mask() + } + + /// Aligns `value` up to `self`. + /// + /// Wraps around to `0` if the requested alignment pushes the result above the + /// type's limits. + /// + /// # Examples + /// + /// ``` + /// use kernel::num::PowerOfTwo; + /// + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::new(0x10).align_up(0x4f), 0x50);" + )] + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::new(0x10).align_up(0x40), 0x40);" + )] + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::new(0x10).align_up(0x0), 0x0);" + )] + #[doc = concat!( + "assert_eq!(PowerOfTwo::<", + stringify!($t), + ">::new(0x10).align_up(", + stringify!($t), "::MAX), 0x0);" + )] + /// ``` + #[inline(always)] + pub const fn align_up(self, value: $t) -> $t { + self.align_down(value.wrapping_add(self.mask())) + } + } + )+ + }; +} + +power_of_two_impl!(usize, u8, u16, u32, u64, u128); -- 2.49.0
Alexandre Courbot
2025-Jun-20 13:14 UTC
[PATCH 2/3] rust: num: add the `last_set_bit` operation
Add an equivalent to the `fls` (Find Last Set bit) C function to Rust unsigned types. It is to be first used by the nova-core driver. Signed-off-by: Alexandre Courbot <acourbot at nvidia.com> --- rust/kernel/num.rs | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs index 6ecff037893dd25420a6369ea0cd6adbe3460b29..95766201a7cf208989f37ecbc6d54d264385a754 100644 --- a/rust/kernel/num.rs +++ b/rust/kernel/num.rs @@ -161,3 +161,41 @@ pub const fn align_up(self, value: $t) -> $t { } power_of_two_impl!(usize, u8, u16, u32, u64, u128); + +macro_rules! impl_last_set_bit { + ($($t:ty),+) => { + $( + ::kernel::macros::paste! { + /// Last Set Bit: return the 1-based index of the last (i.e. most significant) set bit + /// in `v`. + /// + /// Equivalent to the C `fls` function. + /// + /// # Examples + /// + /// ``` + #[doc = concat!("use kernel::num::last_set_bit_", stringify!($t), ";")] + /// + #[doc = concat!("assert_eq!(last_set_bit_", stringify!($t), "(0x0), 0);")] + #[doc = concat!("assert_eq!(last_set_bit_", stringify!($t), "(0x1), 1);")] + #[doc = concat!("assert_eq!(last_set_bit_", stringify!($t), "(0x10), 5);")] + #[doc = concat!("assert_eq!(last_set_bit_", stringify!($t), "(0x1f), 5);")] + #[doc = concat!( + "assert_eq!(last_set_bit_", + stringify!($t), + "(", + stringify!($t), + "::MAX), ", + stringify!($t), "::BITS);" + )] + /// ``` + #[inline(always)] + pub const fn [<last_set_bit_ $t>](v: $t) -> u32 { + $t::BITS - v.leading_zeros() + } + } + )+ + }; +} + +impl_last_set_bit!(usize, u8, u16, u32, u64, u128); -- 2.49.0
Make use of the functions available in the `num` module and remove the corresponding TODO items. Signed-off-by: Alexandre Courbot <acourbot at nvidia.com> --- Documentation/gpu/nova/core/todo.rst | 15 --------------- drivers/gpu/nova-core/falcon/hal/ga102.rs | 4 ++-- drivers/gpu/nova-core/fb.rs | 6 +++--- drivers/gpu/nova-core/firmware/fwsec.rs | 7 ++----- drivers/gpu/nova-core/vbios.rs | 4 ++-- 5 files changed, 9 insertions(+), 27 deletions(-) diff --git a/Documentation/gpu/nova/core/todo.rst b/Documentation/gpu/nova/core/todo.rst index 894a1e9c3741a43ad4eb76d24a9486862999874e..01dfa858d11fe377c345b463742c13c37878e334 100644 --- a/Documentation/gpu/nova/core/todo.rst +++ b/Documentation/gpu/nova/core/todo.rst @@ -141,21 +141,6 @@ Features desired before this happens: | Complexity: Advanced | Contact: Alexandre Courbot -Numerical operations [NUMM] ---------------------------- - -Nova uses integer operations that are not part of the standard library (or not -implemented in an optimized way for the kernel). These include: - -- Aligning up and down to a power of two, -- The "Find Last Set Bit" (`fls` function of the C part of the kernel) - operation. - -A `num` core kernel module is being designed to provide these operations. - -| Complexity: Intermediate -| Contact: Alexandre Courbot - Delay / Sleep abstractions [DLAY] --------------------------------- diff --git a/drivers/gpu/nova-core/falcon/hal/ga102.rs b/drivers/gpu/nova-core/falcon/hal/ga102.rs index 664327f75cf4199cca37d22ca18b2b9abac781f8..9158991ec6e30f42fc0c7e49c87e2c04b426189f 100644 --- a/drivers/gpu/nova-core/falcon/hal/ga102.rs +++ b/drivers/gpu/nova-core/falcon/hal/ga102.rs @@ -4,6 +4,7 @@ use core::time::Duration; use kernel::device; +use kernel::num::last_set_bit_u32; use kernel::prelude::*; use crate::driver::Bar0; @@ -69,8 +70,7 @@ fn signature_reg_fuse_version_ga102( let reg_fuse_version bar.read32(reg_fuse_base + ((ucode_id - 1) as usize * core::mem::size_of::<u32>())); - // TODO[NUMM]: replace with `last_set_bit` once it lands. - Ok(u32::BITS - reg_fuse_version.leading_zeros()) + Ok(last_set_bit_u32(reg_fuse_version)) } fn program_brom_ga102<E: FalconEngine>(bar: &Bar0, params: &FalconBromParams) -> Result { diff --git a/drivers/gpu/nova-core/fb.rs b/drivers/gpu/nova-core/fb.rs index 48003527a2472a4a8b784af0d481a441c8d2426e..ca5e7ef997bc2b2855a1d60e81300fb99fe04cdb 100644 --- a/drivers/gpu/nova-core/fb.rs +++ b/drivers/gpu/nova-core/fb.rs @@ -2,6 +2,7 @@ use core::ops::Range; +use kernel::num::PowerOfTwo; use kernel::prelude::*; use kernel::sizes::*; use kernel::types::ARef; @@ -119,10 +120,9 @@ pub(crate) fn new(chipset: Chipset, bar: &Bar0) -> Result<Self> { }; let frts = { - const FRTS_DOWN_ALIGN: u64 = SZ_128K as u64; + const FRTS_DOWN_ALIGN: PowerOfTwo<u64> = PowerOfTwo::<u64>::new(SZ_128K as u64); const FRTS_SIZE: u64 = SZ_1M as u64; - // TODO[NUMM]: replace with `align_down` once it lands. - let frts_base = (vga_workspace.start & !(FRTS_DOWN_ALIGN - 1)) - FRTS_SIZE; + let frts_base = FRTS_DOWN_ALIGN.align_down(vga_workspace.start) - FRTS_SIZE; frts_base..frts_base + FRTS_SIZE }; diff --git a/drivers/gpu/nova-core/firmware/fwsec.rs b/drivers/gpu/nova-core/firmware/fwsec.rs index 047aab76470ecb0a0486f6917f6fda69b5381391..0edcade5e8b303ee249397736af55c5a6f6fb97f 100644 --- a/drivers/gpu/nova-core/firmware/fwsec.rs +++ b/drivers/gpu/nova-core/firmware/fwsec.rs @@ -15,6 +15,7 @@ use core::ops::Deref; use kernel::device::{self, Device}; +use kernel::num::PowerOfTwo; use kernel::prelude::*; use kernel::transmute::FromBytes; @@ -218,11 +219,7 @@ fn dmem_load_params(&self) -> FalconLoadTarget { FalconLoadTarget { src_start: self.desc.imem_load_size, dst_start: self.desc.dmem_phys_base, - // TODO[NUMM]: replace with `align_up` once it lands. - len: self - .desc - .dmem_load_size - .next_multiple_of(DMEM_LOAD_SIZE_ALIGN), + len: PowerOfTwo::<u32>::new(DMEM_LOAD_SIZE_ALIGN).align_up(self.desc.dmem_load_size), } } diff --git a/drivers/gpu/nova-core/vbios.rs b/drivers/gpu/nova-core/vbios.rs index a5889eb149a16beabc0ddbdc87666520114c8aec..cac55d1534831775c14f3fed1e939ed89c7eba84 100644 --- a/drivers/gpu/nova-core/vbios.rs +++ b/drivers/gpu/nova-core/vbios.rs @@ -8,6 +8,7 @@ use core::convert::TryFrom; use kernel::device; use kernel::error::Result; +use kernel::num::PowerOfTwo; use kernel::pci; use kernel::prelude::*; @@ -175,8 +176,7 @@ fn next(&mut self) -> Option<Self::Item> { // Advance to next image (aligned to 512 bytes) self.current_offset += image_size; - // TODO[NUMM]: replace with `align_up` once it lands. - self.current_offset = self.current_offset.next_multiple_of(512); + self.current_offset = PowerOfTwo::<usize>::new(512).align_up(self.current_offset); Some(Ok(full_image)) } -- 2.49.0