About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / timestamping.txt




Custom Search

Based on kernel version 3.4. Page generated on 2012-05-21 22:08 EST.

1	The 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	
16	The following interface complements the existing ones: receive time
17	stamps can be generated and returned for arbitrary packets and much
18	closer to the point where the packet is really sent. Time stamps can
19	be generated in software (as before) or in hardware (if the hardware
20	has such a feature).
21	
22	SO_TIMESTAMPING:
23	
24	Instructs the socket layer which kind of information is wanted. The
25	parameter is an integer with some of the following bits set. Setting
26	other bits is an error and doesn't change the current state.
27	
28	SOF_TIMESTAMPING_TX_HARDWARE:  try to obtain send time stamp in hardware
29	SOF_TIMESTAMPING_TX_SOFTWARE:  if SOF_TIMESTAMPING_TX_HARDWARE is off or
30	                               fails, then do it in software
31	SOF_TIMESTAMPING_RX_HARDWARE:  return the original, unmodified time stamp
32	                               as generated by the hardware
33	SOF_TIMESTAMPING_RX_SOFTWARE:  if SOF_TIMESTAMPING_RX_HARDWARE is off or
34	                               fails, then do it in software
35	SOF_TIMESTAMPING_RAW_HARDWARE: return original raw hardware time stamp
36	SOF_TIMESTAMPING_SYS_HARDWARE: return hardware time stamp transformed to
37	                               the system time base
38	SOF_TIMESTAMPING_SOFTWARE:     return system time stamp generated in
39	                               software
40	
41	SOF_TIMESTAMPING_TX/RX determine how time stamps are generated.
42	SOF_TIMESTAMPING_RAW/SYS determine how they are reported in the
43	following control message:
44	
45	struct scm_timestamping {
46		struct timespec systime;
47		struct timespec hwtimetrans;
48		struct timespec hwtimeraw;
49	};
50	
51	recvmsg() can be used to get this control message for regular incoming
52	packets. For send time stamps the outgoing packet is looped back to
53	the socket's error queue with the send time stamp(s) attached. It can
54	be received with recvmsg(flags=MSG_ERRQUEUE). The call returns the
55	original outgoing packet data including all headers preprended down to
56	and including the link layer, the scm_timestamping control message and
57	a sock_extended_err control message with ee_errno==ENOMSG and
58	ee_origin==SO_EE_ORIGIN_TIMESTAMPING. A socket with such a pending
59	bounced packet is ready for reading as far as select() is concerned.
60	If the outgoing packet has to be fragmented, then only the first
61	fragment is time stamped and returned to the sending socket.
62	
63	All three values correspond to the same event in time, but were
64	generated in different ways. Each of these values may be empty (= all
65	zero), in which case no such value was available. If the application
66	is not interested in some of these values, they can be left blank to
67	avoid the potential overhead of calculating them.
68	
69	systime is the value of the system time at that moment. This
70	corresponds to the value also returned via SO_TIMESTAMP[NS]. If the
71	time stamp was generated by hardware, then this field is
72	empty. Otherwise it is filled in if SOF_TIMESTAMPING_SOFTWARE is
73	set.
74	
75	hwtimeraw is the original hardware time stamp. Filled in if
76	SOF_TIMESTAMPING_RAW_HARDWARE is set. No assumptions about its
77	relation to system time should be made.
78	
79	hwtimetrans is the hardware time stamp transformed so that it
80	corresponds as good as possible to system time. This correlation is
81	not perfect; as a consequence, sorting packets received via different
82	NICs by their hwtimetrans may differ from the order in which they were
83	received. hwtimetrans may be non-monotonic even for the same NIC.
84	Filled in if SOF_TIMESTAMPING_SYS_HARDWARE is set. Requires support
85	by the network device and will be empty without that support.
86	
87	
88	SIOCSHWTSTAMP:
89	
90	Hardware time stamping must also be initialized for each device driver
91	that is expected to do hardware time stamping. The parameter is defined in
92	/include/linux/net_tstamp.h as:
93	
94	struct hwtstamp_config {
95		int flags;	/* no flags defined right now, must be zero */
96		int tx_type;	/* HWTSTAMP_TX_* */
97		int rx_filter;	/* HWTSTAMP_FILTER_* */
98	};
99	
100	Desired behavior is passed into the kernel and to a specific device by
101	calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whose
102	ifr_data points to a struct hwtstamp_config. The tx_type and
103	rx_filter are hints to the driver what it is expected to do. If
104	the requested fine-grained filtering for incoming packets is not
105	supported, the driver may time stamp more than just the requested types
106	of packets.
107	
108	A driver which supports hardware time stamping shall update the struct
109	with the actual, possibly more permissive configuration. If the
110	requested packets cannot be time stamped, then nothing should be
111	changed and ERANGE shall be returned (in contrast to EINVAL, which
112	indicates that SIOCSHWTSTAMP is not supported at all).
113	
114	Only a processes with admin rights may change the configuration. User
115	space is responsible to ensure that multiple processes don't interfere
116	with each other and that the settings are reset.
117	
118	/* possible values for hwtstamp_config->tx_type */
119	enum {
120		/*
121		 * no outgoing packet will need hardware time stamping;
122		 * should a packet arrive which asks for it, no hardware
123		 * time stamping will be done
124		 */
125		HWTSTAMP_TX_OFF,
126	
127		/*
128		 * enables hardware time stamping for outgoing packets;
129		 * the sender of the packet decides which are to be
130		 * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
131		 * before sending the packet
132		 */
133		HWTSTAMP_TX_ON,
134	};
135	
136	/* possible values for hwtstamp_config->rx_filter */
137	enum {
138		/* time stamp no incoming packet at all */
139		HWTSTAMP_FILTER_NONE,
140	
141		/* time stamp any incoming packet */
142		HWTSTAMP_FILTER_ALL,
143	
144		/* return value: time stamp all packets requested plus some others */
145		HWTSTAMP_FILTER_SOME,
146	
147		/* PTP v1, UDP, any kind of event packet */
148		HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
149	
150		/* for the complete list of values, please check
151		 * the include file /include/linux/net_tstamp.h
152		 */
153	};
154	
155	
156	DEVICE IMPLEMENTATION
157	
158	A driver which supports hardware time stamping must support the
159	SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with
160	the actual values as described in the section on SIOCSHWTSTAMP.
161	
162	Time stamps for received packets must be stored in the skb. To get a pointer
163	to the shared time stamp structure of the skb call skb_hwtstamps(). Then
164	set the time stamps in the structure:
165	
166	struct skb_shared_hwtstamps {
167		/* hardware time stamp transformed into duration
168		 * since arbitrary point in time
169		 */
170		ktime_t	hwtstamp;
171		ktime_t	syststamp; /* hwtstamp transformed to system time base */
172	};
173	
174	Time stamps for outgoing packets are to be generated as follows:
175	- In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP)
176	  is set no-zero. If yes, then the driver is expected to do hardware time
177	  stamping.
178	- If this is possible for the skb and requested, then declare
179	  that the driver is doing the time stamping by setting the flag
180	  SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. with
181	
182	      skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;
183	
184	  You might want to keep a pointer to the associated skb for the next step
185	  and not free the skb. A driver not supporting hardware time stamping doesn't
186	  do that. A driver must never touch sk_buff::tstamp! It is used to store
187	  software generated time stamps by the network subsystem.
188	- As soon as the driver has sent the packet and/or obtained a
189	  hardware time stamp for it, it passes the time stamp back by
190	  calling skb_hwtstamp_tx() with the original skb, the raw
191	  hardware time stamp. skb_hwtstamp_tx() clones the original skb and
192	  adds the timestamps, therefore the original skb has to be freed now.
193	  If obtaining the hardware time stamp somehow fails, then the driver
194	  should not fall back to software time stamping. The rationale is that
195	  this would occur at a later time in the processing pipeline than other
196	  software time stamping and therefore could lead to unexpected deltas
197	  between time stamps.
198	- If the driver did not set the SKBTX_IN_PROGRESS flag (see above), then
199	  dev_hard_start_xmit() checks whether software time stamping
200	  is wanted as fallback and potentially generates the time stamp.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.