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

		      Installation Instructions
			    for PPSkit-0.8
		    Copyright (c) 1997, 1998, 1999
			   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).

   If you intend to use ntpd with PPS support, you'll have to make a
   symbolic link (``ln -s ../linux/ppsclock.h /usr/include/sys/ppsclock.h''),
   because I did not want to patch `/usr/include/sys'.  A correspondig link
   is required for <sys/timepps.h>.

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) There are some discussions about include files, and some people
    think that only ``/usr/include/asm'' and ``/usr/include/linux''
    should be symbolic links to the current kernel include files
    (``/usr/src/linux/include'').  Especially these people think the
    glibc-2.1 should have its own copies of ``/usr/include/scsi'' and
    ``/usr/include/sys''.

    In case where new functionality is introduced, this is bad:
    Sources use ``<sys/timex.h>'' to find the proper definitions.
    Therefore you need to make sure that ``/usr/include/sys/timex.h''
    is a symbolic link to ``/usr/src/linux/include/linux/timex.h''.
    In addition apply the same pattern for ``<sys/ppsclock.h>'' and
    ``<sys/timepps>''.

5) Do whatever you like ;-) If you use ntpd, be sure to get a recent
   version like ntp-4.0.98a (ntp-4.0.98a still supports the obsolete
   draft "03" of the PPS API; you'll have to wait for a newer version
   for automatic activation.

   I managed to use hardpps() via manual activation with enable_pps
   however).  The patch won't automatically create a symbolic link
   from <sys/ppsclock.h> to <linux/ppsclock.h> (similar for
   <sys/timepps.h>); do that manually (cd /usr/include && ln -s
   linux/ppsclock.h sys/ppsclock.h).  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.

   It seems you must recompile ntpd 4.0 to make it use ``STA_NANO''.
   In any case it's highly recommended, as some bit definitions for
   ``adjtimex()'' had to be changed for nanokernel support.

   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:
51309 77437.519 0.000000203 16.824265 0.000008846 0.019343 6
51309 77561.521 0.000000001 16.824265 0.000007661 0.016752 6
51309 77686.523 0.000000013 16.838150 0.000006635 0.016083 6
51309 77811.525 0.000000010 16.838150 0.000005746 0.013928 6
51309 77935.527 0.000000131 16.827240 0.000004977 0.013238 6
51309 78057.529 0.000000005 16.827240 0.000004311 0.011465 6
51309 78179.531 0.000000043 16.803436 0.000003735 0.015500 6
51309 78301.534 0.000000168 16.803436 0.000003235 0.013423 6
