mirror of
https://github.com/torvalds/linux.git
synced 2024-11-11 06:31:49 +00:00
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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Mauro Carvalho Chehab
David S. Miller
parent
aa8a6ee3e3
commit
06bfa47e72
@ -109,6 +109,7 @@ Contents:
|
||||
tc-actions-env-rules
|
||||
tcp-thin
|
||||
team
|
||||
timestamping
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
||||
@ -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
|
||||
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::
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
@ -1,9 +1,16 @@
|
||||
.. 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.
|
||||
@ -13,7 +20,7 @@ The interfaces for receiving network packages timestamps are:
|
||||
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
|
||||
@ -22,17 +29,18 @@ The interfaces for receiving network packages timestamps are:
|
||||
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
|
||||
@ -59,10 +67,11 @@ 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):
|
||||
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));
|
||||
|
||||
@ -76,6 +85,7 @@ 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
|
||||
@ -106,7 +116,6 @@ SOF_TIMESTAMPING_TX_SOFTWARE:
|
||||
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
|
||||
@ -132,6 +141,7 @@ SOF_TIMESTAMPING_TX_ACK:
|
||||
|
||||
|
||||
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
|
||||
@ -151,11 +161,11 @@ SOF_TIMESTAMPING_RAW_HARDWARE:
|
||||
|
||||
|
||||
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
|
||||
@ -183,7 +193,6 @@ SOF_TIMESTAMPING_OPT_ID:
|
||||
|
||||
|
||||
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
|
||||
@ -193,7 +202,6 @@ SOF_TIMESTAMPING_OPT_CMSG:
|
||||
|
||||
|
||||
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
|
||||
@ -202,7 +210,6 @@ SOF_TIMESTAMPING_OPT_TSONLY:
|
||||
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
|
||||
@ -213,7 +220,6 @@ SOF_TIMESTAMPING_OPT_STATS:
|
||||
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
|
||||
@ -223,7 +229,6 @@ SOF_TIMESTAMPING_OPT_PKTINFO:
|
||||
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,
|
||||
@ -242,12 +247,13 @@ 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:
|
||||
setsockopt::
|
||||
|
||||
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.
|
||||
|
||||
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 */;
|
||||
@ -272,6 +278,7 @@ setsockopt to receive timestamps:
|
||||
|
||||
|
||||
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
|
||||
@ -331,6 +338,7 @@ unusual.
|
||||
|
||||
|
||||
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
|
||||
@ -339,20 +347,21 @@ SO_TIMESTAMP and SO_TIMESTAMPNS records can be retrieved.
|
||||
|
||||
|
||||
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];
|
||||
};
|
||||
struct scm_timestamping {
|
||||
struct timespec ts[3];
|
||||
};
|
||||
|
||||
For SO_TIMESTAMPING_NEW:
|
||||
For SO_TIMESTAMPING_NEW::
|
||||
|
||||
struct scm_timestamping64 {
|
||||
struct __kernel_timespec ts[3];
|
||||
struct scm_timestamping64 {
|
||||
struct __kernel_timespec ts[3];
|
||||
|
||||
Always use SO_TIMESTAMPING_NEW timestamp to always get timestamp in
|
||||
struct scm_timestamping64 format.
|
||||
@ -377,6 +386,7 @@ in ts[0] when a real software timestamp is missing. This happens also
|
||||
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
|
||||
@ -393,6 +403,7 @@ embeds the struct scm_timestamping.
|
||||
|
||||
|
||||
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
|
||||
@ -408,6 +419,7 @@ case the timestamp is stored in ts[0].
|
||||
|
||||
|
||||
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,
|
||||
@ -416,6 +428,7 @@ socket.
|
||||
|
||||
|
||||
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
|
||||
@ -427,6 +440,7 @@ however, the full packet is queued, taking up budget from SO_RCVBUF.
|
||||
|
||||
|
||||
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
|
||||
@ -436,6 +450,7 @@ ignored on request. See also `man 2 poll`.
|
||||
|
||||
|
||||
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
|
||||
@ -447,16 +462,17 @@ is again deprecated and ts[2] holds a hardware timestamp if set.
|
||||
|
||||
|
||||
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 */
|
||||
int tx_type; /* HWTSTAMP_TX_* */
|
||||
int rx_filter; /* HWTSTAMP_FILTER_* */
|
||||
};
|
||||
struct hwtstamp_config {
|
||||
int flags; /* no flags defined right now, must be zero */
|
||||
int tx_type; /* HWTSTAMP_TX_* */
|
||||
int rx_filter; /* HWTSTAMP_FILTER_* */
|
||||
};
|
||||
|
||||
Desired behavior is passed into the kernel and to a specific device by
|
||||
calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whose
|
||||
@ -487,44 +503,47 @@ Any process can read the actual configuration by passing this
|
||||
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 {
|
||||
/*
|
||||
* no outgoing packet will need hardware time stamping;
|
||||
* should a packet arrive which asks for it, no hardware
|
||||
* time stamping will be done
|
||||
*/
|
||||
HWTSTAMP_TX_OFF,
|
||||
::
|
||||
|
||||
/*
|
||||
* enables hardware time stamping for outgoing packets;
|
||||
* the sender of the packet decides which are to be
|
||||
* time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
|
||||
* before sending the packet
|
||||
*/
|
||||
HWTSTAMP_TX_ON,
|
||||
};
|
||||
/* possible values for hwtstamp_config->tx_type */
|
||||
enum {
|
||||
/*
|
||||
* no outgoing packet will need hardware time stamping;
|
||||
* should a packet arrive which asks for it, no hardware
|
||||
* time stamping will be done
|
||||
*/
|
||||
HWTSTAMP_TX_OFF,
|
||||
|
||||
/* possible values for hwtstamp_config->rx_filter */
|
||||
enum {
|
||||
/* time stamp no incoming packet at all */
|
||||
HWTSTAMP_FILTER_NONE,
|
||||
/*
|
||||
* enables hardware time stamping for outgoing packets;
|
||||
* the sender of the packet decides which are to be
|
||||
* time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
|
||||
* before sending the packet
|
||||
*/
|
||||
HWTSTAMP_TX_ON,
|
||||
};
|
||||
|
||||
/* time stamp any incoming packet */
|
||||
HWTSTAMP_FILTER_ALL,
|
||||
/* possible values for hwtstamp_config->rx_filter */
|
||||
enum {
|
||||
/* time stamp no incoming packet at all */
|
||||
HWTSTAMP_FILTER_NONE,
|
||||
|
||||
/* return value: time stamp all packets requested plus some others */
|
||||
HWTSTAMP_FILTER_SOME,
|
||||
/* time stamp any incoming packet */
|
||||
HWTSTAMP_FILTER_ALL,
|
||||
|
||||
/* PTP v1, UDP, any kind of event packet */
|
||||
HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
|
||||
/* return value: time stamp all packets requested plus some others */
|
||||
HWTSTAMP_FILTER_SOME,
|
||||
|
||||
/* for the complete list of values, please check
|
||||
* the include file include/uapi/linux/net_tstamp.h
|
||||
*/
|
||||
};
|
||||
/* PTP v1, UDP, any kind of event packet */
|
||||
HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
|
||||
|
||||
/* for the complete list of values, please check
|
||||
* the include file include/uapi/linux/net_tstamp.h
|
||||
*/
|
||||
};
|
||||
|
||||
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
|
||||
@ -533,22 +552,23 @@ should also support SIOCGHWTSTAMP.
|
||||
|
||||
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
|
||||
* since arbitrary point in time
|
||||
*/
|
||||
ktime_t hwtstamp;
|
||||
};
|
||||
struct skb_shared_hwtstamps {
|
||||
/* hardware time stamp transformed into duration
|
||||
* since arbitrary point in time
|
||||
*/
|
||||
ktime_t hwtstamp;
|
||||
};
|
||||
|
||||
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;
|
||||
|
||||
@ -36,7 +36,7 @@ struct sock_extended_err {
|
||||
*
|
||||
* 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user