Skip to contentSkip to conversation

rust: add `#[macro_export_scoped]` for scoped declarative macro

PATCH In review Gary Guo 2 participants 6 messages Aug 11 – Aug 12

Subsystems (7)
lore
Share & tools
lore

Gary Guo

author maintainer
#0 lore raw

cover rust: add `#[macro_export_scoped]` for scoped declarative macro

Rust's declarative macro scoping rule is confusing because it was historically purely textual scoped and the path-based scoping is added as an afterthought.

#[macro_export] will make the macro available for use outside the crate, but it also adds the macro to the root of crate. This has the issue where it prevents us from cleanly put things in modules where they belong. Macro 2.0 is supposed to address this issue, but currently it seems that we are unlikely to get macro 2.0 any time soon.

There is a way to approximate the scoping -- hide the macro from the crate root using #[doc(hidden)], and then re-export the macro from where they are supposed to appear, and undo the #[doc(hidden)] with #[doc(inline)]. We have used this approach for a few macros already. This is not fully bullet-proof; users can still reference the items from crate root, as it is hidden from documentation but is still present in name resolution.

Introduce a macro #[macro_export_scoped], that implements the above trick, so people can create new properly-scoped macros easily. Also, adopt a solution where we assign the macros non-guessable names, and then just re-export them under intended name. This removes the possibility of using the macro from incorrect path unintentionally.

---
Gary Guo (4):
rust: macros: add #[macro_export_scoped]
rust: build_assert: remove macro from crate root
rust: list: convert to use #[macro_export_scoped]
rust: io: convert to use #[macro_export_scoped]

 rust/kernel/build_assert.rs            | 24 +++++----------
 rust/kernel/configfs.rs                |  4 +--
 rust/kernel/firmware.rs                |  4 +--
 rust/kernel/io.rs                      | 27 +++++++----------
 rust/kernel/list/arc.rs                |  4 +--
 rust/kernel/list/arc_field.rs          |  4 +--
 rust/kernel/list/impl_list_item_mod.rs | 14 ++++-----
 rust/kernel/ptr.rs                     |  6 +---
 rust/kernel/sync/atomic.rs             |  2 +-
 rust/macros/lib.rs                     | 25 ++++++++++++++++
 rust/macros/macro_export_scoped.rs     | 53 ++++++++++++++++++++++++++++++++++
 11 files changed, 108 insertions(+), 59 deletions(-)

---
base-commit: 6b8c8af514d739d0335f5579b585e02babe8a727
change-id: 20260811-macro_export_scoped-5ce38b5db968

Best regards,

Signature · 1 line
Gary Guo <[email protected]>
author maintainer
#1 lore raw

PATCH 1/4 rust: macros: add `#[macro_export_scoped]`

Due to Rust macro scoping rules, macros that are exported with #[macro_export_scoped] gets added to the crate root, and this causes the crate root to get crowded with various macros.

We used a trick of #[doc(hidden)] + #[doc(inline)] pub use to make these macros to appear to be only defined in the documentation, but this does not actually prevent them from being referenced from crate root.

Create a macro #[macro_export_scoped], that automates these definition and re-export and also give these macro unique and non-guessable names.

---
 rust/macros/lib.rs                 | 25 ++++++++++++++++++
 rust/macros/macro_export_scoped.rs | 53 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
rust/macros/lib.rs +25 -0
index 0514fc7c0a55..6f8ef9043255 100644
@@ -20,6 +20,7 @@
 mod for_lt;
 mod helpers;
 mod kunit;
+mod macro_export_scoped;
 mod module;
 mod paste;
 mod vtable;
@@ -320,6 +321,30 @@ pub fn concat_idents(input: TokenStream) -> TokenStream {
     concat_idents::concat_idents(parse_macro_input!(input)).into()
 }
 
+/// Export a macro publicly, but from the current module instead of crate root.
+///
+/// # Examples
+///
+/// ```
+/// mod foo {
+///     #[kernel::macros::macro_export_scoped]
+///     macro_rules! my_macro {
+///         () => {}
+///     }
+/// }
+///
+/// foo::my_macro!();
+/// ```
+#[doc(hidden)]
+#[proc_macro_attribute]
+#[allow(non_snake_case)]
+pub fn macro_export_scoped(attr: TokenStream, input: TokenStream) -> TokenStream {
+    parse_macro_input!(attr as syn::parse::Nothing);
+    macro_export_scoped::macro_export_scoped(parse_macro_input!(input))
+        .unwrap_or_else(|e| e.into_compile_error())
+        .into()
+}
+
 /// Paste identifiers together.
 ///
 /// Within the `paste!` macro, identifiers inside `[<` and `>]` are concatenated together to form a
