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

Add a helper function equivalent to the C's might_sleep(), which
serves as a debugging aid and a potential scheduling point.

Note that this function can only be used in a nonatomic context.

This will be used by Rust version of read_poll_timeout().

[boqun: Use file_from_location() to get a C string instead of changing
__might_sleep()]

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
---
 rust/helpers/task.c |  6 ++++++
 rust/kernel/task.rs | 22 ++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/rust/helpers/task.c b/rust/helpers/task.c
index 31c33ea2dce6..2c85bbc2727e 100644
--- a/rust/helpers/task.c
+++ b/rust/helpers/task.c
@@ -1,7 +1,13 @@
 // SPDX-License-Identifier: GPL-2.0
 
+#include <linux/kernel.h>
 #include <linux/sched/task.h>
 
+void rust_helper_might_resched(void)
+{
+	might_resched();
+}
+
 struct task_struct *rust_helper_get_current(void)
 {
 	return current;
diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs
index 834368313088..518c42beaad1 100644
--- a/rust/kernel/task.rs
+++ b/rust/kernel/task.rs
@@ -400,3 +400,25 @@ fn eq(&self, other: &Kuid) -> bool {
 }
 
 impl Eq for Kuid {}
+
+/// Annotation for functions that can sleep.
+///
+/// Equivalent to the C side [`might_sleep()`], this function serves as
+/// a debugging aid and a potential scheduling point.
+///
+/// This function can only be used in a nonatomic context.
+#[track_caller]
+#[inline]
+pub fn might_sleep() {
+    #[cfg(CONFIG_DEBUG_ATOMIC_SLEEP)]
+    {
+        let loc = core::panic::Location::caller();
+        let file = kernel::file_from_location(loc);
+
+        // SAFETY: `file.as_ptr()` is valid for reading and guaranteed to be nul-terminated.
+        unsafe { crate::bindings::__might_sleep(file.as_ptr().cast(), loc.line() as i32) }
+    }
+
+    // SAFETY: Always safe to call.
+    unsafe { crate::bindings::might_resched() }
+}
-- 
2.39.5 (Apple Git-154)

On Mon, Jun 16, 2025 at 5:36 PM Boqun Feng <boqun.feng@gmail.com> wrote:
>
> +/// Equivalent to the C side [`might_sleep()`], this function serves as

I am always pleased to see intra-doc links, but wouldn't this one
point to the Rust item? :) i.e. we need to add the link, right?

I would normally ask for an example of typical usage, but do we have
some good C docs on that already that we could link otherwise?

Thanks!

Cheers,
Miguel

On Mon, 16 Jun 2025 23:28:31 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Mon, Jun 16, 2025 at 5:36 PM Boqun Feng <boqun.feng@gmail.com> wrote:
>>
>> +/// Equivalent to the C side [`might_sleep()`], this function serves as
> 
> I am always pleased to see intra-doc links, but wouldn't this one
> point to the Rust item? :) i.e. we need to add the link, right?

Ah, you're right.

> I would normally ask for an example of typical usage, but do we have
> some good C docs on that already that we could link otherwise?

I can't find C docs on might_sleep(). Device driver developers
probably don't need to use might_sleep() directly. I can't think of a
good example.

How about adding a link to the header file where the might_sleep macro
is defined, like this?

/// Annotation for functions that can sleep.
///
/// Equivalent to the C side [`might_sleep`] macro, this function serves as
/// a debugging aid and a potential scheduling point.
///
/// This function can only be used in a nonatomic context.
///
/// [`might_sleep`]: srctree/include/linux/kernel.h
#[track_caller]
#[inline]
pub fn might_sleep() {
    #[cfg(CONFIG_DEBUG_ATOMIC_SLEEP)]
    {
        let loc = core::panic::Location::caller();
        let file = kernel::file_from_location(loc);

        // SAFETY: `file.as_ptr()` is valid for reading and guaranteed to be nul-terminated.
        unsafe { crate::bindings::__might_sleep(file.as_ptr().cast(), loc.line() as i32) }
    }

    // SAFETY: Always safe to call.
    unsafe { crate::bindings::might_resched() }
}

On Tue, Jun 17, 2025 at 5:05 AM FUJITA Tomonori
<fujita.tomonori@gmail.com> wrote:
>
> How about adding a link to the header file where the might_sleep macro
> is defined, like this?

Sounds good to me. Though, for APIs that have rendered docs, we
typically point to those instead:

    https://docs.kernel.org/driver-api/basics.html#c.might_sleep

(Ideally those kernel.org docs would then have a source view
themselves, but that is a different problem... :)

Cheers,
Miguel

On Tue, 17 Jun 2025 10:02:22 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Tue, Jun 17, 2025 at 5:05 AM FUJITA Tomonori
> <fujita.tomonori@gmail.com> wrote:
>>
>> How about adding a link to the header file where the might_sleep macro
>> is defined, like this?
> 
> Sounds good to me. Though, for APIs that have rendered docs, we
> typically point to those instead:
> 
>     https://docs.kernel.org/driver-api/basics.html#c.might_sleep

