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

[Richard Cochran <richardcochran@gmail.com>]

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