[v2] rust: add `register!` macro

[PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`

Posted by Alexandre Courbot 2 weeks, 3 days ago

Shifting a `Bounded` left or right changes the number of bits required
to represent the value. Add methods that perform the shift and return a
`Bounded` with the appropriately adjusted bit width.

These methods are particularly useful for bitfield extraction.

Suggested-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
---
 rust/kernel/num/bounded.rs | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
index f870080af8ac..8782535770f1 100644
--- a/rust/kernel/num/bounded.rs
+++ b/rust/kernel/num/bounded.rs
@@ -470,6 +470,46 @@ pub fn cast<U>(self) -> Bounded<U, N>
         // `N` bits, and with the same signedness.
         Bounded::__new(value)
     }
+
+    /// Right-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N - SHIFT }>`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::Bounded;
+    ///
+    /// let v = Bounded::<u32, 16>::new::<0xff00>();
+    /// let v_shifted: Bounded::<u32, 8> = v.shr::<8, _>();
+    ///
+    /// assert_eq!(v_shifted.get(), 0xff);
+    /// ```
+    pub fn shr<const SHIFT: u32, const RES: u32>(self) -> Bounded<T, RES> {
+        const { assert!(RES >= N - SHIFT) }
+
+        // SAFETY: we shift the value right by `SHIFT`, reducing the number of bits needed to
+        // represent the shifted value by as much, and just asserted that `RES == N - SHIFT`.
+        unsafe { Bounded::__new(self.0 >> SHIFT) }
+    }
+
+    /// Left-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N + SHIFT }>`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::Bounded;
+    ///
+    /// let v = Bounded::<u32, 8>::new::<0xff>();
+    /// let v_shifted: Bounded::<u32, 16> = v.shl::<8, _>();
+    ///
+    /// assert_eq!(v_shifted.get(), 0xff00);
+    /// ```
+    pub fn shl<const SHIFT: u32, const RES: u32>(self) -> Bounded<T, RES> {
+        const { assert!(RES >= N + SHIFT) }
+
+        // SAFETY: we shift the value left by `SHIFT`, augmenting the number of bits needed to
+        // represent the shifted value by as much, and just asserted that `RES == N + SHIFT`.
+        unsafe { Bounded::__new(self.0 << SHIFT) }
+    }
 }
 
 impl<T, const N: u32> Deref for Bounded<T, N>

-- 
2.52.0

