1ktime accessors
2===============
3
4Device drivers can read the current time using ktime_get() and the many
5related functions declared in linux/timekeeping.h. As a rule of thumb,
6using an accessor with a shorter name is preferred over one with a longer
7name if both are equally fit for a particular use case.
8
9Basic ktime_t based interfaces
10------------------------------
11
12The recommended simplest form returns an opaque ktime_t, with variants
13that 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
59nanosecond, timespec64, and second output
60-----------------------------------------
61
62For all of the above, there are variants that return the time in a
63different 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 )
68		u64 ktime_get_clocktai_ns( void )
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
97Coarse and fast_ns access
98-------------------------
99
100Some additional variants exist for more specialized cases:
101
102.. c:function:: ktime_t ktime_get_coarse( void )
103		ktime_t ktime_get_coarse_boottime( void )
104		ktime_t ktime_get_coarse_real( void )
105		ktime_t ktime_get_coarse_clocktai( void )
106
107.. c:function:: u64 ktime_get_coarse_ns( void )
108		u64 ktime_get_coarse_boottime_ns( void )
109		u64 ktime_get_coarse_real_ns( void )
110		u64 ktime_get_coarse_clocktai_ns( void )
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 * )
116
117	These are quicker than the non-coarse versions, but less accurate,
118	corresponding to CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE
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 )
135		u64 ktime_get_tai_fast_ns( void )
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
145Deprecated time interfaces
146--------------------------
147
148Older kernels used some other interfaces that are now being phased out
149but may appear in third-party drivers being ported here. In particular,
150all interfaces returning a 'struct timeval' or 'struct timespec' have
151been replaced because the tv_sec member overflows in year 2038 on 32-bit
152architectures. 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
158.. c:function:: void do_gettimeofday( struct timeval * )
159		void getnstimeofday( struct timespec * )
160		void getnstimeofday64( struct timespec64 * )
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.
191