[patch] adjtimex.2: add explanation about ADJ_TAI action

[patch] adjtimex.2: add explanation about ADJ_TAI action

[Laurent Georget]

Here is another fix for adjtimex(2) for one of the FIXME. Other three
FIXMEs remain in the file but as those are my first patches, I prefer to
have them reviewed first before I submit other.

Information for ADJ_TAI was obtained through reading the source code of
the last version available on the kernel repo, exploring the git logs,
and through external documentation on the NTP protocol and TAI.

Thanks,

Laurent


diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 20a2f0b..8418b4f 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
 .\" Modified 2014-11-28 by Laurent Georget <laurent.georget@supelec.fr>
 .\"
-.\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
-.\"		commit 153b5d054ac2d98ea0d86504884326b6777f683d
-.\"
 .\" FIXME Document ADJ_MICRO and ADJ_NANO (added in Linux 2.6.26)
 .\"		commit eea83d896e318bda54be2d2770d2c5d6668d11db
 .\"		Author: Roman Zippel <zippel@linux-m68k.org>
@@ -93,6 +90,7 @@ combination of zero or more of the following bits:
 #define ADJ_ESTERROR          0x0008 /* estimated time error */
 #define ADJ_STATUS            0x0010 /* clock status */
 #define ADJ_TIMECONST         0x0020 /* pll time constant */
+#define ADJ_TAI               0x0080 /* TAI offset */
 #define ADJ_TICK              0x4000 /* tick value */
 #define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime() */
 .fi
@@ -101,7 +99,19 @@ combination of zero or more of the following bits:
 Ordinary users are restricted to a zero value for
 .IR modes .
 Only the superuser may set any parameters.
+.PP
+Support for TAI (Atomic International Time, for a complete explanation
about
+what it is and what is the difference between TAI and UTC, see
+.UR http://www.bipm.org/en/bipm/tai/tai.html
+.I BIPM
+.UE )
+has been added in version 2.6.29. For any clock, the TAI offset may
+be calculated by adding a value to the UTC offset which is updated when a
+leap second is added or deleted.
 .br
+All the offsets in the timex structure are expressed between the value
of the
+clock and the corresponding value (e.g. TAI offset is the difference
between
+the clock and the TAI, not between TAI and another value such as UTC).
 .ne 12v
 .SH RETURN VALUE
 On success,

Re: [patch] adjtimex.2: add explanation about ADJ_TAI action

[Richard Cochran]

On Fri, Nov 28, 2014 at 02:40:44PM +0100, Laurent Georget wrote:
> @@ -101,7 +99,19 @@ combination of zero or more of the following bits:
>  Ordinary users are restricted to a zero value for
>  .IR modes .
>  Only the superuser may set any parameters.
> +.PP
> +Support for TAI (Atomic International Time, for a complete explanation
> about
> +what it is and what is the difference between TAI and UTC, see
> +.UR http://www.bipm.org/en/bipm/tai/tai.html
> +.I BIPM
> +.UE )
> +has been added in version 2.6.29. For any clock, the TAI offset may

Not for "any clock", just for CLOCK_REALTIME.

> +be calculated by adding a value to the UTC offset which is updated when a
> +leap second is added or deleted.
>  .br
> +All the offsets in the timex structure are expressed between the value
> of the
> +clock and the corresponding value (e.g. TAI offset is the difference
> between
> +the clock and the TAI, not between TAI and another value such as UTC).

The TAI offset is just (TAI - UTC). That's all.

Thanks,
Richard

Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action

[Laurent Georget]

Le 28/11/2014 22:00, Richard Cochran a écrit :
> On Fri, Nov 28, 2014 at 02:40:44PM +0100, Laurent Georget wrote:
>> @@ -101,7 +99,19 @@ combination of zero or more of the following bits:
>>  Ordinary users are restricted to a zero value for
>>  .IR modes .
>>  Only the superuser may set any parameters.
>> +.PP
>> +Support for TAI (Atomic International Time, for a complete explanation
>> about
>> +what it is and what is the difference between TAI and UTC, see
>> +.UR http://www.bipm.org/en/bipm/tai/tai.html
>> +.I BIPM
>> +.UE )
>> +has been added in version 2.6.29. For any clock, the TAI offset may
> 
> Not for "any clock", just for CLOCK_REALTIME.

Considering that this is the only one representing the "human" time and
supporting an adjtime action, indeed, it's not relevant for anything
else than the realtime clock.