Re: [PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`

Posted by kernel test robot 2 weeks, 3 days ago

Hi Alexandre,

kernel test robot noticed the following build warnings:

[auto build test WARNING on c259cd7ea3c9ad369c473ba2385d82e3432088b1]

url:    https://github.com/intel-lab-lkp/linux/commits/Alexandre-Courbot/rust-enable-the-generic_arg_infer-feature/20260121-152936
base:   c259cd7ea3c9ad369c473ba2385d82e3432088b1
patch link:    https://lore.kernel.org/r/20260121-register-v2-2-79d9b8d5e36a%40nvidia.com
patch subject: [PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`
config: x86_64-randconfig-071-20260121 (https://download.01.org/0day-ci/archive/20260122/202601220119.LQY1LLC8-lkp@intel.com/config)
compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261)
rustc: rustc 1.88.0 (6b00bc388 2025-06-23)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260122/202601220119.LQY1LLC8-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202601220119.LQY1LLC8-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> warning: unnecessary `unsafe` block
   --> rust/kernel/num/bounded.rs:491:9
   |
   491 |         unsafe { Bounded::__new(self.0 >> SHIFT) }
   |         ^^^^^^ unnecessary `unsafe` block
   |
   = note: `#[warn(unused_unsafe)]` on by default
--
>> warning: unnecessary `unsafe` block
   --> rust/kernel/num/bounded.rs:511:9
   |
   511 |         unsafe { Bounded::__new(self.0 << SHIFT) }
   |         ^^^^^^ unnecessary `unsafe` block

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`

Posted by Gary Guo 2 weeks, 3 days ago

On Wed Jan 21, 2026 at 7:23 AM GMT, Alexandre Courbot wrote:
> Shifting a `Bounded` left or right changes the number of bits required
> to represent the value. Add methods that perform the shift and return a
> `Bounded` with the appropriately adjusted bit width.
>
> These methods are particularly useful for bitfield extraction.
>
> Suggested-by: Alice Ryhl <aliceryhl@google.com>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
> ---
>  rust/kernel/num/bounded.rs | 40 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
>
> diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
> index f870080af8ac..8782535770f1 100644
> --- a/rust/kernel/num/bounded.rs
> +++ b/rust/kernel/num/bounded.rs
> @@ -470,6 +470,46 @@ pub fn cast<U>(self) -> Bounded<U, N>
>          // `N` bits, and with the same signedness.
>          Bounded::__new(value)

This patch doesn't apply cleanly. Looks like you send it from the wrong base
commit.

The __new call here is still safe while your code has `unsafe {}` in it.

>      }
> +
> +    /// Right-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N - SHIFT }>`.

The returned bound can be larger given the assert below?

> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::num::Bounded;
> +    ///
> +    /// let v = Bounded::<u32, 16>::new::<0xff00>();
> +    /// let v_shifted: Bounded::<u32, 8> = v.shr::<8, _>();
> +    ///
> +    /// assert_eq!(v_shifted.get(), 0xff);
> +    /// ```
> +    pub fn shr<const SHIFT: u32, const RES: u32>(self) -> Bounded<T, RES> {
> +        const { assert!(RES >= N - SHIFT) }

Quite surprised that rustfmt didn't ask for the block to be expanded into
multiple lines.

I think we probably want to create a new assert macro for this pattern
(obviously this doesn't block this patch).

> +
> +        // SAFETY: we shift the value right by `SHIFT`, reducing the number of bits needed to
> +        // represent the shifted value by as much, and just asserted that `RES == N - SHIFT`.
> +        unsafe { Bounded::__new(self.0 >> SHIFT) }
> +    }
> +
> +    /// Left-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N + SHIFT }>`.

Same, the bound can be actually larger.

Best,
Gary

> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::num::Bounded;
> +    ///
> +    /// let v = Bounded::<u32, 8>::new::<0xff>();
> +    /// let v_shifted: Bounded::<u32, 16> = v.shl::<8, _>();
> +    ///
> +    /// assert_eq!(v_shifted.get(), 0xff00);
> +    /// ```
> +    pub fn shl<const SHIFT: u32, const RES: u32>(self) -> Bounded<T, RES> {
> +        const { assert!(RES >= N + SHIFT) }
> +
> +        // SAFETY: we shift the value left by `SHIFT`, augmenting the number of bits needed to
> +        // represent the shifted value by as much, and just asserted that `RES == N + SHIFT`.
> +        unsafe { Bounded::__new(self.0 << SHIFT) }
> +    }
>  }
>  
>  impl<T, const N: u32> Deref for Bounded<T, N>

Re: [PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`

Posted by Alexandre Courbot 1 week, 6 days ago

On Wed Jan 21, 2026 at 11:12 PM JST, Gary Guo wrote:
> On Wed Jan 21, 2026 at 7:23 AM GMT, Alexandre Courbot wrote:
>> Shifting a `Bounded` left or right changes the number of bits required
>> to represent the value. Add methods that perform the shift and return a
>> `Bounded` with the appropriately adjusted bit width.
>>
>> These methods are particularly useful for bitfield extraction.
>>
>> Suggested-by: Alice Ryhl <aliceryhl@google.com>
>> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>> Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
>> ---
>>  rust/kernel/num/bounded.rs | 40 ++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 40 insertions(+)
>>
>> diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
>> index f870080af8ac..8782535770f1 100644
>> --- a/rust/kernel/num/bounded.rs
>> +++ b/rust/kernel/num/bounded.rs
>> @@ -470,6 +470,46 @@ pub fn cast<U>(self) -> Bounded<U, N>
>>          // `N` bits, and with the same signedness.
>>          Bounded::__new(value)
>
> This patch doesn't apply cleanly. Looks like you send it from the wrong base
> commit.
>
> The __new call here is still safe while your code has `unsafe {}` in it.

The cover letter mentions that the base for this patchset is
`driver-core-next`, since `register!` lands in `kernel/rust/io` and we
need to rebase on top of Zhi's Io patchset, which will land there as
well.

This indeed creates a minor conflict with `rust-next` as it includes a
couple of patches for `bounded.rs`.

>
>>      }
>> +
>> +    /// Right-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N - SHIFT }>`.
>
> The returned bound can be larger given the assert below?

Indeed, I forgot to update this comment - thanks!

>
>> +    ///
>> +    /// # Examples
>> +    ///
>> +    /// ```
>> +    /// use kernel::num::Bounded;
>> +    ///
>> +    /// let v = Bounded::<u32, 16>::new::<0xff00>();
>> +    /// let v_shifted: Bounded::<u32, 8> = v.shr::<8, _>();
>> +    ///
>> +    /// assert_eq!(v_shifted.get(), 0xff);
>> +    /// ```
>> +    pub fn shr<const SHIFT: u32, const RES: u32>(self) -> Bounded<T, RES> {
>> +        const { assert!(RES >= N - SHIFT) }
>
> Quite surprised that rustfmt didn't ask for the block to be expanded into
> multiple lines.
>
> I think we probably want to create a new assert macro for this pattern
> (obviously this doesn't block this patch).
>
>> +
>> +        // SAFETY: we shift the value right by `SHIFT`, reducing the number of bits needed to
>> +        // represent the shifted value by as much, and just asserted that `RES == N - SHIFT`.
>> +        unsafe { Bounded::__new(self.0 >> SHIFT) }
>> +    }
>> +
>> +    /// Left-shifts `self` by `SHIFT` and returns the result as a `Bounded<_, { N + SHIFT }>`.
>
> Same, the bound can be actually larger.

Fixed, thanks.

Re: [PATCH v2 2/5] rust: num: add `shr` and `shl` methods to `Bounded`

Posted by Miguel Ojeda 1 week, 6 days ago

On Mon, Jan 26, 2026 at 4:24 AM Alexandre Courbot <acourbot@nvidia.com> wrote:
>
> This indeed creates a minor conflict with `rust-next` as it includes a
> couple of patches for `bounded.rs`.

`rust-fixes`, i.e. it will be in mainline soon, but yeah :)

Cheers,
Miguel