Rust provides traits for standard arithmetic and logic operations, but
in the context of the kernel we often need to consider overflows. The
checked Rust arithmetic methods are unfortunately not behind a trait,
which makes them unavailable to generic code.

As a start, add the `CheckedAdd` trait providing the `checked_add`
operation and implement it for all integer types. Its name and location
are inspired by the user-space `num` crate.

This trait is to be first used by the `Alignment` type.

Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
---
 rust/kernel/lib.rs |  1 +
 rust/kernel/num.rs | 28 ++++++++++++++++++++++++++++
 2 files changed, 29 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..c81bb046078b70c321dd52aa9c2b5518be49d249
--- /dev/null
+++ b/rust/kernel/num.rs
@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Numerical and binary utilities for primitive types.
+
+use core::ops::Add;
+
+/// Trait for performing a checked addition that returns `None` if the operation would overflow.
+///
+/// This trait exists in order to represent scalar types already having a `checked_add` method in
+/// generic code.
+pub trait CheckedAdd: Sized + Add<Self, Output = Self> {
+    /// Computes `self + rhs`, returning `None` if an overflow would occur.
+    fn checked_add(self, rhs: Self) -> Option<Self>;
+}
+
+macro_rules! impl_checked_add {
+    ($($t:ty),*) => {
+        $(
+        impl CheckedAdd for $t {
+            fn checked_add(self, rhs: Self) -> Option<Self> {
+                self.checked_add(rhs)
+            }
+        }
+        )*
+    };
+}
+
+impl_checked_add!(u8, u16, u32, u64, usize, i8, i16, i32, i64, isize);

-- 
2.50.1

Hi Alex,

> On 4 Aug 2025, at 08:45, Alexandre Courbot <acourbot@nvidia.com> wrote:
> 
> Rust provides traits for standard arithmetic and logic operations, but
> in the context of the kernel we often need to consider overflows. The
> checked Rust arithmetic methods are unfortunately not behind a trait,
> which makes them unavailable to generic code.
> 
> As a start, add the `CheckedAdd` trait providing the `checked_add`
> operation and implement it for all integer types. Its name and location
> are inspired by the user-space `num` crate.
> 
> This trait is to be first used by the `Alignment` type.
> 
> Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
> ---
> rust/kernel/lib.rs |  1 +
> rust/kernel/num.rs | 28 ++++++++++++++++++++++++++++
> 2 files changed, 29 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..c81bb046078b70c321dd52aa9c2b5518be49d249
> --- /dev/null
> +++ b/rust/kernel/num.rs
> @@ -0,0 +1,28 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Numerical and binary utilities for primitive types.
> +
> +use core::ops::Add;
> +
> +/// Trait for performing a checked addition that returns `None` if the operation would overflow.

nit: this can be [`None`] instead, which will let users click on it in the docs.

This is of course pretty frivolous.

> +///
> +/// This trait exists in order to represent scalar types already having a `checked_add` method in
> +/// generic code.

Maybe “scalar types that already have a `checked_add` method?

But overall I feel like the whole sentence is a bit hard to parse, JFYI.

> +pub trait CheckedAdd: Sized + Add<Self, Output = Self> {
> +    /// Computes `self + rhs`, returning `None` if an overflow would occur.
> +    fn checked_add(self, rhs: Self) -> Option<Self>;
> +}
> +
> +macro_rules! impl_checked_add {
> +    ($($t:ty),*) => {
> +        $(
> +        impl CheckedAdd for $t {
> +            fn checked_add(self, rhs: Self) -> Option<Self> {
> +                self.checked_add(rhs)
> +            }
> +        }
> +        )*
> +    };
> +}
> +
> +impl_checked_add!(u8, u16, u32, u64, usize, i8, i16, i32, i64, isize);
> 
> -- 
> 2.50.1
> 
> 


Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>

On Mon Aug 4, 2025 at 11:37 PM JST, Daniel Almeida wrote:
> Hi Alex,
>
>> On 4 Aug 2025, at 08:45, Alexandre Courbot <acourbot@nvidia.com> wrote:
>> 
>> Rust provides traits for standard arithmetic and logic operations, but
>> in the context of the kernel we often need to consider overflows. The
>> checked Rust arithmetic methods are unfortunately not behind a trait,
>> which makes them unavailable to generic code.
>> 
>> As a start, add the `CheckedAdd` trait providing the `checked_add`
>> operation and implement it for all integer types. Its name and location
>> are inspired by the user-space `num` crate.
>> 
>> This trait is to be first used by the `Alignment` type.
>> 
>> Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
>> ---
>> rust/kernel/lib.rs |  1 +
>> rust/kernel/num.rs | 28 ++++++++++++++++++++++++++++
>> 2 files changed, 29 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..c81bb046078b70c321dd52aa9c2b5518be49d249
>> --- /dev/null
>> +++ b/rust/kernel/num.rs
>> @@ -0,0 +1,28 @@
>> +// SPDX-License-Identifier: GPL-2.0
>> +
>> +//! Numerical and binary utilities for primitive types.
>> +
>> +use core::ops::Add;
>> +
>> +/// Trait for performing a checked addition that returns `None` if the operation would overflow.
>
> nit: this can be [`None`] instead, which will let users click on it in the docs.
>
> This is of course pretty frivolous.

... but correct. Thanks.

>
>> +///
>> +/// This trait exists in order to represent scalar types already having a `checked_add` method in
>> +/// generic code.
>
> Maybe “scalar types that already have a `checked_add` method?
>
> But overall I feel like the whole sentence is a bit hard to parse, JFYI.

Let me rephrase this as "This trait exists to model scalar types with a
`checked_add` method in generic code." (provided this trait survives the
next revision).