Commit 06bfa47e authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

docs: networking: convert timestamping.txt to ReST 



- add SPDX header;
- add a document title;
- adjust titles and chapters, adding proper markups;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent aa8a6ee3

Documentation/networking/index.rst

+1 −0
Original line number Original line Diff line number Diff line
@@ -109,6 +109,7 @@ Contents: 
   tc-actions-env-rules

   tc-actions-env-rules

   tcp-thin

   tcp-thin

   team

   team

   timestamping





.. only::  subproject and html

.. only::  subproject and html

Documentation/networking/packet_mmap.rst

+2 −2
Original line number Original line Diff line number Diff line
@@ -1030,7 +1030,7 @@ the packet meta information for mmap(2)ed RX_RING and TX_RINGs. If your 
NIC is capable of timestamping packets in hardware, you can request those

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

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

of hardware timestamps with SIOCSHWTSTAMP (see related information from

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

PACKET_TIMESTAMP accepts the same integer bit field as SO_TIMESTAMPING::
@@ -1069,7 +1069,7 @@ TX_RING part only TP_STATUS_AVAILABLE is set, then the tp_sec and tp_{n,u}sec 
members do not contain a valid value. For TX_RINGs, by default no timestamp

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

is generated!

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.

for more information on hardware timestamps.





Miscellaneous bits

Miscellaneous bits

Documentation/networking/timestamping.txt→Documentation/networking/timestamping.rst

+93 −73
Original line number Original line Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



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

Timestamping

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







1. Control Interfaces

1. Control Interfaces

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





The interfaces for receiving network packages timestamps are:

The interfaces for receiving network packages timestamps are:





* SO_TIMESTAMP

SO_TIMESTAMP

  Generates a timestamp for each incoming packet in (not necessarily

  Generates a timestamp for each incoming packet in (not necessarily

  monotonic) system time. Reports the timestamp via recvmsg() in a

  monotonic) system time. Reports the timestamp via recvmsg() in a

  control message in usec resolution.

  control message in usec resolution.
@@ -13,7 +20,7 @@ The interfaces for receiving network packages timestamps are: 
  SO_TIMESTAMP_OLD and in struct __kernel_sock_timeval for

  SO_TIMESTAMP_OLD and in struct __kernel_sock_timeval for

  SO_TIMESTAMP_NEW options respectively.

  SO_TIMESTAMP_NEW options respectively.





* SO_TIMESTAMPNS

SO_TIMESTAMPNS

  Same timestamping mechanism as SO_TIMESTAMP, but reports the

  Same timestamping mechanism as SO_TIMESTAMP, but reports the

  timestamp as struct timespec in nsec resolution.

  timestamp as struct timespec in nsec resolution.

  SO_TIMESTAMPNS is defined as SO_TIMESTAMPNS_NEW or SO_TIMESTAMPNS_OLD

  SO_TIMESTAMPNS is defined as SO_TIMESTAMPNS_NEW or SO_TIMESTAMPNS_OLD
@@ -22,17 +29,18 @@ The interfaces for receiving network packages timestamps are: 
  and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options

  and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options

  respectively.

  respectively.





* IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]

IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]

  Only for multicast:approximate transmit timestamp obtained by

  Only for multicast:approximate transmit timestamp obtained by

  reading the looped packet receive timestamp.

  reading the looped packet receive timestamp.





* SO_TIMESTAMPING

SO_TIMESTAMPING

  Generates timestamps on reception, transmission or both. Supports

  Generates timestamps on reception, transmission or both. Supports

  multiple timestamp sources, including hardware. Supports generating

  multiple timestamp sources, including hardware. Supports generating

  timestamps for stream sockets.

  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

This socket option enables timestamping of datagrams on the reception

path. Because the destination socket, if any, is not known early in

path. Because the destination socket, if any, is not known early in
@@ -59,10 +67,11 @@ struct __kernel_timespec format. 
SO_TIMESTAMPNS_OLD returns incorrect timestamps after the year 2038

SO_TIMESTAMPNS_OLD returns incorrect timestamps after the year 2038

on 32 bit machines.

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

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

  err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val));
