ADJTIMEX 

I will assume you have already read the man page for adjtimex :-)


BACKGROUND

You probably already know that your computer has two clocks - the "real
time clock" (RTC) that runs all the time, and the system clock that runs
only while the computer is on.  The system clock has much better
precision (approximately 1 usec), but the RTC probably has better
long-term stability.  adjtimex can be used to approximately correct the
system clock for drift.

The handiest reference clock is the RTC.  
  adjtimex --compare
shows the time, the difference between the two clocks, the first
difference (how much the system clock has gained or lost relative to
the RTC since the last check), and two kernel time parameters: tick
and frequency offset.  After the first two comparisons, it also prints
suggested values of tick and frequency offset that will adjust the
system clock to approximately agree with the RTC.  Of course, the RTC
may have a systematic error of its own.  clock(8) uses the file
/etc/adjtime to record the drift rate and the time since the RTC was
last set.  adjtimex also consults this file and applies the correction
to the times from the RTC.


INSTALLATION

Type "make" to compile, then copy the binary to /sbin, and the man page
to /usr/man/man8 or wherever.


ASIDES

You will have to log in as root for most of the following.

The standard kernel will leave the RTC alone only until one of the
time parameters is set (using adjtimex, for example).  Then it thinks
xntpd is regulating the system time, and it starts "correcting" the
RTC approximately every eleven minutes.  adjtimex prevents this by
setting the time after setting any parameter.  It does not actually
change the time.


USAGE

Create /etc/adjtime, which is used by clock(8) to correct for
systematic error in the RTC.  Set it up as explained in the man page
for clock(8).  clock is included (along with a lot of other useful
utilities) in Rik Faith's collection:
sunsite.unc.edu:pub/Linux/system/Misc/util-linux-1.10.tar.gz If your
RTC is already accurate enough to suit you, just create a file
/etc/adjtime containing as the first and only line: '0.0 0 0.0'.

I'll explain the manual procedure first.

Compile and run adjtimex with the --compare switch.
Suppose the result is:

# adjtimex --compare
794625929   -0.597638 -0.597638  ...
794625939   -0.602050 -0.004412  ...
                      ^^^^^^^^^
This number says the system clock lost over 4 msec in just 10 sec with
respect to the RTC, or 4 parts in 10000.  Therefore, we increase the
tick parameter to 10004, and repeat the comparison:

# adjtimex  --tick 10004
# adjtimex --compare
794626037   -0.644860 -0.644860  ...
794626047   -0.645259 -0.000399  ...

Now the system clock is slow by about 39.9 parts per million.  We can
change the frequency offset to fix this.  Recall that the frequency
offset is in parts per million, with the fraction point in the center
(16 bits on either side).  Therefore, we set the offset to 39.9*65536 =
2614886:

# adjtimex  --frequency 2614886
# adjtimex --compare
794626313   -0.652147 -0.652147  ...
794626323   -0.652247 -0.000100  ...

It still seems to be off by about 10 ppm, so we increase the offset
by 10*65536, to 3270246:

# adjtimex  --frequency 3270246
# adjtimex --compare
794627233   -0.795221 -0.795221  ...
794627243   -0.795231 -0.000009  ...

The entries in the "suggested" columns are calculated in this way.
Using the --adjust switch automates the entire process.

By the way, using the --offset or --singleshot options seems to have a
long-term effect on the clock.  I suggest you determine the tick and
frequency settings before trying the other options.

You may already have an entry like this in rc.S or one of the
other startup files:

	# Adjust CMOS clock based on /etc/adjtime, then set system clock.
	# Add -u switch if your system keeps GMT.
	if [ -x /sbin/clock ]; then
	  /sbin/clock -a
	fi


Just add an entry like this:

	# Regulate the sytem clock
	if [ -x /sbin/adjtimex ]; then
	  /sbin/adjtimex  --tick 10004  --frequency 3270246 
	fi


FURTHER READING

For authoritative documentation on the kernel time software, see
the following, all by David L. Mills <mills@udel.edu>:

[MIL92a] Mills, D.L. Network Time Protocol (Version 3) specification,
implementation and analysis, RFC 1305, University of Delaware, March
1992, 113 pp.

[MIL92c] Mills, D.L. Simple Network Time Protocol (SNTP), RFC 1361,
University of Delaware, August 1992, 10 pp.

[MIL94a] Mills, D.L. A kernel model for precision timekeeping. ARPA
Network Working Group Report RFC-1589, University of Delaware, March
1994. 31 pp.

README.kern, which can be found in louie.udel.edu:/pub/ntp/kernel.tar.Z.


THANKS

to David Mills for the kernel timekeeping code, and Steven Dick for
writing adjtimex.  (I've changed the code a lot.  Any problems are my
responsibility.)


Enjoy!
                - Jim Van Zandt <jrv@vanzandt.mv.com>

