[PATCH] net: Improve SO_TIMESTAMPING documentation and fix a minor code bug

[PATCH] net: Improve SO_TIMESTAMPING documentation and fix a minor code bug

[Andy Lutomirski]

The original documentation was very unclear.

The code fix is presumably related to the formerly unclear
documentation: SOCK_TIMESTAMPING_RX_SOFTWARE has no effect on
__sock_recv_timestamp's behavior, so calling __sock_recv_ts_and_drops
from sock_recv_ts_and_drops if only SOCK_TIMESTAMPING_RX_SOFTWARE is
set is pointless.  This should have no user-observable effect.

Signed-off-by: Andy Lutomirski <luto@amacapital.net>
---
 Documentation/networking/timestamping.txt | 52 +++++++++++++++++++------------
 include/net/sock.h                        |  1 -
 2 files changed, 32 insertions(+), 21 deletions(-)

diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt
index 661d3c3..048c92b 100644
--- a/Documentation/networking/timestamping.txt
+++ b/Documentation/networking/timestamping.txt
@@ -21,26 +21,38 @@ has such a feature).
 
 SO_TIMESTAMPING:
 
-Instructs the socket layer which kind of information is wanted. The
-parameter is an integer with some of the following bits set. Setting
-other bits is an error and doesn't change the current state.
-
-SOF_TIMESTAMPING_TX_HARDWARE:  try to obtain send time stamp in hardware
-SOF_TIMESTAMPING_TX_SOFTWARE:  if SOF_TIMESTAMPING_TX_HARDWARE is off or
-                               fails, then do it in software
-SOF_TIMESTAMPING_RX_HARDWARE:  return the original, unmodified time stamp
-                               as generated by the hardware
-SOF_TIMESTAMPING_RX_SOFTWARE:  if SOF_TIMESTAMPING_RX_HARDWARE is off or
-                               fails, then do it in software
-SOF_TIMESTAMPING_RAW_HARDWARE: return original raw hardware time stamp
-SOF_TIMESTAMPING_SYS_HARDWARE: return hardware time stamp transformed to
-                               the system time base
-SOF_TIMESTAMPING_SOFTWARE:     return system time stamp generated in
-                               software
-
-SOF_TIMESTAMPING_TX/RX determine how time stamps are generated.
-SOF_TIMESTAMPING_RAW/SYS determine how they are reported in the
-following control message:
+Instructs the socket layer which kind of information should be collected
+and/or reported.  The parameter is an integer with some of the following
+bits set. Setting other bits is an error and doesn't change the current
+state.
+
+Four of the bits are requests to the stack to try to generate
+timestamps.  Any combination of them is valid.
+
+SOF_TIMESTAMPING_TX_HARDWARE:  try to obtain send time stamps in hardware
+SOF_TIMESTAMPING_TX_SOFTWARE:  try to obtain send time stamps in software
+SOF_TIMESTAMPING_RX_HARDWARE:  try to obtain receive time stamps in hardware
+SOF_TIMESTAMPING_RX_SOFTWARE:  try to obtain receive time stamps in software
+
+The other three bits control which timestamps will be reported in a
+generated control message.  If none of these bits are set or if none of
+the set bits correspond to data that is available, then the control
+message will not be generated:
+
+SOF_TIMESTAMPING_SOFTWARE:     report systime if available
+SOF_TIMESTAMPING_SYS_HARDWARE: report hwtimetrans if available
+SOF_TIMESTAMPING_RAW_HARDWARE: report hwtimeraw if available
+
+It is worth noting that timestamps may be collected for reasons other
+than being requested by a particular socket with
+SOF_TIMESTAMPING_[TR]X_(HARD|SOFT)WARE.  For example, most drivers that
+can generate hardware receive timestamps ignore
+SOF_TIMESTAMPING_RX_HARDWARE.  It is still a good idea to set that flag
+in case future drivers pay attention.
+
+If timestamps are reported, they will appear in a control message with
+cmsg_level==SOL_SOCKET, cmsg_type==SO_TIMESTAMPING, and a payload like
+this:
 
 struct scm_timestamping {
 	struct timespec systime;
diff --git a/include/net/sock.h b/include/net/sock.h
index 5c3f7c3..7c4167b 100644
--- a/include/net/sock.h
+++ b/include/net/sock.h
@@ -2186,7 +2186,6 @@ static inline void sock_recv_ts_and_drops(struct msghdr *msg, struct sock *sk,
 {
 #define FLAGS_TS_OR_DROPS ((1UL << SOCK_RXQ_OVFL)			| \
 			   (1UL << SOCK_RCVTSTAMP)			| \
-			   (1UL << SOCK_TIMESTAMPING_RX_SOFTWARE)	| \
 			   (1UL << SOCK_TIMESTAMPING_SOFTWARE)		| \
 			   (1UL << SOCK_TIMESTAMPING_RAW_HARDWARE)	| \
 			   (1UL << SOCK_TIMESTAMPING_SYS_HARDWARE))
-- 
1.8.5.3

Re: [PATCH] net: Improve SO_TIMESTAMPING documentation and fix a minor code bug

[Richard Cochran]

On Tue, Mar 04, 2014 at 05:24:10PM -0800, Andy Lutomirski wrote:
> The original documentation was very unclear.
> 
> The code fix is presumably related to the formerly unclear
> documentation: SOCK_TIMESTAMPING_RX_SOFTWARE has no effect on
> __sock_recv_timestamp's behavior, so calling __sock_recv_ts_and_drops
> from sock_recv_ts_and_drops if only SOCK_TIMESTAMPING_RX_SOFTWARE is
> set is pointless.  This should have no user-observable effect.
> 
> Signed-off-by: Andy Lutomirski <luto@amacapital.net>
> ---

Acked-by: Richard Cochran <richardcochran@gmail.com>

Re: [PATCH] net: Improve SO_TIMESTAMPING documentation and fix a minor code bug

[David Miller]

From: Andy Lutomirski <luto@amacapital.net>
Date: Tue,  4 Mar 2014 17:24:10 -0800

> The original documentation was very unclear.
> 
> The code fix is presumably related to the formerly unclear
> documentation: SOCK_TIMESTAMPING_RX_SOFTWARE has no effect on
> __sock_recv_timestamp's behavior, so calling __sock_recv_ts_and_drops
> from sock_recv_ts_and_drops if only SOCK_TIMESTAMPING_RX_SOFTWARE is
> set is pointless.  This should have no user-observable effect.
> 
> Signed-off-by: Andy Lutomirski <luto@amacapital.net>

Applied, thanks Andy.