Commit | Line | Data |
---|---|---|
0e3fd810 AB |
1 | ktime accessors |
2 | =============== | |
3 | ||
4 | Device drivers can read the current time using ktime_get() and the many | |
5 | related functions declared in linux/timekeeping.h. As a rule of thumb, | |
6 | using an accessor with a shorter name is preferred over one with a longer | |
7 | name if both are equally fit for a particular use case. | |
8 | ||
9 | Basic ktime_t based interfaces | |
10 | ------------------------------ | |
11 | ||
12 | The recommended simplest form returns an opaque ktime_t, with variants | |
13 | that return time for different clock references: | |
14 | ||
15 | ||
16 | .. c:function:: ktime_t ktime_get( void ) | |
17 | ||
18 | CLOCK_MONOTONIC | |
19 | ||
20 | Useful for reliable timestamps and measuring short time intervals | |
21 | accurately. Starts at system boot time but stops during suspend. | |
22 | ||
23 | .. c:function:: ktime_t ktime_get_boottime( void ) | |
24 | ||
25 | CLOCK_BOOTTIME | |
26 | ||
27 | Like ktime_get(), but does not stop when suspended. This can be | |
28 | used e.g. for key expiration times that need to be synchronized | |
29 | with other machines across a suspend operation. | |
30 | ||
31 | .. c:function:: ktime_t ktime_get_real( void ) | |
32 | ||
33 | CLOCK_REALTIME | |
34 | ||
35 | Returns the time in relative to the UNIX epoch starting in 1970 | |
36 | using the Coordinated Universal Time (UTC), same as gettimeofday() | |
37 | user space. This is used for all timestamps that need to | |
38 | persist across a reboot, like inode times, but should be avoided | |
39 | for internal uses, since it can jump backwards due to a leap | |
40 | second update, NTP adjustment settimeofday() operation from user | |
41 | space. | |
42 | ||
43 | .. c:function:: ktime_t ktime_get_clocktai( void ) | |
44 | ||
45 | CLOCK_TAI | |
46 | ||
47 | Like ktime_get_real(), but uses the International Atomic Time (TAI) | |
48 | reference instead of UTC to avoid jumping on leap second updates. | |
49 | This is rarely useful in the kernel. | |
50 | ||
51 | .. c:function:: ktime_t ktime_get_raw( void ) | |
52 | ||
53 | CLOCK_MONOTONIC_RAW | |
54 | ||
55 | Like ktime_get(), but runs at the same rate as the hardware | |
56 | clocksource without (NTP) adjustments for clock drift. This is | |
57 | also rarely needed in the kernel. | |
58 | ||
59 | nanosecond, timespec64, and second output | |
60 | ----------------------------------------- | |
61 | ||
62 | For all of the above, there are variants that return the time in a | |
63 | different format depending on what is required by the user: | |
64 | ||
65 | .. c:function:: u64 ktime_get_ns( void ) | |
66 | u64 ktime_get_boottime_ns( void ) | |
67 | u64 ktime_get_real_ns( void ) | |
9285ec4c | 68 | u64 ktime_get_clocktai_ns( void ) |
0e3fd810 AB |
69 | u64 ktime_get_raw_ns( void ) |
70 | ||
71 | Same as the plain ktime_get functions, but returning a u64 number | |
72 | of nanoseconds in the respective time reference, which may be | |
73 | more convenient for some callers. | |
74 | ||
75 | .. c:function:: void ktime_get_ts64( struct timespec64 * ) | |
76 | void ktime_get_boottime_ts64( struct timespec64 * ) | |
77 | void ktime_get_real_ts64( struct timespec64 * ) | |
78 | void ktime_get_clocktai_ts64( struct timespec64 * ) | |
79 | void ktime_get_raw_ts64( struct timespec64 * ) | |
80 | ||
81 | Same above, but returns the time in a 'struct timespec64', split | |
82 | into seconds and nanoseconds. This can avoid an extra division | |
83 | when printing the time, or when passing it into an external | |
84 | interface that expects a 'timespec' or 'timeval' structure. | |
85 | ||
86 | .. c:function:: time64_t ktime_get_seconds( void ) | |
87 | time64_t ktime_get_boottime_seconds( void ) | |
88 | time64_t ktime_get_real_seconds( void ) | |
89 | time64_t ktime_get_clocktai_seconds( void ) | |
90 | time64_t ktime_get_raw_seconds( void ) | |
91 | ||
92 | Return a coarse-grained version of the time as a scalar | |
93 | time64_t. This avoids accessing the clock hardware and rounds | |
94 | down the seconds to the full seconds of the last timer tick | |
95 | using the respective reference. | |
96 | ||
97 | Coarse and fast_ns access | |
98 | ------------------------- | |
99 | ||
100 | Some additional variants exist for more specialized cases: | |
101 | ||
4c54294d JD |
102 | .. c:function:: ktime_t ktime_get_coarse( void ) |
103 | ktime_t ktime_get_coarse_boottime( void ) | |
0e3fd810 AB |
104 | ktime_t ktime_get_coarse_real( void ) |
105 | ktime_t ktime_get_coarse_clocktai( void ) | |
4c54294d JD |
106 | |
107 | .. c:function:: u64 ktime_get_coarse_ns( void ) | |
d48e0cd8 | 108 | u64 ktime_get_coarse_boottime_ns( void ) |
4c54294d JD |
109 | u64 ktime_get_coarse_real_ns( void ) |
110 | u64 ktime_get_coarse_clocktai_ns( void ) | |
0e3fd810 AB |
111 | |
112 | .. c:function:: void ktime_get_coarse_ts64( struct timespec64 * ) | |
113 | void ktime_get_coarse_boottime_ts64( struct timespec64 * ) | |
114 | void ktime_get_coarse_real_ts64( struct timespec64 * ) | |
115 | void ktime_get_coarse_clocktai_ts64( struct timespec64 * ) | |
0e3fd810 AB |
116 | |
117 | These are quicker than the non-coarse versions, but less accurate, | |
e0cef9ff | 118 | corresponding to CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE |
0e3fd810 AB |
119 | in user space, along with the equivalent boottime/tai/raw |
120 | timebase not available in user space. | |
121 | ||
122 | The time returned here corresponds to the last timer tick, which | |
123 | may be as much as 10ms in the past (for CONFIG_HZ=100), same as | |
124 | reading the 'jiffies' variable. These are only useful when called | |
125 | in a fast path and one still expects better than second accuracy, | |
126 | but can't easily use 'jiffies', e.g. for inode timestamps. | |
127 | Skipping the hardware clock access saves around 100 CPU cycles | |
128 | on most modern machines with a reliable cycle counter, but | |
129 | up to several microseconds on older hardware with an external | |
130 | clocksource. | |
131 | ||
132 | .. c:function:: u64 ktime_get_mono_fast_ns( void ) | |
133 | u64 ktime_get_raw_fast_ns( void ) | |
134 | u64 ktime_get_boot_fast_ns( void ) | |
3dc6ffae | 135 | u64 ktime_get_tai_fast_ns( void ) |
0e3fd810 AB |
136 | u64 ktime_get_real_fast_ns( void ) |
137 | ||
138 | These variants are safe to call from any context, including from | |
139 | a non-maskable interrupt (NMI) during a timekeeper update, and | |
140 | while we are entering suspend with the clocksource powered down. | |
141 | This is useful in some tracing or debugging code as well as | |
142 | machine check reporting, but most drivers should never call them, | |
143 | since the time is allowed to jump under certain conditions. | |
144 | ||
145 | Deprecated time interfaces | |
146 | -------------------------- | |
147 | ||
148 | Older kernels used some other interfaces that are now being phased out | |
149 | but may appear in third-party drivers being ported here. In particular, | |
150 | all interfaces returning a 'struct timeval' or 'struct timespec' have | |
151 | been replaced because the tv_sec member overflows in year 2038 on 32-bit | |
152 | architectures. These are the recommended replacements: | |
153 | ||
154 | .. c:function:: void ktime_get_ts( struct timespec * ) | |
155 | ||
156 | Use ktime_get() or ktime_get_ts64() instead. | |
157 | ||
404e603f CP |
158 | .. c:function:: void do_gettimeofday( struct timeval * ) |
159 | void getnstimeofday( struct timespec * ) | |
160 | void getnstimeofday64( struct timespec64 * ) | |
0e3fd810 AB |
161 | void ktime_get_real_ts( struct timespec * ) |
162 | ||
163 | ktime_get_real_ts64() is a direct replacement, but consider using | |
164 | monotonic time (ktime_get_ts64()) and/or a ktime_t based interface | |
165 | (ktime_get()/ktime_get_real()). | |
166 | ||
167 | .. c:function:: struct timespec current_kernel_time( void ) | |
168 | struct timespec64 current_kernel_time64( void ) | |
169 | struct timespec get_monotonic_coarse( void ) | |
170 | struct timespec64 get_monotonic_coarse64( void ) | |
171 | ||
172 | These are replaced by ktime_get_coarse_real_ts64() and | |
173 | ktime_get_coarse_ts64(). However, A lot of code that wants | |
174 | coarse-grained times can use the simple 'jiffies' instead, while | |
175 | some drivers may actually want the higher resolution accessors | |
176 | these days. | |
177 | ||
178 | .. c:function:: struct timespec getrawmonotonic( void ) | |
179 | struct timespec64 getrawmonotonic64( void ) | |
180 | struct timespec timekeeping_clocktai( void ) | |
181 | struct timespec64 timekeeping_clocktai64( void ) | |
182 | struct timespec get_monotonic_boottime( void ) | |
183 | struct timespec64 get_monotonic_boottime64( void ) | |
184 | ||
185 | These are replaced by ktime_get_raw()/ktime_get_raw_ts64(), | |
186 | ktime_get_clocktai()/ktime_get_clocktai_ts64() as well | |
187 | as ktime_get_boottime()/ktime_get_boottime_ts64(). | |
188 | However, if the particular choice of clock source is not | |
189 | important for the user, consider converting to | |
190 | ktime_get()/ktime_get_ts64() instead for consistency. |