rust/macros/macro_export_scoped.rs new file +53 -0

53 lines not on this page · raw message

Signature · 1 line
2.54.0
author maintainer
#2 lore raw

PATCH 2/4 rust: build_assert: remove macro from crate root

In reply to Gary Guo

Convert build_assert to use #[macro_export_scoped]. This removes the macros from crate root of kernel. A few remaining mentions of the macros from crate root are removed.

---
 rust/kernel/build_assert.rs | 24 +++++++-----------------
 rust/kernel/configfs.rs     |  4 ++--
 rust/kernel/firmware.rs     |  4 ++--
 rust/kernel/ptr.rs          |  6 +-----
 rust/kernel/sync/atomic.rs  |  2 +-
 5 files changed, 13 insertions(+), 27 deletions(-)
rust/kernel/build_assert.rs +7 -17
index c3acb9b68a65..4774c7fb6976 100644
@@ -61,17 +61,11 @@
 //! 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_macro as build_assert,
-    build_error,
-    const_assert,
-    static_assert, //
-};
-
 #[doc(hidden)]
 pub use build_error::build_error as build_error_fn;
 
+use macros::macro_export_scoped;
+
 /// Static assert (i.e. compile-time assert).
 ///
 /// Similar to C11 [`_Static_assert`] and C++11 [`static_assert`].
