docs: networking: convert timestamping.txt to ReST

   tc-actions-env-rules

   tcp-thin

   team

   timestamping

.. only::  subproject and html

NIC is capable of timestamping packets in hardware, you can request those

hardware timestamps to be used. Note: you may need to enable the generation

of hardware timestamps with SIOCSHWTSTAMP (see related information from

Documentation/networking/timestamping.txt).

Documentation/networking/timestamping.rst).

PACKET_TIMESTAMP accepts the same integer bit field as SO_TIMESTAMPING::

members do not contain a valid value. For TX_RINGs, by default no timestamp

is generated!

See include/linux/net_tstamp.h and Documentation/networking/timestamping.txt

See include/linux/net_tstamp.h and Documentation/networking/timestamping.rst

for more information on hardware timestamps.

Miscellaneous bits

.. SPDX-License-Identifier: GPL-2.0

============

Timestamping

============

1. Control Interfaces

=====================

The interfaces for receiving network packages timestamps are:

* SO_TIMESTAMP

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_OLD and in struct __kernel_sock_timeval for

  SO_TIMESTAMP_NEW options respectively.

* SO_TIMESTAMPNS

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

  and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options

  respectively.

* IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]

IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]

  Only for multicast:approximate transmit timestamp obtained by

  reading the looped packet receive timestamp.

* SO_TIMESTAMPING

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):

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

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):

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

socket option takes a bitmap of flags, not a boolean. In::

  err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val));

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

  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

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

1.3.3 Timestamp Options

^^^^^^^^^^^^^^^^^^^^^^^

The interface supports the options

SOF_TIMESTAMPING_OPT_ID:

  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

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

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

  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

  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

  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,

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:

setsockopt::

  struct msghdr *msg;

  ...

the SOF_TIMESTAMPING_TX_* flags set via setsockopt.

Moreover, applications must still enable timestamp reporting via

setsockopt to receive timestamps:

setsockopt to receive timestamps::

  __u32 val = SOF_TIMESTAMPING_SOFTWARE |

	      SOF_TIMESTAMPING_OPT_ID /* or any other flag */;

1.4 Bytestream Timestamps

-------------------------

The SO_TIMESTAMPING interface supports timestamping of bytes in a

bytestream. Each request is interpreted as a request for when the

2 Data Interfaces

==================

Timestamps are read using the ancillary data feature of recvmsg().

See `man 3 cmsg` for details of this interface. The socket manual

2.1 SCM_TIMESTAMPING records

----------------------------

These timestamps are returned in a control message with cmsg_level

SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type

For SO_TIMESTAMPING_OLD:

For SO_TIMESTAMPING_OLD::

	struct scm_timestamping {

		struct timespec ts[3];

	};

For SO_TIMESTAMPING_NEW:

For SO_TIMESTAMPING_NEW::

	struct scm_timestamping64 {

		struct __kernel_timespec ts[3];

on hardware transmit timestamps.

2.1.1 Transmit timestamps with MSG_ERRQUEUE

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For transmit timestamps the outgoing packet is looped back to the

socket's error queue with the send timestamp(s) attached. A process

2.1.1.2 Timestamp types

~~~~~~~~~~~~~~~~~~~~~~~

The semantics of the three struct timespec are defined by field

ee_info in the extended error structure. It contains a value of

2.1.1.3 Fragmentation

~~~~~~~~~~~~~~~~~~~~~

Fragmentation of outgoing datagrams is rare, but is possible, e.g., by

explicitly disabling PMTU discovery. If an outgoing packet is fragmented,

2.1.1.4 Packet Payload

~~~~~~~~~~~~~~~~~~~~~~

The calling application is often not interested in receiving the whole

packet payload that it passed to the stack originally: the socket

2.1.1.5 Blocking Read

~~~~~~~~~~~~~~~~~~~~~

Reading from the error queue is always a non-blocking operation. To

block waiting on a timestamp, use poll or select. poll() will return

2.1.2 Receive timestamps

^^^^^^^^^^^^^^^^^^^^^^^^

On reception, there is no reason to read from the socket error queue.

The SCM_TIMESTAMPING ancillary data is sent along with the packet data

3. Hardware Timestamping configuration: SIOCSHWTSTAMP and SIOCGHWTSTAMP

=======================================================================

Hardware time stamping must also be initialized for each device driver

that is expected to do hardware time stamping. The parameter is defined in

include/uapi/linux/net_tstamp.h as:

include/uapi/linux/net_tstamp.h as::

	struct hwtstamp_config {

		int flags;	/* no flags defined right now, must be zero */

structure to ioctl(SIOCGHWTSTAMP) in the same way.  However, this has

not been implemented in all drivers.

::

    /* possible values for hwtstamp_config->tx_type */

    enum {

	    /*

    };

3.1 Hardware Timestamping Implementation: Device Drivers

--------------------------------------------------------

A driver which supports hardware time stamping must support the

SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with

Time stamps for received packets must be stored in the skb. To get a pointer

to the shared time stamp structure of the skb call skb_hwtstamps(). Then

set the time stamps in the structure:

set the time stamps in the structure::

    struct skb_shared_hwtstamps {

	    /* hardware time stamp transformed into duration

    };

Time stamps for outgoing packets are to be generated as follows:

- In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP)

  is set no-zero. If yes, then the driver is expected to do hardware time

  stamping.

- If this is possible for the skb and requested, then declare

  that the driver is doing the time stamping by setting the flag

  SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with

  SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with::

      skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;

 *

 *	The timestamping interfaces SO_TIMESTAMPING, MSG_TSTAMP_*

 *	communicate network timestamps by passing this struct in a cmsg with

 *	recvmsg(). See Documentation/networking/timestamping.txt for details.

 *	recvmsg(). See Documentation/networking/timestamping.rst for details.

 *	User space sees a timespec definition that matches either

 *	__kernel_timespec or __kernel_old_timespec, in the kernel we

 *	require two structure definitions to provide both.