projects/linux·blob v6.15 · refs

151 lines · 5.7 KiB

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
11pub mod hrtimer;
12
13/// The number of nanoseconds per millisecond.
14pub 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.
17pub type Jiffies = crate::ffi::c_ulong;
18
19/// The millisecond time unit.
20pub type Msecs = crate::ffi::c_uint;
21
22/// Converts milliseconds to jiffies.
23#[inline]
24pub 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)]
33pub struct Ktime {
34 inner: bindings::ktime_t,
35}
36
37impl 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]
72pub fn ktime_ms_delta(later: Ktime, earlier: Ktime) -> i64 {
73 (later - earlier).to_ms()
74}
75
76impl 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)]
97pub 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
147impl ClockId {
148 fn into_c(self) -> bindings::clockid_t {
149 self as bindings::clockid_t
150 }
151}