man2: adjtimex.2 : add info about Clock source

This is a patch to the adjtimex.2 file that add more
	detail about clock source in man page which is asked to be fixed.
	I got this information from standard document RFC5909 which is
	available at https://tools.ietf.org/html/rfc5905#appendix-A.5.5.1
Signed-off-by: Punit Vara <punitvara@gmail.com>
---
 man2/adjtimex.2 | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

Hello!

I'm not sure that this is what is meant by "Clock source" in struct timex.h.
STA_CLK can take only two values ("A" and "B"), and is read-only.
It was added in commit ee9851b218b8bafa22942b5404505ff3d2d34324
(kernel 2.6.25) at the same time MOD_CLKA and MOD_CLKB were removed.

> tree 581f455e02ed3d03e543642b5d54b83dc75d47c7
> parent ee9851b218b8bafa22942b5404505ff3d2d34324
> author Roman Zippel <zippel@linux-m68k.org> Thu May 1 04:34:33 2008 -0700
> committer Linus Torvalds <torvalds@linux-foundation.org> Thu May 1 08:03:58 2008 -0700
>
> ntp: NTP4 user space bits update
>
> This adds a few more things from the ntp nanokernel related to user space.
> It's now possible to select the resolution used of some values via STA_NANO
> and the kernel reports in which mode it works (pll/fll).
>
> If some values for adjtimex() are outside the acceptable range, they are now
> simply normalized instead of letting the syscall fail.  I removed
> MOD_CLKA/MOD_CLKB as the mapping didn't really makes any sense, the kernel
> doesn't support setting the clock.
>
> Signed-off-by: Roman Zippel <zippel@linux-m68k.org>
> Cc: john stultz <johnstul@us.ibm.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Originally, A and B were present to distinguish two modes of functioning:
whether an external clock is present or not. If an external clock system adjusts
the local clock, then NTP is not used. In the case of Linux, I think this
distinction between sources "A" and "B" is present for historical reasons, and
because it was present in the reference implementation for ntp but I don't see
where it's used in the kernel. See this for example of use of STA_CLK in another
implementation:
http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/ntpNanoclock/api.htm
And this for the NTP standard, version 4:
http://www.eecis.udel.edu/~mills/ntp/html/extern.html

In Linux, there are two ways to adjust the clock. If it's not by NTP, then it can
be through the use of system call clock_adjtime(2) (for which there is no man
page yet, see clock_settime(2) to get an idea of the interface) which uses a
function pointer clock_adj declared in a k_clock struct, which can be initialised
to function posix_clock_realtime_adj. (Everything is in kernel/time/posix-timers.c.)
Eventually, this boils down to using do_adjtimex, just as adjtimex(2) does.
I guess STA_CLK should be set/reset with one of the method and not the other, if
my understanding is correct, but it's not. Maybe because it's unused anyway?

Laurent

Le 30/08/2015 13:50, Punit Vara a écrit :
> 	This is a patch to the adjtimex.2 file that add more
> 	detail about clock source in man page which is asked to be fixed.
> 	I got this information from standard document RFC5909 which is
> 	available at https://tools.ietf.org/html/rfc5905#appendix-A.5.5.1
> Signed-off-by: Punit Vara <punitvara@gmail.com>
> ---
>  man2/adjtimex.2 | 24 ++++++++++++++++++++++--
>  1 file changed, 22 insertions(+), 2 deletions(-)
>
> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index 04b53b1..77b4e30 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.2
> @@ -276,8 +276,28 @@ Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop; read-only).
>  .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
>  .\" Author: Roman Zippel <zippel@linux-m68k.org>
>  Clock source (0 = A, 1 = B; read-only).
> -.\" FIXME It would be helpful to have some explanation of what
> -.\"       "Clock source" is.
> +Clock source is used to synchronized the time.It can be any standard clock 
> +sources like :
> +
> +Geosynchronous Orbit Environment Satellite
> +Global Position System
> +Galileo Positioning System
> +Generic pulse-per-second
> +Inter-Range Instrumentation Group
> +LF Radio WWVB Ft. Collins, CO 60 kHz
> +LF Radio DCF77 Mainflingen, DE 77.5 kHz
> +LF Radio HBG Prangins, HB 75 kHz 
> +LF Radio MSF Anthorn, UK 60 kHz
> +LF Radio JJY Fukushima, JP 40 kHz, Saga, JP 60 kHz
> +MF Radio LORAN C station, 100 kHz
> +MF Radio Allouis, FR 162 kHz
> +HF Radio CHU Ottawa, Ontario
> +HF Radio WWV Ft. Collins, CO
> +HF Radio WWVH Kauai, HI
> +NIST telephone modem
> +NIST telephone modem
> +USNO telephone modem
> +European telephone modem
>  .PP
>  Attempts to set read-only
>  .I status
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html