System time linux kernel

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:

ktime_t ktime_get ( void ) В¶

Useful for reliable timestamps and measuring short time intervals accurately. Starts at system boot time but stops during suspend.

ktime_t ktime_get_boottime ( void ) В¶

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.

ktime_t ktime_get_real ( void ) В¶

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.

ktime_t ktime_get_clocktai ( void ) В¶

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.

ktime_t ktime_get_raw ( void ) В¶

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:

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.

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.

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:

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 ) В¶ 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 ) В¶ 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.

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:

void ktime_get_ts ( struct timespecВ * ) В¶

void do_gettimeofday ( struct timevalВ * ) В¶ void getnstimeofday ( struct timespecВ * ) В¶ void getnstimeofday64 ( struct timespec64В * ) В¶ 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() ).

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.

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.

© Copyright The kernel development community.

Источник

Timestamping¶

1. Control Interfaces¶

The interfaces for receiving network packages timestamps are:

SO_TIMESTAMP Generates a timestamp for each incoming packet in (not necessarily monotonic) system time. Reports the timestamp via recvmsg() in a control message in usec resolution. SO_TIMESTAMP is defined as SO_TIMESTAMP_NEW or SO_TIMESTAMP_OLD based on the architecture type and time_t representation of libc. Control message format is in struct __kernel_old_timeval for SO_TIMESTAMP_OLD and in struct __kernel_sock_timeval for SO_TIMESTAMP_NEW options respectively. SO_TIMESTAMPNS Same timestamping mechanism as SO_TIMESTAMP, but reports the timestamp as struct timespec in nsec resolution. SO_TIMESTAMPNS is defined as SO_TIMESTAMPNS_NEW or SO_TIMESTAMPNS_OLD based on the architecture type and time_t representation of libc. Control message format is in struct timespec for SO_TIMESTAMPNS_OLD and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options respectively. IP_MULTICAST_LOOP + SO_TIMESTAMP[NS] Only for multicast:approximate transmit timestamp obtained by reading the looped packet receive timestamp. SO_TIMESTAMPING Generates timestamps on reception, transmission or both. Supports multiple timestamp sources, including hardware. Supports generating timestamps for stream sockets.

1.1 SO_TIMESTAMP (also SO_TIMESTAMP_OLD and SO_TIMESTAMP_NEW)В¶

This socket option enables timestamping of datagrams on the reception path. Because the destination socket, if any, is not known early in the network stack, the feature has to be enabled for all packets. The same is true for all early receive timestamp options.

For interface details, see man 7 socket .

Always use SO_TIMESTAMP_NEW timestamp to always get timestamp in struct __kernel_sock_timeval format.

SO_TIMESTAMP_OLD returns incorrect timestamps after the year 2038 on 32 bit machines.

1.2 SO_TIMESTAMPNS (also SO_TIMESTAMPNS_OLD and SO_TIMESTAMPNS_NEW):

This option is identical to SO_TIMESTAMP except for the returned data type. Its struct timespec allows for higher resolution (ns) timestamps than the timeval of SO_TIMESTAMP (ms).

Always use SO_TIMESTAMPNS_NEW timestamp to always get timestamp in struct __kernel_timespec format.

SO_TIMESTAMPNS_OLD returns incorrect timestamps after the year 2038 on 32 bit machines.

1.3 SO_TIMESTAMPING (also SO_TIMESTAMPING_OLD and SO_TIMESTAMPING_NEW)В¶

Supports multiple types of timestamp requests. As a result, this socket option takes a bitmap of flags, not a boolean. In:

val is an integer with any of the following bits set. Setting other bit returns EINVAL and does not change the current state.

The socket option configures timestamp generation for individual sk_buffs (1.3.1), timestamp reporting to the socket’s error queue (1.3.2) and options (1.3.3). Timestamp generation can also be enabled for individual sendmsg calls using cmsg (1.3.4).

1.3.1 Timestamp Generation¶

Some bits are requests to the stack to try to generate timestamps. Any combination of them is valid. Changes to these bits apply to newly created packets, not to packets already in the stack. As a result, it is possible to selectively request timestamps for a subset of packets (e.g., for sampling) by embedding an send() call within two setsockopt calls, one to enable timestamp generation and one to disable it. Timestamps may also be generated for reasons other than being requested by a particular socket, such as when receive timestamping is enabled system wide, as explained earlier.

SOF_TIMESTAMPING_RX_HARDWARE: Request rx timestamps generated by the network adapter. SOF_TIMESTAMPING_RX_SOFTWARE: Request rx timestamps when data enters the kernel. These timestamps are generated just after a device driver hands a packet to the kernel receive stack. SOF_TIMESTAMPING_TX_HARDWARE: Request tx timestamps generated by the network adapter. This flag can be enabled via both socket options and control messages. SOF_TIMESTAMPING_TX_SOFTWARE: Request tx timestamps when data leaves the kernel. These timestamps are generated in the device driver as close as possible, but always prior to, passing the packet to the network interface. Hence, they require driver support and may not be available for all devices. This flag can be enabled via both socket options and control messages. SOF_TIMESTAMPING_TX_SCHED: Request tx timestamps prior to entering the packet scheduler. Kernel transmit latency is, if long, often dominated by queuing delay. The difference between this timestamp and one taken at SOF_TIMESTAMPING_TX_SOFTWARE will expose this latency independent of protocol processing. The latency incurred in protocol processing, if any, can be computed by subtracting a userspace timestamp taken immediately before send() from this timestamp. On machines with virtual devices where a transmitted packet travels through multiple devices and, hence, multiple packet schedulers, a timestamp is generated at each layer. This allows for fine grained measurement of queuing delay. This flag can be enabled via both socket options and control messages. SOF_TIMESTAMPING_TX_ACK: Request tx timestamps when all data in the send buffer has been acknowledged. This only makes sense for reliable protocols. It is currently only implemented for TCP. For that protocol, it may over-report measurement, because the timestamp is generated when all data up to and including the buffer at send() was acknowledged: the cumulative acknowledgment. The mechanism ignores SACK and FACK. This flag can be enabled via both socket options and control messages.