> 
>> +be calculated by adding a value to the UTC offset which is updated when a
>> +leap second is added or deleted.
>>  .br
>> +All the offsets in the timex structure are expressed between the value
>> of the
>> +clock and the corresponding value (e.g. TAI offset is the difference
>> between
>> +the clock and the TAI, not between TAI and another value such as UTC).
> 
> The TAI offset is just (TAI - UTC). That's all.
> 

Yes, my mistake, I misunderstood the part about timekeeping
(__timekeeping_set_tai_offset() in kernel/time/timekeeping.c, line 815)
which does store the offset in several formats (monotonic -> TAI and UTC
-> TAI). But this is not directly related to the timex value. Aniway
this is not very relevant in the man page.

Thank you for your comments. Below is a new version of the patch. Less
unrelevant chit-chat, more useful information (hopefully).


diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index 20a2f0b..871e607 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
 .\" Modified 2014-11-28 by Laurent Georget <laurent.georget@supelec.fr>
 .\"
-.\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
-.\"		commit 153b5d054ac2d98ea0d86504884326b6777f683d
-.\"
 .\" FIXME Document ADJ_MICRO and ADJ_NANO (added in Linux 2.6.26)
 .\"		commit eea83d896e318bda54be2d2770d2c5d6668d11db
 .\"		Author: Roman Zippel <zippel@linux-m68k.org>
@@ -74,6 +71,17 @@ struct timex {
                             (read-only) */
     struct timeval time; /* current time (read-only) */
     long tick;           /* usecs between clock ticks */
+
+    long ppsfreq;        /* pps frequency (scaled ppm) (read-only) */
+    long jitter;         /* pps jitter (usec) (read-only) */
+    int shift;           /* interval duration (sec) (read-only) */
+    long stabil;         /* pps stability (scaled ppm) (read-only) */
+    long jitcnt;         /* jitter limit exceeded (read-only) */
+    long calcnt;         /* calibration intervals (read-only) */
+    long errcnt;         /* calibration errors (read-only) */
+    long stbcnt;         /* stability limit exceeded (read-only) */
+
+    int tai;             /* TAI offset (s) (read-only) */
 };
 .fi
 .in
@@ -93,6 +101,7 @@ combination of zero or more of the following bits:
 #define ADJ_ESTERROR          0x0008 /* estimated time error */
 #define ADJ_STATUS            0x0010 /* clock status */
 #define ADJ_TIMECONST         0x0020 /* pll time constant */
+#define ADJ_TAI               0x0080 /* TAI offset */
 #define ADJ_TICK              0x4000 /* tick value */
 #define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime() */
 .fi
@@ -102,6 +111,20 @@ Ordinary users are restricted to a zero value for
 .IR modes .
 Only the superuser may set any parameters.
 .br
+In the case of
+.BR ADJ_TAI ,
+as
+.I buf->tai
+is read-only, the new value is passed through
+.IR buf->constant .
+.PP
+Support for TAI (Atomic International Time, for a complete explanation
about
+what it is and what is the difference between TAI and UTC, see
+.UR http://www.bipm.org/en/bipm/tai/tai.html
+.I BIPM
+.UE )
+has been added in version 2.6.29.
+.br
 .ne 12v
 .SH RETURN VALUE
 On success,

Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action

[Michael Kerrisk (man-pages)]

Hello Laurent,

Thanks for working on this. I have one question; see below.

