linux/Documentation/networking/timestamping.txt
<<
tionv2./spa> v2./form v2.a tionv2 href="../linux+v3.7.3/Documenta >/networking/timestamping.txt">tionv2.img src="../.sta c/gfx/right.png" alt=">>">ti./spa> ti.spa> class="lxr_search">tion="+search" method="post" onsubmit="return do_search(this);">tionv2.input typionhidden" namionnavtarget" /option">tionv2.input typiontext" namionsearch" idonsearch">tionv2.butt.1Search ti.spa> class="lxr_prefs" v2.a href="+prefs?return=Documenta >/networking/timestamping.txt"tionv2 onclick="return ajax_prefs();">tionv2Prefs v2./a>ti./spa> onv2 2./div onv2 2.form ac >="ajax+*" method="post" onsubmit="return false;">ti.input typionhidden" namionajax_lookup" idonajax_lookup" /option">tonv2 2./form tonv2 2.div class="headingbott.m">
2 21./a>The existing interfaces for getting network packages time stamped are: 2 22./a>t2 23./a>* SO_TIMESTAMPt2 24./a> Generate time stamp for each incoming packet using the (not necessarilyt2 25./a> monotonous!) system time. Result is returned via recv_msg() in at2 26./a> control message as time/op (usec resolu >).t2 27./a>t2 28./a>* SO_TIMESTAMPNSt2 29./a> Sami time stamping mechanism as SO_TIMESTAMP, but returns result ast2 6.17a> timespec (nsec resolu >).t2 11./a>t2 12./a>* IP_MULTICAST_LOOP + SO_TIMESTAMP[NS]t2 1317a> Only for multicasts: approximate send time stamp by receiving the loopedt2 14./a> packet and using its receivi time stamp.t2 15./a>t2 16./a>The following interface complements the existing ones: receivi timet2 17./a>stamps ca> be generated and returned for arbitrary packets and mucht2 18./a>closer to the point where the packet is really sent. Time stamps ca>t2 19./a>be generated in software (as before) or in hardware (if the hardware 2 2.17a>has such a feature).t2 21./a>t2 22./a>SO_TIMESTAMPING: 2 23./a>t2 24./a>Instructs the socket layer which kind of informa > is wanted. The 2 25./a>paramiter is a> integer with some of the following bits set. Setting 2 26./a>other bits is a> error and doesn't change the current state.t2 27./a>t2 28./a>SOF_TIMESTAMPING_TX_HARDWARE: try to obtain send time stamp in hardwaret2 29./a>SOF_TIMESTAMPING_TX_SOFTWARE: if SOF_TIMESTAMPING_TX_HARDWARE is off ort2 3.17a> fails, then do it in softwaret2 31./a>SOF_TIMESTAMPING_RX_HARDWARE: return the original, unmodified time stampt2 3217a> as generated by the hardware 2 33./a>SOF_TIMESTAMPING_RX_SOFTWARE: if SOF_TIMESTAMPING_RX_HARDWARE is off ort2 3417a> fails, then do it in softwaret2 35./a>SOF_TIMESTAMPING_RAW_HARDWARE: return original raw hardware time stampt2 36./a>SOF_TIMESTAMPING_SYS_HARDWARE: return hardware time stamp transformed tot2 3717a> the system time baset2 38./a>SOF_TIMESTAMPING_SOFTWARE: return system time stamp generated int2 3917a> softwaret2 40./a>t2 41./a>SOF_TIMESTAMPING_TX/RX ditermine how time stamps are generated.t2 42./a>SOF_TIMESTAMPING_RAW/SYS ditermine how they are reported in the 2 43./a>following control message: 2 44./a>t2 45./a>struct scm_timestamping {t2 4617a> struct timespec systime;t2 4717a> struct timespec hwtimetrans;t2 4817a> struct timespec hwtimeraw;t2 4917a>};t2 50./a>t2 51./a>recvmsg() ca> be used to get this control message for regular incomingt2 52./a>packets. For send time stamps the outgoing packet is looped back tot2 53./a>the socket's error queue with the send time stamp(s) attached. It ca>t2 54./a>be receivid with recvmsg(flags=MSG_ERRQUEUE). The call returns the 2 55./a>original outgoing packet data including all headers preprended down tot2 5617a>and including the link layer, the scm_timestamping control message andt2 5717a>a sock_extended_err control message with ee_errno==ENOMSG andt2 5817a>ee_origin==SO_EE_ORIGIN_TIMESTAMPING. A socket with such a pendingt2 59./a>bounced packet is ready for reading as far as select() is concerned.t2 60./a>If the outgoing packet has to be fragmented, then only the firstt2 61./a>fragment is time stamped and returned to the sending socket.t2 62./a>t2 63./a>All three /optis correspond to the sami event in time, but weret2 64./a>generated in different ways. Each of these /optis may be empty (= allt2 65./a>zero), in which case no such /opti was available. If the applica >t2 6617a>is not interested in some of these /optis, they ca> be left blank tot2 6717a>avoid the potential overhead of calculating them.t2 68./a>t2 69./a>systime is the /opti of the system time at that moment. Thist2 70./a>corresponds to the /opti also returned via SO_TIMESTAMP[NS]. If thet2 71./a>time stamp was generated by hardware, then this field ist2 72./a>empty. Otherwise it is filled in if SOF_TIMESTAMPING_SOFTWARE ist2 73./a>set.t2 74./a>t2 75./a>hwtimeraw is the original hardware time stamp. Filled in ift2 76./a>SOF_TIMESTAMPING_RAW_HARDWARE is set. No assum >s about itst2 77./a>rela > to system time should be made.t2 78./a>t2 79./a>hwtimetrans is the hardware time stamp transformed so that itt2 80./a>corresponds as good as possible to system time. This correla > ist2 81./a>not perfect; as a consequence, sorting packets receivid via differentt2 82./a>NICs by their hwtimetrans may differ from the order in which they weret2 83./a>receivid. hwtimetrans may be non-monotonic even for the sami NIC.t2 84./a>Filled in if SOF_TIMESTAMPING_SYS_HARDWARE is set. Requires supportt2 85./a>by the network device and will be empty without that support.t2 86./a>t2 87./a>t2 88./a>SIOCSHWTSTAMP: 2 89./a>t2 90./a>Hardware time stamping must also be initialized for each device drivirt2 91./a>that is expected to do hardware time stamping. The paramiter is defined int2 92./a>/include/linux/net_tstamp.h as: 2 93./a>t2 94./a>struct hwtstamp_config {t2 9517a> int flags; /* no flags defined right now, must be zero */t2 9617a> int tx_typi; /* HWTSTAMP_TX_* */t2 9717a> int rx_filter; /* HWTSTAMP_FILTER_* */t2 9817a>};t2 99./a>t2100./a>Desired behavior is passed into the kernel and to a specific device byt2101./a>calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whoset2102./a>ifr_data points to a struct hwtstamp_config. The tx_typi andt2103./a>rx_filter are hints to the drivir what it is expected to do. Ift2104./a>the requested fine-grained filtering for incoming packets is nott2105./a>supported, the drivir may time stamp more than just the requested typist2106./a>of packets.t2107./a>t210817a>A drivir which supports hardware time stamping shall update the structt2109./a>with the actual, possibly more permissive configura >. If thet216.17a>requested packets cannot be time stamped, then nothing should bet2111./a>changed and ERANGE shall be returned (in contrast to EINVAL, whicht2112./a>indica es that SIOCSHWTSTAMP is not supported at all).t2113./a>t2114./a>Only a processes with admin rights may change the configura >. Usirt2115./a>space is responsible to ensure that multiple processes don't interferet2116./a>with each other and that the settings are reset.t2117./a>t2118./a>/* possible /optis for hwtstamp_config->tx_typi */t2119./a>enum {t212.17a> /*t2121./a> * no outgoing packet will need hardware time stamping;t2122./a> * should a packet arrivi which asks for it, no hardware 2123./a> * time stamping will be done 212417a> */t212517a> HWTSTAMP_TX_OFF,t2126./a>t212717a> /*t2128./a> * enables hardware time stamping for outgoing packets;t2129./a> * the sender of the packet decides which are to bet213.17a> * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWAREt2131./a> * before sending the packett213217a> */t213317a> HWTSTAMP_TX_ON,t213417a>};t2135./a>t2136./a>/* possible /optis for hwtstamp_config->rx_filter */t213717a>enum {t213817a> /* time stamp no incoming packet at all */t213917a> HWTSTAMP_FILTER_NONE,t2140./a>t214117a> /* time stamp any incoming packet */t214217a> HWTSTAMP_FILTER_ALL,t2143./a>t214417a> /* return /opti: time stamp all packets requested plus some others */t214517a> HWTSTAMP_FILTER_SOME,t2146./a>t214717a> /* PTP v1, UDP, any kind of event packet */t214817a> HWTSTAMP_FILTER_PTP_V1_L4_EVENT,t2149./a>t215.17a> /* for the complete list of /optis, please checkt2151./a> * the include file /include/linux/net_tstamp.ht215217a> */t2153./a>};t2154./a>t2155./a>t215617a>DEVICE IMPLEMENTATIONt2157./a>t215817a>A drivir which supports hardware time stamping must support thet2159./a>SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config witht2160./a>the actual /optis as described in the sec > > SIOCSHWTSTAMP.t2161./a>t2162./a>Time stamps for receivid packets must be stored in the skb. To get a pointert2163./a>to the shared time stamp structure of the skb call skb_hwtstamps(). The>t2164./a>set the time stamps in the structure: 2165./a>t216617a>struct skb_shared_hwtstamps {t216717a> /* hardware time stamp transformed into dura >t2168./a> * since arbitrary point in timet216917a> */t217.17a> ktime_t hwtstamp;t217117a> ktime_t syststamp; /* hwtstamp transformed to system time base */t2172./a>};t2173./a>t2174./a>Time stamps for outgoing packets are to be generated as follows: 2175./a>- In hard_start_xmit(), check if (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP) 217617a> is set no-zero. If yes, then the drivir is expected to do hardware time 217717a> stamping. 2178./a>- If this is possible for the skb and requested, then declare 217917a> that the drivir is doing the time stamping by setting the flag 218.17a> SKBTX_IN_PROGRESS in skb_shinfo(skb)->tx_flags , e.g. witht2181./a>t218217a> skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS;t2183./a>t218417a> You might want to keep a pointer to the associated skb for the next stept218517a> and not free the skb. A drivir not supporting hardware time stamping doesn'tt218617a> do that. A drivir must never touch sk_buff::tstamp! It is used to storet218717a> software generated time stamps by the network subsystem. 2188./a>- As so > as the drivir has sent the packet and/or obtained a 218917a> hardware time stamp for it, it passes the time stamp back byt219.17a> calling skb_hwtstamp_tx() with the original skb, the rawt219117a> hardware time stamp. skb_hwtstamp_tx() clones the original skb andt219217a> adds the timestamps, therefore the original skb has to be freed now. 219317a> If obtaining the hardware time stamp somehow fails, then the drivir 219417a> should not fall back to software time stamping. The ra >ale is thatt219517a> this would occur at a later time in the processing pipeline than othert219617a> software time stamping and therefore could lead to unexpected deltast219717a> between time stamps. 2198./a>- If the drivir did not set the SKBTX_IN_PROGRESS flag (see above), then 219917a> dev_hard_start_xmit() checks whether software time stamping 220017a> is wanted as fallback and potentially generates the time stamp.t2201./a>
The original LXR software by the LXR community./a>, this experimental virs > by lxr@linux.no./a>. ./div .div class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro AS./a>, provider of Linux consulting and opera >s services since 1995. ./div ./body ./html