[PATCH v3 0/2] rust: `overflow_assert!` macro

[PATCH v3 0/2] rust: `overflow_assert!` macro

[Antonio Hickey]

This patch set introduces a macro for overflow assertions, the use of
this macro will avoid local `#ifdef`s by encapsulating the conditional
behavior to the macro. In addition this macro also allows us to document
the intent of the assertion more clearly.

This patch set requires Alice's `strncpy_from_user` patch[1] linked below, 
because I use it as an example usecase for the `overflow_assert!` macro.

Dependent Patch [1]: https://lore.kernel.org/rust-for-linux/20250616-strncpy-from-user-v5-0-2d3fb0e1f5af@google.com/

Changes in v3:
- Made the `overflow_assert!` macro take in expressions instead of
  values.
- Fixed path in macro to fully qualify.
- Refactor macro to make the conditional compilation as local as
  possible.
- Refactor macro to utilize the `cfg!` macro like the standard library
  does to reduce boilerplate.
- Added an example use case of the `overflow_assert!` macro
- Link to v2: https://lore.kernel.org/rust-for-linux/20250504165612.86459-1-contact@antoniohickey.com/

Changes in v2:
- Fixed example doc comment so it doesn't panic.
- Link to v1: https://lore.kernel.org/rust-for-linux/20250504164349.84149-1-contact@antoniohickey.com/

Co-developed-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Antonio Hickey <contact@antoniohickey.com>
Link: https://github.com/Rust-for-Linux/linux/issues/1159
Suggested-by: Miguel Ojeda <ojeda@kernel.org>

Antonio Hickey (2):
  rust: kernel: create `overflow_assert!` macro
  rust: uaccess: refactor to use `overflow_assert!`

 rust/kernel/lib.rs             |  1 +
 rust/kernel/overflow_assert.rs | 33 +++++++++++++++++++++++++++++++++
 rust/kernel/uaccess.rs         |  4 ++--
 3 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 rust/kernel/overflow_assert.rs

-- 
2.50.0

[PATCH v3 1/2] rust: kernel: create `overflow_assert!` macro

[Antonio Hickey]

This commit creates a macro for overflow assertions. The use of this
macro will avoid local `#ifdef`s by encapsulating the conditional
behavior (like `#[cfg(CONFIG_RUST_OVERFLOW_CHECKS)]`) to the macro.

In addition this macro allows us to document the intent of the assertion
more clearly.

Co-developed-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Antonio Hickey <contact@antoniohickey.com>
Link: https://github.com/Rust-for-Linux/linux/issues/1159
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/lib.rs             |  1 +
 rust/kernel/overflow_assert.rs | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 rust/kernel/overflow_assert.rs

diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 6b4774b2b1c3..e395adb6b293 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -92,6 +92,7 @@
 pub mod of;
 #[cfg(CONFIG_PM_OPP)]
 pub mod opp;
+pub mod overflow_assert;
 pub mod page;
 #[cfg(CONFIG_PCI)]
 pub mod pci;
diff --git a/rust/kernel/overflow_assert.rs b/rust/kernel/overflow_assert.rs
new file mode 100644
index 000000000000..cc5f60611ba2
--- /dev/null
+++ b/rust/kernel/overflow_assert.rs
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Overflow assert.
+
+/// Verifies at runtime that an expression is within an expected bound.
+///
+/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
+///
+/// # Examples
+///
+/// ```
+/// overflow_assert!(3 <= 10);
+/// overflow_assert!(5 <= 5);
+///
+/// const X: u8 = 5;
+/// overflow_assert!(X + 3 < 10);
+///
+/// const fn f(x: i32) -> i32 {
+///     x + 1
+/// }
+/// overflow_assert!(f(40) < 42);
+/// ```
+#[macro_export]
+macro_rules! overflow_assert {
+    ($cond:expr) => {
+        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
+            ::core::assert!(
+                $cond,
+                concat!("overflow assertion failed: ", stringify!($cond))
+            );
+        }
+    };
+}
-- 
2.50.0

[PATCH v3 2/2] rust: uaccess: refactor to use `overflow_assert!`

[Antonio Hickey]

Using the `overflow_assert!` macro here adds documentation to
the intent of the assertion, and avoids local `#ifdefs`s by
encapsulating the conditional behavior to the macro itself.