On 11/29/2014 12:02 AM, Laurent Georget wrote:
> Le 28/11/2014 22:00, Richard Cochran a écrit :
>> On Fri, Nov 28, 2014 at 02:40:44PM +0100, Laurent Georget wrote:
>>> @@ -101,7 +99,19 @@ combination of zero or more of the following bits:
>>>  Ordinary users are restricted to a zero value for
>>>  .IR modes .
>>>  Only the superuser may set any parameters.
>>> +.PP
>>> +Support for TAI (Atomic International Time, for a complete explanation
>>> about
>>> +what it is and what is the difference between TAI and UTC, see
>>> +.UR http://www.bipm.org/en/bipm/tai/tai.html
>>> +.I BIPM
>>> +.UE )
>>> +has been added in version 2.6.29. For any clock, the TAI offset may
>>
>> Not for "any clock", just for CLOCK_REALTIME.
> 
> Considering that this is the only one representing the "human" time and
> supporting an adjtime action, indeed, it's not relevant for anything
> else than the realtime clock.
> 
>>
>>> +be calculated by adding a value to the UTC offset which is updated when a
>>> +leap second is added or deleted.
>>>  .br
>>> +All the offsets in the timex structure are expressed between the value
>>> of the
>>> +clock and the corresponding value (e.g. TAI offset is the difference
>>> between
>>> +the clock and the TAI, not between TAI and another value such as UTC).
>>
>> The TAI offset is just (TAI - UTC). That's all.
>>
> 
> Yes, my mistake, I misunderstood the part about timekeeping
> (__timekeeping_set_tai_offset() in kernel/time/timekeeping.c, line 815)
> which does store the offset in several formats (monotonic -> TAI and UTC
> -> TAI). But this is not directly related to the timex value. Aniway
> this is not very relevant in the man page.
> 
> Thank you for your comments. Below is a new version of the patch. Less
> unrelevant chit-chat, more useful information (hopefully).
> 
> 
> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index 20a2f0b..871e607 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.2
> @@ -26,9 +26,6 @@
>  .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
>  .\" Modified 2014-11-28 by Laurent Georget <laurent.georget@supelec.fr>
>  .\"
> -.\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
> -.\"		commit 153b5d054ac2d98ea0d86504884326b6777f683d
> -.\"
>  .\" FIXME Document ADJ_MICRO and ADJ_NANO (added in Linux 2.6.26)
>  .\"		commit eea83d896e318bda54be2d2770d2c5d6668d11db
>  .\"		Author: Roman Zippel <zippel@linux-m68k.org>
> @@ -74,6 +71,17 @@ struct timex {
>                              (read-only) */
>      struct timeval time; /* current time (read-only) */
>      long tick;           /* usecs between clock ticks */

What is the following piece about? Did you mean to include it in this patch?

> +
> +    long ppsfreq;        /* pps frequency (scaled ppm) (read-only) */
> +    long jitter;         /* pps jitter (usec) (read-only) */
> +    int shift;           /* interval duration (sec) (read-only) */
> +    long stabil;         /* pps stability (scaled ppm) (read-only) */
> +    long jitcnt;         /* jitter limit exceeded (read-only) */
> +    long calcnt;         /* calibration intervals (read-only) */
> +    long errcnt;         /* calibration errors (read-only) */
> +    long stbcnt;         /* stability limit exceeded (read-only) */
> +
> +    int tai;             /* TAI offset (s) (read-only) */
>  };

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action

[Richard Cochran]

On Sat, Nov 29, 2014 at 12:02:33AM +0100, Laurent Georget wrote:
> 
> Thank you for your comments. Below is a new version of the patch. Less
> unrelevant chit-chat, more useful information (hopefully).

Looks better to me.

Thanks,
Richard

Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action

[Laurent Georget]

Hello,

Le 29/11/2014 10:27, Michael Kerrisk (man-pages) a écrit :
> Hello Laurent,
> 
> Thanks for working on this. I have one question; see below.
> 
>>
>> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
>> index 20a2f0b..871e607 100644
>> --- a/man2/adjtimex.2
>> +++ b/man2/adjtimex.2
>> @@ -26,9 +26,6 @@
>>  .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
>>  .\" Modified 2014-11-28 by Laurent Georget <laurent.georget@supelec.fr>
>>  .\"
>> -.\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
>> -.\"		commit 153b5d054ac2d98ea0d86504884326b6777f683d
>> -.\"
>>  .\" FIXME Document ADJ_MICRO and ADJ_NANO (added in Linux 2.6.26)
>>  .\"		commit eea83d896e318bda54be2d2770d2c5d6668d11db
>>  .\"		Author: Roman Zippel <zippel@linux-m68k.org>
>> @@ -74,6 +71,17 @@ struct timex {
>>                              (read-only) */
>>      struct timeval time; /* current time (read-only) */
>>      long tick;           /* usecs between clock ticks */
> 
> What is the following piece about? Did you mean to include it in this patch?

Those are new fields added in struct timex since the last edition of the
man page. Maybe I should split the commit in two subcommits: the first
one to add the new fields, and the second one to specifically add the
ADJ_TAI flag?

> 
>> +
>> +    long ppsfreq;        /* pps frequency (scaled ppm) (read-only) */
>> +    long jitter;         /* pps jitter (usec) (read-only) */
>> +    int shift;           /* interval duration (sec) (read-only) */
>> +    long stabil;         /* pps stability (scaled ppm) (read-only) */
>> +    long jitcnt;         /* jitter limit exceeded (read-only) */
>> +    long calcnt;         /* calibration intervals (read-only) */
>> +    long errcnt;         /* calibration errors (read-only) */
>> +    long stbcnt;         /* stability limit exceeded (read-only) */
>> +
>> +    int tai;             /* TAI offset (s) (read-only) */
>>  };
> 
> Thanks,
> 
> Michael
> 

Thanks,

Laurent