[PATCH v2 0/3] rust: Add pr_*_once macros

[PATCH v2 0/3] rust: Add pr_*_once macros

[Jens Korinth via B4 Relay]

Add Rust version of pr_[emerg|alert|crit|err|warn|notic|info]_once
functions, which print a message only once.

v2:
- Split patch into do_once_lite part and pr_*_once macros
- Add macro rule for call without condition => renamed to do_once_lite
- Used condition-less call in pr_*_once macros
- Added examples
- Removed TODO in kernel/error.rs using pr_warn_once
v1: https://lore.kernel.org/rust-for-linux/20241106.083113.356536037967804464.fujita.tomonori@gmail.com/

Signed-off-by: Jens Korinth <jens.korinth@tuta.io>
Co-developed-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Co-developed-by: Boqun Feng <boqun.feng@gmail.com>
---
FUJITA Tomonori (1):
      rust: print: Add pr_*_once macros

Jens Korinth (2):
      rust: print: Add do_once_lite macro
      rust: error: Replace pr_warn by pr_warn_once

 rust/kernel/error.rs |   3 +-
 rust/kernel/print.rs | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+), 2 deletions(-)
---
base-commit: ae7851c29747fa3765ecb722fe722117a346f988
change-id: 20241107-pr_once_macros-6438e6f5b923

Best regards,
-- 
Jens Korinth <jens.korinth@tuta.io>

[PATCH v2 1/3] rust: print: Add do_once_lite macro

[Jens Korinth via B4 Relay]

From: Jens Korinth <jens.korinth@tuta.io>

Add do_once_lite macro that executes code only once.
Has two rules, one with a condition to replace [`do_once_lite_if`] in
the kernel, and one without.

Signed-off-by: Jens Korinth <jens.korinth@tuta.io>
---
 rust/kernel/print.rs | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index a28077a7cb301193dcca293befb096b2dd153202..9c7434b221984ad325138e5dc90ab4340cd0be2e 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -414,3 +414,37 @@ macro_rules! pr_cont (
         $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*)
     )
 );
+
+/// Executes code only once.
+///
+/// Equivalent to the kernel's [`do_once_lite_if`] macro when called with
+/// a condition expression.
+/// Public but hidden since it should only be used from public macros.
+///
+/// # Examples
+///
+/// ```
+/// kernel::do_once_lite!(pr_warn!("warn once"));
+/// kernel::do_once_lite!({ /* perform_complex_test() */ true }, pr_warn!("warn only once"));
+/// ```
+#[doc(hidden)]
+#[macro_export]
+macro_rules! do_once_lite (
+    ($e:expr) => (
+         $crate::do_once_lite!(true, $e);
+    );
+    ($condition:expr, $e:expr) => (
+        {
+            #[link_section = ".data.once"]
+            static ALREADY_DONE: core::sync::atomic::AtomicBool =
+                core::sync::atomic::AtomicBool::new(false);
+
+            if !ALREADY_DONE.load(core::sync::atomic::Ordering::Relaxed)
+                && $condition
+                && !ALREADY_DONE.swap(true, core::sync::atomic::Ordering::Relaxed)
+            {
+                $e;
+            }
+        }
+    );
+);

-- 
2.44.1

[PATCH v2 2/3] rust: print: Add pr_*_once macros

[Jens Korinth via B4 Relay]

From: FUJITA Tomonori <fujita.tomonori@gmail.com>

Add Rust version of pr_[emerg|alert|crit|err|warn|notic|info]_once
functions, which print a message only once.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
 rust/kernel/print.rs | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)

diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index 9c7434b221984ad325138e5dc90ab4340cd0be2e..3c7414f99934359112b39d01392029feda8802e8 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -448,3 +448,112 @@ macro_rules! do_once_lite (
         }
     );
 );
+
+/// Prints an emergency-level message (level 0) only once.
+///
+/// Equivalent to the kernel's [`pr_emerg_once`] macro.
+///
+/// # Examples
+///
+/// ```
+/// kernel::pr_emerg_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_emerg_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_emerg!($($arg)*))
+    )
+);
+
+/// Prints an alert-level message (level 1) only once.
+///
+/// Equivalent to the kernel's [`pr_alert_once`] macro.
+///
+/// # Examples
+///
+/// ```
+/// kernel::pr_alert_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_alert_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_alert!($($arg)*))
+    )
+);
+
+/// Prints a critical-level message (level 2) only once.
+///
+/// Equivalent to the kernel's [`pr_crit_once`] macro.
+///
+/// # Examples
+///
+/// ```
+/// kernel::pr_crit_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_crit_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_crit!($($arg)*))
+    )
+);
+
+/// Prints an error-level message (level 3) only once.
+///
+/// Equivalent to the kernel's [`pr_err_once`] macro.
+///
+/// # Examples
+///
+/// ```
+/// pr_err_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_err_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_err!($($arg)*))
+    )
+);
+
+/// Prints a warning-level message (level 4) only once.
+///
+/// Equivalent to the kernel's [`pr_warn_once`] macro.
+///
+/// # Examples
+/// ```
+/// kernel::pr_warn_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_warn_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_warn!($($arg)*))
+    )
+);
+
+/// Prints a notice-level message (level 5) only once.
+///
+/// Equivalent to the kernel's [`pr_notice_once`] macro.
+///
+/// # Examples
+/// ```
+/// kernel::pr_notice_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_notice_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_notice!($($arg)*))
+    )
+);
+
+/// Prints an info-level message (level 6) only once.
+///
+/// Equivalent to the kernel's [`pr_info_once`] macro.
+///
+/// # Examples
+/// ```
+/// kernel::pr_info_once!("hello {}\n", "there");
+/// ```
+#[macro_export]
+macro_rules! pr_info_once (
+    ($($arg:tt)*) => (
+        $crate::do_once_lite!($crate::pr_info!($($arg)*))
+    )
+);

