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

[PATCH v4 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 v4:
- Added the ability for callers to supply a custom message to the
  overflow assertion.
- Small change to verbage in documentation. 
- Link to v3: https://lore.kernel.org/all/20250621230231.100181-1-contact@antoniohickey.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>
Cc: Tamir Duberstein <tamird@gmail.com>

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 | 32 ++++++++++++++++++++++++++++++++
 rust/kernel/uaccess.rs         |  4 ++--
 3 files changed, 35 insertions(+), 2 deletions(-)
 create mode 100644 rust/kernel/overflow_assert.rs

-- 
2.50.0

[PATCH v4 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 | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 33 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..5164339813cb
--- /dev/null
+++ b/rust/kernel/overflow_assert.rs
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Overflow assertion.
+
+/// 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 MAX: i32 = 42;
+/// const fn f(x: i32) -> i32 {
+///     x + 1
+/// }
+/// overflow_assert!(f(40) < MAX);
+/// overflow_assert!(f(40) < MAX, "f(x) must not overflow the max value.");
+/// ```
+#[macro_export]
+macro_rules! overflow_assert {
+    ($cond:expr $(,$arg:literal)?) => {
+        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
+            ::core::assert!($cond $(,$arg)?);
+        }
+    };
+}
-- 
2.50.0

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

[Tamir Duberstein]

On Sat, Jun 28, 2025 at 10:43 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 | 32 ++++++++++++++++++++++++++++++++
>  2 files changed, 33 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..5164339813cb
> --- /dev/null
> +++ b/rust/kernel/overflow_assert.rs
> @@ -0,0 +1,32 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Overflow assertion.
> +
> +/// Verifies at runtime that an expression is within an expected bound.

This is a strange comment, imo. The only thing special about this
macro relative to a plain `assert` is that it disabled when
CONFIG_RUST_OVERFLOW_CHECKS=n.

> +///
> +/// 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 MAX: i32 = 42;
> +/// const fn f(x: i32) -> i32 {
> +///     x + 1
> +/// }
> +/// overflow_assert!(f(40) < MAX);
> +/// overflow_assert!(f(40) < MAX, "f(x) must not overflow the max value.");
> +/// ```
> +#[macro_export]
> +macro_rules! overflow_assert {
> +    ($cond:expr $(,$arg:literal)?) => {
> +        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
> +            ::core::assert!($cond $(,$arg)?);
> +        }
> +    };
> +}
> --
> 2.50.0
>
>
>

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

[Antonio Hickey]

Tamir Duberstein wrote:
> On Sat, Jun 28, 2025 at 10:43 PM Antonio Hickey
> <contact@antoniohickey.com> wrote:
> > +//! Overflow assertion.
> > +
> > +/// Verifies at runtime that an expression is within an expected bound.
> 
> This is a strange comment, imo. The only thing special about this
> macro relative to a plain `assert` is that it disabled when
> CONFIG_RUST_OVERFLOW_CHECKS=n.

Special yes, but it also documents the intent of the `assert`.
I did include a comment about the conditional behaviour with 
CONFIG_RUST_OVERFLOW_CHECKS being enabled/disabled. 

I'm open to rewording this doc comment to be better though. 
I should also add information about the optional panic message 
like the `static_assert` does as well, what about something like:

```
/// Overflow assertion.
///
/// Runtime assertion that an expression is within an expected bounds.
///
/// This macro is only enabled when `CONFIG_RUST_OVERFLOW_CHECKS` is true.
///
/// An optional panic message can be supplied after the expression.
/// Currently only a string literal without formatting is supported
/// due to constness limitations of the [`assert!`] macro.
```

Thanks

> 
> > +///
> > +/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.

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

[Tamir Duberstein]

On Sun, Jul 20, 2025 at 12:17 PM Antonio Hickey
<contact@antoniohickey.com> wrote:
>
> Tamir Duberstein wrote:
> > On Sat, Jun 28, 2025 at 10:43 PM Antonio Hickey
> > <contact@antoniohickey.com> wrote:
> > > +//! Overflow assertion.
> > > +
> > > +/// Verifies at runtime that an expression is within an expected bound.
> >
> > This is a strange comment, imo. The only thing special about this
> > macro relative to a plain `assert` is that it disabled when
> > CONFIG_RUST_OVERFLOW_CHECKS=n.
>
> Special yes, but it also documents the intent of the `assert`.
> I did include a comment about the conditional behaviour with
> CONFIG_RUST_OVERFLOW_CHECKS being enabled/disabled.
>
> I'm open to rewording this doc comment to be better though.
> I should also add information about the optional panic message
> like the `static_assert` does as well, what about something like:
>
> ```
> /// Overflow assertion.
> ///
> /// Runtime assertion that an expression is within an expected bounds.

I still disprefer this phrasing because there's nothing stopping
someone from writing

overflow_assert!(sky_is_blue());

In other words the type of the expression is bool while the comment
implies that the type of the expression is numeric.

> ///
> /// This macro is only enabled when `CONFIG_RUST_OVERFLOW_CHECKS` is true.
> ///
> /// An optional panic message can be supplied after the expression.
> /// Currently only a string literal without formatting is supported
> /// due to constness limitations of the [`assert!`] macro.

I don't think this is correct; in a non-const context you could use
formatting with this macro, no? IMO the doc comment on `debug_assert`
is good to use as a guide here.

https://doc.rust-lang.org/stable/std/macro.debug_assert.html

Consider also using the same implementation as that macro; there's no
need to separate `cond` from the other arguments.

> ```
>
> Thanks
>
> >
> > > +///
> > > +/// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
>

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

[Miguel Ojeda]

Hi Antonio,

Since you are sending likely a new version, a couple quick comments...

On Sun, Jun 29, 2025 at 4:43 AM Antonio Hickey
<contact@antoniohickey.com> wrote:
>
> 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>

The usual order of the tags would be:

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

> /// This macro is only active when `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.

I would probably add another paragraph to clarify/warn that,
therefore, one can only use this macro to add extra checks for users
that don't mind panics in such a case, but that it cannot be relied
for things that need to be always tested for (to prevent UB, access
checks, etc.), similar to what the standard library says for
`debug_assert!` like Tamir mentions or the `WARN*()` docs in C.

> +/// # Examples
> +///
> +/// ```
> +/// overflow_assert!(3 <= 10);
> +/// overflow_assert!(5 <= 5);
> +///
> +/// const X: u8 = 5;
> +/// overflow_assert!(X + 3 < 10);
> +///
> +/// const MAX: i32 = 42;
> +/// const fn f(x: i32) -> i32 {
> +///     x + 1
> +/// }
> +/// overflow_assert!(f(40) < MAX);
> +/// overflow_assert!(f(40) < MAX, "f(x) must not overflow the max value.");
> +/// ```

Since now the macro takes just a `bool`, I would probably try to keep
two or so of these, and I would add a couple comments and try to have
a more "real life" example if possible.

Thanks!

Cheers,
Miguel

[PATCH v4 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 v4 2/2] rust: uaccess: refactor to use `overflow_assert!`

[Tamir Duberstein]

On Sat, Jun 28, 2025 at 10:44 PM Antonio Hickey
<contact@antoniohickey.com> wrote:
>
> 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>
> ---

Reviewed-by: Tamir Duberstein <tamird@gmail.com>

>  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 v4 2/2] rust: uaccess: refactor to use `overflow_assert!`

[Alice Ryhl]

On Sun, Jun 29, 2025 at 02:43:47AM +0000, Antonio Hickey wrote:
> 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>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>