linux/Documentation/core-api/timekeeping.rst
Linus Torvalds e9a83bd232 It's been a relatively busy cycle for docs:
- A fair pile of RST conversions, many from Mauro.  These create more
    than the usual number of simple but annoying merge conflicts with other
    trees, unfortunately.  He has a lot more of these waiting on the wings
    that, I think, will go to you directly later on.
 
  - A new document on how to use merges and rebases in kernel repos, and one
    on Spectre vulnerabilities.
 
  - Various improvements to the build system, including automatic markup of
    function() references because some people, for reasons I will never
    understand, were of the opinion that :c:func:``function()`` is
    unattractive and not fun to type.
 
  - We now recommend using sphinx 1.7, but still support back to 1.4.
 
  - Lots of smaller improvements, warning fixes, typo fixes, etc.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl0krAEPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5Yg98H/AuLqO9LpOgUjF4LhyjxGPdzJkY9RExSJ7km
 gznyreLCZgFaJR+AY6YDsd4Jw6OJlPbu1YM/Qo3C3WrZVFVhgL/s2ebvBgCo50A8
 raAFd8jTf4/mGCHnAqRotAPQ3mETJUk315B66lBJ6Oc+YdpRhwXWq8ZW2bJxInFF
 3HDvoFgMf0KhLuMHUkkL0u3fxH1iA+KvDu8diPbJYFjOdOWENz/CV8wqdVkXRSEW
 DJxIq89h/7d+hIG3d1I7Nw+gibGsAdjSjKv4eRKauZs4Aoxd1Gpl62z0JNk6aT3m
 dtq4joLdwScydonXROD/Twn2jsu4xYTrPwVzChomElMowW/ZBBY=
 =D0eO
 -----END PGP SIGNATURE-----

Merge tag 'docs-5.3' of git://git.lwn.net/linux

Pull Documentation updates from Jonathan Corbet:
 "It's been a relatively busy cycle for docs:

   - A fair pile of RST conversions, many from Mauro. These create more
     than the usual number of simple but annoying merge conflicts with
     other trees, unfortunately. He has a lot more of these waiting on
     the wings that, I think, will go to you directly later on.

   - A new document on how to use merges and rebases in kernel repos,
     and one on Spectre vulnerabilities.

   - Various improvements to the build system, including automatic
     markup of function() references because some people, for reasons I
     will never understand, were of the opinion that
     :c:func:``function()`` is unattractive and not fun to type.

   - We now recommend using sphinx 1.7, but still support back to 1.4.

   - Lots of smaller improvements, warning fixes, typo fixes, etc"

* tag 'docs-5.3' of git://git.lwn.net/linux: (129 commits)
  docs: automarkup.py: ignore exceptions when seeking for xrefs
  docs: Move binderfs to admin-guide
  Disable Sphinx SmartyPants in HTML output
  doc: RCU callback locks need only _bh, not necessarily _irq
  docs: format kernel-parameters -- as code
  Doc : doc-guide : Fix a typo
  platform: x86: get rid of a non-existent document
  Add the RCU docs to the core-api manual
  Documentation: RCU: Add TOC tree hooks
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU basic concepts to reST
  docs: filesystems: Remove uneeded .rst extension on toctables
  scripts/sphinx-pre-install: fix out-of-tree build
  docs: zh_CN: submitting-drivers.rst: Remove a duplicated Documentation/
  Documentation: PGP: update for newer HW devices
  Documentation: Add section about CPU vulnerabilities for Spectre
  Documentation: platform: Delete x86-laptop-drivers.txt
  docs: Note that :c:func: should no longer be used
  ...
2019-07-09 12:34:26 -07:00

190 lines
7.2 KiB
ReStructuredText