@@ -76,6 +85,7 @@ be enabled for individual sendmsg calls using cmsg (1.3.4). 








1.3.1 Timestamp Generation

1.3.1 Timestamp Generation

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





Some bits are requests to the stack to try to generate timestamps. Any

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

combination of them is valid. Changes to these bits apply to newly
@@ -106,7 +116,6 @@ SOF_TIMESTAMPING_TX_SOFTWARE: 
  require driver support and may not be available for all devices.

  require driver support and may not be available for all devices.

  This flag can be enabled via both socket options and control messages.

  This flag can be enabled via both socket options and control messages.







SOF_TIMESTAMPING_TX_SCHED:

SOF_TIMESTAMPING_TX_SCHED:

  Request tx timestamps prior to entering the packet scheduler. Kernel

  Request tx timestamps prior to entering the packet scheduler. Kernel

  transmit latency is, if long, often dominated by queuing delay. The

  transmit latency is, if long, often dominated by queuing delay. The
@@ -132,6 +141,7 @@ SOF_TIMESTAMPING_TX_ACK: 








1.3.2 Timestamp Reporting

1.3.2 Timestamp Reporting

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





The other three bits control which timestamps will be reported in a

The other three bits control which timestamps will be reported in a

generated control message. Changes to the bits take immediate

generated control message. Changes to the bits take immediate
@@ -151,11 +161,11 @@ SOF_TIMESTAMPING_RAW_HARDWARE: 








1.3.3 Timestamp Options

1.3.3 Timestamp Options

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





The interface supports the options

The interface supports the options





SOF_TIMESTAMPING_OPT_ID:

SOF_TIMESTAMPING_OPT_ID:



  Generate a unique identifier along with each packet. A process can

  Generate a unique identifier along with each packet. A process can

  have multiple concurrent timestamping requests outstanding. Packets

  have multiple concurrent timestamping requests outstanding. Packets

  can be reordered in the transmit path, for instance in the packet

  can be reordered in the transmit path, for instance in the packet
@@ -183,7 +193,6 @@ SOF_TIMESTAMPING_OPT_ID: 








SOF_TIMESTAMPING_OPT_CMSG:

SOF_TIMESTAMPING_OPT_CMSG:



  Support recv() cmsg for all timestamped packets. Control messages

  Support recv() cmsg for all timestamped packets. Control messages

  are already supported unconditionally on all packets with receive

  are already supported unconditionally on all packets with receive

  timestamps and on IPv6 packets with transmit timestamp. This option

  timestamps and on IPv6 packets with transmit timestamp. This option
@@ -193,7 +202,6 @@ SOF_TIMESTAMPING_OPT_CMSG: 








SOF_TIMESTAMPING_OPT_TSONLY:

SOF_TIMESTAMPING_OPT_TSONLY:



  Applies to transmit timestamps only. Makes the kernel return the

  Applies to transmit timestamps only. Makes the kernel return the

  timestamp as a cmsg alongside an empty packet, as opposed to

  timestamp as a cmsg alongside an empty packet, as opposed to

  alongside the original packet. This reduces the amount of memory

  alongside the original packet. This reduces the amount of memory
@@ -202,7 +210,6 @@ SOF_TIMESTAMPING_OPT_TSONLY: 
  This option disables SOF_TIMESTAMPING_OPT_CMSG.

  This option disables SOF_TIMESTAMPING_OPT_CMSG.





SOF_TIMESTAMPING_OPT_STATS:

SOF_TIMESTAMPING_OPT_STATS:



  Optional stats that are obtained along with the transmit timestamps.

  Optional stats that are obtained along with the transmit timestamps.

  It must be used together with SOF_TIMESTAMPING_OPT_TSONLY. When the

  It must be used together with SOF_TIMESTAMPING_OPT_TSONLY. When the

  transmit timestamp is available, the stats are available in a

  transmit timestamp is available, the stats are available in a
@@ -213,7 +220,6 @@ SOF_TIMESTAMPING_OPT_STATS: 
  data was limited by peer's receiver window.

  data was limited by peer's receiver window.





SOF_TIMESTAMPING_OPT_PKTINFO:

SOF_TIMESTAMPING_OPT_PKTINFO:



  Enable the SCM_TIMESTAMPING_PKTINFO control message for incoming

  Enable the SCM_TIMESTAMPING_PKTINFO control message for incoming

  packets with hardware timestamps. The message contains struct

  packets with hardware timestamps. The message contains struct

  scm_ts_pktinfo, which supplies the index of the real interface which

  scm_ts_pktinfo, which supplies the index of the real interface which
@@ -223,7 +229,6 @@ SOF_TIMESTAMPING_OPT_PKTINFO: 
  other fields, but they are reserved and undefined.

  other fields, but they are reserved and undefined.





SOF_TIMESTAMPING_OPT_TX_SWHW:

SOF_TIMESTAMPING_OPT_TX_SWHW:



  Request both hardware and software timestamps for outgoing packets

  Request both hardware and software timestamps for outgoing packets

  when SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE

  when SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE

  are enabled at the same time. If both timestamps are generated,

  are enabled at the same time. If both timestamps are generated,
@@ -242,12 +247,13 @@ combined with SOF_TIMESTAMPING_OPT_TSONLY. 








1.3.4. Enabling timestamps via control messages

1.3.4. Enabling timestamps via control messages

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





In addition to socket options, timestamp generation can be requested

In addition to socket options, timestamp generation can be requested

per write via cmsg, only for SOF_TIMESTAMPING_TX_* (see Section 1.3.1).

per write via cmsg, only for SOF_TIMESTAMPING_TX_* (see Section 1.3.1).

Using this feature, applications can sample timestamps per sendmsg()

Using this feature, applications can sample timestamps per sendmsg()

without paying the overhead of enabling and disabling timestamps via

without paying the overhead of enabling and disabling timestamps via

setsockopt:

setsockopt::





  struct msghdr *msg;

  struct msghdr *msg;

  ...

  ...
@@ -264,7 +270,7 @@ The SOF_TIMESTAMPING_TX_* flags set via cmsg will override 
the SOF_TIMESTAMPING_TX_* flags set via setsockopt.

the SOF_TIMESTAMPING_TX_* flags set via setsockopt.





Moreover, applications must still enable timestamp reporting via

Moreover, applications must still enable timestamp reporting via

setsockopt to receive timestamps:

setsockopt to receive timestamps::





  __u32 val = SOF_TIMESTAMPING_SOFTWARE |

  __u32 val = SOF_TIMESTAMPING_SOFTWARE |

	      SOF_TIMESTAMPING_OPT_ID /* or any other flag */;

	      SOF_TIMESTAMPING_OPT_ID /* or any other flag */;
@@ -272,6 +278,7 @@ setsockopt to receive timestamps: 








1.4 Bytestream Timestamps

1.4 Bytestream Timestamps

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





The SO_TIMESTAMPING interface supports timestamping of bytes in a

The SO_TIMESTAMPING interface supports timestamping of bytes in a

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

bytestream. Each request is interpreted as a request for when the
@@ -331,6 +338,7 @@ unusual. 








2 Data Interfaces

2 Data Interfaces

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





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

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

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

See `man 3 cmsg` for details of this interface. The socket manual
@@ -339,17 +347,18 @@ SO_TIMESTAMP and SO_TIMESTAMPNS records can be retrieved. 








2.1 SCM_TIMESTAMPING records

2.1 SCM_TIMESTAMPING records

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





These timestamps are returned in a control message with cmsg_level

These timestamps are returned in a control message with cmsg_level

SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type

SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type





For SO_TIMESTAMPING_OLD:

For SO_TIMESTAMPING_OLD::





	struct scm_timestamping {

	struct scm_timestamping {

		struct timespec ts[3];

		struct timespec ts[3];

	};

	};





For SO_TIMESTAMPING_NEW:

