rust: make `build_assert` module the home of related macros
Subsystems (15)
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
@@ -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
@@ -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>()); valueas $into }
rust/kernel/build_assert.rs +12 -7
@@ -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_macroas build_assert, build_error, const_assert, static_assert,// };#[doc(hidden)] -pub use build_error::build_error; +pub use build_error::build_erroras 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
@@ -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] )* $visstruct $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 < <$aliasas $crate ::io::register::RegisterArray >::SIZE ); + $crate::build_assert::static_assert!( + $idx < <$aliasas $crate ::io::register::RegisterArray >::SIZE + ); $crate::register!(@bitfield $(#[$attr] )* $visstruct $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] )* $visstruct $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 < <$aliasas $crate ::io::register::RegisterArray >::SIZE ); + $crate::build_assert::static_assert!( + $idx < <$aliasas $crate ::io::register::RegisterArray >::SIZE + ); $crate::register!(@bitfield $(#[$attr] )* $visstruct $name($storage) { $($fields)* }); $crate::register!(
rust/kernel/io/resource.rs +1 -1
@@ -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!(valueas u64 <= c_ulong::MAX as u64 ); +build_assert! (valueas u64 <= c_ulong::MAX as u64 );Flags (valueas c_ulong ) } }
rust/kernel/ioctl.rs +1 -1
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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
Gary Guo
maintainerQuoted 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_inlinesomehow behaves differently this way.Quoted 1 line
rust/kernel/sync/atomic/predefine.rsIn 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
Miguel Ojeda
maintainerQuoted 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_voidwhich 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
Gary Guo
maintainerQuoted 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_voidwhich 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 arustdoc-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
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
Gary Guo
maintainerQuoted 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
Quoted 4 lines · Gary Guo
Quoted 2 lines
Good first issue?
Agreed.
For future reference:
https://github.com/Rust-for-Linux/linux/issues/1242
Cheers,
Miguel
Miguel Ojeda
AppliedQuoted 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 insidebuild_assertmodule so the top-level items are hidden.
Quoted 6 lines
Acked-by Danilo Krummrich <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Acked-by FUJITA Tomonori <[email protected]>Acked-by Boqun Feng <[email protected]>Signed-off-by Gary Guo <[email protected]>
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