Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

sock: document timestamping via cmsg in Documentation

Update docs and add code snippet for using cmsg for timestamping.

Signed-off-by: Soheil Hassas Yeganeh <soheil@google.com>
Acked-by: Willem de Bruijn <willemb@google.com>
Signed-off-by: David S. Miller <davem@davemloft.net>

authored by

Soheil Hassas Yeganeh and committed by
David S. Miller
fd91e12f c14ac945

+45 -3
+45 -3
Documentation/networking/timestamping.txt
··· 44 44 Supports multiple types of timestamp requests. As a result, this 45 45 socket option takes a bitmap of flags, not a boolean. In 46 46 47 - err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val, &val); 47 + err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val, 48 + sizeof(val)); 48 49 49 50 val is an integer with any of the following bits set. Setting other 50 51 bit returns EINVAL and does not change the current state. 52 + 53 + The socket option configures timestamp generation for individual 54 + sk_buffs (1.3.1), timestamp reporting to the socket's error 55 + queue (1.3.2) and options (1.3.3). Timestamp generation can also 56 + be enabled for individual sendmsg calls using cmsg (1.3.4). 51 57 52 58 53 59 1.3.1 Timestamp Generation ··· 77 71 kernel receive stack. 78 72 79 73 SOF_TIMESTAMPING_TX_HARDWARE: 80 - Request tx timestamps generated by the network adapter. 74 + Request tx timestamps generated by the network adapter. This flag 75 + can be enabled via both socket options and control messages. 81 76 82 77 SOF_TIMESTAMPING_TX_SOFTWARE: 83 78 Request tx timestamps when data leaves the kernel. These timestamps 84 79 are generated in the device driver as close as possible, but always 85 80 prior to, passing the packet to the network interface. Hence, they 86 81 require driver support and may not be available for all devices. 82 + This flag can be enabled via both socket options and control messages. 83 + 87 84 88 85 SOF_TIMESTAMPING_TX_SCHED: 89 86 Request tx timestamps prior to entering the packet scheduler. Kernel ··· 99 90 machines with virtual devices where a transmitted packet travels 100 91 through multiple devices and, hence, multiple packet schedulers, 101 92 a timestamp is generated at each layer. This allows for fine 102 - grained measurement of queuing delay. 93 + grained measurement of queuing delay. This flag can be enabled 94 + via both socket options and control messages. 103 95 104 96 SOF_TIMESTAMPING_TX_ACK: 105 97 Request tx timestamps when all data in the send buffer has been ··· 109 99 over-report measurement, because the timestamp is generated when all 110 100 data up to and including the buffer at send() was acknowledged: the 111 101 cumulative acknowledgment. The mechanism ignores SACK and FACK. 102 + This flag can be enabled via both socket options and control messages. 112 103 113 104 114 105 1.3.2 Timestamp Reporting ··· 192 181 Then pass option SOF_TIMESTAMPING_OPT_CMSG. This option depends on 193 182 having access to the contents of the original packet, so cannot be 194 183 combined with SOF_TIMESTAMPING_OPT_TSONLY. 184 + 185 + 186 + 1.3.4. Enabling timestamps via control messages 187 + 188 + In addition to socket options, timestamp generation can be requested 189 + per write via cmsg, only for SOF_TIMESTAMPING_TX_* (see Section 1.3.1). 190 + Using this feature, applications can sample timestamps per sendmsg() 191 + without paying the overhead of enabling and disabling timestamps via 192 + setsockopt: 193 + 194 + struct msghdr *msg; 195 + ... 196 + cmsg = CMSG_FIRSTHDR(msg); 197 + cmsg->cmsg_level = SOL_SOCKET; 198 + cmsg->cmsg_type = SO_TIMESTAMPING; 199 + cmsg->cmsg_len = CMSG_LEN(sizeof(__u32)); 200 + *((__u32 *) CMSG_DATA(cmsg)) = SOF_TIMESTAMPING_TX_SCHED | 201 + SOF_TIMESTAMPING_TX_SOFTWARE | 202 + SOF_TIMESTAMPING_TX_ACK; 203 + err = sendmsg(fd, msg, 0); 204 + 205 + The SOF_TIMESTAMPING_TX_* flags set via cmsg will override 206 + the SOF_TIMESTAMPING_TX_* flags set via setsockopt. 207 + 208 + Moreover, applications must still enable timestamp reporting via 209 + setsockopt to receive timestamps: 210 + 211 + __u32 val = SOF_TIMESTAMPING_SOFTWARE | 212 + SOF_TIMESTAMPING_OPT_ID /* or any other flag */; 213 + err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val, 214 + sizeof(val)); 195 215 196 216 197 217 1.4 Bytestream Timestamps