blob: bc35541249032c4d64c8888741eddc64f87e4f2e [file] [log] [blame]
Patrick Ohlycb9eff02009-02-12 05:03:36 +00001The existing interfaces for getting network packages time stamped are:
2
3* SO_TIMESTAMP
4 Generate time stamp for each incoming packet using the (not necessarily
5 monotonous!) system time. Result is returned via recv_msg() in a
6 control message as timeval (usec resolution).
7
8* SO_TIMESTAMPNS
9 Same time stamping mechanism as SO_TIMESTAMP, but returns result as
10 timespec (nsec resolution).
11
12* IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]
13 Only for multicasts: approximate send time stamp by receiving the looped
14 packet and using its receive time stamp.
15
16The following interface complements the existing ones: receive time
17stamps can be generated and returned for arbitrary packets and much
18closer to the point where the packet is really sent. Time stamps can
19be generated in software (as before) or in hardware (if the hardware
20has such a feature).
21
22SO_TIMESTAMPING:
23
Andrew Lutomirskiadca4762014-03-04 17:24:10 -080024Instructs the socket layer which kind of information should be collected
25and/or reported. The parameter is an integer with some of the following
26bits set. Setting other bits is an error and doesn't change the current
27state.
Patrick Ohlycb9eff02009-02-12 05:03:36 +000028
Andrew Lutomirskiadca4762014-03-04 17:24:10 -080029Four of the bits are requests to the stack to try to generate
30timestamps. Any combination of them is valid.
Patrick Ohlycb9eff02009-02-12 05:03:36 +000031
Andrew Lutomirskiadca4762014-03-04 17:24:10 -080032SOF_TIMESTAMPING_TX_HARDWARE: try to obtain send time stamps in hardware
33SOF_TIMESTAMPING_TX_SOFTWARE: try to obtain send time stamps in software
34SOF_TIMESTAMPING_RX_HARDWARE: try to obtain receive time stamps in hardware
35SOF_TIMESTAMPING_RX_SOFTWARE: try to obtain receive time stamps in software
36
37The other three bits control which timestamps will be reported in a
38generated control message. If none of these bits are set or if none of
39the set bits correspond to data that is available, then the control
40message will not be generated:
41
42SOF_TIMESTAMPING_SOFTWARE: report systime if available
43SOF_TIMESTAMPING_SYS_HARDWARE: report hwtimetrans if available
44SOF_TIMESTAMPING_RAW_HARDWARE: report hwtimeraw if available
45
46It is worth noting that timestamps may be collected for reasons other
47than being requested by a particular socket with
48SOF_TIMESTAMPING_[TR]X_(HARD|SOFT)WARE. For example, most drivers that
49can generate hardware receive timestamps ignore
50SOF_TIMESTAMPING_RX_HARDWARE. It is still a good idea to set that flag
51in case future drivers pay attention.
52
53If timestamps are reported, they will appear in a control message with
54cmsg_level==SOL_SOCKET, cmsg_type==SO_TIMESTAMPING, and a payload like
55this:
Patrick Loschmidt69298692010-04-07 21:52:07 -070056
57struct scm_timestamping {
58 struct timespec systime;
59 struct timespec hwtimetrans;
60 struct timespec hwtimeraw;
61};
Patrick Ohlycb9eff02009-02-12 05:03:36 +000062
63recvmsg() can be used to get this control message for regular incoming
64packets. For send time stamps the outgoing packet is looped back to
65the socket's error queue with the send time stamp(s) attached. It can
66be received with recvmsg(flags=MSG_ERRQUEUE). The call returns the
67original outgoing packet data including all headers preprended down to
68and including the link layer, the scm_timestamping control message and
69a sock_extended_err control message with ee_errno==ENOMSG and
70ee_origin==SO_EE_ORIGIN_TIMESTAMPING. A socket with such a pending
71bounced packet is ready for reading as far as select() is concerned.
Patrick Ohly51f31ca2009-02-12 05:03:39 +000072If the outgoing packet has to be fragmented, then only the first
73fragment is time stamped and returned to the sending socket.
Patrick Ohlycb9eff02009-02-12 05:03:36 +000074
75All three values correspond to the same event in time, but were
76generated in different ways. Each of these values may be empty (= all
77zero), in which case no such value was available. If the application
78is not interested in some of these values, they can be left blank to
79avoid the potential overhead of calculating them.
80
81systime is the value of the system time at that moment. This
82corresponds to the value also returned via SO_TIMESTAMP[NS]. If the
83time stamp was generated by hardware, then this field is
84empty. Otherwise it is filled in if SOF_TIMESTAMPING_SOFTWARE is
85set.
86
87hwtimeraw is the original hardware time stamp. Filled in if
88SOF_TIMESTAMPING_RAW_HARDWARE is set. No assumptions about its
89relation to system time should be made.
90
91hwtimetrans is the hardware time stamp transformed so that it
92corresponds as good as possible to system time. This correlation is
93not perfect; as a consequence, sorting packets received via different
94NICs by their hwtimetrans may differ from the order in which they were
95received. hwtimetrans may be non-monotonic even for the same NIC.
96Filled in if SOF_TIMESTAMPING_SYS_HARDWARE is set. Requires support
97by the network device and will be empty without that support.
98
99
Ben Hutchingsfd468c72013-11-14 01:19:29 +0000100SIOCSHWTSTAMP, SIOCGHWTSTAMP:
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000101
102Hardware time stamping must also be initialized for each device driver
Patrick Loschmidt69298692010-04-07 21:52:07 -0700103that is expected to do hardware time stamping. The parameter is defined in
104/include/linux/net_tstamp.h as:
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000105
106struct hwtstamp_config {
Patrick Loschmidt69298692010-04-07 21:52:07 -0700107 int flags; /* no flags defined right now, must be zero */
108 int tx_type; /* HWTSTAMP_TX_* */
109 int rx_filter; /* HWTSTAMP_FILTER_* */
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000110};
111
112Desired behavior is passed into the kernel and to a specific device by
113calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whose
114ifr_data points to a struct hwtstamp_config. The tx_type and
115rx_filter are hints to the driver what it is expected to do. If
116the requested fine-grained filtering for incoming packets is not
117supported, the driver may time stamp more than just the requested types
118of packets.
119
120A driver which supports hardware time stamping shall update the struct
121with the actual, possibly more permissive configuration. If the
122requested packets cannot be time stamped, then nothing should be
123changed and ERANGE shall be returned (in contrast to EINVAL, which
124indicates that SIOCSHWTSTAMP is not supported at all).
125
126Only a processes with admin rights may change the configuration. User
127space is responsible to ensure that multiple processes don't interfere
128with each other and that the settings are reset.
129
Ben Hutchingsfd468c72013-11-14 01:19:29 +0000130Any process can read the actual configuration by passing this
131structure to ioctl(SIOCGHWTSTAMP) in the same way. However, this has
132not been implemented in all drivers.
133
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000134/* possible values for hwtstamp_config->tx_type */
135enum {
136 /*
137 * no outgoing packet will need hardware time stamping;
138 * should a packet arrive which asks for it, no hardware
139 * time stamping will be done
140 */
141 HWTSTAMP_TX_OFF,
142
143 /*
144 * enables hardware time stamping for outgoing packets;
145 * the sender of the packet decides which are to be
146 * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
147 * before sending the packet
148 */
149 HWTSTAMP_TX_ON,
150};
151
152/* possible values for hwtstamp_config->rx_filter */
153enum {
154 /* time stamp no incoming packet at all */
155 HWTSTAMP_FILTER_NONE,
156
157 /* time stamp any incoming packet */
158 HWTSTAMP_FILTER_ALL,
159
Patrick Loschmidt69298692010-04-07 21:52:07 -0700160 /* return value: time stamp all packets requested plus some others */
161 HWTSTAMP_FILTER_SOME,
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000162
163 /* PTP v1, UDP, any kind of event packet */
164 HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
165
Patrick Loschmidt69298692010-04-07 21:52:07 -0700166 /* for the complete list of values, please check
167 * the include file /include/linux/net_tstamp.h
168 */
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000169};
170
171
172DEVICE IMPLEMENTATION
173
174A driver which supports hardware time stamping must support the
Patrick Loschmidt69298692010-04-07 21:52:07 -0700175SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with
Ben Hutchingsfd468c72013-11-14 01:19:29 +0000176the actual values as described in the section on SIOCSHWTSTAMP. It
177should also support SIOCGHWTSTAMP.
Patrick Loschmidt69298692010-04-07 21:52:07 -0700178
179Time stamps for received packets must be stored in the skb. To get a pointer
180to the shared time stamp structure of the skb call skb_hwtstamps(). Then
181set the time stamps in the structure:
182
183struct skb_shared_hwtstamps {
184 /* hardware time stamp transformed into duration
185 * since arbitrary point in time
186 */
187 ktime_t hwtstamp;
188 ktime_t syststamp; /* hwtstamp transformed to system time base */
189};
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000190
191Time stamps for outgoing packets are to be generated as follows:
Oliver Hartkopp2244d072010-08-17 08:59:14 +0000192- In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP)
193 is set no-zero. If yes, then the driver is expected to do hardware time
194 stamping.
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000195- If this is possible for the skb and requested, then declare
Oliver Hartkopp2244d072010-08-17 08:59:14 +0000196 that the driver is doing the time stamping by setting the flag
197 SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with
198
199 skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;
200
201 You might want to keep a pointer to the associated skb for the next step
202 and not free the skb. A driver not supporting hardware time stamping doesn't
203 do that. A driver must never touch sk_buff::tstamp! It is used to store
204 software generated time stamps by the network subsystem.
Jakub Kicinski59cb89e2014-03-16 20:32:48 +0100205- Driver should call skb_tx_timestamp() as close to passing sk_buff to hardware
206 as possible. skb_tx_timestamp() provides a software time stamp if requested
207 and hardware timestamping is not possible (SKBTX_IN_PROGRESS not set).
Patrick Ohlycb9eff02009-02-12 05:03:36 +0000208- As soon as the driver has sent the packet and/or obtained a
209 hardware time stamp for it, it passes the time stamp back by
210 calling skb_hwtstamp_tx() with the original skb, the raw
Patrick Loschmidt69298692010-04-07 21:52:07 -0700211 hardware time stamp. skb_hwtstamp_tx() clones the original skb and
212 adds the timestamps, therefore the original skb has to be freed now.
213 If obtaining the hardware time stamp somehow fails, then the driver
214 should not fall back to software time stamping. The rationale is that
215 this would occur at a later time in the processing pipeline than other
216 software time stamping and therefore could lead to unexpected deltas
217 between time stamps.