@@ -105,8 +99,7 @@
 /// static_assert!(f(40) == 42);
 /// static_assert!(f(40) == 42, "f(x) must add 2 to the given input.");
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! static_assert {
     ($condition:expr $(,$arg:literal)?) => {
         const _: () = ::core::assert!($condition $(,$arg)?);
@@ -134,8 +127,7 @@ macro_rules! static_assert {
 ///     const_assert!(size_of::<T>() > 0, "T cannot be ZST");
 /// }
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! const_assert {
     ($condition:expr $(,$arg:literal)?) => {
         const { ::core::assert!($condition $(,$arg)?) };
@@ -159,8 +151,7 @@ macro_rules! const_assert {
 /// assert_eq!(foo(usize::MAX - 1), usize::MAX); // OK.
 /// // foo(usize::MAX); // Fails to compile.
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! build_error {
     () => {{
         $crate::build_assert::build_error_fn("")
@@ -203,9 +194,8 @@ macro_rules! build_error {
 ///
 /// const _: () = const_bar(2);
 /// ```
-#[macro_export]
-#[doc(hidden)]
-macro_rules! build_assert_macro {
+#[macros::macro_export_scoped]
+macro_rules! build_assert {
     ($cond:expr $(,)?) => {{
         if !$cond {
             $crate::build_assert::build_error_fn(concat!("assertion failed: ", stringify!($cond)));
rust/kernel/configfs.rs +2 -2
index 2339c6467325..8660ce01d97f 100644
@@ -511,7 +511,7 @@ pub trait GroupOperations {
     /// NOTE: "drop" in the name of this function is not related to the Rust drop term. Rather, the
     /// name is inherited from the callback name in the underlying C code.
     fn drop_item(&self, _child: ArcBorrow<'_, Group<Self::Child>>) {
-        kernel::build_error!(kernel::error::VTABLE_DEFAULT_ERROR)
+        build_error!(kernel::error::VTABLE_DEFAULT_ERROR)
     }
 }
 
@@ -660,7 +660,7 @@ pub trait AttributeOperations<const ID: u64 = 0> {
     /// Implementations should parse the value from `page` and update internal
     /// state to reflect the parsed value.
     fn store(_data: &Self::Data, _page: &[u8]) -> Result {
-        kernel::build_error!(kernel::error::VTABLE_DEFAULT_ERROR)
+        build_error!(kernel::error::VTABLE_DEFAULT_ERROR)
     }
 }
 
rust/kernel/firmware.rs +2 -2
index a18f8b84f3e3..1abc66b84ef2 100644
@@ -325,7 +325,7 @@ const fn push_internal(mut self, bytes: &[u8]) -> Self {
     pub const fn push(self, s: &str) -> Self {
         // Check whether there has been an initial call to `next_entry()`.
         if N != 0 && self.n == 0 {
-            crate::build_error!("Must call next_entry() before push().");
+            build_error!("Must call next_entry() before push().");
         }
 
         self.push_internal(s.as_bytes())
@@ -369,7 +369,7 @@ pub const fn new_entry(self) -> Self {
         if this.n == N {
             this.buf
         } else {
-            crate::build_error!("Length mismatch.");
+            build_error!("Length mismatch.");
         }
     }
 }
rust/kernel/ptr.rs +1 -5
index 82acb531b17b..b6fb802c2e21 100644
@@ -5,13 +5,9 @@
 pub mod projection;
 pub use crate::project_pointer as project;
 
-use core::mem::{
-    align_of,
-    size_of, //
-};
 use core::num::NonZero;
 
-use crate::const_assert;
+use crate::prelude::*;
 
 /// Type representing an alignment, which is always a power of two.
 ///
rust/kernel/sync/atomic.rs +1 -1
index 9cd009d57e35..c62cb46798ff 100644
@@ -25,7 +25,7 @@
 
 pub(crate) use internal::{AtomicArithmeticOps, AtomicBasicOps, AtomicExchangeOps};
 
-use crate::build_error;
+use crate::build_assert::build_error;
 use internal::AtomicRepr;
 use ordering::OrderingType;
 
Signature · 1 line
2.54.0
maintainer Acked-by on v1 2/4
#3 lore raw

Re: [PATCH 2/4] rust: build_assert: remove macro from crate root

Quoted 5 lines · Gary Guo

Convert build_assert to use #[macro_export_scoped]. This removes the macros from crate root of kernel. A few remaining mentions of the macros from crate root are removed.

Best regards,
Andreas Hindborg

author maintainer
#4 lore raw

PATCH 3/4 rust: list: convert to use `#[macro_export_scoped]`

In reply to Gary Guo

Convert list macros that use #[macro_export] + #[doc(hidden)] trick to use the #[macro_export_scoped] macro.

---
 rust/kernel/list/arc.rs                |  4 +---
 rust/kernel/list/arc_field.rs          |  4 +---
 rust/kernel/list/impl_list_item_mod.rs | 14 +++++---------
 3 files changed, 7 insertions(+), 15 deletions(-)
rust/kernel/list/arc.rs +1 -3
index 209b1173c826..9bb6d2e8104d 100644
@@ -81,8 +81,7 @@ pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
 /// The `tracked_by` strategy is usually used by deferring to a field of type
 /// [`AtomicTracker`]. However, it is also possible to defer the tracking to another struct
 /// using also using this macro.
-#[macro_export]
-#[doc(hidden)]
+#[macros::macro_export_scoped]
 macro_rules! impl_list_arc_safe {
     (impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
         impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
@@ -127,7 +126,6 @@ fn try_new_list_arc(&self) -> bool {
 
     () => {};
 }
-pub use impl_list_arc_safe;
 
 /// A wrapper around [`Arc`] that's guaranteed unique for the given id.
 ///
rust/kernel/list/arc_field.rs +1 -3
index 2ad8aea55993..b59e61e90fe1 100644
@@ -65,8 +65,7 @@ pub unsafe fn assert_mut(&self) -> &mut T {
 }
 
 /// Defines getters for a [`ListArcField`].
-#[macro_export]
-#[doc(hidden)]
+#[macros::macro_export_scoped]
 macro_rules! define_list_arc_field_getter {
     ($pub:vis fn $name:ident(&self $(<$id:tt>)?) -> &$typ:ty { $field:ident }
      $($rest:tt)*
@@ -94,4 +93,3 @@ macro_rules! define_list_arc_field_getter {
 
     () => {};
 }
-pub use define_list_arc_field_getter;
rust/kernel/list/impl_list_item_mod.rs +5 -9
index 5a3eac9f3cf0..e3ec79089696 100644
@@ -4,6 +4,8 @@
 
 //! Helpers for implementing list traits safely.
 
+use macros::macro_export_scoped;
+
 /// Declares that this type has a [`ListLinks<ID>`] field.
 ///
 /// This trait is only used to help implement [`ListItem`] safely. If [`ListItem`] is implemented
@@ -28,8 +30,7 @@ pub unsafe trait HasListLinks<const ID: u64 = 0> {
 }
 
 /// Implements the [`HasListLinks`] trait for the given type.
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! impl_has_list_links {
     ($(impl$({$($generics:tt)*})?
        HasListLinks$(<$id:tt>)?
@@ -55,7 +56,6 @@ unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$
         }
     )*};
 }
-pub use impl_has_list_links;
 
 /// Declares that the [`ListLinks<ID>`] field in this struct is inside a
 /// [`ListLinksSelfPtr<T, ID>`].
@@ -74,8 +74,7 @@ pub unsafe trait HasSelfPtr<T: ?Sized, const ID: u64 = 0>
 }
 
 /// Implements the [`HasListLinks`] and [`HasSelfPtr`] traits for the given type.
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! impl_has_list_links_self_ptr {
     ($(impl$({$($generics:tt)*})?
        HasSelfPtr<$item_type:ty $(, $id:tt)?>
@@ -98,7 +97,6 @@ unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$
         }
     )*};
 }
-pub use impl_has_list_links_self_ptr;
 
 /// Implements the [`ListItem`] trait for the given type.
 ///
@@ -182,8 +180,7 @@ unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$
 ///     }
 /// }
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! impl_list_item {
     (
         $(impl$({$($generics:tt)*})? ListItem<$num:tt> for $self:ty {
@@ -358,4 +355,3 @@ unsafe fn post_remove(me: *mut $crate::list::ListLinks<$num>) -> *const Self {
         }
     )*};
 }
-pub use impl_list_item;
Signature · 1 line
2.54.0
author maintainer
#5 lore raw

PATCH 4/4 rust: io: convert to use `#[macro_export_scoped]`

In reply to Gary Guo

Convert I/O macros that use #[macro_export] + #[doc(hidden)] trick to use the #[macro_export_scoped] macro.

---
 rust/kernel/io.rs | 27 ++++++++++-----------------
 1 file changed, 10 insertions(+), 17 deletions(-)
rust/kernel/io.rs +10 -17
index 5ce9fd129068..891a27fe59b6 100644
@@ -9,6 +9,8 @@
     mem::MaybeUninit, //
 };
 
+use macros::macro_export_scoped;
+
 use crate::{
     bindings,
     prelude::*,
@@ -1673,8 +1675,7 @@ pub unsafe fn project_view<U: ?Sized + KnownSize>(
 /// let nested: Mmio<'_, u32> = io_project!(whole, .field);
 /// # Ok::<(), Error>(()) }
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! io_project {
     ($io:expr, $($proj:tt)*) => {{
         #[allow(unused)]
@@ -1688,8 +1689,6 @@ macro_rules! io_project {
         unsafe { view.project_view(ptr) }
     }};
 }
-#[doc(inline)]
-pub use crate::io_project;
 
 /// Read from I/O memory.
 ///
@@ -1707,15 +1706,12 @@ macro_rules! io_project {
 /// let field: u32 = kernel::io::io_read!(mmio, [try: 2].field);
 /// # Ok::<(), Error>(()) }
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! io_read {
     ($io:expr, $($proj:tt)*) => {
-        $crate::io::Io::read_val($crate::io_project!($io, $($proj)*))
+        $crate::io::Io::read_val($crate::io::io_project!($io, $($proj)*))
     };
 }
-#[doc(inline)]
-pub use crate::io_read;
 
 /// Writes to I/O memory.
 ///
@@ -1734,21 +1730,18 @@ macro_rules! io_read {
 /// kernel::io::io_write!(mmio, [try: 2].field, 10);
 /// # Ok::<(), Error>(()) }
 /// ```
-#[macro_export]
-#[doc(hidden)]
+#[macro_export_scoped]
 macro_rules! io_write {
     (@parse [$io:expr] [$($proj:tt)*] [, $val:expr]) => {
-        $crate::io::Io::write_val($crate::io_project!($io, $($proj)*), $val)
+        $crate::io::Io::write_val($crate::io::io_project!($io, $($proj)*), $val)
     };
     (@parse [$io:expr] [$($proj:tt)*] [.$field:tt $($rest:tt)*]) => {
-        $crate::io_write!(@parse [$io] [$($proj)* .$field] [$($rest)*])
+        $crate::io::io_write!(@parse [$io] [$($proj)* .$field] [$($rest)*])
     };
     (@parse [$io:expr] [$($proj:tt)*] [[$flavor:ident: $index:expr] $($rest:tt)*]) => {
-        $crate::io_write!(@parse [$io] [$($proj)* [$flavor: $index]] [$($rest)*])
+        $crate::io::io_write!(@parse [$io] [$($proj)* [$flavor: $index]] [$($rest)*])
     };
     ($io:expr, $($rest:tt)*) => {
-        $crate::io_write!(@parse [$io] [] [$($rest)*])
+        $crate::io::io_write!(@parse [$io] [] [$($rest)*])
     };
 }
-#[doc(inline)]
-pub use crate::io_write;
Signature · 1 line
2.54.0