For SO_TIMESTAMPING_NEW::





	struct scm_timestamping64 {

	struct scm_timestamping64 {

		struct __kernel_timespec ts[3];

		struct __kernel_timespec ts[3];
@@ -377,6 +386,7 @@ in ts[0] when a real software timestamp is missing. This happens also 
on hardware transmit timestamps.

on hardware transmit timestamps.





2.1.1 Transmit timestamps with MSG_ERRQUEUE

2.1.1 Transmit timestamps with MSG_ERRQUEUE

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





For transmit timestamps the outgoing packet is looped back to the

For transmit timestamps the outgoing packet is looped back to the

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

socket's error queue with the send timestamp(s) attached. A process
@@ -393,6 +403,7 @@ embeds the struct scm_timestamping. 








2.1.1.2 Timestamp types

2.1.1.2 Timestamp types

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





The semantics of the three struct timespec are defined by field

The semantics of the three struct timespec are defined by field

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

ee_info in the extended error structure. It contains a value of
@@ -408,6 +419,7 @@ case the timestamp is stored in ts[0]. 








2.1.1.3 Fragmentation

2.1.1.3 Fragmentation

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





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

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

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

explicitly disabling PMTU discovery. If an outgoing packet is fragmented,
@@ -416,6 +428,7 @@ socket. 








2.1.1.4 Packet Payload

2.1.1.4 Packet Payload

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





The calling application is often not interested in receiving the whole

The calling application is often not interested in receiving the whole

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

packet payload that it passed to the stack originally: the socket
@@ -427,6 +440,7 @@ however, the full packet is queued, taking up budget from SO_RCVBUF. 








2.1.1.5 Blocking Read

2.1.1.5 Blocking Read

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





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

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

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

block waiting on a timestamp, use poll or select. poll() will return
@@ -436,6 +450,7 @@ ignored on request. See also `man 2 poll`. 








2.1.2 Receive timestamps

2.1.2 Receive timestamps

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





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

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

The SCM_TIMESTAMPING ancillary data is sent along with the packet data
@@ -447,10 +462,11 @@ is again deprecated and ts[2] holds a hardware timestamp if set. 








3. Hardware Timestamping configuration: SIOCSHWTSTAMP and SIOCGHWTSTAMP

3. Hardware Timestamping configuration: SIOCSHWTSTAMP and SIOCGHWTSTAMP

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





Hardware time stamping must also be initialized for each device driver

Hardware time stamping must also be initialized for each device driver

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

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 {

	struct hwtstamp_config {

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

		int flags;	/* no flags defined right now, must be zero */
@@ -487,6 +503,8 @@ Any process can read the actual configuration by passing this 
structure to ioctl(SIOCGHWTSTAMP) in the same way.  However, this has

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

not been implemented in all drivers.

not been implemented in all drivers.





::



    /* possible values for hwtstamp_config->tx_type */

    /* possible values for hwtstamp_config->tx_type */

    enum {

    enum {

	    /*

	    /*
@@ -525,6 +543,7 @@ enum { 
    };

    };





3.1 Hardware Timestamping Implementation: Device Drivers

3.1 Hardware Timestamping Implementation: Device Drivers

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





A driver which supports hardware time stamping must support the

A driver which supports hardware time stamping must support the

SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with

SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with
@@ -533,7 +552,7 @@ should also support SIOCGHWTSTAMP. 




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

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

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 {

    struct skb_shared_hwtstamps {

	    /* hardware time stamp transformed into duration

	    /* hardware time stamp transformed into duration
@@ -543,12 +562,13 @@ struct skb_shared_hwtstamps { 
    };

    };





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

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)

- 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

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

  stamping.

  stamping.

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

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

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

  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;

      skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;

include/uapi/linux/errqueue.h

+1 −1
Original line number Original line Diff line number Diff line
@@ -36,7 +36,7 @@ struct sock_extended_err { 
 *

 *

 *	The timestamping interfaces SO_TIMESTAMPING, MSG_TSTAMP_*

 *	The timestamping interfaces SO_TIMESTAMPING, MSG_TSTAMP_*

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

 *	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

 *	User space sees a timespec definition that matches either

 *	__kernel_timespec or __kernel_old_timespec, in the kernel we

 *	__kernel_timespec or __kernel_old_timespec, in the kernel we

 *	require two structure definitions to provide both.

 *	require two structure definitions to provide both.