[PATCH v6 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.

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

diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 9512af7156df..3a562b517952 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -101,6 +101,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..e3e822edda73
--- /dev/null
+++ b/rust/kernel/overflow_assert.rs
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Overflow assertion.
+
+/// Asserts that a boolean expression is `true` at runtime if
+/// `CONFIG_RUST_OVERFLOW_CHECKS` is enabled.
+///
+/// This will invoke the [`panic!`] macro if the provided
+/// expression cannot be evaluated to `true` at runtime.
+///
+/// This assertion is intended only for extra validation within
+/// builds and environments where panics are acceptable. **Do not
+/// rely on `overflow_assert!` for checks that must *always* execute**
+/// (e.g. to prevent undefined behavior, perform access checks, etc).
+///
+/// # Examples
+///
+/// Basic boolean condition:
+///
+/// ```
+/// let a: u32 = 10;
+/// let b: u32 = 5;
+/// overflow_assert!(a >= b);
+/// ```
+///
+/// A guard before doing a size computation that could overflow:
+///
+/// ```
+/// fn reserve_for_concat(curr: usize, to_add: usize, cap: usize) {
+///     // If enabled, these will catch overflow errors early:
+///     overflow_assert!(curr <= cap, "curr={} > cap={}", curr, cap);
+///     overflow_assert!(to_add <= cap - curr, "would exceed cap: {}+{} > {}", curr, to_add, cap);
+///     // ... then proceed to grow/append
+/// }
+/// ```
+#[macro_export]
+macro_rules! overflow_assert {
+    ($($arg:tt)*) => {
+        if cfg!(CONFIG_RUST_OVERFLOW_CHECKS) {
+            ::core::assert!($($arg)*);
+        }
+    };
+}
-- 
2.54.0