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_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
  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( 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_real_fast_ns( void )
 136
 137         These variants are safe to call from any context, including from
 138         a non-maskable interrupt (NMI) during a timekeeper update, and
 139         while we are entering suspend with the clocksource powered down.
 140         This is useful in some tracing or debugging code as well as
 141         machine check reporting, but most drivers should never call them,
 142         since the time is allowed to jump under certain conditions.
 143
 144 Deprecated time interfaces
 145 --------------------------
 146
 147 Older kernels used some other interfaces that are now being phased out
 148 but may appear in third-party drivers being ported here. In particular,
 149 all interfaces returning a 'struct timeval' or 'struct timespec' have
 150 been replaced because the tv_sec member overflows in year 2038 on 32-bit
 151 architectures. These are the recommended replacements:
 152
 153 .. c:function:: void ktime_get_ts( struct timespec * )
 154
 155         Use ktime_get() or ktime_get_ts64() instead.
 156
 157 .. c:function:: struct timeval do_gettimeofday( void )
 158                 struct timespec getnstimeofday( void )
 159                 struct timespec64 getnstimeofday64( void )
 160                 void ktime_get_real_ts( struct timespec * )
 161
 162         ktime_get_real_ts64() is a direct replacement, but consider using
 163         monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
 164         (ktime_get()/ktime_get_real()).
 165
 166 .. c:function:: struct timespec current_kernel_time( void )
 167                 struct timespec64 current_kernel_time64( void )
 168                 struct timespec get_monotonic_coarse( void )
 169                 struct timespec64 get_monotonic_coarse64( void )
 170
 171         These are replaced by ktime_get_coarse_real_ts64() and
 172         ktime_get_coarse_ts64(). However, A lot of code that wants
 173         coarse-grained times can use the simple 'jiffies' instead, while
 174         some drivers may actually want the higher resolution accessors
 175         these days.
 176
 177 .. c:function:: struct timespec getrawmonotonic( void )
 178                 struct timespec64 getrawmonotonic64( void )
 179                 struct timespec timekeeping_clocktai( void )
 180                 struct timespec64 timekeeping_clocktai64( void )
 181                 struct timespec get_monotonic_boottime( void )
 182                 struct timespec64 get_monotonic_boottime64( void )
 183
 184         These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
 185         ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
 186         as ktime_get_boottime()/ktime_get_boottime_ts64().
 187         However, if the particular choice of clock source is not
 188         important for the user, consider converting to
 189         ktime_get()/ktime_get_ts64() instead for consistency.