timekeeping.rst (7405B)
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.