Re: [PATCH v3 2/4] rust: num: add Bounded integer wrapping type

["Alexandre Courbot" <acourbot@nvidia.com>]

On Thu Nov 6, 2025 at 6:53 PM JST, Alice Ryhl wrote:
> On Thu, Nov 06, 2025 at 04:07:14PM +0900, Alexandre Courbot wrote:
>> Add the `Bounded` integer wrapper type, which restricts the number of
>> bits allowed to represent of value.
>> 
>> This is useful to e.g. enforce guarantees when working with bitfields
>> that have an arbitrary number of bits.
>> 
>> Alongside this type, provide many `From` and `TryFrom` implementations
>> are to reduce friction when using with regular integer types. Proxy
>> implementations of common integer operations are also provided.
>> 
>> Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
>> ---
>>  rust/kernel/num.rs         |    3 +
>>  rust/kernel/num/bounded.rs | 1045 ++++++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 1048 insertions(+)
>> 
>> diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
>> index 3f85e50b8632..bc9abcc3a317 100644
>> --- a/rust/kernel/num.rs
>> +++ b/rust/kernel/num.rs
>> @@ -4,6 +4,9 @@
>>  
>>  use core::ops;
>>  
>> +pub mod bounded;
>> +pub use bounded::*;
>> +
>>  /// Designates unsigned primitive types.
>>  pub struct Unsigned(());
>>  
>> diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
>> new file mode 100644
>> index 000000000000..2e4bc4ce9af5
>> --- /dev/null
>> +++ b/rust/kernel/num/bounded.rs
>> @@ -0,0 +1,1045 @@
>> +// SPDX-License-Identifier: GPL-2.0
>> +
>> +//! Implementation of [`Bounded`], a wrapper around integer types limiting the number of bits
>> +//! usable for value representation.
>> +
>> +use core::{
>> +    cmp,
>> +    fmt,
>> +    ops::{
>> +        self,
>> +        Deref, //
>> +    }, //,
>> +};
>> +
>> +use kernel::{
>> +    num::Integer,
>> +    prelude::*, //
>> +};
>> +
>> +/// Evaluates to `true` if `$value` can be represented using at most `$n` bits in a `$type`.
>> +///
>> +/// Can be used in const context.
>> +macro_rules! fits_within {
>> +    ($value:expr, $type:ty, $n:expr) => {{
>> +        let shift: u32 = <$type>::BITS - $n;
>> +
>> +        // `value` fits within `$n` bits if shifting it left by the number of unused bits, then
>> +        // right by the same number, doesn't change it.
>> +        //
>> +        // This method has the benefit of working for both unsigned and signed values.
>> +        ($value << shift) >> shift == $value
>
> I'm still confused about whether this works or not for signed values.
>
> I guess for a signed 4-bit int, the range of values is -8 to 7, so those
> are the values that this shift should preserve the values of. Is that
> what it does?

Let's roll these examples, using a 4 bit integer backed by a i8.

-8i8 in binary is 1111_1000. Shift it left by 4 (`i8::BITS - 4`), and
you get 1000_0000. Shift it back right by 4, you get 1111_1000, which is
the original value. The smallest possible representation of -8 is
`1000`, which indeed fits in 4 bits.

Now -9i8. In binary it is 1111_0111. Shift it left by 4, you get
0111_0000. Shift back right, you get 0000_0111. The value is different,
it doesn't fit - and indeed, its smallest representation is 1_0111,
which requires 5 bits.

And if you go with smaller negative numbers, some `0` will eventually
end up in the 4 MSBs and lost in the shift, so any value < -9 is
properly detected as non-fitting.

Now for the positive limit. 7i8 is 0000_0111. Shift left by 4,
0111_0000. Shift back right, 0000_0111, original value. Smallest
possible representation of 7 as a signed integer (thus including the bit
sign) is 0111, so that works.

8i8 now. In binary, it's 0000_1000. Shift left by 4, 1000_0000. Shift
back right, 1111_1000. Doesn't fit, because its smallest possible
representation is 0_1000, 5 bits.

I have confirmed the above with a kunit test as well. Actually I will
probably add these to the doctest for `try_new` - since all that
constructor does is call `fits_within`, that will cover these edge
cases.