rust/kernel/time.rs - linux - Git at Google

 // SPDX-License-Identifier: GPL-2.0

 //! Time related primitives.
 //!
 //! This module contains the kernel APIs related to time and timers that
 //! have been ported or wrapped for usage by Rust code in the kernel.
 //!
 //! There are two types in this module:
 //!
 //! - The [`Instant`] type represents a specific point in time.
 //! - The [`Delta`] type represents a span of time.
 //!
 //! Note that the C side uses `ktime_t` type to represent both. However, timestamp
 //! and timedelta are different. To avoid confusion, we use two different types.
 //!
 //! A [`Instant`] object can be created by calling the [`Instant::now()`] function.
 //! It represents a point in time at which the object was created.
 //! By calling the [`Instant::elapsed()`] method, a [`Delta`] object representing
 //! the elapsed time can be created. The [`Delta`] object can also be created
 //! by subtracting two [`Instant`] objects.
 //!
 //! A [`Delta`] type supports methods to retrieve the duration in various units.
 //!
 //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
 //! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h).

 use core::marker::PhantomData;

 pub mod delay;
 pub mod hrtimer;

 /// The number of nanoseconds per microsecond.
 pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64;

 /// The number of nanoseconds per millisecond.
 pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;

 /// The number of nanoseconds per second.
 pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64;

 /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
 pub type Jiffies = crate::ffi::c_ulong;

 /// The millisecond time unit.
 pub type Msecs = crate::ffi::c_uint;

 /// Converts milliseconds to jiffies.
 #[inline]
 pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
     // SAFETY: The `__msecs_to_jiffies` function is always safe to call no
     // matter what the argument is.
     unsafe { bindings::__msecs_to_jiffies(msecs) }
 }

 /// Trait for clock sources.
 ///
 /// Selection of the clock source depends on the use case. In some cases the usage of a
 /// particular clock is mandatory, e.g. in network protocols, filesystems. In other
 /// cases the user of the clock has to decide which clock is best suited for the
 /// purpose. In most scenarios clock [`Monotonic`] is the best choice as it
 /// provides a accurate monotonic notion of time (leap second smearing ignored).
 pub trait ClockSource {
     /// The kernel clock ID associated with this clock source.
     ///
     /// This constant corresponds to the C side `clockid_t` value.
     const ID: bindings::clockid_t;

     /// Get the current time from the clock source.
     ///
     /// The function must return a value in the range from 0 to `KTIME_MAX`.
     fn ktime_get() -> bindings::ktime_t;
 }

 /// A monotonically increasing clock.
 ///
 /// A nonsettable system-wide clock that represents monotonic time since as
 /// described by POSIX, "some unspecified point in the past". On Linux, that
 /// point corresponds to the number of seconds that the system has been
 /// running since it was booted.
 ///
 /// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the
 /// CLOCK_REAL (e.g., if the system administrator manually changes the
 /// clock), but is affected by frequency adjustments. This clock does not
 /// count time that the system is suspended.
 pub struct Monotonic;

 impl ClockSource for Monotonic {
     const ID: bindings::clockid_t = bindings::CLOCK_MONOTONIC as bindings::clockid_t;

     fn ktime_get() -> bindings::ktime_t {
         // SAFETY: It is always safe to call `ktime_get()` outside of NMI context.
         unsafe { bindings::ktime_get() }
     }
 }

 /// A settable system-wide clock that measures real (i.e., wall-clock) time.
 ///
 /// Setting this clock requires appropriate privileges. This clock is
 /// affected by discontinuous jumps in the system time (e.g., if the system
 /// administrator manually changes the clock), and by frequency adjustments
 /// performed by NTP and similar applications via adjtime(3), adjtimex(2),
 /// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the
 /// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time
 /// (UTC) except that it ignores leap seconds; near a leap second it may be
 /// adjusted by leap second smearing to stay roughly in sync with UTC. Leap
 /// second smearing applies frequency adjustments to the clock to speed up
 /// or slow down the clock to account for the leap second without
 /// discontinuities in the clock. If leap second smearing is not applied,
 /// the clock will experience discontinuity around leap second adjustment.
 pub struct RealTime;

 impl ClockSource for RealTime {
     const ID: bindings::clockid_t = bindings::CLOCK_REALTIME as bindings::clockid_t;

     fn ktime_get() -> bindings::ktime_t {
         // SAFETY: It is always safe to call `ktime_get_real()` outside of NMI context.
         unsafe { bindings::ktime_get_real() }
     }
 }

 /// A monotonic that ticks while system is suspended.
 ///
 /// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC,
 /// except that it also includes any time that the system is suspended. This
 /// allows applications to get a suspend-aware monotonic clock without
 /// having to deal with the complications of CLOCK_REALTIME, which may have
 /// discontinuities if the time is changed using settimeofday(2) or similar.
 pub struct BootTime;

 impl ClockSource for BootTime {
     const ID: bindings::clockid_t = bindings::CLOCK_BOOTTIME as bindings::clockid_t;

     fn ktime_get() -> bindings::ktime_t {
         // SAFETY: It is always safe to call `ktime_get_boottime()` outside of NMI context.
         unsafe { bindings::ktime_get_boottime() }
     }
 }

 /// International Atomic Time.
 ///
 /// A system-wide clock derived from wall-clock time but counting leap seconds.
 ///
 /// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is
 /// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This
 /// usually happens during boot and **should** not happen during normal operations.
 /// However, if NTP or another application adjusts CLOCK_REALTIME by leap second
 /// smearing, this clock will not be precise during leap second smearing.
 ///
 /// The acronym TAI refers to International Atomic Time.
 pub struct Tai;

 impl ClockSource for Tai {
     const ID: bindings::clockid_t = bindings::CLOCK_TAI as bindings::clockid_t;

     fn ktime_get() -> bindings::ktime_t {
         // SAFETY: It is always safe to call `ktime_get_tai()` outside of NMI context.
         unsafe { bindings::ktime_get_clocktai() }
     }
 }

 /// A specific point in time.
 ///
 /// # Invariants
 ///
 /// The `inner` value is in the range from 0 to `KTIME_MAX`.
 #[repr(transparent)]
 #[derive(PartialEq, PartialOrd, Eq, Ord)]
 pub struct Instant<C: ClockSource> {
     inner: bindings::ktime_t,
     _c: PhantomData<C>,
 }

 impl<C: ClockSource> Clone for Instant<C> {
     fn clone(&self) -> Self {
         *self
     }
 }

 impl<C: ClockSource> Copy for Instant<C> {}

 impl<C: ClockSource> Instant<C> {
     /// Get the current time from the clock source.
     #[inline]
     pub fn now() -> Self {
         // INVARIANT: The `ClockSource::ktime_get()` function returns a value in the range
         // from 0 to `KTIME_MAX`.
         Self {
             inner: C::ktime_get(),
             _c: PhantomData,
         }
     }

     /// Return the amount of time elapsed since the [`Instant`].
     #[inline]
     pub fn elapsed(&self) -> Delta {
         Self::now() - *self
     }

     #[inline]
     pub(crate) fn as_nanos(&self) -> i64 {
         self.inner
     }
 }

 impl<C: ClockSource> core::ops::Sub for Instant<C> {
     type Output = Delta;

     // By the type invariant, it never overflows.
     #[inline]
     fn sub(self, other: Instant<C>) -> Delta {
         Delta {
             nanos: self.inner - other.inner,
         }
     }
 }

 /// A span of time.
 ///
 /// This struct represents a span of time, with its value stored as nanoseconds.
 /// The value can represent any valid i64 value, including negative, zero, and
 /// positive numbers.
 #[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]
 pub struct Delta {
     nanos: i64,
 }

 impl Delta {
     /// A span of time equal to zero.
     pub const ZERO: Self = Self { nanos: 0 };

     /// Create a new [`Delta`] from a number of microseconds.
     ///
     /// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775.
     /// If `micros` is outside this range, `i64::MIN` is used for negative values,
     /// and `i64::MAX` is used for positive values due to saturation.
     #[inline]
     pub const fn from_micros(micros: i64) -> Self {
         Self {
             nanos: micros.saturating_mul(NSEC_PER_USEC),
         }
     }

     /// Create a new [`Delta`] from a number of milliseconds.
     ///
     /// The `millis` can range from -9_223_372_036_854 to 9_223_372_036_854.
     /// If `millis` is outside this range, `i64::MIN` is used for negative values,
     /// and `i64::MAX` is used for positive values due to saturation.
     #[inline]
     pub const fn from_millis(millis: i64) -> Self {
         Self {
             nanos: millis.saturating_mul(NSEC_PER_MSEC),
         }
     }

     /// Create a new [`Delta`] from a number of seconds.
     ///
     /// The `secs` can range from -9_223_372_036 to 9_223_372_036.
     /// If `secs` is outside this range, `i64::MIN` is used for negative values,
     /// and `i64::MAX` is used for positive values due to saturation.
     #[inline]
     pub const fn from_secs(secs: i64) -> Self {
         Self {
             nanos: secs.saturating_mul(NSEC_PER_SEC),
         }
     }

     /// Return `true` if the [`Delta`] spans no time.
     #[inline]
     pub fn is_zero(self) -> bool {
         self.as_nanos() == 0
     }

     /// Return `true` if the [`Delta`] spans a negative amount of time.
     #[inline]
     pub fn is_negative(self) -> bool {
         self.as_nanos() < 0
     }

     /// Return the number of nanoseconds in the [`Delta`].
     #[inline]
     pub const fn as_nanos(self) -> i64 {
         self.nanos
     }

     /// Return the smallest number of microseconds greater than or equal
     /// to the value in the [`Delta`].
     #[inline]
     pub fn as_micros_ceil(self) -> i64 {
         #[cfg(CONFIG_64BIT)]
         {
             self.as_nanos().saturating_add(NSEC_PER_USEC - 1) / NSEC_PER_USEC
         }

         #[cfg(not(CONFIG_64BIT))]
         // SAFETY: It is always safe to call `ktime_to_us()` with any value.
         unsafe {
             bindings::ktime_to_us(self.as_nanos().saturating_add(NSEC_PER_USEC - 1))
         }
     }

     /// Return the number of milliseconds in the [`Delta`].
     #[inline]
     pub fn as_millis(self) -> i64 {
         #[cfg(CONFIG_64BIT)]
         {
             self.as_nanos() / NSEC_PER_MSEC
         }

         #[cfg(not(CONFIG_64BIT))]
         // SAFETY: It is always safe to call `ktime_to_ms()` with any value.
         unsafe {
             bindings::ktime_to_ms(self.as_nanos())
         }
     }
 }
	// SPDX-License-Identifier: GPL-2.0

	//! Time related primitives.
	//!
	//! This module contains the kernel APIs related to time and timers that
	//! have been ported or wrapped for usage by Rust code in the kernel.
	//!
	//! There are two types in this module:
	//!
	//! - The [`Instant`] type represents a specific point in time.
	//! - The [`Delta`] type represents a span of time.
	//!
	//! Note that the C side uses `ktime_t` type to represent both. However, timestamp
	//! and timedelta are different. To avoid confusion, we use two different types.
	//!
	//! A [`Instant`] object can be created by calling the [`Instant::now()`] function.
	//! It represents a point in time at which the object was created.
	//! By calling the [`Instant::elapsed()`] method, a [`Delta`] object representing
	//! the elapsed time can be created. The [`Delta`] object can also be created
	//! by subtracting two [`Instant`] objects.
	//!
	//! A [`Delta`] type supports methods to retrieve the duration in various units.
	//!
	//! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
	//! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h).

	use core::marker::PhantomData;

	pub mod delay;
	pub mod hrtimer;

	/// The number of nanoseconds per microsecond.
	pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64;

	/// The number of nanoseconds per millisecond.
	pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;

	/// The number of nanoseconds per second.
	pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64;

	/// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
	pub type Jiffies = crate::ffi::c_ulong;

	/// The millisecond time unit.
	pub type Msecs = crate::ffi::c_uint;

	/// Converts milliseconds to jiffies.
	#[inline]
	pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
	// SAFETY: The `__msecs_to_jiffies` function is always safe to call no
	// matter what the argument is.
	unsafe { bindings::__msecs_to_jiffies(msecs) }
	}

	/// Trait for clock sources.
	///
	/// Selection of the clock source depends on the use case. In some cases the usage of a
	/// particular clock is mandatory, e.g. in network protocols, filesystems. In other
	/// cases the user of the clock has to decide which clock is best suited for the
	/// purpose. In most scenarios clock [`Monotonic`] is the best choice as it
	/// provides a accurate monotonic notion of time (leap second smearing ignored).
	pub trait ClockSource {
	/// The kernel clock ID associated with this clock source.
	///
	/// This constant corresponds to the C side `clockid_t` value.
	const ID: bindings::clockid_t;

	/// Get the current time from the clock source.
	///
	/// The function must return a value in the range from 0 to `KTIME_MAX`.
	fn ktime_get() -> bindings::ktime_t;
	}

	/// A monotonically increasing clock.
	///
	/// A nonsettable system-wide clock that represents monotonic time since as
	/// described by POSIX, "some unspecified point in the past". On Linux, that
	/// point corresponds to the number of seconds that the system has been
	/// running since it was booted.
	///
	/// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the
	/// CLOCK_REAL (e.g., if the system administrator manually changes the
	/// clock), but is affected by frequency adjustments. This clock does not
	/// count time that the system is suspended.
	pub struct Monotonic;

	impl ClockSource for Monotonic {
	const ID: bindings::clockid_t = bindings::CLOCK_MONOTONIC as bindings::clockid_t;

	fn ktime_get() -> bindings::ktime_t {
	// SAFETY: It is always safe to call `ktime_get()` outside of NMI context.
	unsafe { bindings::ktime_get() }
	}
	}

	/// A settable system-wide clock that measures real (i.e., wall-clock) time.
	///
	/// Setting this clock requires appropriate privileges. This clock is
	/// affected by discontinuous jumps in the system time (e.g., if the system
	/// administrator manually changes the clock), and by frequency adjustments
	/// performed by NTP and similar applications via adjtime(3), adjtimex(2),
	/// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the
	/// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time
	/// (UTC) except that it ignores leap seconds; near a leap second it may be
	/// adjusted by leap second smearing to stay roughly in sync with UTC. Leap
	/// second smearing applies frequency adjustments to the clock to speed up
	/// or slow down the clock to account for the leap second without
	/// discontinuities in the clock. If leap second smearing is not applied,
	/// the clock will experience discontinuity around leap second adjustment.
	pub struct RealTime;

	impl ClockSource for RealTime {
	const ID: bindings::clockid_t = bindings::CLOCK_REALTIME as bindings::clockid_t;

	fn ktime_get() -> bindings::ktime_t {
	// SAFETY: It is always safe to call `ktime_get_real()` outside of NMI context.
	unsafe { bindings::ktime_get_real() }
	}
	}

	/// A monotonic that ticks while system is suspended.
	///
	/// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC,
	/// except that it also includes any time that the system is suspended. This
	/// allows applications to get a suspend-aware monotonic clock without
	/// having to deal with the complications of CLOCK_REALTIME, which may have
	/// discontinuities if the time is changed using settimeofday(2) or similar.
	pub struct BootTime;

	impl ClockSource for BootTime {
	const ID: bindings::clockid_t = bindings::CLOCK_BOOTTIME as bindings::clockid_t;

	fn ktime_get() -> bindings::ktime_t {
	// SAFETY: It is always safe to call `ktime_get_boottime()` outside of NMI context.
	unsafe { bindings::ktime_get_boottime() }
	}
	}

	/// International Atomic Time.
	///
	/// A system-wide clock derived from wall-clock time but counting leap seconds.
	///
	/// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is
	/// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This
	/// usually happens during boot and should not happen during normal operations.
	/// However, if NTP or another application adjusts CLOCK_REALTIME by leap second
	/// smearing, this clock will not be precise during leap second smearing.
	///
	/// The acronym TAI refers to International Atomic Time.
	pub struct Tai;

	impl ClockSource for Tai {
	const ID: bindings::clockid_t = bindings::CLOCK_TAI as bindings::clockid_t;

	fn ktime_get() -> bindings::ktime_t {
	// SAFETY: It is always safe to call `ktime_get_tai()` outside of NMI context.
	unsafe { bindings::ktime_get_clocktai() }
	}
	}

	/// A specific point in time.
	///
	/// # Invariants
	///
	/// The `inner` value is in the range from 0 to `KTIME_MAX`.
	#[repr(transparent)]
	#[derive(PartialEq, PartialOrd, Eq, Ord)]
	pub struct Instant<C: ClockSource> {
	inner: bindings::ktime_t,
	_c: PhantomData<C>,
	}

	impl<C: ClockSource> Clone for Instant<C> {
	fn clone(&self) -> Self {
	*self
	}
	}

	impl<C: ClockSource> Copy for Instant<C> {}

	impl<C: ClockSource> Instant<C> {
	/// Get the current time from the clock source.
	#[inline]
	pub fn now() -> Self {
	// INVARIANT: The `ClockSource::ktime_get()` function returns a value in the range
	// from 0 to `KTIME_MAX`.
	Self {
	inner: C::ktime_get(),
	_c: PhantomData,
	}
	}

	/// Return the amount of time elapsed since the [`Instant`].
	#[inline]
	pub fn elapsed(&self) -> Delta {
	Self::now() - *self
	}

	#[inline]
	pub(crate) fn as_nanos(&self) -> i64 {
	self.inner
	}
	}

	impl<C: ClockSource> core::ops::Sub for Instant<C> {
	type Output = Delta;

	// By the type invariant, it never overflows.
	#[inline]
	fn sub(self, other: Instant<C>) -> Delta {
	Delta {
	nanos: self.inner - other.inner,
	}
	}
	}

	/// A span of time.
	///
	/// This struct represents a span of time, with its value stored as nanoseconds.
	/// The value can represent any valid i64 value, including negative, zero, and
	/// positive numbers.
	#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]
	pub struct Delta {
	nanos: i64,
	}

	impl Delta {
	/// A span of time equal to zero.
	pub const ZERO: Self = Self { nanos: 0 };

	/// Create a new [`Delta`] from a number of microseconds.
	///
	/// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775.
	/// If `micros` is outside this range, `i64::MIN` is used for negative values,
	/// and `i64::MAX` is used for positive values due to saturation.
	#[inline]
	pub const fn from_micros(micros: i64) -> Self {
	Self {
	nanos: micros.saturating_mul(NSEC_PER_USEC),
	}
	}

	/// Create a new [`Delta`] from a number of milliseconds.
	///
	/// The `millis` can range from -9_223_372_036_854 to 9_223_372_036_854.
	/// If `millis` is outside this range, `i64::MIN` is used for negative values,
	/// and `i64::MAX` is used for positive values due to saturation.
	#[inline]
	pub const fn from_millis(millis: i64) -> Self {
	Self {
	nanos: millis.saturating_mul(NSEC_PER_MSEC),
	}
	}

	/// Create a new [`Delta`] from a number of seconds.
	///
	/// The `secs` can range from -9_223_372_036 to 9_223_372_036.
	/// If `secs` is outside this range, `i64::MIN` is used for negative values,
	/// and `i64::MAX` is used for positive values due to saturation.
	#[inline]
	pub const fn from_secs(secs: i64) -> Self {
	Self {
	nanos: secs.saturating_mul(NSEC_PER_SEC),
	}
	}

	/// Return `true` if the [`Delta`] spans no time.
	#[inline]
	pub fn is_zero(self) -> bool {
	self.as_nanos() == 0
	}

	/// Return `true` if the [`Delta`] spans a negative amount of time.
	#[inline]
	pub fn is_negative(self) -> bool {
	self.as_nanos() < 0
	}

	/// Return the number of nanoseconds in the [`Delta`].
	#[inline]
	pub const fn as_nanos(self) -> i64 {
	self.nanos
	}

	/// Return the smallest number of microseconds greater than or equal
	/// to the value in the [`Delta`].
	#[inline]
	pub fn as_micros_ceil(self) -> i64 {
	#[cfg(CONFIG_64BIT)]
	{
	self.as_nanos().saturating_add(NSEC_PER_USEC - 1) / NSEC_PER_USEC
	}

	#[cfg(not(CONFIG_64BIT))]
	// SAFETY: It is always safe to call `ktime_to_us()` with any value.
	unsafe {
	bindings::ktime_to_us(self.as_nanos().saturating_add(NSEC_PER_USEC - 1))
	}
	}

	/// Return the number of milliseconds in the [`Delta`].
	#[inline]
	pub fn as_millis(self) -> i64 {
	#[cfg(CONFIG_64BIT)]
	{
	self.as_nanos() / NSEC_PER_MSEC
	}

	#[cfg(not(CONFIG_64BIT))]
	// SAFETY: It is always safe to call `ktime_to_ms()` with any value.
	unsafe {
	bindings::ktime_to_ms(self.as_nanos())
	}
	}
	}