1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Time related primitives. 4 //! 5 //! This module contains the kernel APIs related to time and timers that 6 //! have been ported or wrapped for usage by Rust code in the kernel. 7 //! 8 //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h). 9 //! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h). 10 11 pub mod hrtimer; 12 13 /// The number of nanoseconds per millisecond. 14 pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64; 15 16 /// The time unit of Linux kernel. One jiffy equals (1/HZ) second. 17 pub type Jiffies = crate::ffi::c_ulong; 18 19 /// The millisecond time unit. 20 pub type Msecs = crate::ffi::c_uint; 21 22 /// Converts milliseconds to jiffies. 23 #[inline] 24 pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies { 25 // SAFETY: The `__msecs_to_jiffies` function is always safe to call no 26 // matter what the argument is. 27 unsafe { bindings::__msecs_to_jiffies(msecs) } 28 } 29 30 /// A Rust wrapper around a `ktime_t`. 31 #[repr(transparent)] 32 #[derive(Copy, Clone)] 33 pub struct Ktime { 34 inner: bindings::ktime_t, 35 } 36 37 impl Ktime { 38 /// Create a `Ktime` from a raw `ktime_t`. 39 #[inline] 40 pub fn from_raw(inner: bindings::ktime_t) -> Self { 41 Self { inner } 42 } 43 44 /// Get the current time using `CLOCK_MONOTONIC`. 45 #[inline] 46 pub fn ktime_get() -> Self { 47 // SAFETY: It is always safe to call `ktime_get` outside of NMI context. 48 Self::from_raw(unsafe { bindings::ktime_get() }) 49 } 50 51 /// Divide the number of nanoseconds by a compile-time constant. 52 #[inline] 53 fn divns_constant<const DIV: i64>(self) -> i64 { 54 self.to_ns() / DIV 55 } 56 57 /// Returns the number of nanoseconds. 58 #[inline] 59 pub fn to_ns(self) -> i64 { 60 self.inner 61 } 62 63 /// Returns the number of milliseconds. 64 #[inline] 65 pub fn to_ms(self) -> i64 { 66 self.divns_constant::<NSEC_PER_MSEC>() 67 } 68 } 69 70 /// Returns the number of milliseconds between two ktimes. 71 #[inline] 72 pub fn ktime_ms_delta(later: Ktime, earlier: Ktime) -> i64 { 73 (later - earlier).to_ms() 74 } 75 76 impl core::ops::Sub for Ktime { 77 type Output = Ktime; 78 79 #[inline] 80 fn sub(self, other: Ktime) -> Ktime { 81 Self { 82 inner: self.inner - other.inner, 83 } 84 } 85 } 86 87 /// An identifier for a clock. Used when specifying clock sources. 88 /// 89 /// 90 /// Selection of the clock depends on the use case. In some cases the usage of a 91 /// particular clock is mandatory, e.g. in network protocols, filesystems.In other 92 /// cases the user of the clock has to decide which clock is best suited for the 93 /// purpose. In most scenarios clock [`ClockId::Monotonic`] is the best choice as it 94 /// provides a accurate monotonic notion of time (leap second smearing ignored). 95 #[derive(Clone, Copy, PartialEq, Eq, Debug)] 96 #[repr(u32)] 97 pub enum ClockId { 98 /// A settable system-wide clock that measures real (i.e., wall-clock) time. 99 /// 100 /// Setting this clock requires appropriate privileges. This clock is 101 /// affected by discontinuous jumps in the system time (e.g., if the system 102 /// administrator manually changes the clock), and by frequency adjustments 103 /// performed by NTP and similar applications via adjtime(3), adjtimex(2), 104 /// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the 105 /// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time 106 /// (UTC) except that it ignores leap seconds; near a leap second it may be 107 /// adjusted by leap second smearing to stay roughly in sync with UTC. Leap 108 /// second smearing applies frequency adjustments to the clock to speed up 109 /// or slow down the clock to account for the leap second without 110 /// discontinuities in the clock. If leap second smearing is not applied, 111 /// the clock will experience discontinuity around leap second adjustment. 112 RealTime = bindings::CLOCK_REALTIME, 113 /// A monotonically increasing clock. 114 /// 115 /// A nonsettable system-wide clock that represents monotonic time since—as 116 /// described by POSIX—"some unspecified point in the past". On Linux, that 117 /// point corresponds to the number of seconds that the system has been 118 /// running since it was booted. 119 /// 120 /// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the 121 /// CLOCK_REAL (e.g., if the system administrator manually changes the 122 /// clock), but is affected by frequency adjustments. This clock does not 123 /// count time that the system is suspended. 124 Monotonic = bindings::CLOCK_MONOTONIC, 125 /// A monotonic that ticks while system is suspended. 126 /// 127 /// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC, 128 /// except that it also includes any time that the system is suspended. This 129 /// allows applications to get a suspend-aware monotonic clock without 130 /// having to deal with the complications of CLOCK_REALTIME, which may have 131 /// discontinuities if the time is changed using settimeofday(2) or similar. 132 BootTime = bindings::CLOCK_BOOTTIME, 133 /// International Atomic Time. 134 /// 135 /// A system-wide clock derived from wall-clock time but counting leap seconds. 136 /// 137 /// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is 138 /// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This 139 /// usually happens during boot and **should** not happen during normal operations. 140 /// However, if NTP or another application adjusts CLOCK_REALTIME by leap second 141 /// smearing, this clock will not be precise during leap second smearing. 142 /// 143 /// The acronym TAI refers to International Atomic Time. 144 TAI = bindings::CLOCK_TAI, 145 } 146 147 impl ClockId { 148 fn into_c(self) -> bindings::clockid_t { 149 self as bindings::clockid_t 150 } 151 } 152