^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Timestamping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) 1. Control Interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) The interfaces for receiving network packages timestamps are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) SO_TIMESTAMP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Generates a timestamp for each incoming packet in (not necessarily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) monotonic) system time. Reports the timestamp via recvmsg() in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) control message in usec resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) SO_TIMESTAMP is defined as SO_TIMESTAMP_NEW or SO_TIMESTAMP_OLD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) based on the architecture type and time_t representation of libc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Control message format is in struct __kernel_old_timeval for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) SO_TIMESTAMP_OLD and in struct __kernel_sock_timeval for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) SO_TIMESTAMP_NEW options respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) SO_TIMESTAMPNS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Same timestamping mechanism as SO_TIMESTAMP, but reports the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) timestamp as struct timespec in nsec resolution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) SO_TIMESTAMPNS is defined as SO_TIMESTAMPNS_NEW or SO_TIMESTAMPNS_OLD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) based on the architecture type and time_t representation of libc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Control message format is in struct timespec for SO_TIMESTAMPNS_OLD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Only for multicast:approximate transmit timestamp obtained by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) reading the looped packet receive timestamp.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) SO_TIMESTAMPING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Generates timestamps on reception, transmission or both. Supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) multiple timestamp sources, including hardware. Supports generating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) timestamps for stream sockets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 1.1 SO_TIMESTAMP (also SO_TIMESTAMP_OLD and SO_TIMESTAMP_NEW)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) -------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) This socket option enables timestamping of datagrams on the reception
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) path. Because the destination socket, if any, is not known early in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) the network stack, the feature has to be enabled for all packets. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) same is true for all early receive timestamp options.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) For interface details, see `man 7 socket`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Always use SO_TIMESTAMP_NEW timestamp to always get timestamp in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) struct __kernel_sock_timeval format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) SO_TIMESTAMP_OLD returns incorrect timestamps after the year 2038
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) on 32 bit machines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 1.2 SO_TIMESTAMPNS (also SO_TIMESTAMPNS_OLD and SO_TIMESTAMPNS_NEW):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) This option is identical to SO_TIMESTAMP except for the returned data type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Its struct timespec allows for higher resolution (ns) timestamps than the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) timeval of SO_TIMESTAMP (ms).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Always use SO_TIMESTAMPNS_NEW timestamp to always get timestamp in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) struct __kernel_timespec format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) SO_TIMESTAMPNS_OLD returns incorrect timestamps after the year 2038
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) on 32 bit machines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) 1.3 SO_TIMESTAMPING (also SO_TIMESTAMPING_OLD and SO_TIMESTAMPING_NEW)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) ----------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) Supports multiple types of timestamp requests. As a result, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) socket option takes a bitmap of flags, not a boolean. In::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) val is an integer with any of the following bits set. Setting other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) bit returns EINVAL and does not change the current state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) The socket option configures timestamp generation for individual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) sk_buffs (1.3.1), timestamp reporting to the socket's error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) queue (1.3.2) and options (1.3.3). Timestamp generation can also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) be enabled for individual sendmsg calls using cmsg (1.3.4).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) 1.3.1 Timestamp Generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Some bits are requests to the stack to try to generate timestamps. Any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) combination of them is valid. Changes to these bits apply to newly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) created packets, not to packets already in the stack. As a result, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) is possible to selectively request timestamps for a subset of packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) (e.g., for sampling) by embedding an send() call within two setsockopt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) calls, one to enable timestamp generation and one to disable it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Timestamps may also be generated for reasons other than being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) requested by a particular socket, such as when receive timestamping is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) enabled system wide, as explained earlier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) SOF_TIMESTAMPING_RX_HARDWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) Request rx timestamps generated by the network adapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) SOF_TIMESTAMPING_RX_SOFTWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) Request rx timestamps when data enters the kernel. These timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) are generated just after a device driver hands a packet to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) kernel receive stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) SOF_TIMESTAMPING_TX_HARDWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Request tx timestamps generated by the network adapter. This flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) can be enabled via both socket options and control messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) SOF_TIMESTAMPING_TX_SOFTWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) Request tx timestamps when data leaves the kernel. These timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) are generated in the device driver as close as possible, but always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) prior to, passing the packet to the network interface. Hence, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) require driver support and may not be available for all devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) This flag can be enabled via both socket options and control messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) SOF_TIMESTAMPING_TX_SCHED:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Request tx timestamps prior to entering the packet scheduler. Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) transmit latency is, if long, often dominated by queuing delay. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) difference between this timestamp and one taken at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) SOF_TIMESTAMPING_TX_SOFTWARE will expose this latency independent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) of protocol processing. The latency incurred in protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) processing, if any, can be computed by subtracting a userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) timestamp taken immediately before send() from this timestamp. On
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) machines with virtual devices where a transmitted packet travels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) through multiple devices and, hence, multiple packet schedulers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) a timestamp is generated at each layer. This allows for fine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) grained measurement of queuing delay. This flag can be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) via both socket options and control messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) SOF_TIMESTAMPING_TX_ACK:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Request tx timestamps when all data in the send buffer has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) acknowledged. This only makes sense for reliable protocols. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) currently only implemented for TCP. For that protocol, it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) over-report measurement, because the timestamp is generated when all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) data up to and including the buffer at send() was acknowledged: the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) cumulative acknowledgment. The mechanism ignores SACK and FACK.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) This flag can be enabled via both socket options and control messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 1.3.2 Timestamp Reporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) ^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) The other three bits control which timestamps will be reported in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) generated control message. Changes to the bits take immediate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) effect at the timestamp reporting locations in the stack. Timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) are only reported for packets that also have the relevant timestamp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) generation request set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) SOF_TIMESTAMPING_SOFTWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) Report any software timestamps when available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) SOF_TIMESTAMPING_SYS_HARDWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) This option is deprecated and ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) SOF_TIMESTAMPING_RAW_HARDWARE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Report hardware timestamps as generated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) SOF_TIMESTAMPING_TX_HARDWARE when available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) 1.3.3 Timestamp Options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) ^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) The interface supports the options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) SOF_TIMESTAMPING_OPT_ID:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Generate a unique identifier along with each packet. A process can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) have multiple concurrent timestamping requests outstanding. Packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) can be reordered in the transmit path, for instance in the packet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) scheduler. In that case timestamps will be queued onto the error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) queue out of order from the original send() calls. It is not always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) possible to uniquely match timestamps to the original send() calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) based on timestamp order or payload inspection alone, then.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) This option associates each packet at send() with a unique
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) identifier and returns that along with the timestamp. The identifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) is derived from a per-socket u32 counter (that wraps). For datagram
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) sockets, the counter increments with each sent packet. For stream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) sockets, it increments with every byte.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) The counter starts at zero. It is initialized the first time that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) the socket option is enabled. It is reset each time the option is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) enabled after having been disabled. Resetting the counter does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) change the identifiers of existing packets in the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) This option is implemented only for transmit timestamps. There, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) timestamp is always looped along with a struct sock_extended_err.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) The option modifies field ee_data to pass an id that is unique
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) among all possibly concurrently outstanding timestamp requests for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) that socket.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) SOF_TIMESTAMPING_OPT_CMSG:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Support recv() cmsg for all timestamped packets. Control messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) are already supported unconditionally on all packets with receive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) timestamps and on IPv6 packets with transmit timestamp. This option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) extends them to IPv4 packets with transmit timestamp. One use case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) is to correlate packets with their egress device, by enabling socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) option IP_PKTINFO simultaneously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) SOF_TIMESTAMPING_OPT_TSONLY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Applies to transmit timestamps only. Makes the kernel return the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) timestamp as a cmsg alongside an empty packet, as opposed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) alongside the original packet. This reduces the amount of memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) charged to the socket's receive budget (SO_RCVBUF) and delivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) the timestamp even if sysctl net.core.tstamp_allow_data is 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) This option disables SOF_TIMESTAMPING_OPT_CMSG.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) SOF_TIMESTAMPING_OPT_STATS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) Optional stats that are obtained along with the transmit timestamps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) It must be used together with SOF_TIMESTAMPING_OPT_TSONLY. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) transmit timestamp is available, the stats are available in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) separate control message of type SCM_TIMESTAMPING_OPT_STATS, as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) list of TLVs (struct nlattr) of types. These stats allow the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) application to associate various transport layer stats with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) the transmit timestamps, such as how long a certain block of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) data was limited by peer's receiver window.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) SOF_TIMESTAMPING_OPT_PKTINFO:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) Enable the SCM_TIMESTAMPING_PKTINFO control message for incoming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) packets with hardware timestamps. The message contains struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) scm_ts_pktinfo, which supplies the index of the real interface which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) received the packet and its length at layer 2. A valid (non-zero)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) interface index will be returned only if CONFIG_NET_RX_BUSY_POLL is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) enabled and the driver is using NAPI. The struct contains also two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) other fields, but they are reserved and undefined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) SOF_TIMESTAMPING_OPT_TX_SWHW:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Request both hardware and software timestamps for outgoing packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) when SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) are enabled at the same time. If both timestamps are generated,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) two separate messages will be looped to the socket's error queue,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) each containing just one timestamp.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) New applications are encouraged to pass SOF_TIMESTAMPING_OPT_ID to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) disambiguate timestamps and SOF_TIMESTAMPING_OPT_TSONLY to operate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) regardless of the setting of sysctl net.core.tstamp_allow_data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) An exception is when a process needs additional cmsg data, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) instance SOL_IP/IP_PKTINFO to detect the egress network interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) Then pass option SOF_TIMESTAMPING_OPT_CMSG. This option depends on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) having access to the contents of the original packet, so cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) combined with SOF_TIMESTAMPING_OPT_TSONLY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) 1.3.4. Enabling timestamps via control messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) In addition to socket options, timestamp generation can be requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) per write via cmsg, only for SOF_TIMESTAMPING_TX_* (see Section 1.3.1).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) Using this feature, applications can sample timestamps per sendmsg()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) without paying the overhead of enabling and disabling timestamps via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) setsockopt::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) struct msghdr *msg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) cmsg = CMSG_FIRSTHDR(msg);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) cmsg->cmsg_level = SOL_SOCKET;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) cmsg->cmsg_type = SO_TIMESTAMPING;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) cmsg->cmsg_len = CMSG_LEN(sizeof(__u32));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) *((__u32 *) CMSG_DATA(cmsg)) = SOF_TIMESTAMPING_TX_SCHED |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) SOF_TIMESTAMPING_TX_SOFTWARE |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) SOF_TIMESTAMPING_TX_ACK;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) err = sendmsg(fd, msg, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) The SOF_TIMESTAMPING_TX_* flags set via cmsg will override
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) the SOF_TIMESTAMPING_TX_* flags set via setsockopt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) Moreover, applications must still enable timestamp reporting via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) setsockopt to receive timestamps::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) __u32 val = SOF_TIMESTAMPING_SOFTWARE |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) SOF_TIMESTAMPING_OPT_ID /* or any other flag */;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) 1.4 Bytestream Timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) The SO_TIMESTAMPING interface supports timestamping of bytes in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) bytestream. Each request is interpreted as a request for when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) entire contents of the buffer has passed a timestamping point. That
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) is, for streams option SOF_TIMESTAMPING_TX_SOFTWARE will record
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) when all bytes have reached the device driver, regardless of how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) many packets the data has been converted into.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) In general, bytestreams have no natural delimiters and therefore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) correlating a timestamp with data is non-trivial. A range of bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) may be split across segments, any segments may be merged (possibly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) coalescing sections of previously segmented buffers associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) independent send() calls). Segments can be reordered and the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) byte range can coexist in multiple segments for protocols that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) implement retransmissions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) It is essential that all timestamps implement the same semantics,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) regardless of these possible transformations, as otherwise they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) incomparable. Handling "rare" corner cases differently from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) simple case (a 1:1 mapping from buffer to skb) is insufficient
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) because performance debugging often needs to focus on such outliers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) In practice, timestamps can be correlated with segments of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) bytestream consistently, if both semantics of the timestamp and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) timing of measurement are chosen correctly. This challenge is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) different from deciding on a strategy for IP fragmentation. There, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) definition is that only the first fragment is timestamped. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) bytestreams, we chose that a timestamp is generated only when all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) bytes have passed a point. SOF_TIMESTAMPING_TX_ACK as defined is easy to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) implement and reason about. An implementation that has to take into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) account SACK would be more complex due to possible transmission holes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) and out of order arrival.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) On the host, TCP can also break the simple 1:1 mapping from buffer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) skbuff as a result of Nagle, cork, autocork, segmentation and GSO. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) implementation ensures correctness in all cases by tracking the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) individual last byte passed to send(), even if it is no longer the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) last byte after an skbuff extend or merge operation. It stores the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) relevant sequence number in skb_shinfo(skb)->tskey. Because an skbuff
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) has only one such field, only one timestamp can be generated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) In rare cases, a timestamp request can be missed if two requests are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) collapsed onto the same skb. A process can detect this situation by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) enabling SOF_TIMESTAMPING_OPT_ID and comparing the byte offset at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) send time with the value returned for each timestamp. It can prevent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) the situation by always flushing the TCP stack in between requests,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) for instance by enabling TCP_NODELAY and disabling TCP_CORK and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) autocork.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) These precautions ensure that the timestamp is generated only when all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) bytes have passed a timestamp point, assuming that the network stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) itself does not reorder the segments. The stack indeed tries to avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) reordering. The one exception is under administrator control: it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) possible to construct a packet scheduler configuration that delays
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) segments from the same stream differently. Such a setup would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) unusual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 2 Data Interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) Timestamps are read using the ancillary data feature of recvmsg().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) See `man 3 cmsg` for details of this interface. The socket manual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) page (`man 7 socket`) describes how timestamps generated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) SO_TIMESTAMP and SO_TIMESTAMPNS records can be retrieved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) 2.1 SCM_TIMESTAMPING records
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) These timestamps are returned in a control message with cmsg_level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) For SO_TIMESTAMPING_OLD::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) struct scm_timestamping {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) struct timespec ts[3];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) For SO_TIMESTAMPING_NEW::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) struct scm_timestamping64 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) struct __kernel_timespec ts[3];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) Always use SO_TIMESTAMPING_NEW timestamp to always get timestamp in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) struct scm_timestamping64 format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) SO_TIMESTAMPING_OLD returns incorrect timestamps after the year 2038
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) on 32 bit machines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) The structure can return up to three timestamps. This is a legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) feature. At least one field is non-zero at any time. Most timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) are passed in ts[0]. Hardware timestamps are passed in ts[2].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) ts[1] used to hold hardware timestamps converted to system time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) Instead, expose the hardware clock device on the NIC directly as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) a HW PTP clock source, to allow time conversion in userspace and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) optionally synchronize system time with a userspace PTP stack such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) as linuxptp. For the PTP clock API, see Documentation/driver-api/ptp.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) Note that if the SO_TIMESTAMP or SO_TIMESTAMPNS option is enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) together with SO_TIMESTAMPING using SOF_TIMESTAMPING_SOFTWARE, a false
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) software timestamp will be generated in the recvmsg() call and passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) in ts[0] when a real software timestamp is missing. This happens also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) on hardware transmit timestamps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) 2.1.1 Transmit timestamps with MSG_ERRQUEUE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) For transmit timestamps the outgoing packet is looped back to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) socket's error queue with the send timestamp(s) attached. A process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) receives the timestamps by calling recvmsg() with flag MSG_ERRQUEUE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) set and with a msg_control buffer sufficiently large to receive the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) relevant metadata structures. The recvmsg call returns the original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) outgoing data packet with two ancillary messages attached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) A message of cm_level SOL_IP(V6) and cm_type IP(V6)_RECVERR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) embeds a struct sock_extended_err. This defines the error type. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) timestamps, the ee_errno field is ENOMSG. The other ancillary message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) will have cm_level SOL_SOCKET and cm_type SCM_TIMESTAMPING. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) embeds the struct scm_timestamping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) 2.1.1.2 Timestamp types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) ~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) The semantics of the three struct timespec are defined by field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) ee_info in the extended error structure. It contains a value of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) type SCM_TSTAMP_* to define the actual timestamp passed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) scm_timestamping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) The SCM_TSTAMP_* types are 1:1 matches to the SOF_TIMESTAMPING_*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) control fields discussed previously, with one exception. For legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) reasons, SCM_TSTAMP_SND is equal to zero and can be set for both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) is the first if ts[2] is non-zero, the second otherwise, in which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) case the timestamp is stored in ts[0].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) 2.1.1.3 Fragmentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) Fragmentation of outgoing datagrams is rare, but is possible, e.g., by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) explicitly disabling PMTU discovery. If an outgoing packet is fragmented,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) then only the first fragment is timestamped and returned to the sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) socket.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) 2.1.1.4 Packet Payload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) The calling application is often not interested in receiving the whole
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) packet payload that it passed to the stack originally: the socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) error queue mechanism is just a method to piggyback the timestamp on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) In this case, the application can choose to read datagrams with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) smaller buffer, possibly even of length 0. The payload is truncated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) accordingly. Until the process calls recvmsg() on the error queue,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) however, the full packet is queued, taking up budget from SO_RCVBUF.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) 2.1.1.5 Blocking Read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) Reading from the error queue is always a non-blocking operation. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) block waiting on a timestamp, use poll or select. poll() will return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) POLLERR in pollfd.revents if any data is ready on the error queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) There is no need to pass this flag in pollfd.events. This flag is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) ignored on request. See also `man 2 poll`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) 2.1.2 Receive timestamps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) ^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) On reception, there is no reason to read from the socket error queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) The SCM_TIMESTAMPING ancillary data is sent along with the packet data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) on a normal recvmsg(). Since this is not a socket error, it is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) accompanied by a message SOL_IP(V6)/IP(V6)_RECVERROR. In this case,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) the meaning of the three fields in struct scm_timestamping is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) implicitly defined. ts[0] holds a software timestamp if set, ts[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) is again deprecated and ts[2] holds a hardware timestamp if set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) 3. Hardware Timestamping configuration: SIOCSHWTSTAMP and SIOCGHWTSTAMP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) =======================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) Hardware time stamping must also be initialized for each device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) that is expected to do hardware time stamping. The parameter is defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) include/uapi/linux/net_tstamp.h as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) struct hwtstamp_config {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) int flags; /* no flags defined right now, must be zero */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) int tx_type; /* HWTSTAMP_TX_* */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) int rx_filter; /* HWTSTAMP_FILTER_* */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) Desired behavior is passed into the kernel and to a specific device by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) ifr_data points to a struct hwtstamp_config. The tx_type and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) rx_filter are hints to the driver what it is expected to do. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) the requested fine-grained filtering for incoming packets is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) supported, the driver may time stamp more than just the requested types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) of packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Drivers are free to use a more permissive configuration than the requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) configuration. It is expected that drivers should only implement directly the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) most generic mode that can be supported. For example if the hardware can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) support HWTSTAMP_FILTER_V2_EVENT, then it should generally always upscale
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) HWTSTAMP_FILTER_V2_L2_SYNC_MESSAGE, and so forth, as HWTSTAMP_FILTER_V2_EVENT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) is more generic (and more useful to applications).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) A driver which supports hardware time stamping shall update the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) with the actual, possibly more permissive configuration. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) requested packets cannot be time stamped, then nothing should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) changed and ERANGE shall be returned (in contrast to EINVAL, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) indicates that SIOCSHWTSTAMP is not supported at all).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) Only a processes with admin rights may change the configuration. User
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) space is responsible to ensure that multiple processes don't interfere
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) with each other and that the settings are reset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) Any process can read the actual configuration by passing this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) structure to ioctl(SIOCGHWTSTAMP) in the same way. However, this has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) not been implemented in all drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) /* possible values for hwtstamp_config->tx_type */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) enum {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) * no outgoing packet will need hardware time stamping;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) * should a packet arrive which asks for it, no hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) * time stamping will be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) HWTSTAMP_TX_OFF,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) * enables hardware time stamping for outgoing packets;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) * the sender of the packet decides which are to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) * before sending the packet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) HWTSTAMP_TX_ON,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) /* possible values for hwtstamp_config->rx_filter */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) enum {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) /* time stamp no incoming packet at all */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) HWTSTAMP_FILTER_NONE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) /* time stamp any incoming packet */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) HWTSTAMP_FILTER_ALL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) /* return value: time stamp all packets requested plus some others */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) HWTSTAMP_FILTER_SOME,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) /* PTP v1, UDP, any kind of event packet */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) /* for the complete list of values, please check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) * the include file include/uapi/linux/net_tstamp.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) 3.1 Hardware Timestamping Implementation: Device Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) --------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) A driver which supports hardware time stamping must support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) the actual values as described in the section on SIOCSHWTSTAMP. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) should also support SIOCGHWTSTAMP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) Time stamps for received packets must be stored in the skb. To get a pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) to the shared time stamp structure of the skb call skb_hwtstamps(). Then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) set the time stamps in the structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) struct skb_shared_hwtstamps {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) /* hardware time stamp transformed into duration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) * since arbitrary point in time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) ktime_t hwtstamp;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) Time stamps for outgoing packets are to be generated as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) - In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) is set no-zero. If yes, then the driver is expected to do hardware time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) stamping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) - If this is possible for the skb and requested, then declare
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) that the driver is doing the time stamping by setting the flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) You might want to keep a pointer to the associated skb for the next step
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) and not free the skb. A driver not supporting hardware time stamping doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) do that. A driver must never touch sk_buff::tstamp! It is used to store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) software generated time stamps by the network subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) - Driver should call skb_tx_timestamp() as close to passing sk_buff to hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) as possible. skb_tx_timestamp() provides a software time stamp if requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) and hardware timestamping is not possible (SKBTX_IN_PROGRESS not set).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) - As soon as the driver has sent the packet and/or obtained a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) hardware time stamp for it, it passes the time stamp back by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) calling skb_hwtstamp_tx() with the original skb, the raw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) hardware time stamp. skb_hwtstamp_tx() clones the original skb and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) adds the timestamps, therefore the original skb has to be freed now.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) If obtaining the hardware time stamp somehow fails, then the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) should not fall back to software time stamping. The rationale is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) this would occur at a later time in the processing pipeline than other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) software time stamping and therefore could lead to unexpected deltas
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) between time stamps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) 3.2 Special considerations for stacked PTP Hardware Clocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) ----------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) There are situations when there may be more than one PHC (PTP Hardware Clock)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) in the data path of a packet. The kernel has no explicit mechanism to allow the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) user to select which PHC to use for timestamping Ethernet frames. Instead, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) assumption is that the outermost PHC is always the most preferable, and that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) kernel drivers collaborate towards achieving that goal. Currently there are 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) cases of stacked PHCs, detailed below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) 3.2.1 DSA (Distributed Switch Architecture) switches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) These are Ethernet switches which have one of their ports connected to an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) (otherwise completely unaware) host Ethernet interface, and perform the role of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) a port multiplier with optional forwarding acceleration features. Each DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) switch port is visible to the user as a standalone (virtual) network interface,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) and its network I/O is performed, under the hood, indirectly through the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) interface (redirecting to the host port on TX, and intercepting frames on RX).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) When a DSA switch is attached to a host port, PTP synchronization has to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) suffer, since the switch's variable queuing delay introduces a path delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) jitter between the host port and its PTP partner. For this reason, some DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) switches include a timestamping clock of their own, and have the ability to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) perform network timestamping on their own MAC, such that path delays only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) measure wire and PHY propagation latencies. Timestamping DSA switches are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) supported in Linux and expose the same ABI as any other network interface (save
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) for the fact that the DSA interfaces are in fact virtual in terms of network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) I/O, they do have their own PHC). It is typical, but not mandatory, for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) interfaces of a DSA switch to share the same PHC.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) By design, PTP timestamping with a DSA switch does not need any special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) handling in the driver for the host port it is attached to. However, when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) host port also supports PTP timestamping, DSA will take care of intercepting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) the ``.ndo_do_ioctl`` calls towards the host port, and block attempts to enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) hardware timestamping on it. This is because the SO_TIMESTAMPING API does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) allow the delivery of multiple hardware timestamps for the same packet, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) anybody else except for the DSA switch port must be prevented from doing so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) In code, DSA provides for most of the infrastructure for timestamping already,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) in generic code: a BPF classifier (``ptp_classify_raw``) is used to identify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) PTP event messages (any other packets, including PTP general messages, are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) timestamped), and provides two hooks to drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) - ``.port_txtstamp()``: The driver is passed a clone of the timestampable skb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) to be transmitted, before actually transmitting it. Typically, a switch will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) have a PTP TX timestamp register (or sometimes a FIFO) where the timestamp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) becomes available. There may be an IRQ that is raised upon this timestamp's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) availability, or the driver might have to poll after invoking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) ``dev_queue_xmit()`` towards the host interface. Either way, in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) ``.port_txtstamp()`` method, the driver only needs to save the clone for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) later use (when the timestamp becomes available). Each skb is annotated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) a pointer to its clone, in ``DSA_SKB_CB(skb)->clone``, to ease the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) job of keeping track of which clone belongs to which skb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) - ``.port_rxtstamp()``: The original (and only) timestampable skb is provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) to the driver, for it to annotate it with a timestamp, if that is immediately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) available, or defer to later. On reception, timestamps might either be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) available in-band (through metadata in the DSA header, or attached in other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) ways to the packet), or out-of-band (through another RX timestamping FIFO).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) Deferral on RX is typically necessary when retrieving the timestamp needs a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) sleepable context. In that case, it is the responsibility of the DSA driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) to call ``netif_rx_ni()`` on the freshly timestamped skb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) 3.2.2 Ethernet PHYs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) ^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) These are devices that typically fulfill a Layer 1 role in the network stack,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) hence they do not have a representation in terms of a network interface as DSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) switches do. However, PHYs may be able to detect and timestamp PTP packets, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) performance reasons: timestamps taken as close as possible to the wire have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) potential to yield a more stable and precise synchronization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) A PHY driver that supports PTP timestamping must create a ``struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) mii_timestamper`` and add a pointer to it in ``phydev->mii_ts``. The presence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) of this pointer will be checked by the networking stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) Since PHYs do not have network interface representations, the timestamping and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) ethtool ioctl operations for them need to be mediated by their respective MAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) driver. Therefore, as opposed to DSA switches, modifications need to be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) to each individual MAC driver for PHY timestamping support. This entails:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) - Checking, in ``.ndo_do_ioctl``, whether ``phy_has_hwtstamp(netdev->phydev)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) is true or not. If it is, then the MAC driver should not process this request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) but instead pass it on to the PHY using ``phy_mii_ioctl()``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) - On RX, special intervention may or may not be needed, depending on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) function used to deliver skb's up the network stack. In the case of plain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) ``netif_rx()`` and similar, MAC drivers must check whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) ``skb_defer_rx_timestamp(skb)`` is necessary or not - and if it is, don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) call ``netif_rx()`` at all. If ``CONFIG_NETWORK_PHY_TIMESTAMPING`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) enabled, and ``skb->dev->phydev->mii_ts`` exists, its ``.rxtstamp()`` hook
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) will be called now, to determine, using logic very similar to DSA, whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) deferral for RX timestamping is necessary. Again like DSA, it becomes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) responsibility of the PHY driver to send the packet up the stack when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) timestamp is available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) For other skb receive functions, such as ``napi_gro_receive`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) ``netif_receive_skb``, the stack automatically checks whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) ``skb_defer_rx_timestamp()`` is necessary, so this check is not needed inside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) - On TX, again, special intervention might or might not be needed. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) function that calls the ``mii_ts->txtstamp()`` hook is named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) ``skb_clone_tx_timestamp()``. This function can either be called directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) (case in which explicit MAC driver support is indeed needed), but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) function also piggybacks from the ``skb_tx_timestamp()`` call, which many MAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) drivers already perform for software timestamping purposes. Therefore, if a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) MAC supports software timestamping, it does not need to do anything further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) at this stage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) 3.2.3 MII bus snooping devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) These perform the same role as timestamping Ethernet PHYs, save for the fact
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) that they are discrete devices and can therefore be used in conjunction with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) any PHY even if it doesn't support timestamping. In Linux, they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) discoverable and attachable to a ``struct phy_device`` through Device Tree, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) for the rest, they use the same mii_ts infrastructure as those. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) Documentation/devicetree/bindings/ptp/timestamper.txt for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) 3.2.4 Other caveats for MAC drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) Stacked PHCs, especially DSA (but not only) - since that doesn't require any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) modification to MAC drivers, so it is more difficult to ensure correctness of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) all possible code paths - is that they uncover bugs which were impossible to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) trigger before the existence of stacked PTP clocks. One example has to do with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) this line of code, already presented earlier::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) Any TX timestamping logic, be it a plain MAC driver, a DSA switch driver, a PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) driver or a MII bus snooping device driver, should set this flag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) But a MAC driver that is unaware of PHC stacking might get tripped up by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) somebody other than itself setting this flag, and deliver a duplicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) timestamp.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) For example, a typical driver design for TX timestamping might be to split the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) transmission part into 2 portions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) 1. "TX": checks whether PTP timestamping has been previously enabled through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) the ``.ndo_do_ioctl`` ("``priv->hwtstamp_tx_enabled == true``") and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) current skb requires a TX timestamp ("``skb_shinfo(skb)->tx_flags &
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) SKBTX_HW_TSTAMP``"). If this is true, it sets the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) "``skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS``" flag. Note: as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) described above, in the case of a stacked PHC system, this condition should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) never trigger, as this MAC is certainly not the outermost PHC. But this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) not where the typical issue is. Transmission proceeds with this packet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) 2. "TX confirmation": Transmission has finished. The driver checks whether it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) is necessary to collect any TX timestamp for it. Here is where the typical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) issues are: the MAC driver takes a shortcut and only checks whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) "``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``" was set. With a stacked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) PHC system, this is incorrect because this MAC driver is not the only entity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) in the TX data path who could have enabled SKBTX_IN_PROGRESS in the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) The correct solution for this problem is for MAC drivers to have a compound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) check in their "TX confirmation" portion, not only for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) "``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``", but also for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) "``priv->hwtstamp_tx_enabled == true``". Because the rest of the system ensures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) that PTP timestamping is not enabled for anything other than the outermost PHC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) this enhanced check will avoid delivering a duplicated TX timestamp to user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) space.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags