0001 ktime accessors
0002 ===============
0003
0004 Device drivers can read the current time using ktime_get() and the many
0005 related functions declared in linux/timekeeping.h. As a rule of thumb,
0006 using an accessor with a shorter name is preferred over one with a longer
0007 name if both are equally fit for a particular use case.
0008
0009 Basic ktime_t based interfaces
0010 ------------------------------
0011
0012 The recommended simplest form returns an opaque ktime_t, with variants
0013 that return time for different clock references:
0014
0015
0016 .. c:function:: ktime_t ktime_get( void )
0017
0018 CLOCK_MONOTONIC
0019
0020 Useful for reliable timestamps and measuring short time intervals
0021 accurately. Starts at system boot time but stops during suspend.
0022
0023 .. c:function:: ktime_t ktime_get_boottime( void )
0024
0025 CLOCK_BOOTTIME
0026
0027 Like ktime_get(), but does not stop when suspended. This can be
0028 used e.g. for key expiration times that need to be synchronized
0029 with other machines across a suspend operation.
0030
0031 .. c:function:: ktime_t ktime_get_real( void )
0032
0033 CLOCK_REALTIME
0034
0035 Returns the time in relative to the UNIX epoch starting in 1970
0036 using the Coordinated Universal Time (UTC), same as gettimeofday()
0037 user space. This is used for all timestamps that need to
0038 persist across a reboot, like inode times, but should be avoided
0039 for internal uses, since it can jump backwards due to a leap
0040 second update, NTP adjustment settimeofday() operation from user
0041 space.
0042
0043 .. c:function:: ktime_t ktime_get_clocktai( void )
0044
0045 CLOCK_TAI
0046
0047 Like ktime_get_real(), but uses the International Atomic Time (TAI)
0048 reference instead of UTC to avoid jumping on leap second updates.
0049 This is rarely useful in the kernel.
0050
0051 .. c:function:: ktime_t ktime_get_raw( void )
0052
0053 CLOCK_MONOTONIC_RAW
0054
0055 Like ktime_get(), but runs at the same rate as the hardware
0056 clocksource without (NTP) adjustments for clock drift. This is
0057 also rarely needed in the kernel.
0058
0059 nanosecond, timespec64, and second output
0060 -----------------------------------------
0061
0062 For all of the above, there are variants that return the time in a
0063 different format depending on what is required by the user:
0064
0065 .. c:function:: u64 ktime_get_ns( void )
0066 u64 ktime_get_boottime_ns( void )
0067 u64 ktime_get_real_ns( void )
0068 u64 ktime_get_clocktai_ns( void )
0069 u64 ktime_get_raw_ns( void )
0070
0071 Same as the plain ktime_get functions, but returning a u64 number
0072 of nanoseconds in the respective time reference, which may be
0073 more convenient for some callers.
0074
0075 .. c:function:: void ktime_get_ts64( struct timespec64 * )
0076 void ktime_get_boottime_ts64( struct timespec64 * )
0077 void ktime_get_real_ts64( struct timespec64 * )
0078 void ktime_get_clocktai_ts64( struct timespec64 * )
0079 void ktime_get_raw_ts64( struct timespec64 * )
0080
0081 Same above, but returns the time in a 'struct timespec64', split
0082 into seconds and nanoseconds. This can avoid an extra division
0083 when printing the time, or when passing it into an external
0084 interface that expects a 'timespec' or 'timeval' structure.
0085
0086 .. c:function:: time64_t ktime_get_seconds( void )
0087 time64_t ktime_get_boottime_seconds( void )
0088 time64_t ktime_get_real_seconds( void )
0089 time64_t ktime_get_clocktai_seconds( void )
0090 time64_t ktime_get_raw_seconds( void )
0091
0092 Return a coarse-grained version of the time as a scalar
0093 time64_t. This avoids accessing the clock hardware and rounds
0094 down the seconds to the full seconds of the last timer tick
0095 using the respective reference.
0096
0097 Coarse and fast_ns access
0098 -------------------------
0099
0100 Some additional variants exist for more specialized cases:
0101
0102 .. c:function:: ktime_t ktime_get_coarse( void )
0103 ktime_t ktime_get_coarse_boottime( void )
0104 ktime_t ktime_get_coarse_real( void )
0105 ktime_t ktime_get_coarse_clocktai( void )
0106
0107 .. c:function:: u64 ktime_get_coarse_ns( void )
0108 u64 ktime_get_coarse_boottime_ns( void )
0109 u64 ktime_get_coarse_real_ns( void )
0110 u64 ktime_get_coarse_clocktai_ns( void )
0111
0112 .. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
0113 void ktime_get_coarse_boottime_ts64( struct timespec64 * )
0114 void ktime_get_coarse_real_ts64( struct timespec64 * )
0115 void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
0116
0117 These are quicker than the non-coarse versions, but less accurate,
0118 corresponding to CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE
0119 in user space, along with the equivalent boottime/tai/raw
0120 timebase not available in user space.
0121
0122 The time returned here corresponds to the last timer tick, which
0123 may be as much as 10ms in the past (for CONFIG_HZ=100), same as
0124 reading the 'jiffies' variable. These are only useful when called
0125 in a fast path and one still expects better than second accuracy,
0126 but can't easily use 'jiffies', e.g. for inode timestamps.
0127 Skipping the hardware clock access saves around 100 CPU cycles
0128 on most modern machines with a reliable cycle counter, but
0129 up to several microseconds on older hardware with an external
0130 clocksource.
0131
0132 .. c:function:: u64 ktime_get_mono_fast_ns( void )
0133 u64 ktime_get_raw_fast_ns( void )
0134 u64 ktime_get_boot_fast_ns( void )
0135 u64 ktime_get_tai_fast_ns( void )
0136 u64 ktime_get_real_fast_ns( void )
0137
0138 These variants are safe to call from any context, including from
0139 a non-maskable interrupt (NMI) during a timekeeper update, and
0140 while we are entering suspend with the clocksource powered down.
0141 This is useful in some tracing or debugging code as well as
0142 machine check reporting, but most drivers should never call them,
0143 since the time is allowed to jump under certain conditions.
0144
0145 Deprecated time interfaces
0146 --------------------------
0147
0148 Older kernels used some other interfaces that are now being phased out
0149 but may appear in third-party drivers being ported here. In particular,
0150 all interfaces returning a 'struct timeval' or 'struct timespec' have
0151 been replaced because the tv_sec member overflows in year 2038 on 32-bit
0152 architectures. These are the recommended replacements:
0153
0154 .. c:function:: void ktime_get_ts( struct timespec * )
0155
0156 Use ktime_get() or ktime_get_ts64() instead.
0157
0158 .. c:function:: void do_gettimeofday( struct timeval * )
0159 void getnstimeofday( struct timespec * )
0160 void getnstimeofday64( struct timespec64 * )
0161 void ktime_get_real_ts( struct timespec * )
0162
0163 ktime_get_real_ts64() is a direct replacement, but consider using
0164 monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
0165 (ktime_get()/ktime_get_real()).
0166
0167 .. c:function:: struct timespec current_kernel_time( void )
0168 struct timespec64 current_kernel_time64( void )
0169 struct timespec get_monotonic_coarse( void )
0170 struct timespec64 get_monotonic_coarse64( void )
0171
0172 These are replaced by ktime_get_coarse_real_ts64() and
0173 ktime_get_coarse_ts64(). However, A lot of code that wants
0174 coarse-grained times can use the simple 'jiffies' instead, while
0175 some drivers may actually want the higher resolution accessors
0176 these days.
0177
0178 .. c:function:: struct timespec getrawmonotonic( void )
0179 struct timespec64 getrawmonotonic64( void )
0180 struct timespec timekeeping_clocktai( void )
0181 struct timespec64 timekeeping_clocktai64( void )
0182 struct timespec get_monotonic_boottime( void )
0183 struct timespec64 get_monotonic_boottime64( void )
0184
0185 These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
0186 ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
0187 as ktime_get_boottime()/ktime_get_boottime_ts64().
0188 However, if the particular choice of clock source is not
0189 important for the user, consider converting to
0190 ktime_get()/ktime_get_ts64() instead for consistency.
