Skip to contentSkip to conversation

rust: use the `build_error!` macro, not the hidden function

PATCH Applied Miguel Ojeda 3 participants 9 messages Nov 23, 2024 – Jan 10, 2025

Subsystems (6)
lore
Share & tools
lore

Miguel Ojeda

author maintainer
#0 lore raw

PATCH 1/3 rust: use the `build_error!` macro, not the hidden function

Code and some examples were using the function, rather than the macro. The macro is what is documented.

Thus move users to the macro.

---
 rust/kernel/block/mq/operations.rs |  2 +-
 rust/kernel/net/phy.rs             | 18 +++++++++---------
 rust/macros/lib.rs                 |  8 ++++----
 3 files changed, 14 insertions(+), 14 deletions(-)
rust/kernel/block/mq/operations.rs +1 -1
index c8646d0d9866..962f16a5a530 100644
@@ -35,7 +35,7 @@ pub trait Operations: Sized {
     /// Called by the kernel to poll the device for completed requests. Only
     /// used for poll queues.
     fn poll() -> bool {
-        crate::build_error(crate::error::VTABLE_DEFAULT_ERROR)
+        crate::build_error!(crate::error::VTABLE_DEFAULT_ERROR)
     }
 }
 
rust/kernel/net/phy.rs +9 -9
index beb62ec712c3..f488f6c55e9a 100644
@@ -587,17 +587,17 @@ pub trait Driver {
 
     /// Issues a PHY software reset.
     fn soft_reset(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Sets up device-specific structures during discovery.
     fn probe(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Probes the hardware to determine what abilities it has.
     fn get_features(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Returns true if this is a suitable driver for the given phydev.
@@ -609,32 +609,32 @@ fn match_phy_device(_dev: &Device) -> bool {
     /// Configures the advertisement and resets auto-negotiation
     /// if auto-negotiation is enabled.
     fn config_aneg(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Determines the negotiated speed and duplex.
     fn read_status(_dev: &mut Device) -> Result<u16> {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Suspends the hardware, saving state if needed.
     fn suspend(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Resumes the hardware, restoring state if needed.
     fn resume(_dev: &mut Device) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Overrides the default MMD read function for reading a MMD register.
     fn read_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16) -> Result<u16> {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Overrides the default MMD write function for writing a MMD register.
     fn write_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16, _val: u16) -> Result {
-        kernel::build_error(VTABLE_DEFAULT_ERROR)
+        kernel::build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Callback for notification of link change.
rust/macros/lib.rs +4 -4
index 4ab94e44adfe..1a30c8075ebd 100644
@@ -123,12 +123,12 @@ pub fn module(ts: TokenStream) -> TokenStream {
 /// used on the Rust side, it should not be possible to call the default
 /// implementation. This is done to ensure that we call the vtable methods
 /// through the C vtable, and not through the Rust vtable. Therefore, the
-/// default implementation should call `kernel::build_error`, which prevents
+/// default implementation should call `kernel::build_error!`, which prevents
 /// calls to this function at compile time:
 ///
 /// ```compile_fail
 /// # // Intentionally missing `use`s to simplify `rusttest`.
-/// kernel::build_error(VTABLE_DEFAULT_ERROR)
+/// kernel::build_error!(VTABLE_DEFAULT_ERROR)
 /// ```
 ///
 /// Note that you might need to import [`kernel::error::VTABLE_DEFAULT_ERROR`].
@@ -145,11 +145,11 @@ pub fn module(ts: TokenStream) -> TokenStream {
 /// #[vtable]
 /// pub trait Operations: Send + Sync + Sized {
 ///     fn foo(&self) -> Result<()> {
-///         kernel::build_error(VTABLE_DEFAULT_ERROR)
+///         kernel::build_error!(VTABLE_DEFAULT_ERROR)
 ///     }
 ///
 ///     fn bar(&self) -> Result<()> {
-///         kernel::build_error(VTABLE_DEFAULT_ERROR)
+///         kernel::build_error!(VTABLE_DEFAULT_ERROR)
 ///     }
 /// }
 ///

base-commit: b2603f8ac8217bc59f5c7f248ac248423b9b99cb

Signature · 1 line
2.47.0
author maintainer
#1 lore raw

PATCH 2/3 rust: kernel: move `build_error` hidden function to prevent mistakes

Users were using the hidden exported kernel::build_error function instead of the intended kernel::build_error! macro, e.g. see the previous commit.

To force to use the macro, move it into the build_assert module, thus making it a compilation error and avoiding a collision in the same "namespace". Using the function now would require typing the module name (which is hidden), not just a single character.

Now attempting to use the function will trigger this error with the right suggestion by the compiler:

      error[E0423]: expected function, found macro `kernel::build_error`
      --> samples/rust/rust_minimal.rs:29:9
         |
      29 |         kernel::build_error();
         |         ^^^^^^^^^^^^^^^^^^^ not a function
         |
      help: use `!` to invoke the macro
         |
      29 |         kernel::build_error!();
         |                            +

An alternative would be using an alias, but it would be more complex and moving it into the module seems right since it belongs there and reduces the amount of code at the crate root.

Keep the #[doc(hidden)] inside build_assert in case the module is not hidden in the future.

---
 rust/kernel/build_assert.rs | 11 +++++++----
 rust/kernel/lib.rs          |  6 ++----
 2 files changed, 9 insertions(+), 8 deletions(-)
rust/kernel/build_assert.rs +7 -4
index 9e37120bc69c..347ba5ce50f4 100644
@@ -2,6 +2,9 @@
 
 //! Build-time assert.
 
+#[doc(hidden)]
+pub use build_error::build_error;
+
 /// Fails the build if the code path calling `build_error!` can possibly be executed.
 ///
 /// If the macro is executed in const context, `build_error!` will panic.
@@ -23,10 +26,10 @@
 #[macro_export]
 macro_rules! build_error {
     () => {{
-        $crate::build_error("")
+        $crate::build_assert::build_error("")
     }};
     ($msg:expr) => {{
-        $crate::build_error($msg)
+        $crate::build_assert::build_error($msg)
     }};
 }
 
@@ -73,12 +76,12 @@ macro_rules! build_error {
 macro_rules! build_assert {
     ($cond:expr $(,)?) => {{
         if !$cond {
-            $crate::build_error(concat!("assertion failed: ", stringify!($cond)));
+            $crate::build_assert::build_error(concat!("assertion failed: ", stringify!($cond)));
         }
     }};
     ($cond:expr, $msg:expr) => {{
         if !$cond {
-            $crate::build_error($msg);
+            $crate::build_assert::build_error($msg);
         }
     }};
 }
rust/kernel/lib.rs +2 -4
index bf8d7f841f94..73e33a41ea04 100644
@@ -32,7 +32,8 @@
 pub mod alloc;
 #[cfg(CONFIG_BLOCK)]
 pub mod block;
-mod build_assert;
+#[doc(hidden)]
+pub mod build_assert;
 pub mod device;
 pub mod error;
 #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
@@ -66,9 +67,6 @@
 pub use macros;
 pub use uapi;
 
-#[doc(hidden)]
-pub use build_error::build_error;
-
 /// Prefix to appear before log messages printed from within the `kernel` crate.
 const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
 
Signature · 1 line
2.47.0
author maintainer
#5 lore raw

PATCH 3/3 rust: add `build_error!` to the prelude

In reply to Miguel Ojeda

The sibling build_assert! is already in the prelude, it makes sense that a "core"/"language" facility like this is part of the prelude and users should not be defining their own one (thus there should be no risk of future name collisions and we would want to be aware of them anyway).

Thus add build_error! into the prelude.

---
 rust/kernel/block/mq/operations.rs |  3 ++-
 rust/kernel/build_assert.rs        |  1 -
 rust/kernel/net/phy.rs             | 18 +++++++++---------
 rust/kernel/prelude.rs             |  2 +-
 rust/macros/lib.rs                 |  8 ++++----
 5 files changed, 16 insertions(+), 16 deletions(-)
rust/kernel/block/mq/operations.rs +2 -1
index 962f16a5a530..864ff379dc91 100644
@@ -9,6 +9,7 @@
     block::mq::request::RequestDataWrapper,
     block::mq::Request,
     error::{from_result, Result},
+    prelude::*,
     types::ARef,
 };
 use core::{marker::PhantomData, sync::atomic::AtomicU64, sync::atomic::Ordering};
@@ -35,7 +36,7 @@ pub trait Operations: Sized {
     /// Called by the kernel to poll the device for completed requests. Only
     /// used for poll queues.
     fn poll() -> bool {
-        crate::build_error!(crate::error::VTABLE_DEFAULT_ERROR)
+        build_error!(crate::error::VTABLE_DEFAULT_ERROR)
     }
 }
 
rust/kernel/build_assert.rs +0 -1
index 347ba5ce50f4..6331b15d7c4d 100644
@@ -14,7 +14,6 @@
 /// # Examples
 ///
 /// ```
-/// # use kernel::build_error;
 /// #[inline]
 /// fn foo(a: usize) -> usize {
 ///     a.checked_add(1).unwrap_or_else(|| build_error!("overflow"))
rust/kernel/net/phy.rs +9 -9
index f488f6c55e9a..654311a783e9 100644
@@ -587,17 +587,17 @@ pub trait Driver {
 
     /// Issues a PHY software reset.
     fn soft_reset(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Sets up device-specific structures during discovery.
     fn probe(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Probes the hardware to determine what abilities it has.
     fn get_features(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Returns true if this is a suitable driver for the given phydev.
@@ -609,32 +609,32 @@ fn match_phy_device(_dev: &Device) -> bool {
     /// Configures the advertisement and resets auto-negotiation
     /// if auto-negotiation is enabled.
     fn config_aneg(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Determines the negotiated speed and duplex.
     fn read_status(_dev: &mut Device) -> Result<u16> {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Suspends the hardware, saving state if needed.
     fn suspend(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Resumes the hardware, restoring state if needed.
     fn resume(_dev: &mut Device) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Overrides the default MMD read function for reading a MMD register.
     fn read_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16) -> Result<u16> {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Overrides the default MMD write function for writing a MMD register.
     fn write_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16, _val: u16) -> Result {
-        kernel::build_error!(VTABLE_DEFAULT_ERROR)
+        build_error!(VTABLE_DEFAULT_ERROR)
     }
 
     /// Callback for notification of link change.
rust/kernel/prelude.rs +1 -1
index 8bdab9aa0d16..ed076b3062ae 100644
@@ -19,7 +19,7 @@
 #[doc(no_inline)]
 pub use macros::{module, pin_data, pinned_drop, vtable, Zeroable};
 
-pub use super::build_assert;
+pub use super::{build_assert, build_error};
 
 // `super::std_vendor` is hidden, which makes the macro inline for some reason.
 #[doc(no_inline)]
rust/macros/lib.rs +4 -4
index 1a30c8075ebd..d61bc6a56425 100644
@@ -123,12 +123,12 @@ pub fn module(ts: TokenStream) -> TokenStream {
 /// used on the Rust side, it should not be possible to call the default
 /// implementation. This is done to ensure that we call the vtable methods
 /// through the C vtable, and not through the Rust vtable. Therefore, the
-/// default implementation should call `kernel::build_error!`, which prevents
+/// default implementation should call `build_error!`, which prevents
 /// calls to this function at compile time:
 ///
 /// ```compile_fail
 /// # // Intentionally missing `use`s to simplify `rusttest`.
-/// kernel::build_error!(VTABLE_DEFAULT_ERROR)
+/// build_error!(VTABLE_DEFAULT_ERROR)
 /// ```
 ///
 /// Note that you might need to import [`kernel::error::VTABLE_DEFAULT_ERROR`].
@@ -145,11 +145,11 @@ pub fn module(ts: TokenStream) -> TokenStream {
 /// #[vtable]
 /// pub trait Operations: Send + Sync + Sized {
 ///     fn foo(&self) -> Result<()> {
-///         kernel::build_error!(VTABLE_DEFAULT_ERROR)
+///         build_error!(VTABLE_DEFAULT_ERROR)
 ///     }
 ///
 ///     fn bar(&self) -> Result<()> {
-///         kernel::build_error!(VTABLE_DEFAULT_ERROR)
+///         build_error!(VTABLE_DEFAULT_ERROR)
 ///     }
 /// }
 ///
Signature · 1 line
2.47.0
reviewer Reviewed-by on v1 2/3
#2 lore raw

Re: [PATCH 2/3] rust: kernel: move `build_error` hidden function to prevent mistakes

In reply to Miguel Ojeda
Quoted 24 lines · Miguel Ojeda

Users were using the hidden exported kernel::build_error function instead of the intended kernel::build_error! macro, e.g. see the previous commit.

To force to use the macro, move it into the build_assert module, thus making it a compilation error and avoiding a collision in the same "namespace". Using the function now would require typing the module name (which is hidden), not just a single character.

Now attempting to use the function will trigger this error with the right suggestion by the compiler:

      error[E0423]: expected function, found macro `kernel::build_error`
      --> samples/rust/rust_minimal.rs:29:9
         |
      29 |         kernel::build_error();
         |         ^^^^^^^^^^^^^^^^^^^ not a function
         |
      help: use `!` to invoke the macro
         |
      29 |         kernel::build_error!();
         |                            +
Quoted 8 lines

An alternative would be using an alias, but it would be more complex and moving it into the module seems right since it belongs there and reduces the amount of code at the crate root.

Keep the #[doc(hidden)] inside build_assert in case the module is not hidden in the future.

rust/kernel/lib.rs line 36

Quoted 11 lines
rust/kernel/lib.rs +2 -1
index bf8d7f841f94..73e33a41ea04 100644
@@ -32,7 +32,8 @@
 pub mod alloc;
 #[cfg(CONFIG_BLOCK)]
 pub mod block;
-mod build_assert;
+#[doc(hidden)]
+pub mod build_assert;

You could also put #![doc(hidden)] at the top of build_assert.rs to simplify the lib.rs list. Not sure what is best.

Alice

reviewer Reviewed-by on v1 3/3
#6 lore raw

Re: [PATCH 3/3] rust: add `build_error!` to the prelude

In reply to Miguel Ojeda
Quoted 9 lines · Miguel Ojeda

The sibling build_assert! is already in the prelude, it makes sense that a "core"/"language" facility like this is part of the prelude and users should not be defining their own one (thus there should be no risk of future name collisions and we would want to be aware of them anyway).

Thus add build_error! into the prelude.

#3 lore raw

Re: [PATCH 2/3] rust: kernel: move `build_error` hidden function to prevent mistakes

In reply to Alice Ryhl
Quoted 3 lines · Alice Ryhl

You could also put #![doc(hidden)] at the top of build_assert.rs to simplify the lib.rs list. Not sure what is best.

Yeah, not sure. We used outer attributes for the rest of doc(hidden)s, including in the same file, so it is probably best to keep it consistent, unless we decide to move all to inner ones.

Thanks!

Cheers,
Miguel

reviewer
#4 lore raw

Re: [PATCH 2/3] rust: kernel: move `build_error` hidden function to prevent mistakes

Quoted 9 lines · Miguel Ojeda
Quoted 3 lines · Alice Ryhl

You could also put #![doc(hidden)] at the top of build_assert.rs to simplify the lib.rs list. Not sure what is best.

Yeah, not sure. We used outer attributes for the rest of doc(hidden)s, including in the same file, so it is probably best to keep it consistent, unless we decide to move all to inner ones.

It might actually make sense to move all of them, I think. I find that they make the list difficult to edit.

But feel free to pick whichever one you prefer for this change. My RB applies with or without it :)

Alice

Applied
#8 lore raw
In reply to Miguel Ojeda
Quoted 7 lines · Miguel Ojeda

Code and some examples were using the function, rather than the macro. The macro is what is documented.

Thus move users to the macro.

Applied series to rust-next -- thanks!

[ Applied the change to the new miscdevice cases. - Miguel ]

[ Applied the change to the new miscdevice cases. - Miguel ]

Cheers,
Miguel