10e3fd810SArnd Bergmannktime accessors 20e3fd810SArnd Bergmann=============== 30e3fd810SArnd Bergmann 40e3fd810SArnd BergmannDevice drivers can read the current time using ktime_get() and the many 50e3fd810SArnd Bergmannrelated functions declared in linux/timekeeping.h. As a rule of thumb, 60e3fd810SArnd Bergmannusing an accessor with a shorter name is preferred over one with a longer 70e3fd810SArnd Bergmannname if both are equally fit for a particular use case. 80e3fd810SArnd Bergmann 90e3fd810SArnd BergmannBasic ktime_t based interfaces 100e3fd810SArnd Bergmann------------------------------ 110e3fd810SArnd Bergmann 120e3fd810SArnd BergmannThe recommended simplest form returns an opaque ktime_t, with variants 130e3fd810SArnd Bergmannthat return time for different clock references: 140e3fd810SArnd Bergmann 150e3fd810SArnd Bergmann 160e3fd810SArnd Bergmann.. c:function:: ktime_t ktime_get( void ) 170e3fd810SArnd Bergmann 180e3fd810SArnd Bergmann CLOCK_MONOTONIC 190e3fd810SArnd Bergmann 200e3fd810SArnd Bergmann Useful for reliable timestamps and measuring short time intervals 210e3fd810SArnd Bergmann accurately. Starts at system boot time but stops during suspend. 220e3fd810SArnd Bergmann 230e3fd810SArnd Bergmann.. c:function:: ktime_t ktime_get_boottime( void ) 240e3fd810SArnd Bergmann 250e3fd810SArnd Bergmann CLOCK_BOOTTIME 260e3fd810SArnd Bergmann 270e3fd810SArnd Bergmann Like ktime_get(), but does not stop when suspended. This can be 280e3fd810SArnd Bergmann used e.g. for key expiration times that need to be synchronized 290e3fd810SArnd Bergmann with other machines across a suspend operation. 300e3fd810SArnd Bergmann 310e3fd810SArnd Bergmann.. c:function:: ktime_t ktime_get_real( void ) 320e3fd810SArnd Bergmann 330e3fd810SArnd Bergmann CLOCK_REALTIME 340e3fd810SArnd Bergmann 350e3fd810SArnd Bergmann Returns the time in relative to the UNIX epoch starting in 1970 360e3fd810SArnd Bergmann using the Coordinated Universal Time (UTC), same as gettimeofday() 370e3fd810SArnd Bergmann user space. This is used for all timestamps that need to 380e3fd810SArnd Bergmann persist across a reboot, like inode times, but should be avoided 390e3fd810SArnd Bergmann for internal uses, since it can jump backwards due to a leap 400e3fd810SArnd Bergmann second update, NTP adjustment settimeofday() operation from user 410e3fd810SArnd Bergmann space. 420e3fd810SArnd Bergmann 430e3fd810SArnd Bergmann.. c:function:: ktime_t ktime_get_clocktai( void ) 440e3fd810SArnd Bergmann 450e3fd810SArnd Bergmann CLOCK_TAI 460e3fd810SArnd Bergmann 470e3fd810SArnd Bergmann Like ktime_get_real(), but uses the International Atomic Time (TAI) 480e3fd810SArnd Bergmann reference instead of UTC to avoid jumping on leap second updates. 490e3fd810SArnd Bergmann This is rarely useful in the kernel. 500e3fd810SArnd Bergmann 510e3fd810SArnd Bergmann.. c:function:: ktime_t ktime_get_raw( void ) 520e3fd810SArnd Bergmann 530e3fd810SArnd Bergmann CLOCK_MONOTONIC_RAW 540e3fd810SArnd Bergmann 550e3fd810SArnd Bergmann Like ktime_get(), but runs at the same rate as the hardware 560e3fd810SArnd Bergmann clocksource without (NTP) adjustments for clock drift. This is 570e3fd810SArnd Bergmann also rarely needed in the kernel. 580e3fd810SArnd Bergmann 590e3fd810SArnd Bergmannnanosecond, timespec64, and second output 600e3fd810SArnd Bergmann----------------------------------------- 610e3fd810SArnd Bergmann 620e3fd810SArnd BergmannFor all of the above, there are variants that return the time in a 630e3fd810SArnd Bergmanndifferent format depending on what is required by the user: 640e3fd810SArnd Bergmann 650e3fd810SArnd Bergmann.. c:function:: u64 ktime_get_ns( void ) 660e3fd810SArnd Bergmann u64 ktime_get_boottime_ns( void ) 670e3fd810SArnd Bergmann u64 ktime_get_real_ns( void ) 689285ec4cSJason A. Donenfeld u64 ktime_get_clocktai_ns( void ) 690e3fd810SArnd Bergmann u64 ktime_get_raw_ns( void ) 700e3fd810SArnd Bergmann 710e3fd810SArnd Bergmann Same as the plain ktime_get functions, but returning a u64 number 720e3fd810SArnd Bergmann of nanoseconds in the respective time reference, which may be 730e3fd810SArnd Bergmann more convenient for some callers. 740e3fd810SArnd Bergmann 750e3fd810SArnd Bergmann.. c:function:: void ktime_get_ts64( struct timespec64 * ) 760e3fd810SArnd Bergmann void ktime_get_boottime_ts64( struct timespec64 * ) 770e3fd810SArnd Bergmann void ktime_get_real_ts64( struct timespec64 * ) 780e3fd810SArnd Bergmann void ktime_get_clocktai_ts64( struct timespec64 * ) 790e3fd810SArnd Bergmann void ktime_get_raw_ts64( struct timespec64 * ) 800e3fd810SArnd Bergmann 810e3fd810SArnd Bergmann Same above, but returns the time in a 'struct timespec64', split 820e3fd810SArnd Bergmann into seconds and nanoseconds. This can avoid an extra division 830e3fd810SArnd Bergmann when printing the time, or when passing it into an external 840e3fd810SArnd Bergmann interface that expects a 'timespec' or 'timeval' structure. 850e3fd810SArnd Bergmann 860e3fd810SArnd Bergmann.. c:function:: time64_t ktime_get_seconds( void ) 870e3fd810SArnd Bergmann time64_t ktime_get_boottime_seconds( void ) 880e3fd810SArnd Bergmann time64_t ktime_get_real_seconds( void ) 890e3fd810SArnd Bergmann time64_t ktime_get_clocktai_seconds( void ) 900e3fd810SArnd Bergmann time64_t ktime_get_raw_seconds( void ) 910e3fd810SArnd Bergmann 920e3fd810SArnd Bergmann Return a coarse-grained version of the time as a scalar 930e3fd810SArnd Bergmann time64_t. This avoids accessing the clock hardware and rounds 940e3fd810SArnd Bergmann down the seconds to the full seconds of the last timer tick 950e3fd810SArnd Bergmann using the respective reference. 960e3fd810SArnd Bergmann 970e3fd810SArnd BergmannCoarse and fast_ns access 980e3fd810SArnd Bergmann------------------------- 990e3fd810SArnd Bergmann 1000e3fd810SArnd BergmannSome additional variants exist for more specialized cases: 1010e3fd810SArnd Bergmann 1024c54294dSJason A. Donenfeld.. c:function:: ktime_t ktime_get_coarse( void ) 1034c54294dSJason A. Donenfeld ktime_t ktime_get_coarse_boottime( void ) 1040e3fd810SArnd Bergmann ktime_t ktime_get_coarse_real( void ) 1050e3fd810SArnd Bergmann ktime_t ktime_get_coarse_clocktai( void ) 1064c54294dSJason A. Donenfeld 1074c54294dSJason A. Donenfeld.. c:function:: u64 ktime_get_coarse_ns( void ) 108d48e0cd8SJason A. Donenfeld u64 ktime_get_coarse_boottime_ns( void ) 1094c54294dSJason A. Donenfeld u64 ktime_get_coarse_real_ns( void ) 1104c54294dSJason A. Donenfeld u64 ktime_get_coarse_clocktai_ns( void ) 1110e3fd810SArnd Bergmann 1120e3fd810SArnd Bergmann.. c:function:: void ktime_get_coarse_ts64( struct timespec64 * ) 1130e3fd810SArnd Bergmann void ktime_get_coarse_boottime_ts64( struct timespec64 * ) 1140e3fd810SArnd Bergmann void ktime_get_coarse_real_ts64( struct timespec64 * ) 1150e3fd810SArnd Bergmann void ktime_get_coarse_clocktai_ts64( struct timespec64 * ) 1160e3fd810SArnd Bergmann 1170e3fd810SArnd Bergmann These are quicker than the non-coarse versions, but less accurate, 118e0cef9ffSAurelien Thierry corresponding to CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE 1190e3fd810SArnd Bergmann in user space, along with the equivalent boottime/tai/raw 1200e3fd810SArnd Bergmann timebase not available in user space. 1210e3fd810SArnd Bergmann 1220e3fd810SArnd Bergmann The time returned here corresponds to the last timer tick, which 1230e3fd810SArnd Bergmann may be as much as 10ms in the past (for CONFIG_HZ=100), same as 1240e3fd810SArnd Bergmann reading the 'jiffies' variable. These are only useful when called 1250e3fd810SArnd Bergmann in a fast path and one still expects better than second accuracy, 1260e3fd810SArnd Bergmann but can't easily use 'jiffies', e.g. for inode timestamps. 1270e3fd810SArnd Bergmann Skipping the hardware clock access saves around 100 CPU cycles 1280e3fd810SArnd Bergmann on most modern machines with a reliable cycle counter, but 1290e3fd810SArnd Bergmann up to several microseconds on older hardware with an external 1300e3fd810SArnd Bergmann clocksource. 1310e3fd810SArnd Bergmann 1320e3fd810SArnd Bergmann.. c:function:: u64 ktime_get_mono_fast_ns( void ) 1330e3fd810SArnd Bergmann u64 ktime_get_raw_fast_ns( void ) 1340e3fd810SArnd Bergmann u64 ktime_get_boot_fast_ns( void ) 135*3dc6ffaeSKurt Kanzenbach u64 ktime_get_tai_fast_ns( void ) 1360e3fd810SArnd Bergmann u64 ktime_get_real_fast_ns( void ) 1370e3fd810SArnd Bergmann 1380e3fd810SArnd Bergmann These variants are safe to call from any context, including from 1390e3fd810SArnd Bergmann a non-maskable interrupt (NMI) during a timekeeper update, and 1400e3fd810SArnd Bergmann while we are entering suspend with the clocksource powered down. 1410e3fd810SArnd Bergmann This is useful in some tracing or debugging code as well as 1420e3fd810SArnd Bergmann machine check reporting, but most drivers should never call them, 1430e3fd810SArnd Bergmann since the time is allowed to jump under certain conditions. 1440e3fd810SArnd Bergmann 1450e3fd810SArnd BergmannDeprecated time interfaces 1460e3fd810SArnd Bergmann-------------------------- 1470e3fd810SArnd Bergmann 1480e3fd810SArnd BergmannOlder kernels used some other interfaces that are now being phased out 1490e3fd810SArnd Bergmannbut may appear in third-party drivers being ported here. In particular, 1500e3fd810SArnd Bergmannall interfaces returning a 'struct timeval' or 'struct timespec' have 1510e3fd810SArnd Bergmannbeen replaced because the tv_sec member overflows in year 2038 on 32-bit 1520e3fd810SArnd Bergmannarchitectures. These are the recommended replacements: 1530e3fd810SArnd Bergmann 1540e3fd810SArnd Bergmann.. c:function:: void ktime_get_ts( struct timespec * ) 1550e3fd810SArnd Bergmann 1560e3fd810SArnd Bergmann Use ktime_get() or ktime_get_ts64() instead. 1570e3fd810SArnd Bergmann 158404e603fSChris Packham.. c:function:: void do_gettimeofday( struct timeval * ) 159404e603fSChris Packham void getnstimeofday( struct timespec * ) 160404e603fSChris Packham void getnstimeofday64( struct timespec64 * ) 1610e3fd810SArnd Bergmann void ktime_get_real_ts( struct timespec * ) 1620e3fd810SArnd Bergmann 1630e3fd810SArnd Bergmann ktime_get_real_ts64() is a direct replacement, but consider using 1640e3fd810SArnd Bergmann monotonic time (ktime_get_ts64()) and/or a ktime_t based interface 1650e3fd810SArnd Bergmann (ktime_get()/ktime_get_real()). 1660e3fd810SArnd Bergmann 1670e3fd810SArnd Bergmann.. c:function:: struct timespec current_kernel_time( void ) 1680e3fd810SArnd Bergmann struct timespec64 current_kernel_time64( void ) 1690e3fd810SArnd Bergmann struct timespec get_monotonic_coarse( void ) 1700e3fd810SArnd Bergmann struct timespec64 get_monotonic_coarse64( void ) 1710e3fd810SArnd Bergmann 1720e3fd810SArnd Bergmann These are replaced by ktime_get_coarse_real_ts64() and 1730e3fd810SArnd Bergmann ktime_get_coarse_ts64(). However, A lot of code that wants 1740e3fd810SArnd Bergmann coarse-grained times can use the simple 'jiffies' instead, while 1750e3fd810SArnd Bergmann some drivers may actually want the higher resolution accessors 1760e3fd810SArnd Bergmann these days. 1770e3fd810SArnd Bergmann 1780e3fd810SArnd Bergmann.. c:function:: struct timespec getrawmonotonic( void ) 1790e3fd810SArnd Bergmann struct timespec64 getrawmonotonic64( void ) 1800e3fd810SArnd Bergmann struct timespec timekeeping_clocktai( void ) 1810e3fd810SArnd Bergmann struct timespec64 timekeeping_clocktai64( void ) 1820e3fd810SArnd Bergmann struct timespec get_monotonic_boottime( void ) 1830e3fd810SArnd Bergmann struct timespec64 get_monotonic_boottime64( void ) 1840e3fd810SArnd Bergmann 1850e3fd810SArnd Bergmann These are replaced by ktime_get_raw()/ktime_get_raw_ts64(), 1860e3fd810SArnd Bergmann ktime_get_clocktai()/ktime_get_clocktai_ts64() as well 1870e3fd810SArnd Bergmann as ktime_get_boottime()/ktime_get_boottime_ts64(). 1880e3fd810SArnd Bergmann However, if the particular choice of clock source is not 1890e3fd810SArnd Bergmann important for the user, consider converting to 1900e3fd810SArnd Bergmann ktime_get()/ktime_get_ts64() instead for consistency. 191