Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 69298698 authored by Patrick Loschmidt's avatar Patrick Loschmidt Committed by David S. Miller
Browse files

net: corrected documentation for hardware time stamping 



The current documentation for hardware time stamping does not
correctly specify the available kernel functions since the
implementation was changed later on.

Signed-off-by: default avatarPatrick Loschmidt <Patrick.Loschmidt@oeaw.ac.at>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent b6222682

Documentation/networking/timestamping.txt

+46 −30
Original line number Original line Diff line number Diff line
@@ -41,6 +41,7 @@ SOF_TIMESTAMPING_SOFTWARE: return system time stamp generated in 
SOF_TIMESTAMPING_TX/RX determine how time stamps are generated.

SOF_TIMESTAMPING_TX/RX determine how time stamps are generated.

SOF_TIMESTAMPING_RAW/SYS determine how they are reported in the

SOF_TIMESTAMPING_RAW/SYS determine how they are reported in the

following control message:

following control message:



struct scm_timestamping {

struct scm_timestamping {

	struct timespec systime;

	struct timespec systime;

	struct timespec hwtimetrans;

	struct timespec hwtimetrans;
@@ -87,7 +88,8 @@ by the network device and will be empty without that support. 
SIOCSHWTSTAMP:

SIOCSHWTSTAMP:





Hardware time stamping must also be initialized for each device driver

Hardware time stamping must also be initialized for each device driver

that is expected to do hardware time stamping. The parameter is:

that is expected to do hardware time stamping. The parameter is defined in

/include/linux/net_tstamp.h as:





struct hwtstamp_config {

struct hwtstamp_config {

	int flags;	/* no flags defined right now, must be zero */

	int flags;	/* no flags defined right now, must be zero */
@@ -145,36 +147,50 @@ enum { 
	/* PTP v1, UDP, any kind of event packet */

	/* PTP v1, UDP, any kind of event packet */

	HWTSTAMP_FILTER_PTP_V1_L4_EVENT,

	HWTSTAMP_FILTER_PTP_V1_L4_EVENT,





        ...

	/* for the complete list of values, please check

	 * the include file /include/linux/net_tstamp.h

	 */

};

};









DEVICE IMPLEMENTATION

DEVICE IMPLEMENTATION





A driver which supports hardware time stamping must support the

A driver which supports hardware time stamping must support the

SIOCSHWTSTAMP ioctl. Time stamps for received packets must be stored

SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with

in the skb with skb_hwtstamp_set().

the actual values as described in the section on SIOCSHWTSTAMP.



Time stamps for received packets must be stored in the skb. To get a pointer

to the shared time stamp structure of the skb call skb_hwtstamps(). Then

set the time stamps in the structure:



struct skb_shared_hwtstamps {

	/* hardware time stamp transformed into duration

	 * since arbitrary point in time

	 */

	ktime_t	hwtstamp;

	ktime_t	syststamp; /* hwtstamp transformed to system time base */

};





Time stamps for outgoing packets are to be generated as follows:

Time stamps for outgoing packets are to be generated as follows:

- In hard_start_xmit(), check if skb_hwtstamp_check_tx_hardware()

- In hard_start_xmit(), check if skb_tx(skb)->hardware is set no-zero.

  returns non-zero. If yes, then the driver is expected

  If yes, then the driver is expected to do hardware time stamping.

  to do hardware time stamping.

- If this is possible for the skb and requested, then declare

- If this is possible for the skb and requested, then declare

  that the driver is doing the time stamping by calling

  that the driver is doing the time stamping by setting the field

  skb_hwtstamp_tx_in_progress(). A driver not supporting

  skb_tx(skb)->in_progress non-zero. You might want to keep a pointer

  hardware time stamping doesn't do that. A driver must never

  to the associated skb for the next step and not free the skb. A driver

  touch sk_buff::tstamp! It is used to store how time stamping

  not supporting hardware time stamping doesn't do that. A driver must

  for an outgoing packets is to be done.

  never touch sk_buff::tstamp! It is used to store software generated

  time stamps by the network subsystem.

- As soon as the driver has sent the packet and/or obtained a

- As soon as the driver has sent the packet and/or obtained a

  hardware time stamp for it, it passes the time stamp back by

  hardware time stamp for it, it passes the time stamp back by

  calling skb_hwtstamp_tx() with the original skb, the raw

  calling skb_hwtstamp_tx() with the original skb, the raw

  hardware time stamp and a handle to the device (necessary

  hardware time stamp. skb_hwtstamp_tx() clones the original skb and

  to convert the hardware time stamp to system time). If obtaining

  adds the timestamps, therefore the original skb has to be freed now.

  the hardware time stamp somehow fails, then the driver should

  If obtaining the hardware time stamp somehow fails, then the driver

  not fall back to software time stamping. The rationale is that

  should not fall back to software time stamping. The rationale is that

  this would occur at a later time in the processing pipeline

  this would occur at a later time in the processing pipeline than other

  than other software time stamping and therefore could lead

  software time stamping and therefore could lead to unexpected deltas

  to unexpected deltas between time stamps.

  between time stamps.

- If the driver did not call skb_hwtstamp_tx_in_progress(), then

- If the driver did not call set skb_tx(skb)->in_progress, then

  dev_hard_start_xmit() checks whether software time stamping

  dev_hard_start_xmit() checks whether software time stamping

  is wanted as fallback and potentially generates the time stamp.
 
  is wanted as fallback and potentially generates the time stamp.