Add a wrapper for fsleep(), flexible sleep functions in
include/linux/delay.h which typically deals with hardware delays.
The kernel supports several sleep functions to handle various lengths
of delay. This adds fsleep(), automatically chooses the best sleep
method based on a duration.
sleep functions including fsleep() belongs to TIMERS, not
TIMEKEEPING. They are maintained separately. rust/kernel/time.rs is an
abstraction for TIMEKEEPING. To make Rust abstractions match the C
side, add rust/kernel/time/delay.rs for this wrapper.
fsleep() can only be used in a nonatomic context. This requirement is
not checked by these abstractions, but it is intended that klint [1]
or a similar tool will be used to check it in the future.
Link: https://rust-for-linux.com/klint [1]
Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
rust/helpers/helpers.c | 1 +
rust/helpers/time.c | 8 +++++++
rust/kernel/time.rs | 2 ++
rust/kernel/time/delay.rs | 49 +++++++++++++++++++++++++++++++++++++++
4 files changed, 60 insertions(+)
create mode 100644 rust/helpers/time.c
create mode 100644 rust/kernel/time/delay.rs
diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c
index 0640b7e115be..9565485a1a54 100644
--- a/rust/helpers/helpers.c
+++ b/rust/helpers/helpers.c
@@ -31,6 +31,7 @@
#include "slab.c"
#include "spinlock.c"
#include "task.c"
+#include "time.c"
#include "uaccess.c"
#include "vmalloc.c"
#include "wait.c"
diff --git a/rust/helpers/time.c b/rust/helpers/time.c
new file mode 100644
index 000000000000..7ae64ad8141d
--- /dev/null
+++ b/rust/helpers/time.c
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/delay.h>
+
+void rust_helper_fsleep(unsigned long usecs)
+{
+ fsleep(usecs);
+}
diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
index d64a05a4f4d1..eeb0f6a7e5d4 100644
--- a/rust/kernel/time.rs
+++ b/rust/kernel/time.rs
@@ -24,6 +24,8 @@
//! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
//! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h).
+pub mod delay;
+
/// The number of nanoseconds per microsecond.
pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64;
diff --git a/rust/kernel/time/delay.rs b/rust/kernel/time/delay.rs
new file mode 100644
index 000000000000..02b8731433c7
--- /dev/null
+++ b/rust/kernel/time/delay.rs
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Delay and sleep primitives.
+//!
+//! This module contains the kernel APIs related to delay and sleep that
+//! have been ported or wrapped for usage by Rust code in the kernel.
+//!
+//! C header: [`include/linux/delay.h`](srctree/include/linux/delay.h).
+
+use super::Delta;
+use crate::ffi::c_ulong;
+
+/// Sleeps for a given duration at least.
+///
+/// Equivalent to the C side [`fsleep()`], flexible sleep function,
+/// which automatically chooses the best sleep method based on a duration.
+///
+/// `delta` must be within `[0, i32::MAX]` microseconds;
+/// otherwise, it is erroneous behavior. That is, it is considered a bug
+/// to call this function with an out-of-range value, in which case the function
+/// will sleep for at least the maximum value in the range and may warn
+/// in the future.
+///
+/// The behavior above differs from the C side [`fsleep()`] for which out-of-range
+/// values mean "infinite timeout" instead.
+///
+/// This function can only be used in a nonatomic context.
+///
+/// [`fsleep`]: https://docs.kernel.org/timers/delay_sleep_functions.html#c.fsleep
+pub fn fsleep(delta: Delta) {
+ // The maximum value is set to `i32::MAX` microseconds to prevent integer
+ // overflow inside fsleep, which could lead to unintentional infinite sleep.
+ const MAX_DELTA: Delta = Delta::from_micros(i32::MAX as i64);
+
+ let delta = if (Delta::ZERO..=MAX_DELTA).contains(&delta) {
+ delta
+ } else {
+ // TODO: Add WARN_ONCE() when it's supported.
+ MAX_DELTA
+ };
+
+ // SAFETY: It is always safe to call `fsleep()` with any duration.
+ unsafe {
+ // Convert the duration to microseconds and round up to preserve
+ // the guarantee; `fsleep()` sleeps for at least the provided duration,
+ // but that it may sleep for longer under some circumstances.
+ bindings::fsleep(delta.as_micros_ceil() as c_ulong)
+ }
+}
--
2.43.0FUJITA Tomonori <fujita.tomonori@gmail.com> writes: > Add a wrapper for fsleep(), flexible sleep functions in > include/linux/delay.h which typically deals with hardware delays. > > The kernel supports several sleep functions to handle various lengths > of delay. This adds fsleep(), automatically chooses the best sleep > method based on a duration. > > sleep functions including fsleep() belongs to TIMERS, not > TIMEKEEPING. They are maintained separately. rust/kernel/time.rs is an > abstraction for TIMEKEEPING. To make Rust abstractions match the C > side, add rust/kernel/time/delay.rs for this wrapper. > > fsleep() can only be used in a nonatomic context. This requirement is > not checked by these abstractions, but it is intended that klint [1] > or a similar tool will be used to check it in the future. > > Link: https://rust-for-linux.com/klint [1] > Tested-by: Daniel Almeida <daniel.almeida@collabora.com> > Reviewed-by: Gary Guo <gary@garyguo.net> > Reviewed-by: Alice Ryhl <aliceryhl@google.com> > Reviewed-by: Fiona Behrens <me@kloenk.dev> > Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com> Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org> Best regards, Andreas Hindborg
Le Thu, Feb 20, 2025 at 04:06:07PM +0900, FUJITA Tomonori a écrit :
> Add a wrapper for fsleep(), flexible sleep functions in
> include/linux/delay.h which typically deals with hardware delays.
>
> The kernel supports several sleep functions to handle various lengths
> of delay. This adds fsleep(), automatically chooses the best sleep
> method based on a duration.
>
> sleep functions including fsleep() belongs to TIMERS, not
> TIMEKEEPING. They are maintained separately. rust/kernel/time.rs is an
> abstraction for TIMEKEEPING. To make Rust abstractions match the C
> side, add rust/kernel/time/delay.rs for this wrapper.
>
> fsleep() can only be used in a nonatomic context. This requirement is
> not checked by these abstractions, but it is intended that klint [1]
> or a similar tool will be used to check it in the future.
>
> Link: https://rust-for-linux.com/klint [1]
> Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Gary Guo <gary@garyguo.net>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> Reviewed-by: Fiona Behrens <me@kloenk.dev>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Sorry to make a late review. I don't mean to delay that any further
but:
> +/// `delta` must be within `[0, i32::MAX]` microseconds;
> +/// otherwise, it is erroneous behavior. That is, it is considered a bug
> +/// to call this function with an out-of-range value, in which case the function
> +/// will sleep for at least the maximum value in the range and may warn
> +/// in the future.
> +///
> +/// The behavior above differs from the C side [`fsleep()`] for which out-of-range
> +/// values mean "infinite timeout" instead.
And very important: the behaviour also differ in that the C side takes
usecs while this takes nsecs. We should really disambiguate the situation
as that might create confusion or misusage.
Either this should be renamed to fsleep_ns() or fsleep_nsecs(), or this should
take microseconds directly.
Thanks.
> +///
> +/// This function can only be used in a nonatomic context.
> +///
> +/// [`fsleep`]: https://docs.kernel.org/timers/delay_sleep_functions.html#c.fsleep
> +pub fn fsleep(delta: Delta) {
> + // The maximum value is set to `i32::MAX` microseconds to prevent integer
> + // overflow inside fsleep, which could lead to unintentional infinite sleep.
> + const MAX_DELTA: Delta = Delta::from_micros(i32::MAX as i64);
> +
> + let delta = if (Delta::ZERO..=MAX_DELTA).contains(&delta) {
> + delta
> + } else {
> + // TODO: Add WARN_ONCE() when it's supported.
> + MAX_DELTA
> + };
> +
> + // SAFETY: It is always safe to call `fsleep()` with any duration.
> + unsafe {
> + // Convert the duration to microseconds and round up to preserve
> + // the guarantee; `fsleep()` sleeps for at least the provided duration,
> + // but that it may sleep for longer under some circumstances.
> + bindings::fsleep(delta.as_micros_ceil() as c_ulong)
> + }
> +}
> --
> 2.43.0
>
On Fri, 21 Mar 2025 23:05:23 +0100 Frederic Weisbecker <frederic@kernel.org> wrote: > Le Thu, Feb 20, 2025 at 04:06:07PM +0900, FUJITA Tomonori a écrit : >> Add a wrapper for fsleep(), flexible sleep functions in >> include/linux/delay.h which typically deals with hardware delays. >> >> The kernel supports several sleep functions to handle various lengths >> of delay. This adds fsleep(), automatically chooses the best sleep >> method based on a duration. >> >> sleep functions including fsleep() belongs to TIMERS, not >> TIMEKEEPING. They are maintained separately. rust/kernel/time.rs is an >> abstraction for TIMEKEEPING. To make Rust abstractions match the C >> side, add rust/kernel/time/delay.rs for this wrapper. >> >> fsleep() can only be used in a nonatomic context. This requirement is >> not checked by these abstractions, but it is intended that klint [1] >> or a similar tool will be used to check it in the future. >> >> Link: https://rust-for-linux.com/klint [1] >> Tested-by: Daniel Almeida <daniel.almeida@collabora.com> >> Reviewed-by: Gary Guo <gary@garyguo.net> >> Reviewed-by: Alice Ryhl <aliceryhl@google.com> >> Reviewed-by: Fiona Behrens <me@kloenk.dev> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com> > > Sorry to make a late review. I don't mean to delay that any further > but: No problem at all. Thanks for reviewing! >> +/// `delta` must be within `[0, i32::MAX]` microseconds; >> +/// otherwise, it is erroneous behavior. That is, it is considered a bug >> +/// to call this function with an out-of-range value, in which case the function >> +/// will sleep for at least the maximum value in the range and may warn >> +/// in the future. >> +/// >> +/// The behavior above differs from the C side [`fsleep()`] for which out-of-range >> +/// values mean "infinite timeout" instead. > > And very important: the behaviour also differ in that the C side takes > usecs while this takes nsecs. We should really disambiguate the situation > as that might create confusion or misusage. > > Either this should be renamed to fsleep_ns() or fsleep_nsecs(), or this should > take microseconds directly. You meant that `Delta` type internally tracks time in nanoseconds? It's true but Delta type is a unit-agnostic time abstraction, designed to represent durations across different granularities — seconds, milliseconds, microseconds, nanoseconds. The Rust abstraction always tries to us Delta type to represent durations. Rust's fsleep takes Delta, internally converts it in usecs, and calls C's fsleep. Usually, drivers convert from a certain time unit to Delta before calling fsleep like the following, so misuse or confusion is unlikely to occur, I think. fsleep(Delta::from_micros(50)); However, as you pointed out, there is a difference; C's fsleep takes usecs while Rust's fsleep takes a unit-agnostic time type. Taking this difference into account, if we were to rename fsleep for Rust, I think that a name that is agnostic to the time unit would seem more appropriate. Simply sleep(), perhaps?
FUJITA Tomonori <fujita.tomonori@gmail.com> writes: > On Fri, 21 Mar 2025 23:05:23 +0100 > Frederic Weisbecker <frederic@kernel.org> wrote: > [...] >>> +/// `delta` must be within `[0, i32::MAX]` microseconds; >>> +/// otherwise, it is erroneous behavior. That is, it is considered a bug >>> +/// to call this function with an out-of-range value, in which case the function >>> +/// will sleep for at least the maximum value in the range and may warn >>> +/// in the future. >>> +/// >>> +/// The behavior above differs from the C side [`fsleep()`] for which out-of-range >>> +/// values mean "infinite timeout" instead. >> >> And very important: the behaviour also differ in that the C side takes >> usecs while this takes nsecs. We should really disambiguate the situation >> as that might create confusion or misusage. >> >> Either this should be renamed to fsleep_ns() or fsleep_nsecs(), or this should >> take microseconds directly. > > You meant that `Delta` type internally tracks time in nanoseconds? > > It's true but Delta type is a unit-agnostic time abstraction, designed > to represent durations across different granularities — seconds, > milliseconds, microseconds, nanoseconds. The Rust abstraction always > tries to us Delta type to represent durations. > > Rust's fsleep takes Delta, internally converts it in usecs, and calls > C's fsleep. > > Usually, drivers convert from a certain time unit to Delta before > calling fsleep like the following, so misuse or confusion is unlikely > to occur, I think. > > fsleep(Delta::from_micros(50)); > > However, as you pointed out, there is a difference; C's fsleep takes > usecs while Rust's fsleep takes a unit-agnostic time type. Taking this > difference into account, if we were to rename fsleep for Rust, I think > that a name that is agnostic to the time unit would seem more > appropriate. Simply sleep(), perhaps? I would prefer to keep the same name. But if we must change it, how about `flexible_sleep` to indicate the behavior? And just to reiterate what Tomonori already said, it is not possible to call this method with an integer, fsleep(500) will not compile. A unit based conversion into `Duration` is required. Best regards, Andreas Hindborg
© 2016 - 2025 Red Hat, Inc.