Re: [PATCH V8 02/13] ntp: add ADJ_SETOFFSET mode bit

Richard Cochran
2011-01-08T17:50:28Z

On Sun, Jan 02, 2011 at 05:38:19AM +0900, Kuwahara,T. wrote:
> As you know, it conflicts with MOD_PPSMAX. And also, it is logically
> the same as ADJ_OFFSET, unless the kernel PLL is enabled explicitly.

I choose another bit, for the next version of the patch series.

>
> So here's my simple solution:
>

I have read the API documentation in the nanokernel source archive. It
explains the (very complex looking) timex structure quite clearly and
nicely. Now I am more convinced than ever that adding a new mode bit
is the best way to go, as opposed to ADJ_OFFSET/!STA_PLL, because:

1. The mode bits update kernel variables. That is what we want.
2. Clearing STA_PLL means disable adjustments.
3. The range of the timex.offset is way too small.

I expand on each point, below. BTW, the API document is also available
for online reading here:

http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/ntpNanoclock/api.htm

1. Looking at the API, the documentation for the bits of the 'modes'
field states:

These bits control which field of the timex structure are used
to update the corresponding kernel variable. The bits may be
set in any combination. See the description below for which
bits control which variable.

With the ADJ_SETOFFSET mode, we are telling the kernel to update
the instantaneous value of the 'current time' variable. That usage
agrees with the sematics of the other mode bits.

2. The documentation for STA_PLL states:

Master enable switch for the PLL/FLL loop. The algorithm is
responsive to time and/or frequency updates if set; otherwise,
no change in the current time or frequency will be made other
than to complete a pending phase adjustment. This bit does not
affect the PPS loop.

So when we clear this bit, the kernel promises that it will make
"no change in the current time." The proposed ADJ_OFFSET/!STA_PLL
solution would break this pattern.

3. The timex.offset field is of type "long" and represents either
nanoseconds or microseconds. On 32 bit architectures, the maximum
possible adjustment would be

2^31 * 10^-6 = 2147.5 seconds

which is less than one hour. For the first adjustment of a clock,
we want to be able to jump the clock arbitrarily. Not every
computer has an RTC, and so some boot up believing that it is still
the year 1970.

Richard