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>
This commit is contained in:
parent
c14ac9451c
commit
fd91e12f59
1 changed files with 45 additions and 3 deletions
|
@ -44,11 +44,17 @@ timeval of SO_TIMESTAMP (ms).
|
|||
Supports multiple types of timestamp requests. As a result, this
|
||||
socket option takes a bitmap of flags, not a boolean. In
|
||||
|
||||
err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val, &val);
|
||||
err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val,
|
||||
sizeof(val));
|
||||
|
||||
val is an integer with any of the following bits set. Setting other
|
||||
bit returns EINVAL and does not change the current state.
|
||||
|
||||
The socket option configures timestamp generation for individual
|
||||
sk_buffs (1.3.1), timestamp reporting to the socket's error
|
||||
queue (1.3.2) and options (1.3.3). Timestamp generation can also
|
||||
be enabled for individual sendmsg calls using cmsg (1.3.4).
|
||||
|
||||
|
||||
1.3.1 Timestamp Generation
|
||||
|
||||
|
@ -71,13 +77,16 @@ SOF_TIMESTAMPING_RX_SOFTWARE:
|
|||
kernel receive stack.
|
||||
|
||||
SOF_TIMESTAMPING_TX_HARDWARE:
|
||||
Request tx timestamps generated by the network adapter.
|
||||
Request tx timestamps generated by the network adapter. This flag
|
||||
can be enabled via both socket options and control messages.
|
||||
|
||||
SOF_TIMESTAMPING_TX_SOFTWARE:
|
||||
Request tx timestamps when data leaves the kernel. These timestamps
|
||||
are generated in the device driver as close as possible, but always
|
||||
prior to, passing the packet to the network interface. Hence, they
|
||||
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
|
||||
|
@ -90,7 +99,8 @@ SOF_TIMESTAMPING_TX_SCHED:
|
|||
machines with virtual devices where a transmitted packet travels
|
||||
through multiple devices and, hence, multiple packet schedulers,
|
||||
a timestamp is generated at each layer. This allows for fine
|
||||
grained measurement of queuing delay.
|
||||
grained measurement of queuing delay. This flag can be enabled
|
||||
via both socket options and control messages.
|
||||
|
||||
SOF_TIMESTAMPING_TX_ACK:
|
||||
Request tx timestamps when all data in the send buffer has been
|
||||
|
@ -99,6 +109,7 @@ SOF_TIMESTAMPING_TX_ACK:
|
|||
over-report measurement, because the timestamp is generated when all
|
||||
data up to and including the buffer at send() was acknowledged: the
|
||||
cumulative acknowledgment. The mechanism ignores SACK and FACK.
|
||||
This flag can be enabled via both socket options and control messages.
|
||||
|
||||
|
||||
1.3.2 Timestamp Reporting
|
||||
|
@ -183,6 +194,37 @@ having access to the contents of the original packet, so cannot be
|
|||
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:
|
||||
|
||||
struct msghdr *msg;
|
||||
...
|
||||
cmsg = CMSG_FIRSTHDR(msg);
|
||||
cmsg->cmsg_level = SOL_SOCKET;
|
||||
cmsg->cmsg_type = SO_TIMESTAMPING;
|
||||
cmsg->cmsg_len = CMSG_LEN(sizeof(__u32));
|
||||
*((__u32 *) CMSG_DATA(cmsg)) = SOF_TIMESTAMPING_TX_SCHED |
|
||||
SOF_TIMESTAMPING_TX_SOFTWARE |
|
||||
SOF_TIMESTAMPING_TX_ACK;
|
||||
err = sendmsg(fd, msg, 0);
|
||||
|
||||
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:
|
||||
|
||||
__u32 val = SOF_TIMESTAMPING_SOFTWARE |
|
||||
SOF_TIMESTAMPING_OPT_ID /* or any other flag */;
|
||||
err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val,
|
||||
sizeof(val));
|
||||
|
||||
|
||||
1.4 Bytestream Timestamps
|
||||
|
||||
The SO_TIMESTAMPING interface supports timestamping of bytes in a
|
||||
|
|
Loading…
Reference in a new issue