ktime accessors
===============
Device drivers can read the current time using ktime_get() and the many
related functions declared in linux/timekeeping.h. As a rule of thumb,
using an accessor with a shorter name is preferred over one with a longer
name if both are equally fit for a particular use case.
Basic ktime_t based interfaces
------------------------------
The recommended simplest form returns an opaque ktime_t, with variants
that return time for different clock references:
.. c:function:: ktime_t ktime_get( void )
CLOCK_MONOTONIC
Useful for reliable timestamps and measuring short time intervals
accurately. Starts at system boot time but stops during suspend.
.. c:function:: ktime_t ktime_get_boottime( void )
CLOCK_BOOTTIME
Like ktime_get(), but does not stop when suspended. This can be
used e.g. for key expiration times that need to be synchronized
with other machines across a suspend operation.
.. c:function:: ktime_t ktime_get_real( void )
CLOCK_REALTIME
Returns the time in relative to the UNIX epoch starting in 1970
using the Coordinated Universal Time (UTC), same as gettimeofday()
user space. This is used for all timestamps that need to
persist across a reboot, like inode times, but should be avoided
for internal uses, since it can jump backwards due to a leap
second update, NTP adjustment settimeofday() operation from user
space.
.. c:function:: ktime_t ktime_get_clocktai( void )
CLOCK_TAI
Like ktime_get_real(), but uses the International Atomic Time (TAI)
reference instead of UTC to avoid jumping on leap second updates.
This is rarely useful in the kernel.
.. c:function:: ktime_t ktime_get_raw( void )
CLOCK_MONOTONIC_RAW
Like ktime_get(), but runs at the same rate as the hardware
clocksource without (NTP) adjustments for clock drift. This is
also rarely needed in the kernel.
nanosecond, timespec64, and second output
-----------------------------------------
For all of the above, there are variants that return the time in a
different format depending on what is required by the user:
.. c:function:: u64 ktime_get_ns( void )
u64 ktime_get_boottime_ns( void )
u64 ktime_get_real_ns( void )
u64 ktime_get_clocktai_ns( void )
u64 ktime_get_raw_ns( void )
Same as the plain ktime_get functions, but returning a u64 number
of nanoseconds in the respective time reference, which may be
more convenient for some callers.
.. c:function:: void ktime_get_ts64( struct timespec64 * )
void ktime_get_boottime_ts64( struct timespec64 * )
void ktime_get_real_ts64( struct timespec64 * )
void ktime_get_clocktai_ts64( struct timespec64 * )
void ktime_get_raw_ts64( struct timespec64 * )
Same above, but returns the time in a 'struct timespec64', split
into seconds and nanoseconds. This can avoid an extra division
when printing the time, or when passing it into an external
interface that expects a 'timespec' or 'timeval' structure.
.. c:function:: time64_t ktime_get_seconds( void )
time64_t ktime_get_boottime_seconds( void )
time64_t ktime_get_real_seconds( void )
time64_t ktime_get_clocktai_seconds( void )
time64_t ktime_get_raw_seconds( void )
Return a coarse-grained version of the time as a scalar
time64_t. This avoids accessing the clock hardware and rounds
down the seconds to the full seconds of the last timer tick
using the respective reference.
Coarse and fast_ns access
-------------------------
Some additional variants exist for more specialized cases:
.. c:function:: ktime_t ktime_get_coarse( void )
ktime_t ktime_get_coarse_boottime( void )
ktime_t ktime_get_coarse_real( void )
ktime_t ktime_get_coarse_clocktai( void )
.. c:function:: u64 ktime_get_coarse_ns( void )
u64 ktime_get_coarse_boottime_ns( void )
u64 ktime_get_coarse_real_ns( void )
u64 ktime_get_coarse_clocktai_ns( void )
.. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
void ktime_get_coarse_boottime_ts64( struct timespec64 * )
void ktime_get_coarse_real_ts64( struct timespec64 * )
void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
These are quicker than the non-coarse versions, but less accurate,
corresponding to CLOCK_MONOTONIC_COARSE and CLOCK_REALTIME_COARSE
in user space, along with the equivalent boottime/tai/raw
timebase not available in user space.
The time returned here corresponds to the last timer tick, which
may be as much as 10ms in the past (for CONFIG_HZ=100), same as
reading the 'jiffies' variable. These are only useful when called
in a fast path and one still expects better than second accuracy,
but can't easily use 'jiffies', e.g. for inode timestamps.
Skipping the hardware clock access saves around 100 CPU cycles
on most modern machines with a reliable cycle counter, but
up to several microseconds on older hardware with an external
clocksource.
.. c:function:: u64 ktime_get_mono_fast_ns( void )
u64 ktime_get_raw_fast_ns( void )
u64 ktime_get_boot_fast_ns( void )
u64 ktime_get_real_fast_ns( void )
These variants are safe to call from any context, including from
a non-maskable interrupt (NMI) during a timekeeper update, and
while we are entering suspend with the clocksource powered down.
This is useful in some tracing or debugging code as well as
machine check reporting, but most drivers should never call them,
since the time is allowed to jump under certain conditions.
Deprecated time interfaces
--------------------------
Older kernels used some other interfaces that are now being phased out
but may appear in third-party drivers being ported here. In particular,
all interfaces returning a 'struct timeval' or 'struct timespec' have
been replaced because the tv_sec member overflows in year 2038 on 32-bit
architectures. These are the recommended replacements:
.. c:function:: void ktime_get_ts( struct timespec * )
Use ktime_get() or ktime_get_ts64() instead.
.. c:function:: struct timeval do_gettimeofday( void )
struct timespec getnstimeofday( void )
struct timespec64 getnstimeofday64( void )
void ktime_get_real_ts( struct timespec * )
ktime_get_real_ts64() is a direct replacement, but consider using
monotonic time (ktime_get_ts64()) and/or a ktime_t based interface
(ktime_get()/ktime_get_real()).
.. c:function:: struct timespec current_kernel_time( void )
struct timespec64 current_kernel_time64( void )
struct timespec get_monotonic_coarse( void )
struct timespec64 get_monotonic_coarse64( void )
These are replaced by ktime_get_coarse_real_ts64() and
ktime_get_coarse_ts64(). However, A lot of code that wants
coarse-grained times can use the simple 'jiffies' instead, while
some drivers may actually want the higher resolution accessors
these days.
.. c:function:: struct timespec getrawmonotonic( void )
struct timespec64 getrawmonotonic64( void )
struct timespec timekeeping_clocktai( void )
struct timespec64 timekeeping_clocktai64( void )
struct timespec get_monotonic_boottime( void )
struct timespec64 get_monotonic_boottime64( void )
These are replaced by ktime_get_raw()/ktime_get_raw_ts64(),
ktime_get_clocktai()/ktime_get_clocktai_ts64() as well
as ktime_get_boottime()/ktime_get_boottime_ts64().
However, if the particular choice of clock source is not
important for the user, consider converting to
ktime_get()/ktime_get_ts64() instead for consistency.