Co-developed-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Daniel Cote <danielstonecote@gmail.com>
Signed-off-by: Antonio Hickey <contact@antoniohickey.com>
Link: https://github.com/Rust-for-Linux/linux/issues/1159
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/uaccess.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/uaccess.rs b/rust/kernel/uaccess.rs
index 635a03e0989f..452a5e0d76d2 100644
--- a/rust/kernel/uaccess.rs
+++ b/rust/kernel/uaccess.rs
@@ -9,6 +9,7 @@
     bindings,
     error::Result,
     ffi::{c_char, c_void},
+    overflow_assert,
     prelude::*,
     transmute::{AsBytes, FromBytes},
 };
@@ -394,8 +395,7 @@ fn raw_strncpy_from_user(dst: &mut [MaybeUninit<u8>], src: UserPtr) -> Result<us
         return Err(Error::from_errno(res as i32));
     }
 
-    #[cfg(CONFIG_RUST_OVERFLOW_CHECKS)]
-    assert!(res <= len);
+    overflow_assert!(res <= len);
 
     // GUARANTEES: `strncpy_from_user` was successful, so `dst` has contents in accordance with the
     // guarantees of this function.
-- 
2.50.0

Re: [PATCH v3 1/2] rust: kernel: create `overflow_assert!` macro

[Tamir Duberstein]

On Sat, Jun 21, 2025 at 7:06 PM Antonio Hickey
<contact@antoniohickey.com> wrote:
>
> This commit creates a macro for overflow assertions. The use of this
> macro will avoid local `#ifdef`s by encapsulating the conditional
> behavior (like `#[cfg(CONFIG_RUST_OVERFLOW_CHECKS)]`) to the macro.
>
> In addition this macro allows us to document the intent of the assertion
> more clearly.
>
> Co-developed-by: Daniel Cote <danielstonecote@gmail.com>
> Signed-off-by: Daniel Cote <danielstonecote@gmail.com>
> Signed-off-by: Antonio Hickey <contact@antoniohickey.com>
> Link: https://github.com/Rust-for-Linux/linux/issues/1159
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> ---
>  rust/kernel/lib.rs             |  1 +
>  rust/kernel/overflow_assert.rs | 33 +++++++++++++++++++++++++++++++++
>  2 files changed, 34 insertions(+)
>  create mode 100644 rust/kernel/overflow_assert.rs
>
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index 6b4774b2b1c3..e395adb6b293 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -92,6 +92,7 @@
>  pub mod of;
>  #[cfg(CONFIG_PM_OPP)]
>  pub mod opp;
> +pub mod overflow_assert;
>  pub mod page;
>  #[cfg(CONFIG_PCI)]
>  pub mod pci;
> diff --git a/rust/kernel/overflow_assert.rs b/rust/kernel/overflow_assert.rs
> new file mode 100644
> index 000000000000..cc5f60611ba2
> --- /dev/null
> +++ b/rust/kernel/overflow_assert.rs
> @@ -0,0 +1,33 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Overflow assert.

s/assert/assertion/

AFAIK the standard library always uses assertion where a noun is
needed, and assert where a verb is needed.

> +
> +/// Verifies at runtime that an expression is within an expected bound.
> +///
> +/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// overflow_assert!(3 <= 10);
> +/// overflow_assert!(5 <= 5);
> +///
> +/// const X: u8 = 5;
> +/// overflow_assert!(X + 3 < 10);
> +///
> +/// const fn f(x: i32) -> i32 {
> +///     x + 1
> +/// }
> +/// overflow_assert!(f(40) < 42);
> +/// ```
> +#[macro_export]
> +macro_rules! overflow_assert {
> +    ($cond:expr) => {
> +        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
> +            ::core::assert!(
> +                $cond,
> +                concat!("overflow assertion failed: ", stringify!($cond))

Can we still allow the caller to pass additional arguments to the
macro, so that the overflowing value can be emitted? Alternatively if
the expectation is that this macro is always used with a comparison
operator perhaps we could have `overflow_assert_lt` and
`overflow_assert_le` which provide panic messages containing the
operand values?

> +            );
> +        }
> +    };
> +}
> --
> 2.50.0
>
>
>

Re: [PATCH v3 1/2] rust: kernel: create `overflow_assert!` macro

[Antonio Hickey]

On Sun 22 Jun 13:48, Tamir Duberstein wrote:
> On Sat, Jun 21, 2025 at 7:06 PM Antonio Hickey
> <contact@antoniohickey.com> wrote:
> > +//! Overflow assert.
> 
> s/assert/assertion/
> 
> AFAIK the standard library always uses assertion where a noun is
> needed, and assert where a verb is needed.
> 

Reasonable, I'll fix this verbage in my next version.