Ah, somehow, I overlooked that. Thanks!

Boqun, here is the revised version.

diff --git a/rust/helpers/task.c b/rust/helpers/task.c
index 31c33ea2dce6..2c85bbc2727e 100644
--- a/rust/helpers/task.c
+++ b/rust/helpers/task.c
@@ -1,7 +1,13 @@
 // SPDX-License-Identifier: GPL-2.0
 
+#include <linux/kernel.h>
 #include <linux/sched/task.h>
 
+void rust_helper_might_resched(void)
+{
+	might_resched();
+}
+
 struct task_struct *rust_helper_get_current(void)
 {
 	return current;
diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs
index 834368313088..b79d19deb02e 100644
--- a/rust/kernel/task.rs
+++ b/rust/kernel/task.rs
@@ -400,3 +400,27 @@ fn eq(&self, other: &Kuid) -> bool {
 }
 
 impl Eq for Kuid {}
+
+/// Annotation for functions that can sleep.
+///
+/// Equivalent to the C side [`might_sleep`] macro, this function serves as
+/// a debugging aid and a potential scheduling point.
+///
+/// This function can only be used in a nonatomic context.
+///
+/// [`might_sleep`]: https://docs.kernel.org/driver-api/basics.html#c.might_sleep
+#[track_caller]
+#[inline]
+pub fn might_sleep() {
+    #[cfg(CONFIG_DEBUG_ATOMIC_SLEEP)]
+    {
+        let loc = core::panic::Location::caller();
+        let file = kernel::file_from_location(loc);
+
+        // SAFETY: `file.as_ptr()` is valid for reading and guaranteed to be nul-terminated.
+        unsafe { crate::bindings::__might_sleep(file.as_ptr().cast(), loc.line() as i32) }
+    }
+
+    // SAFETY: Always safe to call.
+    unsafe { crate::bindings::might_resched() }
+}

On Tue, Jun 17, 2025 at 09:42:07PM +0900, FUJITA Tomonori wrote:
> On Tue, 17 Jun 2025 10:02:22 +0200
> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
> 
> > On Tue, Jun 17, 2025 at 5:05 AM FUJITA Tomonori
> > <fujita.tomonori@gmail.com> wrote:
> >>
> >> How about adding a link to the header file where the might_sleep macro
> >> is defined, like this?
> > 
> > Sounds good to me. Though, for APIs that have rendered docs, we
> > typically point to those instead:
> > 
> >     https://docs.kernel.org/driver-api/basics.html#c.might_sleep
> 
> Ah, somehow, I overlooked that. Thanks!
> 
> Boqun, here is the revised version.
> 

Thanks, applied. Although I kept the parentheses because might_sleep()
is a C macro, in the same spirit of [1].

[1]: https://docs.kernel.org/process/maintainer-tip.html#function-references-in-changelogs

Regards,
Boqun

> diff --git a/rust/helpers/task.c b/rust/helpers/task.c
> index 31c33ea2dce6..2c85bbc2727e 100644
> --- a/rust/helpers/task.c
> +++ b/rust/helpers/task.c
> @@ -1,7 +1,13 @@
>  // SPDX-License-Identifier: GPL-2.0
>  
> +#include <linux/kernel.h>
>  #include <linux/sched/task.h>
>  
> +void rust_helper_might_resched(void)
> +{
> +	might_resched();
> +}
> +
>  struct task_struct *rust_helper_get_current(void)
>  {
>  	return current;
> diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs
> index 834368313088..b79d19deb02e 100644
> --- a/rust/kernel/task.rs
> +++ b/rust/kernel/task.rs
> @@ -400,3 +400,27 @@ fn eq(&self, other: &Kuid) -> bool {
>  }
>  
>  impl Eq for Kuid {}
> +
> +/// Annotation for functions that can sleep.
> +///
> +/// Equivalent to the C side [`might_sleep`] macro, this function serves as
> +/// a debugging aid and a potential scheduling point.
> +///
> +/// This function can only be used in a nonatomic context.
> +///
> +/// [`might_sleep`]: https://docs.kernel.org/driver-api/basics.html#c.might_sleep
> +#[track_caller]
> +#[inline]
> +pub fn might_sleep() {
> +    #[cfg(CONFIG_DEBUG_ATOMIC_SLEEP)]
> +    {
> +        let loc = core::panic::Location::caller();
> +        let file = kernel::file_from_location(loc);
> +
> +        // SAFETY: `file.as_ptr()` is valid for reading and guaranteed to be nul-terminated.
> +        unsafe { crate::bindings::__might_sleep(file.as_ptr().cast(), loc.line() as i32) }
> +    }
> +
> +    // SAFETY: Always safe to call.
> +    unsafe { crate::bindings::might_resched() }
> +}