(Emacs: -*- indented-text -*-)

		      Installation Instructions
			    for PPSkit-1.0
		      Copyright (c) 1997 - 2000
			   by Ulrich Windl

0) Unpack a compatible version of the Linux kernel sources (if not
   already done).  The kernel version should match the version of the
   patch (e.g. `patch-2.0.31pre9' matches `linux-2.0.31pre9').  Make
   sure that you have the tools and resources needed for a kernel
   compilation (see /usr/src/linux/Documentation/Changes)

1) The patches against the kernel follow the usual convention, that is
   you need `-p1' if your are standing in your kernel directory.
   Apply the patch as usual (e.g. cd /usr/src/linux; patch -p1 <the_patch).

2a) `make config' and enable `experimental drivers'.

2b) Select `NTP kernel support', `NTP PPS support', and `NTP PPS
    support on serial port' after selecting the serial driver.  The
    driver can be inserted as a module at runtime if you like.

3a) `make dep' and then make the kernel as usual (e.g. `make bzImage')

3b) OPTIONAL: Have a small break with coffee, tee, cookies, or whatever...

4a) Activate the new kernel (copy the files and modules into place,
    maybe edit /etc/lilo.conf, and re-run LILO) and reboot (as
    usual)...

4b) If you have built the serial driver as a module, load that module
    (`insmod serial.o' if it isn't done automatically) and be sure
    that the `PPSAPI' option is displayed (or logged).  The string
    should read similar to ``Serial driver version 4.27+ with
    PPSAPI_1999-08-17 enabled''.

4c) Make sure the right include files are found and used: The patch
    creates new files "ppsclock.h", "timepps.h", and "timex.h".
    Despite of discussions whether files in /usr/include/sys should be
    the current kernel's versions I simply state:

    If you intend to use ntpd with PPS support, you'll have to make a
    symbolic link
    (e.g. ``ln -s ../linux/ppsclock.h /usr/include/sys/ppsclock.h'')
    for the files mentioned above.

    Remember to repeat this step whenever you upgrade your C library
    or include files.

5) Do whatever you like ;-) If you use ntpd, be sure to get a recent
   version like ntp-4.0.99f (ntp-4.0.98b is the first release to
   support the draft "05" of the PPS API, hacked rather quickly using
   the FreeBSD implementation.  So be prepared for surprises and
   incompatibilities.)  You can set up the PPS API using
   ``enable_pps'' if the daemon fails to do so. However make sure you
   specify options ``-k'' and ``-j'' to preserve the state of the
   status word. Just make sure the port remains opened).

   For ntpd-4.0.98a the ATOM driver worked out-of-the-box.  But you'll
   have to remove config.cache, do re-configure, and recompile ntpd to
   get PPS support into the daemon.  You should configure the ATOM
   reference clock in addition to your usual clocks.

   You must recompile ntpd 4.0 to work correctly with the new kernel.

   When everything is working, the `ATOM' clock will become ``PPS
   peer'' (`o') after some time if the preferred peer has been chosen
   as primary synchronization source, and the PPS signal has been
   monitored to be good enough.  You can force the PPS signal to be
   valid by using ``enable pps'' either in your configuration file, or
   at runtime using ntpdc (not recommended however).  I only
   tested it with PARSE drivers though.

   With ntpd-4.0 the flag ``STA_TIMEFREQ'' should go on once the
   preferred time source is reachable and seems valid.  If the jitter
   is low enough, or if the offset is small enough, ``STA_PPSTIME''
   will also go on.

   Maybe after a while your loopstats file will look like this:
51791 75053.799 0.000000609 16.613007 0.000013035 0.009817 6
51791 75119.800 -0.000000286 16.614990 0.000011292 0.008559 6
51791 75185.801 0.000000192 16.614990 0.000009781 0.007413 6
51791 75249.802 -0.000000460 16.613998 0.000008473 0.006439 6
51791 75313.804 0.000000138 16.613998 0.000007342 0.005576 6
51791 75379.805 0.000000020 16.608047 0.000006371 0.005672 6
51791 75443.806 -0.000000158 16.608047 0.000005532 0.004912 6