> > +/// Verifies at runtime that an expression is within an expected bound.
> > +///
> > +/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// overflow_assert!(3 <= 10);
> > +/// overflow_assert!(5 <= 5);
> > +///
> > +/// const X: u8 = 5;
> > +/// overflow_assert!(X + 3 < 10);
> > +///
> > +/// const fn f(x: i32) -> i32 {
> > +///     x + 1
> > +/// }
> > +/// overflow_assert!(f(40) < 42);
> > +/// ```
> > +#[macro_export]
> > +macro_rules! overflow_assert {
> > +    ($cond:expr) => {
> > +        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
> > +            ::core::assert!(
> > +                $cond,
> > +                concat!("overflow assertion failed: ", stringify!($cond))
> 
> Can we still allow the caller to pass additional arguments to the
> macro, so that the overflowing value can be emitted? Alternatively if
> the expectation is that this macro is always used with a comparison
> operator perhaps we could have `overflow_assert_lt` and
> `overflow_assert_le` which provide panic messages containing the
> operand values?
> 

Me and Miguel discussed the `overflow_assert_le` and other variants in 
my previous v2 patch set[1]. We decided it would be best to just start 
with a more flexable general expression based variant of the macro for 
now, and consider other variants later. 

I agree we should expand this into more specific variants, so it would
document the intent of the assertions even more clearly.

[1] Link to Miguel's comment on a `overflow_assert_le` variant:
https://lore.kernel.org/all/CANiq72mvu54B=U+YCUmbFctj_wXgF5zjeE-BB-vHVnAP+3mPcQ@mail.gmail.com/

Thanks

Re: [PATCH v3 1/2] rust: kernel: create `overflow_assert!` macro

[Tamir Duberstein]

On Sun, Jun 22, 2025 at 6:20 PM Antonio Hickey
<contact@antoniohickey.com> wrote:
>
> On Sun 22 Jun 13:48, Tamir Duberstein wrote:
> > On Sat, Jun 21, 2025 at 7:06 PM Antonio Hickey
> > <contact@antoniohickey.com> wrote:
> > > +//! Overflow assert.
> >
> > s/assert/assertion/
> >
> > AFAIK the standard library always uses assertion where a noun is
> > needed, and assert where a verb is needed.
> >
>
> Reasonable, I'll fix this verbage in my next version.
>
> > > +/// Verifies at runtime that an expression is within an expected bound.
> > > +///
> > > +/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
> > > +///
> > > +/// # Examples
> > > +///
> > > +/// ```
> > > +/// overflow_assert!(3 <= 10);
> > > +/// overflow_assert!(5 <= 5);
> > > +///
> > > +/// const X: u8 = 5;
> > > +/// overflow_assert!(X + 3 < 10);
> > > +///
> > > +/// const fn f(x: i32) -> i32 {
> > > +///     x + 1
> > > +/// }
> > > +/// overflow_assert!(f(40) < 42);
> > > +/// ```
> > > +#[macro_export]
> > > +macro_rules! overflow_assert {
> > > +    ($cond:expr) => {
> > > +        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
> > > +            ::core::assert!(
> > > +                $cond,
> > > +                concat!("overflow assertion failed: ", stringify!($cond))
> >
> > Can we still allow the caller to pass additional arguments to the
> > macro, so that the overflowing value can be emitted? Alternatively if
> > the expectation is that this macro is always used with a comparison
> > operator perhaps we could have `overflow_assert_lt` and
> > `overflow_assert_le` which provide panic messages containing the
> > operand values?
> >
>
> Me and Miguel discussed the `overflow_assert_le` and other variants in
> my previous v2 patch set[1]. We decided it would be best to just start
> with a more flexable general expression based variant of the macro for
> now, and consider other variants later.
>
> I agree we should expand this into more specific variants, so it would
> document the intent of the assertions even more clearly.
>
> [1] Link to Miguel's comment on a `overflow_assert_le` variant:
> https://lore.kernel.org/all/CANiq72mvu54B=U+YCUmbFctj_wXgF5zjeE-BB-vHVnAP+3mPcQ@mail.gmail.com/

Ack, thanks for that. Still, I think the "any expression" version
should allow the caller to supply a custom message.

Re: [PATCH v3 1/2] rust: kernel: create `overflow_assert!` macro

[Miguel Ojeda]

On Mon, Jun 23, 2025 at 12:54 AM Tamir Duberstein <tamird@gmail.com> wrote:
>
> Ack, thanks for that. Still, I think the "any expression" version
> should allow the caller to supply a custom message.

Agreed, we should add that, like we did for `static_assert!` recently.

Cheers,
Miguel