adjtimex.2: add explanation about ADJ_TAI action

PATCH In review Laurent Georget 3 participants 6 messages Nov 28, 2014 – Nov 29, 2014 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Laurent Georget

author

2014-11-28 13:40 UTC #0 lore raw

PATCH 1/1 adjtimex.2: add explanation about ADJ_TAI action

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

man2/adjtimex.2 +3 -3

index 20a2f0b..8418b4f 100644
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
 .\" Modified 2014-11-28 by Laurent Georget <[email protected]>
 .\"
-.\" 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 <[email protected]>

@@ -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,
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Richard Cochran

2014-11-28 21:00 UTC #1 lore raw

Review

Quoted 12 lines · Laurent Georget

man2/adjtimex.2 +2 -0

@@ -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

(quoted diff) +5 -0

+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.

Quoted 8 lines

(quoted diff) +3 -0
+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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Laurent Georget

author

2014-11-28 23:02 UTC #2 lore raw

Quoted 15 lines · Richard Cochran

Review

Quoted 12 lines · Laurent Georget

(quoted diff) +2 -0

@@ -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

(quoted diff) +5 -0

+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.

Quoted 12 lines

Quoted 9 lines
(quoted diff) +3 -0
+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).

man2/adjtimex.2 +20 -3

index 20a2f0b..871e607 100644
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
 .\" Modified 2014-11-28 by Laurent Georget <[email protected]>
 .\"
-.\" 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 <[email protected]>

@@ -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,
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2014-11-29 09:27 UTC #3 lore raw

Hello Laurent,

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

Quoted 59 lines · Laurent Georget

Quoted 15 lines · Richard Cochran
Review
Quoted 12 lines · Laurent Georget
man2/adjtimex.2 +2 -0
@@ -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
(quoted diff) +5 -0
+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.
Quoted 12 lines
Quoted 9 lines
(quoted diff) +3 -0
+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).
man2/adjtimex.2 +0 -3
index 20a2f0b..871e607 100644
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
 .\" Modified 2014-11-28 by Laurent Georget <[email protected]>
 .\"
-.\" 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 <[email protected]>

man2/adjtimex.2 struct timex { · line 73

Quoted 3 lines

man2/adjtimex.2 +0 -0

@@ -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?

man2/adjtimex.2 struct timex { · line 85

Quoted 12 lines

man2/adjtimex.2 +11 -0

+
+    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

Signature · 3 lines

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

Laurent Georget

author

2014-11-29 09:46 UTC #4 lore raw

Hello,

Quoted 17 lines · Michael Kerrisk (man-pages)

Hello Laurent,

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

Quoted 13 lines

man2/adjtimex.2 +0 -3

index 20a2f0b..871e607 100644
@@ -26,9 +26,6 @@
 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
 .\" Modified 2014-11-28 by Laurent Georget <[email protected]>
 .\"
-.\" 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)

Quoted 8 lines

man2/adjtimex.2 struct timex { · line 73

Quoted 6 lines

man2/adjtimex.2 +0 -0

 .\"		commit eea83d896e318bda54be2d2770d2c5d6668d11db
 .\"		Author: Roman Zippel <[email protected]>

@@ -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?

Quoted 16 lines

man2/adjtimex.2 struct timex { · line 85

Quoted 13 lines

man2/adjtimex.2 +11 -0

+
+    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,

Quoted 2 lines

Michael

Thanks,

Laurent

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Richard Cochran

2014-11-29 09:32 UTC #5 lore raw

In reply to Laurent Georget

Quoted 3 lines · Laurent Georget

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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html