-- 
2.44.1

[PATCH v2 3/3] rust: error: Replace pr_warn by pr_warn_once

[Jens Korinth via B4 Relay]

From: Jens Korinth <jens.korinth@tuta.io>

Use new pr_warn_once macro to resolve TODO in error.rs.

Signed-off-by: Jens Korinth <jens.korinth@tuta.io>
---
 rust/kernel/error.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 7cd3bbab52f208961390de03a255446950e9eb04..fe1b31506b30fba0ec9d5339d80c2a7fa76ce7c7 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -102,8 +102,7 @@ impl Error {
     /// be returned in such a case.
     pub fn from_errno(errno: core::ffi::c_int) -> Error {
         if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 {
-            // TODO: Make it a `WARN_ONCE` once available.
-            crate::pr_warn!(
+            crate::pr_warn_once!(
                 "attempted to create `Error` with out of range `errno`: {}",
                 errno
             );

-- 
2.44.1

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[Miguel Ojeda]

On Thu, Nov 7, 2024 at 12:29 AM Jens Korinth via B4 Relay
<devnull+jens.korinth.tuta.io@kernel.org> wrote:
>
> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
>
> Add Rust version of pr_[emerg|alert|crit|err|warn|notic|info]_once
> functions, which print a message only once.
>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>

When sending a patch from someone else, then you need to sign the
commit too, i.e. after Tomonori's SoB:

    https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

I think you added examples (which is great!), i.e. you modified
Tomonori's patch/code/message -- did Tomonori agree on the changes? If
you did agree in private, please ignore this. If not, Tomonori: can
you please say whether you are OK with the patch? Thanks!

> +/// Equivalent to the kernel's [`pr_emerg_once`] macro.

I think these intra-doc links go to the Rust one, not the C one, since
I don't see the reference below. (Please see how it is was done in the
other macros in the file.)

> +/// # Examples
> +/// ```
> +/// kernel::pr_warn_once!("hello {}\n", "there");
> +/// ```

Nit: missing newline between the header and the example (also other
instances below).

Thanks!

Cheers,
Miguel

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[kernel test robot]

Hi Jens,

kernel test robot noticed the following build errors:

[auto build test ERROR on ae7851c29747fa3765ecb722fe722117a346f988]

url:    https://github.com/intel-lab-lkp/linux/commits/Jens-Korinth-via-B4-Relay/rust-print-Add-do_once_lite-macro/20241107-073105
base:   ae7851c29747fa3765ecb722fe722117a346f988
patch link:    https://lore.kernel.org/r/20241107-pr_once_macros-v2-2-dc0317ff301e%40tuta.io
patch subject: [PATCH v2 2/3] rust: print: Add pr_*_once macros
config: arm64-randconfig-003-20241107 (https://download.01.org/0day-ci/archive/20241107/202411072242.YQFMjUwb-lkp@intel.com/config)
compiler: clang version 20.0.0git (https://github.com/llvm/llvm-project 592c0fe55f6d9a811028b5f3507be91458ab2713)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20241107/202411072242.YQFMjUwb-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202411072242.YQFMjUwb-lkp@intel.com/

All errors (new ones prefixed by >>):

>> error: cannot find macro `pr_err_once` in this scope
   --> rust/doctests_kernel_generated.rs:3782:1
   |
   3782 | pr_err_once!("hello {}n", "there");
   | ^^^^^^^^^^^
   |
   help: consider importing this macro
   |
   3    + use kernel::pr_err_once;
   |

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[FUJITA Tomonori]

On Thu, 7 Nov 2024 12:14:49 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Thu, Nov 7, 2024 at 12:29 AM Jens Korinth via B4 Relay
> <devnull+jens.korinth.tuta.io@kernel.org> wrote:
>>
>> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
>>
>> Add Rust version of pr_[emerg|alert|crit|err|warn|notic|info]_once
>> functions, which print a message only once.
>>
>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> 
> When sending a patch from someone else, then you need to sign the
> commit too, i.e. after Tomonori's SoB:
> 
>     https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
> 
> I think you added examples (which is great!), i.e. you modified
> Tomonori's patch/code/message -- did Tomonori agree on the changes? If
> you did agree in private, please ignore this. If not, Tomonori: can
> you please say whether you are OK with the patch? Thanks!

Fine by me.

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[Dirk Behme]

On 07.11.2024 00:28, Jens Korinth via B4 Relay wrote:
> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
> 
> Add Rust version of pr_[emerg|alert|crit|err|warn|notic|info]_once
> functions, which print a message only once.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> ---
>   rust/kernel/print.rs | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 109 insertions(+)
> 
> diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
> index 9c7434b221984ad325138e5dc90ab4340cd0be2e..3c7414f99934359112b39d01392029feda8802e8 100644
> --- a/rust/kernel/print.rs
> +++ b/rust/kernel/print.rs
> @@ -448,3 +448,112 @@ macro_rules! do_once_lite (
>           }
>       );
>   );
> +
> +/// Prints an emergency-level message (level 0) only once.
> +///
> +/// Equivalent to the kernel's [`pr_emerg_once`] macro.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// kernel::pr_emerg_once!("hello {}\n", "there");
> +/// ```
> +#[macro_export]
> +macro_rules! pr_emerg_once (
> +    ($($arg:tt)*) => (
> +        $crate::do_once_lite!($crate::pr_emerg!($($arg)*))
> +    )
> +);
> +
> +/// Prints an alert-level message (level 1) only once.
> +///
> +/// Equivalent to the kernel's [`pr_alert_once`] macro.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// kernel::pr_alert_once!("hello {}\n", "there");
> +/// ```
> +#[macro_export]
> +macro_rules! pr_alert_once (
> +    ($($arg:tt)*) => (
> +        $crate::do_once_lite!($crate::pr_alert!($($arg)*))
> +    )
> +);
> +
> +/// Prints a critical-level message (level 2) only once.
> +///
> +/// Equivalent to the kernel's [`pr_crit_once`] macro.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// kernel::pr_crit_once!("hello {}\n", "there");
> +/// ```
> +#[macro_export]
> +macro_rules! pr_crit_once (
> +    ($($arg:tt)*) => (
> +        $crate::do_once_lite!($crate::pr_crit!($($arg)*))
> +    )
> +);
> +
> +/// Prints an error-level message (level 3) only once.
> +///
> +/// Equivalent to the kernel's [`pr_err_once`] macro.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// pr_err_once!("hello {}\n", "there");
> +/// ```

'kernel::' is missing here:

error: cannot find macro `pr_err_once` in this scope
     --> rust/doctests_kernel_generated.rs:4482:1
      |
4482 | pr_err_once!("hello {}\n", "there");
      | ^^^^^^^^^^^

Best regards

Dirk

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[jens.korinth]

> When sending a patch from someone else, then you need to sign the
> commit too, i.e. after Tomonori's SoB:
>
> https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
>
Understood, will fix it (still practicing the whole flow).

> I think you added examples (which is great!), i.e. you modified
> Tomonori's patch/code/message -- did Tomonori agree on the changes? If
> you did agree in private, please ignore this.
>
We did not, but luckily he already replied and is fine with it. I was unsure about how to do this - general question: Should each commit in a patch series only contain the "final" code for the topic? Or should the series also reflect the development history (other than via the changelog and acknowledgements)?

E.g., in this case: Was it correct to modify Tomonori's commit, or should I rather have added a separate commit that changes the code added by his commit?

> Nit: missing newline between the header and the example (also other
> instances below).
>
Ah, right, will fix that, too.

Thanks a lot for your kind help!
Jens

Re: [PATCH v2 2/3] rust: print: Add pr_*_once macros

[Miguel Ojeda]

On Fri, Nov 8, 2024 at 9:10 PM <jens.korinth@tuta.io> wrote:
>
> Should each commit in a patch series only contain the "final" code for the topic? Or should the series also reflect the development history (other than via the changelog and acknowledgements)?

Only the final code, i.e. you would typically craft each version by
modifying locally previous ones, e.g. by rebasing.

> E.g., in this case: Was it correct to modify Tomonori's commit, or should I rather have added a separate commit that changes the code added by his commit?

I see. So I asked the question not because of the changes themselves,
but because of the SoB.

In other words, normally you will be modifying your own patches, and
in that case the expected workflow is, in fact, to modify the patch
and sending it as a new version.

But since here you modified a patch that wasn't yours, and there was
no note about the modifications done, it looked like Tomonori
originally did those changes, so I just wanted to make sure Tomonori
was OK with it.

> Thanks a lot for your kind help!

You're very welcome! :)

Cheers,
Miguel