Skip to contentSkip to conversation

rust: make `build_assert` module the home of related macros

PATCH Applied Gary Guo 4 participants 9 messages Jun 9 – Jun 13

Subsystems (15)
lore
Share & tools
lore

Gary Guo

author
#0 lore raw

PATCH v4 1/1 rust: make `build_assert` module the home of related macros

From: Gary Guo <[email protected]>

Given the macro scoping rules, all macros are rendered twice, in the module and in the top-level of kernel crate.

Add #[doc(no_inline)] to the prelude so it just shows up as re-export. Add #[doc(hidden)] to the macro definition and #[doc(inline)] to the re-export inside build_assert module so the top-level items are hidden.

---
This is the remaining unapplied patch from
https://lore.kernel.org/rust-for-linux/[email protected]/.

Changes:
- Rebased so it applies cleanly. (both on linux-next and rust-next)
- Picked up tags
- Updated commit message to reflect that my other patch "rust: doc: disable doc inlining for all prelude items" already reduce number of rendering times from 3 to 2.

---
 drivers/gpu/nova-core/bitfield.rs    |  4 ++--
 drivers/gpu/nova-core/num.rs         |  2 +-
 rust/kernel/build_assert.rs          | 19 ++++++++++++-------
 rust/kernel/io/register.rs           | 19 ++++++++++++-------
 rust/kernel/io/resource.rs           |  2 +-
 rust/kernel/ioctl.rs                 |  2 +-
 rust/kernel/net/phy/reg.rs           |  8 +++++---
 rust/kernel/num/bounded.rs           |  2 +-
 rust/kernel/prelude.rs               | 12 ++++++++----
 rust/kernel/sync/atomic/internal.rs  |  9 ++++++---
 rust/kernel/sync/atomic/predefine.rs |  2 +-
 rust/kernel/sync/locked_by.rs        |  2 +-
 rust/kernel/sync/refcount.rs         |  8 +++++---
 rust/kernel/xarray.rs                | 10 ++++++++--
 14 files changed, 64 insertions(+), 37 deletions(-)