1.3.2 Timestamp Reporting¶

The other three bits control which timestamps will be reported in a generated control message. Changes to the bits take immediate effect at the timestamp reporting locations in the stack. Timestamps are only reported for packets that also have the relevant timestamp generation request set.

SOF_TIMESTAMPING_SOFTWARE: Report any software timestamps when available. SOF_TIMESTAMPING_SYS_HARDWARE: This option is deprecated and ignored. SOF_TIMESTAMPING_RAW_HARDWARE: Report hardware timestamps as generated by SOF_TIMESTAMPING_TX_HARDWARE when available.

1.3.3 Timestamp Options¶

The interface supports the options

Generate a unique identifier along with each packet. A process can have multiple concurrent timestamping requests outstanding. Packets can be reordered in the transmit path, for instance in the packet scheduler. In that case timestamps will be queued onto the error queue out of order from the original send() calls. It is not always possible to uniquely match timestamps to the original send() calls based on timestamp order or payload inspection alone, then.

This option associates each packet at send() with a unique identifier and returns that along with the timestamp. The identifier is derived from a per-socket u32 counter (that wraps). For datagram sockets, the counter increments with each sent packet. For stream sockets, it increments with every byte.

The counter starts at zero. It is initialized the first time that the socket option is enabled. It is reset each time the option is enabled after having been disabled. Resetting the counter does not change the identifiers of existing packets in the system.

This option is implemented only for transmit timestamps. There, the timestamp is always looped along with a struct sock_extended_err. The option modifies field ee_data to pass an id that is unique among all possibly concurrently outstanding timestamp requests for that socket.

SOF_TIMESTAMPING_OPT_CMSG: Support recv() cmsg for all timestamped packets. Control messages are already supported unconditionally on all packets with receive timestamps and on IPv6 packets with transmit timestamp. This option extends them to IPv4 packets with transmit timestamp. One use case is to correlate packets with their egress device, by enabling socket option IP_PKTINFO simultaneously. SOF_TIMESTAMPING_OPT_TSONLY: Applies to transmit timestamps only. Makes the kernel return the timestamp as a cmsg alongside an empty packet, as opposed to alongside the original packet. This reduces the amount of memory charged to the socket’s receive budget (SO_RCVBUF) and delivers the timestamp even if sysctl net.core.tstamp_allow_data is 0. This option disables SOF_TIMESTAMPING_OPT_CMSG. SOF_TIMESTAMPING_OPT_STATS: Optional stats that are obtained along with the transmit timestamps. It must be used together with SOF_TIMESTAMPING_OPT_TSONLY. When the transmit timestamp is available, the stats are available in a separate control message of type SCM_TIMESTAMPING_OPT_STATS, as a list of TLVs (struct nlattr) of types. These stats allow the application to associate various transport layer stats with the transmit timestamps, such as how long a certain block of data was limited by peer’s receiver window. SOF_TIMESTAMPING_OPT_PKTINFO: Enable the SCM_TIMESTAMPING_PKTINFO control message for incoming packets with hardware timestamps. The message contains struct scm_ts_pktinfo, which supplies the index of the real interface which received the packet and its length at layer 2. A valid (non-zero) interface index will be returned only if CONFIG_NET_RX_BUSY_POLL is enabled and the driver is using NAPI. The struct contains also two other fields, but they are reserved and undefined. SOF_TIMESTAMPING_OPT_TX_SWHW: Request both hardware and software timestamps for outgoing packets when SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE are enabled at the same time. If both timestamps are generated, two separate messages will be looped to the socket’s error queue, each containing just one timestamp.

New applications are encouraged to pass SOF_TIMESTAMPING_OPT_ID to disambiguate timestamps and SOF_TIMESTAMPING_OPT_TSONLY to operate regardless of the setting of sysctl net.core.tstamp_allow_data.

An exception is when a process needs additional cmsg data, for instance SOL_IP/IP_PKTINFO to detect the egress network interface. Then pass option SOF_TIMESTAMPING_OPT_CMSG. This option depends on having access to the contents of the original packet, so cannot be combined with SOF_TIMESTAMPING_OPT_TSONLY.

1.3.4. Enabling timestamps via control messages¶

In addition to socket options, timestamp generation can be requested per write via cmsg, only for SOF_TIMESTAMPING_TX_* (see Section 1.3.1). Using this feature, applications can sample timestamps per sendmsg() without paying the overhead of enabling and disabling timestamps via setsockopt:

The SOF_TIMESTAMPING_TX_* flags set via cmsg will override the SOF_TIMESTAMPING_TX_* flags set via setsockopt.

Moreover, applications must still enable timestamp reporting via setsockopt to receive timestamps:

Источник