Documentation/core-api/timekeeping.rst

   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 )
  68                 u64 ktime_get_tai_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
  97 Coarse and fast_ns access
  98 -------------------------
  99
 100 Some additional variants exist for more specialized cases:
 101
 102 .. c:function:: ktime_t ktime_get_coarse_boottime( void )
 103                 ktime_t ktime_get_coarse_real( void )
 104                 ktime_t ktime_get_coarse_clocktai( void )
 105                 ktime_t ktime_get_coarse_raw( void )
 106
 107 .. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
 108                 void ktime_get_coarse_boottime_ts64( struct timespec64 * )
 109                 void ktime_get_coarse_real_ts64( struct timespec64 * )
 110                 void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
 111                 void ktime_get_coarse_raw_ts64( struct timespec64 * )
 112
 113         These are quicker than the non-coarse versions, but less accurate,
 114         corresponding to CLOCK_MONONOTNIC_COARSE and CLOCK_REALTIME_COARSE
 115         in user space, along with the equivalent boottime/tai/raw
 116         timebase not available in user space.
 117
 118         The time returned here corresponds to the last timer tick, which
 119         may be as much as 10ms in the past (for CONFIG_HZ=100), same as
 120         reading the 'jiffies' variable.  These are only useful when called
 121         in a fast path and one still expects better than second accuracy,
 122         but can't easily use 'jiffies', e.g. for inode timestamps.
 123         Skipping the hardware clock access saves around 100 CPU cycles
 124         on most modern machines with a reliable cycle counter, but
 125         up to several microseconds on older hardware with an external
 126         clocksource.
 127
 128 .. c:function:: u64 ktime_get_mono_fast_ns( void )
 129                 u64 ktime_get_raw_fast_ns( void )
 130                 u64 ktime_get_boot_fast_ns( void )
 131                 u64 ktime_get_real_fast_ns( void )
 132
 133         These variants are safe to call from any context, including from
 134         a non-maskable interrupt (NMI) during a timekeeper update, and
 135         while we are entering suspend with the clocksource powered down.
 136         This is useful in some tracing or debugging code as well as
 137         machine check reporting, but most drivers should never call them,
 138         since the time is allowed to jump under certain conditions.
 139
 140 Deprecated time interfaces
 141 --------------------------
 142
 143 Older kernels used some other interfaces that are now being phased out
 144 but may appear in third-party drivers being ported here. In particular,
 145 all interfaces returning a 'struct timeval' or 'struct timespec' have
 146 been replaced because the tv_sec member overflows in year 2038 on 32-bit
 147 architectures. These are the recommended replacements:
 148
 149 .. c:function:: void ktime_get_ts( struct timespec * )
 150
 151         Use ktime_get() or ktime_get_ts64() instead.
 152
 153 .. c:function:: struct timeval do_gettimeofday( void )
 154                 struct timespec getnstimeofday( void )
 155                 struct timespec64 getnstimeofday64( void )
 156                 void ktime_get_real_ts( struct timespec * )
 157
 158         ktime_get_real_ts64() is a direct replacement, but consider using
 159         monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
 160         (ktime_get()/ktime_get_real()).
 161
 162 .. c:function:: struct timespec current_kernel_time( void )
 163                 struct timespec64 current_kernel_time64( void )
 164                 struct timespec get_monotonic_coarse( void )
 165                 struct timespec64 get_monotonic_coarse64( void )
 166
 167         These are replaced by ktime_get_coarse_real_ts64() and
 168         ktime_get_coarse_ts64(). However, A lot of code that wants
 169         coarse-grained times can use the simple 'jiffies' instead, while
 170         some drivers may actually want the higher resolution accessors
 171         these days.
 172
 173 .. c:function:: struct timespec getrawmonotonic( void )
 174                 struct timespec64 getrawmonotonic64( void )
 175                 struct timespec timekeeping_clocktai( void )
 176                 struct timespec64 timekeeping_clocktai64( void )
 177                 struct timespec get_monotonic_boottime( void )
 178                 struct timespec64 get_monotonic_boottime64( void )
 179
 180         These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
 181         ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
 182         as ktime_get_boottime()/ktime_get_boottime_ts64().
 183         However, if the particular choice of clock source is not
 184         important for the user, consider converting to
 185         ktime_get()/ktime_get_ts64() instead for consistency.