Commit fd91e12f authored by Soheil Hassas Yeganeh's avatar Soheil Hassas Yeganeh Committed by David S. Miller

sock: document timestamping via cmsg in Documentation

Update docs and add code snippet for using cmsg for timestamping.
Signed-off-by: default avatarSoheil Hassas Yeganeh <soheil@google.com>
Acked-by: default avatarWillem de Bruijn <willemb@google.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent c14ac945
...@@ -44,11 +44,17 @@ timeval of SO_TIMESTAMP (ms). ...@@ -44,11 +44,17 @@ timeval of SO_TIMESTAMP (ms).
Supports multiple types of timestamp requests. As a result, this Supports multiple types of timestamp requests. As a result, this
socket option takes a bitmap of flags, not a boolean. In socket option takes a bitmap of flags, not a boolean. In
err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (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 val is an integer with any of the following bits set. Setting other
bit returns EINVAL and does not change the current state. 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 1.3.1 Timestamp Generation
...@@ -71,13 +77,16 @@ SOF_TIMESTAMPING_RX_SOFTWARE: ...@@ -71,13 +77,16 @@ SOF_TIMESTAMPING_RX_SOFTWARE:
kernel receive stack. kernel receive stack.
SOF_TIMESTAMPING_TX_HARDWARE: 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: SOF_TIMESTAMPING_TX_SOFTWARE:
Request tx timestamps when data leaves the kernel. These timestamps Request tx timestamps when data leaves the kernel. These timestamps
are generated in the device driver as close as possible, but always are generated in the device driver as close as possible, but always
prior to, passing the packet to the network interface. Hence, they prior to, passing the packet to the network interface. Hence, they
require driver support and may not be available for all devices. require driver support and may not be available for all devices.
This flag can be enabled via both socket options and control messages.
SOF_TIMESTAMPING_TX_SCHED: SOF_TIMESTAMPING_TX_SCHED:
Request tx timestamps prior to entering the packet scheduler. Kernel Request tx timestamps prior to entering the packet scheduler. Kernel
...@@ -90,7 +99,8 @@ SOF_TIMESTAMPING_TX_SCHED: ...@@ -90,7 +99,8 @@ SOF_TIMESTAMPING_TX_SCHED:
machines with virtual devices where a transmitted packet travels machines with virtual devices where a transmitted packet travels
through multiple devices and, hence, multiple packet schedulers, through multiple devices and, hence, multiple packet schedulers,
a timestamp is generated at each layer. This allows for fine 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: SOF_TIMESTAMPING_TX_ACK:
Request tx timestamps when all data in the send buffer has been Request tx timestamps when all data in the send buffer has been
...@@ -99,6 +109,7 @@ SOF_TIMESTAMPING_TX_ACK: ...@@ -99,6 +109,7 @@ SOF_TIMESTAMPING_TX_ACK:
over-report measurement, because the timestamp is generated when all over-report measurement, because the timestamp is generated when all
data up to and including the buffer at send() was acknowledged: the data up to and including the buffer at send() was acknowledged: the
cumulative acknowledgment. The mechanism ignores SACK and FACK. 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 1.3.2 Timestamp Reporting
...@@ -183,6 +194,37 @@ having access to the contents of the original packet, so cannot be ...@@ -183,6 +194,37 @@ having access to the contents of the original packet, so cannot be
combined with SOF_TIMESTAMPING_OPT_TSONLY. 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 1.4 Bytestream Timestamps
The SO_TIMESTAMPING interface supports timestamping of bytes in a The SO_TIMESTAMPING interface supports timestamping of bytes in a
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment