net: Improve SO_TIMESTAMPING documentation and fix a minor code bug

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;

{

#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))