drivers/gpu/nova-core/bitfield.rs +2 -2
index 02efdcf78d89..660c3911402d 100644
@@ -170,7 +170,7 @@ impl $name {
     (@check_field_bounds $hi:tt:$lo:tt $field:ident as bool) => {
         #[allow(clippy::eq_op)]
         const _: () = {
-            ::kernel::build_assert!(
+            ::kernel::build_assert::build_assert!(
                 $hi == $lo,
                 concat!("boolean field `", stringify!($field), "` covers more than one bit")
             );
@@ -181,7 +181,7 @@ impl $name {
     (@check_field_bounds $hi:tt:$lo:tt $field:ident as $type:tt) => {
         #[allow(clippy::eq_op)]
         const _: () = {
-            ::kernel::build_assert!(
+            ::kernel::build_assert::build_assert!(
                 $hi >= $lo,
                 concat!("field `", stringify!($field), "`'s MSB is smaller than its LSB")
             );
drivers/gpu/nova-core/num.rs +1 -1
index 6c824b8d7b97..6eb174d136ab 100644
@@ -49,7 +49,7 @@ macro_rules! impl_safe_as {
             #[allow(unused)]
             #[inline(always)]
             pub(crate) const fn [<$from _as_ $into>](value: $from) -> $into {
-                kernel::static_assert!(size_of::<$into>() >= size_of::<$from>());
+                ::kernel::build_assert::static_assert!(size_of::<$into>() >= size_of::<$from>());
 
                 value as $into
             }
rust/kernel/build_assert.rs +12 -7
index 2ea2154ec30c..c3acb9b68a65 100644
@@ -61,15 +61,16 @@
 //! undefined symbols and linker errors, it is not developer friendly to debug, so it is recommended
 //! to avoid it and prefer other two assertions where possible.
 
+#[doc(inline)]
 pub use crate::{
-    build_assert,
+    build_assert_macro as build_assert,
     build_error,
     const_assert,
     static_assert, //
 };
 
 #[doc(hidden)]
-pub use build_error::build_error;
+pub use build_error::build_error as build_error_fn;
 
 /// Static assert (i.e. compile-time assert).
 ///
@@ -105,6 +106,7 @@
 /// static_assert!(f(40) == 42, "f(x) must add 2 to the given input.");
 /// ```
 #[macro_export]
+#[doc(hidden)]
 macro_rules! static_assert {
     ($condition:expr $(,$arg:literal)?) => {
         const _: () = ::core::assert!($condition $(,$arg)?);
@@ -133,6 +135,7 @@ macro_rules! static_assert {
 /// }
 /// ```
 #[macro_export]
+#[doc(hidden)]
 macro_rules! const_assert {
     ($condition:expr $(,$arg:literal)?) => {
         const { ::core::assert!($condition $(,$arg)?) };
@@ -157,12 +160,13 @@ macro_rules! const_assert {
 /// // foo(usize::MAX); // Fails to compile.
 /// ```
 #[macro_export]
+#[doc(hidden)]
 macro_rules! build_error {
     () => {{
-        $crate::build_assert::build_error("")
+        $crate::build_assert::build_error_fn("")
     }};
     ($msg:expr) => {{
-        $crate::build_assert::build_error($msg)
+        $crate::build_assert::build_error_fn($msg)
     }};
 }
 
@@ -200,15 +204,16 @@ macro_rules! build_error {
 /// const _: () = const_bar(2);
 /// ```
 #[macro_export]
-macro_rules! build_assert {
+#[doc(hidden)]
+macro_rules! build_assert_macro {
     ($cond:expr $(,)?) => {{
         if !$cond {
-            $crate::build_assert::build_error(concat!("assertion failed: ", stringify!($cond)));
+            $crate::build_assert::build_error_fn(concat!("assertion failed: ", stringify!($cond)));
         }
     }};
     ($cond:expr, $msg:expr) => {{
         if !$cond {
-            $crate::build_assert::build_error($msg);
+            $crate::build_assert::build_error_fn($msg);
         }
     }};
 }
rust/kernel/io/register.rs +12 -7
index 388647f28292..f924c7c7c1db 100644
@@ -108,9 +108,10 @@
 
 use core::marker::PhantomData;
 
-use crate::io::IoLoc;
-
-use kernel::build_assert;
+use crate::{
+    build_assert::build_assert,
+    io::IoLoc, //
+};
 
 /// Trait implemented by all registers.
 pub trait Register: Sized {
@@ -872,7 +873,7 @@ macro_rules! register {
         @reg $(#[$attr:meta])* $vis:vis $name:ident ($storage:ty)
             [ $size:expr, stride = $stride:expr ] @ $offset:literal { $($fields:tt)* }
     ) => {
-        ::kernel::static_assert!(::core::mem::size_of::<$storage>() <= $stride);
+        $crate::build_assert::static_assert!(::core::mem::size_of::<$storage>() <= $stride);
 
         $crate::register!(@bitfield $(#[$attr])* $vis struct $name($storage) { $($fields)* });
         $crate::register!(@io_base $name($storage) @ $offset);
@@ -895,7 +896,9 @@ macro_rules! register {
         @reg $(#[$attr:meta])* $vis:vis $name:ident ($storage:ty) => $alias:ident [ $idx:expr ]
             { $($fields:tt)* }
     ) => {
-        ::kernel::static_assert!($idx < <$alias as $crate::io::register::RegisterArray>::SIZE);
+        $crate::build_assert::static_assert!(
+            $idx < <$alias as $crate::io::register::RegisterArray>::SIZE
+        );
 
         $crate::register!(@bitfield $(#[$attr])* $vis struct $name($storage) { $($fields)* });
         $crate::register!(
@@ -912,7 +915,7 @@ macro_rules! register {
             [ $size:expr, stride = $stride:expr ]
             @ $base:ident + $offset:literal { $($fields:tt)* }
     ) => {
-        ::kernel::static_assert!(::core::mem::size_of::<$storage>() <= $stride);
+        $crate::build_assert::static_assert!(::core::mem::size_of::<$storage>() <= $stride);
 
         $crate::register!(@bitfield $(#[$attr])* $vis struct $name($storage) { $($fields)* });
         $crate::register!(@io_base $name($storage) @ $offset);
@@ -938,7 +941,9 @@ macro_rules! register {
         @reg $(#[$attr:meta])* $vis:vis $name:ident ($storage:ty)
             => $base:ident + $alias:ident [ $idx:expr ] { $($fields:tt)* }
     ) => {
-        ::kernel::static_assert!($idx < <$alias as $crate::io::register::RegisterArray>::SIZE);
+        $crate::build_assert::static_assert!(
+            $idx < <$alias as $crate::io::register::RegisterArray>::SIZE
+        );
 
         $crate::register!(@bitfield $(#[$attr])* $vis struct $name($storage) { $($fields)* });
         $crate::register!(
rust/kernel/io/resource.rs +1 -1
index b7ac9faf141d..17b0c174cfc5 100644
@@ -229,7 +229,7 @@ impl Flags {
     // Always inline to optimize out error path of `build_assert`.
     #[inline(always)]
     const fn new(value: u32) -> Self {
-        crate::build_assert!(value as u64 <= c_ulong::MAX as u64);
+        build_assert!(value as u64 <= c_ulong::MAX as u64);
         Flags(value as c_ulong)
     }
 }
rust/kernel/ioctl.rs +1 -1
index 2fc7662339e5..5bb5b48cf949 100644
@@ -6,7 +6,7 @@
 
 #![expect(non_snake_case)]
 
-use crate::build_assert;
+use crate::build_assert::build_assert;
 
 /// Build an ioctl number, analogous to the C macro of the same name.
 #[inline(always)]
rust/kernel/net/phy/reg.rs +5 -3
index a7db0064cb7d..80e22c264ea8 100644
@@ -9,9 +9,11 @@
 //! defined in IEEE 802.3.
 
 use super::Device;
-use crate::build_assert;
-use crate::error::*;
-use crate::uapi;
+use crate::{
+    build_assert::build_assert,
+    error::*,
+    uapi, //
+};
 
 mod private {
     /// Marker that a trait cannot be implemented outside of this crate
rust/kernel/num/bounded.rs +1 -1
index f9f90d6ec482..dafe77782d79 100644
@@ -364,7 +364,7 @@ pub fn try_new(value: T) -> Option<Self> {
     // Always inline to optimize out error path of `build_assert`.
     #[inline(always)]
     pub fn from_expr(expr: T) -> Self {
-        crate::build_assert!(
+        crate::build_assert::build_assert!(
             fits_within(expr, N),
             "Requested value larger than maximal representable value."
         );
rust/kernel/prelude.rs +8 -4
index ca260cc3937a..f6e852638ade 100644
@@ -79,9 +79,6 @@
         VVec,
         Vec, //
     },
-    build_assert,
-    build_error,
-    const_assert,
     current,
     dev_alert,
     dev_crit,
@@ -105,7 +102,6 @@
     pr_info,
     pr_notice,
     pr_warn,
-    static_assert,
     str::CStrExt as _,
     try_init,
     try_pin_init,
@@ -113,6 +109,14 @@
     ThisModule, //
 };
 
+#[doc(no_inline)]
+pub use crate::build_assert::{
+    build_assert,
+    build_error,
+    const_assert,
+    static_assert, //
+};
+
 // `super::std_vendor` is hidden, which makes the macro inline for some reason.
 #[doc(no_inline)]
 pub use super::dbg;
rust/kernel/sync/atomic/internal.rs +6 -3
index ad810c2172ec..9c8a7a203abd 100644
@@ -4,8 +4,11 @@
 //!
 //! Provides 1:1 mapping to the C atomic operations.
 
-use crate::bindings;
-use crate::macros::paste;
+use crate::{
+    bindings,
+    build_assert::static_assert,
+    macros::paste, //
+};
 use core::cell::UnsafeCell;
 use ffi::c_void;
 
@@ -46,7 +49,7 @@ pub trait AtomicImpl: Sized + Copy + private::Sealed {
 // In the future when a CONFIG_ARCH_SUPPORTS_ATOMIC_RMW=n architecture plans to support Rust, the
 // load/store helpers that guarantee atomicity against RmW operations (usually via a lock) need to
 // be added.
-crate::static_assert!(
+static_assert!(
     cfg!(CONFIG_ARCH_SUPPORTS_ATOMIC_RMW),
     "The current implementation of atomic i8/i16/ptr relies on the architecure being \
     ARCH_SUPPORTS_ATOMIC_RMW"
rust/kernel/sync/atomic/predefine.rs +1 -1
index 7468153429e1..adc5fa126487 100644
@@ -2,7 +2,7 @@
 
 //! Pre-defined atomic types
 
-use crate::static_assert;
+use crate::prelude::*;
 use core::mem::{align_of, size_of};
 use ffi::c_void;
 
rust/kernel/sync/locked_by.rs +1 -1
index 61f100a45b35..fb4a1430b3b4 100644
@@ -3,7 +3,7 @@
 //! A wrapper for data protected by a lock that does not wrap it.
 
 use super::{lock::Backend, lock::Lock};
-use crate::build_assert;
+use crate::build_assert::build_assert;
 use core::{cell::UnsafeCell, mem::size_of, ptr};
 
 /// Allows access to some data to be serialised by a lock that does not wrap it.
rust/kernel/sync/refcount.rs +5 -3
index 6c7ae8b05a0b..23a5d201f343 100644
@@ -4,9 +4,11 @@
 //!
 //! C header: [`include/linux/refcount.h`](srctree/include/linux/refcount.h)
 
-use crate::build_assert;
-use crate::sync::atomic::Atomic;
-use crate::types::Opaque;
+use crate::{
+    build_assert::build_assert,
+    sync::atomic::Atomic,
+    types::Opaque, //
+};
 
 /// Atomic reference counter.
 ///
rust/kernel/xarray.rs +8 -2
index 46e5f43223fe..987c9c0c2198 100644
@@ -5,10 +5,16 @@
 //! C header: [`include/linux/xarray.h`](srctree/include/linux/xarray.h)
 
 use crate::{
-    alloc, bindings, build_assert,
+    alloc,
+    bindings,
+    build_assert::build_assert,
     error::{Error, Result},
     ffi::c_void,
-    types::{ForeignOwnable, NotThreadSafe, Opaque},
+    types::{
+        ForeignOwnable,
+        NotThreadSafe,
+        Opaque, //
+    }, //
 };
 use core::{iter, marker::PhantomData, pin::Pin, ptr::NonNull};
 use pin_init::{pin_data, pin_init, pinned_drop, PinInit};

base-commit: 98cc68794c003bc76fc9da2e8a075e947eee5921

Signature · 1 line
2.54.0
#1 lore raw
Quoted 3 lines · Gary Guo

This is the remaining unapplied patch from
https://lore.kernel.org/rust-for-linux/[email protected]/.

Thanks for rebasing! I had it as "Waiting for apply" in the spreadsheet, but this saved me a bit of work.

Quick question below about the prelude...

rust/kernel/prelude.rs line 118

Quoted 7 lines
rust/kernel/prelude.rs +7 -0
+#[doc(no_inline)]
+pub use crate::build_assert::{
+    build_assert,
+    build_error,
+    const_assert,
+    static_assert, //
+};

Did you split this for some reason? I moved the file to a single group per crate when I moved the file to the new formatting style, so I was wondering if we could keep it non-split. I mean, it may be nicer for macros since it allows us to group them, but I hope we don't end up with many uses again if we go down that road again...

Or perhaps you did it for the attribute, i.e. it may behave differently, but I doubt that is the case? i.e. if no_inline somehow behaves differently this way.

Quoted 1 line

rust/kernel/sync/atomic/predefine.rs

In this one you used the prelude, but in the others not -- which is fine, we should be using the prelude more (though perhaps it is a separate change), but I wonder if there was a reason.

Thanks!

Cheers,
Miguel

maintainer
#2 lore raw
Quoted 10 lines · Miguel Ojeda
Quoted 3 lines · Gary Guo

This is the remaining unapplied patch from
https://lore.kernel.org/rust-for-linux/[email protected]/.

Thanks for rebasing! I had it as "Waiting for apply" in the spreadsheet, but this saved me a bit of work.

Quick question below about the prelude...

Quoted 13 lines

rust/kernel/prelude.rs line 118

Quoted 7 lines
rust/kernel/prelude.rs +7 -0
+#[doc(no_inline)]
+pub use crate::build_assert::{
+    build_assert,
+    build_error,
+    const_assert,
+    static_assert, //
+};

Did you split this for some reason? I moved the file to a single group per crate when I moved the file to the new formatting style, so I was wondering if we could keep it non-split. I mean, it may be nicer for macros since it allows us to group them, but I hope we don't end up with many uses again if we go down that road again...

I think I just kept it as is when rebasing. It's file to have them grouped in the crate to.

Quoted 10 lines

Or perhaps you did it for the attribute, i.e. it may behave differently, but I doubt that is the case? i.e. if no_inline somehow behaves differently this way.

Quoted 1 line

rust/kernel/sync/atomic/predefine.rs

In this one you used the prelude, but in the others not -- which is fine, we should be using the prelude more (though perhaps it is a separate change), but I wonder if there was a reason.

This one is using size_of, align_of, c_void which are all in prelude. However it looks like I forgot to actually remove these imports in the last version, and I didn't change it during rebase.

Are you okay with fixing during applying, or do you want me to send a new version?

Best,
Gary

maintainer
#3 lore raw
Quoted 3 lines · On Tue, 09 Jun 2026 19:19:42 +0100 Gary Guo <[email protected]> wrote:

I think I just kept it as is when rebasing. It's file to have them grouped in the crate to.

Thanks for confirming!

Quoted 3 lines

This one is using size_of, align_of, c_void which are all in prelude. However it looks like I forgot to actually remove these imports in the last version, and I didn't change it during rebase.

Ah, I see, makes sense.

Quoted 1 line

Are you okay with fixing during applying, or do you want me to send a new version?

I did it on my side. I also tweaked a couple more bits: they were already no_inline, and I noted that they sadly do not appear in the prelude anymore, but the change looks fine and that may be more of a rustdoc-side issue or design choice.

Cheers,
Miguel

maintainer
#4 lore raw
Quoted 11 lines · Miguel Ojeda
Quoted 3 lines · On Tue, 09 Jun 2026 19:19:42 +0100 Gary Guo <[email protected]> wrote:

I think I just kept it as is when rebasing. It's file to have them grouped in the crate to.

Thanks for confirming!

Quoted 3 lines

This one is using size_of, align_of, c_void which are all in prelude. However it looks like I forgot to actually remove these imports in the last version, and I didn't change it during rebase.

Quoted 8 lines

Ah, I see, makes sense.

Quoted 1 line

Are you okay with fixing during applying, or do you want me to send a new version?

I did it on my side. I also tweaked a couple more bits: they were already no_inline, and I noted that they sadly do not appear in the prelude anymore, but the change looks fine and that may be more of a rustdoc-side issue or design choice.

I think if the re-export is of form "use crate::build_assert::*" then it will still be the same semantics but would be appearing now?

Best,
Gary

#5 lore raw
Quoted 3 lines · Gary Guo

I think if the re-export is of form "use crate::build_assert::*" then it will still be the same semantics but would be appearing now?

If you mean a glob import (within or outside the existing use -- same behavior), then that makes the glob import appear in the list at least, which is an improvement because at least people have a link to the module (i.e. but not the individual ones).

Or do you mean something else?

Good first issue?

Cheers,
Miguel

maintainer
#6 lore raw
Quoted 9 lines · Miguel Ojeda
Quoted 3 lines · Gary Guo

I think if the re-export is of form "use crate::build_assert::*" then it will still be the same semantics but would be appearing now?

If you mean a glob import (within or outside the existing use -- same behavior), then that makes the glob import appear in the list at least, which is an improvement because at least people have a link to the module (i.e. but not the individual ones).

Yes, I meant this. All items of build_assert! are in the prelude so this is no change of behaviour anyway.

Quoted 4 lines

Or do you mean something else?

Good first issue?

Agreed.

Best,
Gary

Applied
#8 lore raw
In reply to Gary Guo
Quoted 10 lines · Gary Guo

From: Gary Guo <[email protected]>

Given the macro scoping rules, all macros are rendered twice, in the module and in the top-level of kernel crate.

Add #[doc(no_inline)] to the prelude so it just shows up as re-export. Add #[doc(hidden)] to the macro definition and #[doc(inline)] to the re-export inside build_assert module so the top-level items are hidden.

Quoted 6 lines

Applied to rust-next -- thanks everyone!

[ Sadly, because the definition is hidden, rustdoc decides to not list
them as re-exports in the prelude page anymore, even if we refer to the not-actually-hidden item.

- Miguel ]

[ Kept a single declaration in the prelude, and reworded since they
already had no_inline. Removed other imports from predefine since we now use the prelude. - Miguel ]

Cheers,
Miguel