* [patch] adjtimex.2: add explanation about ADJ_TAI action @ 2014-11-28 13:40 Laurent Georget 2014-11-28 21:00 ` Richard Cochran 0 siblings, 1 reply; 6+ messages in thread From: Laurent Georget @ 2014-11-28 13:40 UTC (permalink / raw) To: mtk.manpages; +Cc: linux-man, linux-kernel 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, ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [patch] adjtimex.2: add explanation about ADJ_TAI action 2014-11-28 13:40 [patch] adjtimex.2: add explanation about ADJ_TAI action Laurent Georget @ 2014-11-28 21:00 ` Richard Cochran 2014-11-28 23:02 ` [patch v2] " Laurent Georget 0 siblings, 1 reply; 6+ messages in thread From: Richard Cochran @ 2014-11-28 21:00 UTC (permalink / raw) To: Laurent Georget; +Cc: mtk.manpages, linux-man, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action 2014-11-28 21:00 ` Richard Cochran @ 2014-11-28 23:02 ` Laurent Georget 2014-11-29 9:27 ` Michael Kerrisk (man-pages) 2014-11-29 9:32 ` Richard Cochran 0 siblings, 2 replies; 6+ messages in thread From: Laurent Georget @ 2014-11-28 23:02 UTC (permalink / raw) To: Richard Cochran; +Cc: mtk.manpages, linux-man, linux-kernel 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, ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action 2014-11-28 23:02 ` [patch v2] " Laurent Georget @ 2014-11-29 9:27 ` Michael Kerrisk (man-pages) 2014-11-29 9:46 ` Laurent Georget 2014-11-29 9:32 ` Richard Cochran 1 sibling, 1 reply; 6+ messages in thread From: Michael Kerrisk (man-pages) @ 2014-11-29 9:27 UTC (permalink / raw) To: Laurent Georget, Richard Cochran; +Cc: mtk.manpages, linux-man, linux-kernel 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/ ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action 2014-11-29 9:27 ` Michael Kerrisk (man-pages) @ 2014-11-29 9:46 ` Laurent Georget 0 siblings, 0 replies; 6+ messages in thread From: Laurent Georget @ 2014-11-29 9:46 UTC (permalink / raw) To: Michael Kerrisk (man-pages), Richard Cochran; +Cc: linux-man, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [patch v2] adjtimex.2: add explanation about ADJ_TAI action 2014-11-28 23:02 ` [patch v2] " Laurent Georget 2014-11-29 9:27 ` Michael Kerrisk (man-pages) @ 2014-11-29 9:32 ` Richard Cochran 1 sibling, 0 replies; 6+ messages in thread From: Richard Cochran @ 2014-11-29 9:32 UTC (permalink / raw) To: Laurent Georget; +Cc: mtk.manpages, linux-man, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-11-29 9:56 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-11-28 13:40 [patch] adjtimex.2: add explanation about ADJ_TAI action Laurent Georget 2014-11-28 21:00 ` Richard Cochran 2014-11-28 23:02 ` [patch v2] " Laurent Georget 2014-11-29 9:27 ` Michael Kerrisk (man-pages) 2014-11-29 9:46 ` Laurent Georget 2014-11-29 9:32 ` Richard Cochran
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).