path: root/usr.sbin/xntpd/doc/README.refclock

                 Information on Reference Clock Drivers

                         Revised 5 August 1994

Support for most of the commonly available radio clocks is included in
the default configuration of xntpd. Individual clocks can be activated
by configuration file commands, specifically the server and fudge
commands described in the xntpd.8 man page. This file contains
information useful in configuring and operating these clocks. Note that
the man pages and documentation files mentioned in this note can be
found in the ./doc directory of the xntp3 distribution.

Radio clocks by convention have addresses in the form 127.127.t.u, where
"t" is the clock type and "u" is a unit number in the range 0-3 used to
distinguish multiple instances of clocks of the same type. Most of these
clocks require support in the form of a serial port or special bus
peripheral. The particular device is normally specified by adding a soft
link /dev/device%d to the particular hardware device involved. The name
"device" is compiled in the driver according to the table below. The
table shows the type number, device name, short description used in some
displays, and long description used in other displays.

Type Device    Name           Description
-------------------------------------------------------
1    (none)    LOCAL          Undisciplined Local Clock
2    trak      GPS_TRAK       TRAK 8820 GPS Receiver
3    pst       WWV_PST        PSTI/Traconex WWV/WWVH Receiver
4    wwvb      WWVB_SPEC      Spectracom WWVB Receiver
5    goes      GPS_GOES_TRUE  TrueTime GPS/GOES Receivers
6    irig      IRIG_AUDIO     IRIG Audio Decoder
7    chu       CHU            Scratchbuilt CHU Receiver
8    refclock- GENERIC        Generic Reference Clock Driver
9    gps       GPS_MX4200     Magnavox MX4200 GPS Receiver
10   gps       GPS_AS2201     Austron 2201A GPS Receiver
11   omega     OMEGA_TRUE     TrueTime OM-DC OMEGA Receiver
12   tpro      IRIG_TPRO      KSI/Odetics TPRO/S IRIG Interface
13   leitch    ATOM_LEITCH    Leitch CSD 5300 Master Clock Controller
14   ees       MSF_EES        EES M201 MSF Receiver
15   gpstm     GPS_TRUE       TrueTime GPS/TM-TMD Receiver
16   *         GPS_BANC       Bancomm GPS/IRIG Receiver
17   datum     GPS_DATUM      Datum Precision Time System
18   acts      NIST_ACTS      NIST Automated Computer Time Service
19   heath     WWV_HEATH      Heath WWV/WWVH Receiver
20   nmea      GPS_NMEA       Generic NMEA GPS Receiver
21   *         GPS_MOTO       Motorola Six Gun GPS Receiver
22   pps       ATOM_PPS       PPS Clock Discipline

* Not yet available.

A radio clock is specified in the configuration using the server command

     server 127.127.t.u [ prefer ] [ mode m ]

where t is the type number above and u can be in the range 0-3,
conventionally 1. Ordinarily, this is the only command necessary to
configure a radio clock. The optional prefer keyword can be used to
modify the clock selection algorithm as described in Appendix B. For
those clock drivers that support multiple modes of operation, the
optional mode parameter selects which one. This parameter affects the
operation of each driver as described in Appendix A.

In rare cases a fudge command is necessary to specify additional
details. This command has the following syntax

fudge 127.127.t.u [stratum s] [refid r] [time1 t1] [time2 t2] [flags]
and must follow the corresponding server command in the configuration
file. The optional fields following the clock address are interpreted as
follows:

stratum s The s, a decimal number in the range 0-15, overrides the
          default stratum assigned by the driver.

refid r   The r, a 4-character, null-terminated ASCII string, overrides
          the reference identifier assigned by the driver.

time1 t1  The t1, a fixed-point decimal number in seconds, specifies a
          constant to be added to the time offset produced by the
          driver. This provides a way to correct a systematic error or
          bias on the part of the particular clock.

time2 t2  The t2, a fixed-point decimal number, is interpreted in a
          driver-dependent way. See the descriptions of specific clock
          drivers in Appendix A.

There are four optional flags named flag1, flag2, flag3 and flag4. A
flag is specified in the form <keyword> <value>, where <keyword> is one
of the flag names and <value> is either 0 or 1, as appropriate. Two of
the flags are generic and are interpreted by all applicable drivers, and
two are driver dependent. The generic ones are as follows:

flag4     This flag is used to enable detailed status monitoring and
          event recording. The data collected are written to the
          clockstats file maintained by the filegen utility (See the
          xntpd.8 man page). This file is normally processed by a cron
          job run once per day to produce summary statistics and
          performance data. The ./scripts/stats directory contains a
          number of shell and awk scripts for this, as well as S-
          language programs that produce PostScript plots of performance
          data.

flag3     This flag is used with Sun SPARCstation baseboard serial ports
          to assign the ppsclock streams driver for a 1-pps signal
          produced by some radio clocks and timekeeping devices. See the
          dscription of the PPS Clock Discipline Driver (type 22) in
          Appendix A for further information.

Note that the fudge factors above can be changed at run time using the
xntpdc program (see the xntpdc.8 man page). This program does not have
to be run on the server machine itself, since it communicates with the
xntpd daemon using cryptographically authenticated messages.

The PPS Signal

Some radio clocks and related timekeeping gear have a pulse-per-second
(PPS) signal that can be used to discipline the local clock oscillator
to a high degree of precision, typically to the order less than 50 us in
time and 0.1 ppm in frequency. The PPS signal can be connected in either
of two ways, either via the data leads of a serial port or via the modem
control leads. Either way requires conversion of the PPS signal, usually
at TTL levels, to RS232 levels, which can be done using a circuit such
as described in the ./gadget directory of the xntp3 distribution.

The data leads interface requires regenerating the PPS pulse and
converting to RS232 signal levels, so that the pulse looks like a
legitimate ASCII character. The tty_clk module in the ./kernel directory
inserts a timestamp following this character in the input data stream.
The driver uses this timestamp to determine the time of arrival of the
PPS pulse to within 26 us at 38.4 kbps while eliminating error due to
operating system queues and service times. In order to use the tty_clk
module, the xntp3 distribution must be compiled with CLK defined.
The modem control leads interface requires converting to RS232 levels
and connecting to the carrier detect (CD) lead of a serial port. The
ppsclock streams module in the ./ppsclock directory is used to capture a
timestamp upon transition of the PPS signal. The driver reads the latest
timestamp with a designated ioctl() system call to determine the time of
arrival of the PPS pulse to within a few tens of microseconds. In order
to use the ppsclock module, the xntp3 distribution must be compiled with
PPS defined.

Both of these mechanisms are supported by the ATOM_PPS reference clock
driver described in Appendix A. This driver is ordinarily used in
conjunction with another clock driver that supports the radio clock that
produces the PPS pulse. This driver furnishes the coarse timecode used
to disambiguate the seconds numbering of the PPS pulse itself. The NTP
daemon mitigates between the radio clock driver and ATOM_PPS driver as
described in Appendix B in order to provide the most accurate time,
while respecting the various types of equipment failures that could
happen.

For the utmost time quality, a number of Unix system kernel
modifications can be made as described in the README.magic and
README.kernel files. Specifically, the ppsclock module can be used to
interface the PPS signal directly to the kernel for use as discipline
sources for both time and frequency. These sources can be separately
enabled and monitored using the ntp_adjtime() system call described in
README.kernel and the ./include/sys/timex.h header file in the xntp3
distribution. In order to use the kernel PPS signal, the xntp3
distribution must be compiled with KERNEL_PLL defined.

In some configurations may have multiple radio clocks, each with PPS
outputs, as well as a kernel modified to use the PPS signal. In order to
provide the highest degree of redundancy and survivability, the kernel
PPS discipline, tty_clk module and ppsclock module may all be in use at
the same time, each backing up the other. The sometimes complicated
mitigation rules are described in Appendix B.

Debugging Hints

The ntpq and xntpdc utility programs can be used to debug reference
clocks, either on the server itself or from another machine elsewhere in
the network. The server is compiled, installed and started using the
command-line switches described in the xntpd.8 man page. The first thing
to look for are error messages on the system log. If none occur, the
daemon has started, opened the devices specified and waiting for peers
and radios to come up.

The next step is to be sure the RS232 messages, if used, are getting to
and from the clock. The most reliable way to do this is with an RS232
tester and to look for data flashes as the driver polls the clock and/or
as data arrive from the clock. Our experience is that the overwhelming
fraction of problems occurring during installation are due to problems
such as miswired connectors or improperly configured radio clocks at
this stage.

If RS232 messages are getting to and from the clock, the variables of
interest can be inspected using the ntpq program and various commands
described in the ntpq.8 man page. First, use the pe and as commands to
display a pair of billboards showing the peer configuration and
association IDs for all peers, including the radio clock peers. The
assigned clock address should appear in the pe billboard and the
association ID for it at the same relative line position in the as
billboard. If things are operating correctly, after a minute or two
samples should show up in the pe display line for the clock.

Additional information is available with the rv and clockvar commands,
which take as argument the association ID shown in the as billboard. The
rv command with no argument shows the system variables, while the rv
command with argument shows the peer variables for the clock, as well as
any other peers of interest. The clockvar command with argument shows
the peer variables specific to reference clock peers, including the
clock status, device name, last received timecode (if relevant), and
various event counters. In addition, a subset of the fudge parameters is
included.

The xntpdc utility program can be used for detailed inspection of the
clock driver status. The most useful are the clockstat and clkbug
commands described in the xntpdc.8 man page. While these commands permit
getting quite personal with the particular driver involved, their use is
seldom necessary, unless an implementation bug shows up.

Most drivers write a message to the clockstats file as each timecode or
surrogate is received from the radio clock. By convention, this is the
last ASCII timecode (or ASCII gloss of a binary-coded one) received from
the radio. This file is managed by the filegen facility described in the
xntpd.8 man page and requires specific commands in the configuration
file. This forms a highly useful record to discover anomalies during
regular operation of the clock. The scripts included in the
./scripts/stats directory can be run from a cron job to collect and
summarize these data on a daily or weekly basis. The summary files have
proven invaluable to detect infrequent misbehavior due to clock
implementation bugs in some radios.

Appendix A. Individual Driver Descriptions

Following are detailed descriptions of the clock drivers, together with
configuration data useful for special circumstances.

Type 1: Undisciplined Local Clock

     This is a hack to allow a machine to use its own system clock as a
     reference clock, i.e., to free-run using no outside clock
     discipline source. This is useful if you want to use NTP in an
     isolated environment with no radio clock or NIST modem available.
     Pick a machine that you figure has a good clock oscillator and
     configure it with this driver. Set the clock using the best means
     available, like eyeball-and-wristwatch. Then, point all the other
     machines at this one or use broadcast (not multicast) mode to
     distribute time.

     Another application for this driver is if you want to use a
     particular server's clock as the clock of last resort when all
     other normal synchronization sources have gone away. This is
     especially useful if that server has an ovenized oscillator. For
     this you would configure this driver at a higher stratum (say 3 or
     4) to prevent the server's stratum from falling below that.

     A third application for this driver is when an external discipline
     source is available, such as the NIST "lockclock" program, which
     synchronizes the local clock via a telephone modem and the NIST
     Automated Computer Time Service (ACTS), or the Digital Time
     Synchronization Service (DTSS), which runs on DCE machines. In this
     case the stratum should be set at zero, indicating a bona fide
     stratum-1 source. Exercise some caution with this, since there is
     no easy way to telegraph via NTP that something might be wrong in
     the discipline source itself. In the case of DTSS, the local clock
     can have a rather large jitter, depending on the interval between
     corrections and the intrinsic frequency error of the clock
     oscillator. In extreme cases, this can cause clients to exceed the
     128-ms slew window and drop off the NTP subnet.

     In the default mode the behavior of the clock selection algorithm
     is modified when this driver is in use. The algorithm is designed
     so that this driver will never be selected unless no other
     discipline source is available. This can be overridden with the
     prefer keyword of the server configuration command, in which case
     only this driver will be selected for synchronization and all other
     discipline sources will be ignored. This behavior is intended for
     use when an external discipline source controls the system clock.

     Fudge Factors

     The stratum for this driver LCLSTRATUM is set at 3 by default, but
     can be changed by the fudge command and/or the xntpdc utility. The
     reference ID is "LCL" by default, but can be changed using the same
     mechanisms. *NEVER* configure this driver to operate at a stratum
     which might possibly disrupt a client with access to a bona fide
     primary server, unless the local clock oscillator is reliably
     disciplined by another source. *NEVER NEVER* configure a server
     which might devolve to an undisciplined local clock to use
     multicast mode.

     This driver provides a mechanism to trim the local clock in both
     time and frequency, as well as a way to manipulate the leap bits.
     The fudge time1 parameter adjusts the time, in seconds, and the
     fudge time2 parameter adjusts the frequency, in ppm. Both
     parameters are additive; that is, they add increments in time or
     frequency to the present values. (Note: The frequency cannot be
     changed when the kernel modifications are in use - see the
     README.kern file). The fudge flag1 and fudge flag2 bits set the
     corresponding leap bits; for example, setting flag1 causes a leap
     second to be added at the end of the UTC day. These bits are not
     reset automatically when the leap takes place; they must be turned
     off manually after the leap event.

Type 2: TRAK 8820 GPS Receiver

     This driver supports the TRAK 8820 GPS Station Clock. The claimed
     accuracy at the 1-pps output is 200-300 ns relative to the
     broadcast signal; however, in most cases the actual accuracy is
     limited by the precision of the timecode and the latencies of the
     serial interface and operating system.

     For best accuracy, this radio requires the LDISC_ACTS line
     discipline, which captures a timestamp at the '*' on-time character
     of the timecode. Using this discipline the jitter is in the order
     of 1 ms and systematic error about 0.5 ms. If unavailable, the
     buffer timestamp is used, which is captured at the \r ending the
     timecode message. This introduces a systematic error of 23
     character times, or about 24 ms at 9600 bps, together with a jitter
     well over 8 ms on Sun IPC-class machines.

     Using the menus, the radio should be set for 9600 bps, one stop bit
     and no parity. It should be set to operate in computer (no echo)
     mode. The timecode format includes neither the year nor leap-second
     warning. No provisions are included in this preliminary version of
     the driver to read and record detailed internal radio status.

     In operation, this driver sends a RQTS\r request to the radio at
     initialization in order to put it in continuous time output mode.
     The radio then sends the following message once each second:

     *RQTS U,ddd:hh:mm:ss.0,q<cr><lf>

     on-time = '*'
     ddd = day of year
     hh:mm:ss = hours, minutes, seconds
     q = quality indicator (phase error), 0-6:
          0 > 20 us
          6 > 10 us
          5 > 1 us
          4 > 100 ns
          3 > 10 ns
          2 < 10 ns

     The alarm condition is indicated by '0' at Q, which means the radio
     has a phase error than 20 usec relative to the broadcast time. The
     absence of year, DST and leap-second warning in this format is also
     alarming.

     The continuous time mode is disabled using the RQTX<cr> request,
     following which the radio sends a RQTX DONE<cr><lf> response. In
     the normal mode, other control and status requests are effective,
     including the leap-second status request RQLS<cr>. The radio
     responds with RQLS yy,mm,dd<cr><lf>, where yy,mm,dd are the year,
     month and day. Presumably, this gives the epoch of the next leap
     second, RQLS 00,00,00 if none is specified in the GPS message.
     Specified in this form, the information is generally useless and is
     ignored by the driver.

     Fudge Factors

     There are no special fudge factors other than the generic.

Type 3: PSTI/Traconex WWV/WWVH Receiver

     This driver supports the PSTI 1010 and Traconex 1020 WWV/WWVH
     Receivers. No specific claim of accuracy is made for these
     receiver, but actual experience suggests that 10 ms would be a
     conservative assumption.

     The DIPswitches should be set for 9600 bps line speed, 24-hour day-
     of-year format and UTC time zone. Automatic correction for DST
     should be disabled. It is very important that the year be set
     correctly in the DIPswitches; otherwise, the day of year will be
     incorrect after 28 April of a normal or leap year. The propagation
     delay DIPswitches should be set according to the distance from the
     transmitter for both WWV and WWVH, as described in the
     instructions. While the delay can be set only to within 11 ms, the
     fudge time1 parameter can be used for vernier corrections.

     Using the poll sequence QTQDQM, the response timecode is in three
     sections totalling 50 ASCII printing characters, as concatenated by
     the driver, in the following format:

     ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr> frdzycchhSSFTttttuuxx<cr>

     on-time = first <cr>
     hh:mm:ss.fff = hours, minutes, seconds, milliseconds
     a = AM/PM indicator (' ' for 24-hour mode)
     yy = year (from DIPswitches)
     dd/mm/ddd = day of month, month, day of year
     s = daylight-saving indicator (' ' for 24-hour mode)
     f = frequency enable (O = all frequencies enabled)
     r = baud rate (3 = 1200, 6 = 9600)
     d = features indicator (@ = month/day display enabled)
     z = time zone (0 = UTC)
     y = year (5 = 91)
     cc = WWV propagation delay (52 = 22 ms)
     hh = WWVH propagation delay (81 = 33 ms)
     SS = status (80 or 82 = operating correctly)
     F = current receive frequency (4 = 15 MHz)
     T = transmitter (C = WWV, H = WWVH)
     tttt = time since last update (0000 = minutes)
     uu = flush character (03 = ^c)
     xx = 94 (unknown)

     The alarm condition is indicated by other than '8' at A, which
     occurs during initial synchronization and when received signal is
     lost for an extended period; unlock condition is indicated by other
     than "0000" in the tttt subfield at Q.

     Fudge Factors

     There are no special fudge factors other than the generic.

Type 4: Spectracom WWVB Receiver

     This driver supports the Spectracom Model 8170 and Netclock/2 WWVB
     Synchronized Clock. This clock has proven a reliable source of
     time, except in some cases of high ambient conductive RF
     interference. The claimed accuracy of the clock is 100 usec
     relative to the broadcast signal; however, in most cases the actual
     accuracy is limited by the precision of the timecode and the
     latencies of the serial interface and operating system.

     The DIPswitches on this clock should be set to 24-hour display,
     AUTO DST off, time zone 0 (UTC), data format 0 or 2 (see below) and
     baud rate 9600. If this clock is to used as the source for the IRIG
     Audio Decoder (refclock_irig.c in this distribution), set the
     DIPswitches for AM IRIG output and IRIG format 1 (IRIG B with
     signature control).

     There are two timecode formats used by these clocks. Format 0,
     which is available with both the Netclock/2 and 8170, and format 2,
     which is available only with the Netclock/2 and specially modified
     8170.

     Format 0 (22 ASCII printing characters):

     <cr><lf>i  ddd hh:mm:ss  TZ=zz<cr><lf>

     on-time = first <cr>
     hh:mm:ss = hours, minutes, seconds
     i = synchronization flag (' ' = in synch, '?' = out synch)

     The alarm condition is indicated by other than ' ' at A, which
     occurs during initial synchronization and when received signal is
     lost for about ten hours.

     Format 2 (24 ASCII printing characters):

     <cr><lf>iqyy ddd hh:mm:ss.fff ld

     on-time = <cr>
     i = synchronization flag (' ' = in synch, '?' = out synch)
     q = quality indicator (' ' = locked, 'A'...'D' = unlocked)
     yy = year (as broadcast)
     ddd = day of year
     hh:mm:ss.fff = hours, minutes, seconds, milliseconds

     The alarm condition is indicated by other than ' ' at A, which
     occurs during initial synchronization and when received signal is
     lost for about ten hours. The unlock condition is indicated by
     other than ' ' at Q.

     The Q is normally ' ' when the time error is less than 1 ms and a
     character in the set 'A'...'D' when the time error is less than 10,
     100, 500 and greater than 500 ms respectively. The L is normally '
     ', but is set to 'L' early in the month of an upcoming UTC leap
     second and reset to ' ' on the first day of the following month.
     The D is set to 'S' for standard time 'I' on the day preceding a
     switch to daylight time, 'D' for daylight time and 'O' on the day
     preceding a switch to standard time. The start bit of the first
     <cr> is synchronized to the indicated time as returned.

     This driver does not need to be told which format is in use - it
     figures out which one from the length of the message. A three-stage
     median filter is used to reduce jitter and provide a dispersion
     measure. The driver makes no attempt to correct for the intrinsic
     jitter of the radio itself, which is a known problem with the older
     radios.

     Fudge Factors

     This driver can retrieve a table of quality data maintained
     internally by the Netclock/2 receiver. If flag4 of the fudge
     configuration command is set to 1, the driver will retrieve this
     table and write it to the clockstats file on when the first
     timecode message of a new day is received.

Type 5: TrueTime GPS/GOES Receivers

     This driver supports at least two models of Kinemetrics/TrueTime
     Timing Receivers, the 468-DC MK III GOES Synchronized Clock and
     GPS-DC MK III GPS Synchronized Clock and very likely others in the
     same model family that use the same timecode formats. The clocks
     are connected via a serial port. Up to four units, with unit
     numbers in the range 0 through 3, can be configured. The driver
     assumes the serial port device name is /dev/goes%d (i.e., unit 1 at
     127.127.5.1 opens the clock at /dev/goes1) and that the clock is
     configured for 9600-baud operation.

Type 6: IRIG Audio Decoder

     This driver supports the Inter-Range Instrumentation Group standard
     time-distribution signal IRIG-B using the audio codec native to the
     Sun SPARCstation. This signal is generated by several radio clocks,
     including those made by Austron, TrueTime, Odetics and Spectracom,
     among others, although it is generally an add-on option. The signal
     is connected via an attenuator box and cable to the audio codec
     input on a Sun SPARCstation and requires a specially modified
     kernel audio driver. Details are in the README.irig file.

     Timing jitter using the decoder and a Sun IPC is in the order of a
     few microseconds, although the overall timing accuracy is limited
     by the wander of the CPU oscillator used for timing purposes to a
     few hundred microseconds. These figures are comparable with what
     can be achieved using the 1-pps discipline as describe elsewhere in
     this note.

     Fudge Factors

     There are no special fudge factors other than the generic. The
     flag3 and flag4 flags are not applicable to this driver.

Type 7: Scratchbuilt CHU Receiver

     This driver supports a shortwave receiver and special modem
     circuitry described in the ./gadget directory of the xntp3
     distribution. It requires the chu-clk line discipline or chu_clk
     STREAMS module described in the ./kernel directory of that
     distribution. It is connected via a serial port operating at 300
     baud.
     Unlike the NIST time services, whose timecode requires quite
     specialized hardware to interpret, the CHU timecode can be received
     directly via a serial port after demodulation. While there are
     currently no known commercial CHU receivers, the hardware required
     to receive the CHU timecode is fairly simple to build. While it is
     possible to configure several CHU units simultaneously, this is in
     general not useful.

     Fudge Factors

     The time1 option can be used to set the CHU propagation delay,
     compensate for inherent latencies in the serial port hardware and
     operating system. The default value is 0.0025 seconds, which is
     about right for Toronto. Values for other locations can be
     calculated using the propdelay program in the util directory of the
     xntp3 distribution or equivalent means.

     The time2 option can be used to compensate for inherent latencies
     in the serial port hardware and operating system. The value, which
     defaults to zero, is in addition to the propagation delay provided
     by the time1 option. The default value is 0.0002 seconds, which is
     about right for typical telephone modem chips.

     The flag1 option can be used to modify the averaging algorithm used
     to smooth the clock indications. Ordinarily, the algorithm picks
     the median of a set of samples, which is appropriate under
     conditions of poor to fair radio propagation conditions. If the
     clock is located relatively close to the WWV or WWVH transmitters,
     setting this flag will cause the algorithm to average the set of
     samples, which can reduce the residual jitter and improve accuracy.

Type 8: Generic Reference Clock Driver

     The timecode of these receivers is sampled via a STREAMS module in
     the kernel (The STREAMS module has been designed for use with SUN
     Systems under SunOS 4.1.x. It can be linked directly into the
     kernel or loaded via the loadable driver mechanism). This STREAMS
     module can be adapted to be able to convert different time code
     formats. If the daemon is

     compiled without the STREAM definition synchronization will work
     without the Sun streams module, though accuracy is significantly
     degraded.

     The actual receiver status is mapped into various synchronization
     states generally used by receivers. The STREAMS module is
     configured to interpret the time codes of DCF U/A 31, PZF535,
     GPS166, Trimble SV6 GPS, ELV DCF7000, Schmid and low cost receivers
     (see list below).

     The reference clock support in xntp contains the necessary
     configuration tables for those receivers. In addition to supporting
     up to 32 different clock types and 4 devices, the generation a a
     PPS signal is also provided as an configuration option. The PPS
     configuration option uses the receiver generated time stamps for
     feeding the PPS loopfilter control for much finer clock
     synchronization.

     CAUTION: The PPS configuration option is different from the
     hardware PPS signal, which is also supported (see below), as it
     controls the way xntpd is synchronized to the reference clock,
     while the hardware PPS signal controls the way time offsets are
     determined.

     The use of the PPS option requires receivers with an accuracy of
     better than 1ms.
     Fudge factors

     Only two fudge factors are utilized. The time1 fudge factor defines
     the phase offset of the synchronization character to the actual
     time. On the availability of PPS information the time2 fudge factor
     defines the skew between the PPS time stamp and the receiver
     timestamp of the PPS signal. This parameter is usually zero, as
     usually the PPS signal is believed in time and OS delays should be
     corrected in the machine specific section of the kernel driver.
     time2 needs only be set when the actual PPS signal is delayed for
     some reason. The flag0 enables input filtering. This a median
     filter with continuous sampling. The flag1 selects averaging of the
     samples remaining after the filtering. Leap secondhandling is
     controlled with the flag2. When set a leap second will be deleted
     on receipt of a leap second indication from the receiver. Otherwise
     the leap second will be added, (which is the default).

     ntpq (8)

     timecode variable

     The ntpq program can read clock variables command list several
     variables. These hold the following information: refclock_time is
     the local time with the offset to UTC (format HHMM). The currently
     active receiver flags are listed in refclock_status. Additional
     feature flags of the receiver are optionally listed in parentheses.
     The actual time code is listed in timecode. A qualification of the
     decoded time code format is following in refclock_format. The last
     piece of information is the overall running time and the
     accumulated times for the clock event states in refclock_states.
     When PPS information is present additional variable are available.
     refclock_ppstime lists then the PPS timestamp and refclock_ppsskew
     lists the difference between RS232 derived timestamp and the PPS
     timestamp.

     Unit encoding

     The unit field <u> encodes the device, clock type and the PPS
     generation option. There are 4 possible units, which are encoded in
     the lower two bits of the <u> field. The devices are named
     /dev/refclock-0 through /dev/refclock-3. Bits 2 thru 6 encode the
     clock type. The fudge factors of the clock type are taken from a
     table clockinfo in refclock_parse.c. The generation of PPS
     information for disciplining the local NTP clock is encoded in bit
     7 of <u>.

     Currently, nine clock types (devices /dev/refclock-0 -
     /dev/refclock-3) are supported.

     127.127.8.0-3 16

     Meinberg PZF535 receiver (FM demodulation/TCXO / 50us)

     127.127.8.4-7 16

     Meinberg PZF535 receiver (FM demodulation/OCXO / 50us)

     127.127.8.8-11 16

     Meinberg DCF U/A 31 receiver (AM demodulation / 4ms)

     127.127.8.12-15 16

     ELV DCF7000 (sloppy AM demodulation / 50ms)

     127.127.8.16-19 16
     Walter Schmid DCF receiver Kit (AM demodulation / 1ms)

     127.127.8.20-23 16

     RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)

     127.127.8.24-27 16

     RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)

     127.127.8.28-31 16

     Meinberg GPS166 receiver (GPS / <<1us)

     127.127.8.32-35 16

     Trimble SV6 GPS receiver (GPS / <<1us)

     The reference clock support carefully monitors the state
     transitions of the receiver. All state changes and exceptional
     events such as loss of time code transmission are logged via the
     syslog facility. Every hour a summary of the accumulated times for
     the clock states is listed via syslog.

     PPS support is only available when the receiver is completely
     synchronized. The receiver is believed to deliver correct time for
     an additional period of time after losing synchronizations, unless
     a disruption in time code transmission is detected (possible power
     loss). The trust period is dependent on the receiver oscillator and
     thus a function of clock type. This is one of the parameters in the
     clockinfo field of the reference clock implementation. This
     parameter cannot be configured by xntpdc.

     In addition to the PPS loopfilter control a true PPS hardware
     signal can be applied on Sun Sparc stations via the CPU serial
     ports on the CD pin. This signal is automatically detected and will
     be used for offset calculation. The input signal must be the time
     mark for the following time code. (The edge sensitivity can be
     selected - look into the appropriate kernel/parsestreams.c for
     details). Meinberg receivers can be connected by feeding the PPS
     pulse of the receiver via a 1488 level converter to Pin 8 (CD) of a
     Sun serial zs\-port.

     There exists a special firmware release for the PZF535 Meinberg
     receivers. This release (PZFUERL 4.6 (or higher - The UERL is
     important)) is absolutely recommended for XNTP use, as it provides
     LEAP warning, time code time zone information and alternate antenna
     indication. Please check with Meinberg for this firmware release.
     For the Meinberg GPS166 receiver is also a special firmware release
     available (Uni-Erlangen). This release must be used for proper
     operation.

     The raw DCF77 pulses can be fed via a level converter directly into
     Pin 3 (Rx) of the Sun. The telegrams will be decoded an used for
     synchronization. AM DCF77 receivers are running as low as $25. The
     accuracy is dependent on the receiver and is somewhere between 2ms
     (expensive) to 10ms (cheap). Upon bad signal reception of DCF77
     synchronizations will cease as no backup oscillator is available as
     usually found in other reference clock receivers. So it is
     important to have a good place for the DCF77 antenna. For
     transmitter shutdowns you are out of luck unless you have other NTP
     servers with alternate time sources available.

Type 9: Magnavox MX4200 GPS Receiver

     This driver supports the Magnavox MX4200 Navigation Receiver
     adapted to precision timing applications. This requires an
     interface box described in the ./ppsclock directory of the xntp3
     distribution. It is connected via a serial port and requires the
     ppsclock STREAMS module described in the same directory.

     Fudge Factors

     There are no special fudge factors other than the generic.

Type 10: Austron 2201A GPS Receiver

     This driver supports the Austron 2200A/2201A GPS/LORAN Synchronized
     Clock and Timing Receiver connected via a serial port. It supports
     several special features of the clock, including the Input Buffer
     Module, Output Buffer Module, IRIG-B Interface Module and LORAN
     Assist Module. It requires the RS232 Serial Interface module for
     communication with the driver.

     This receiver is capable of a comprehensive and large volume of
     statistics and operational data. The specific data collection
     commands and attributes are embedded in the driver source code;
     however, the collection process can be enabled or disabled using
     the flag4 flag. If set, collection is enabled; if not, which is the
     default, it is disabled. A comprehensive suite of data reduction
     and summary scripts is in the ./scripts/stats directory of the
     xntp3 distribution.

     To achieve the high accuracy this device provides, it is necessary
     to use the ppsclock feature of the xntp3 program distribution or,
     alternatively, to install the kernel modifications described in the
     README.kern. The clock can be wired to provide time to a single CPU
     or bussed in parallel to several CPUs, with one CPU controlling the
     receiver and the others just listening. Fair accuracy can be
     achieved in the single-CPU configuration without use of the 1-pps
     signal, but in multiple CPU configurations accuracy is severely
     degraded without it.

     Fudge Factors

     There are no special fudge factors other than the generic.

Type 11: TrueTime OM-DC OMEGA Receiver

     This driver supports the Kinemetrics/TrueTime OMEGA-DC OMEGA
     Synchronized Clock connected via a serial port. This clock is
     sufficiently different from other Kinemetrics/TrueTime models that
     a separate driver is required. Up to four units, with unit numbers
     in the range 0 through 3, can be configured. The driver assumes the
     serial port device name is /dev/omega%d (i.e., unit 1 at
     127.127.11.1 opens the clock at /dev/omega1) and that the clock is
     configured for 9600-baud operation.

     Fudge Factors

     There are no special fudge factors other than the generic.

Type 12: KSI/Odetics TPRO/S IRIG Interface

     This driver supports the KSI/Odetics TPRO and TPRO-SAT IRIG-B
     Decoder, which is a module connected directly to the SBus of a Sun
     workstation. The module works with the IRIG-B signal generated by
     several radio clocks, including those made by Austron, TrueTime,
     Odetics and Spectracom, among others, although it is generally an
     add-on option. In the case of the TPRO-SAT, the module is an
     integral part of a GPS receiver, which serves as the primary timing
     source.

     Using the TPRO interface as a NTP reference clock provides
     precision time only to xntpd and its clients. With suitable kernel
     modifications, it is possible to use the TPRO as the CPU system
     clock, avoiding errors introduced by the CPU clock oscillator
     wander. See the README.kernel and kern.c files for further details.

Type 13: Leitch CSD 5300 Master Clock Controller

     Information not available.

Type 14: EES M201 MSF Receiver

     This driver supports the EES M201 MSF receiver connected to a Sun
     SPARCstation running SunOS 4.x with the "ppsclock" STREAMS module.

     Fudge Factors

     If flag1 is set, then the system clock is assumed to be sloppy
     (e.g. Sun4 with 20ms clock), so samples are averaged. If flag2 is
     set, then leaphold is set. If flag3 is set, then the sample
     information is dumped. If flag4 is set, then the input data is
     smoothed, and all data points are used.

Type 15: TrueTime GPS/TM-TMD Receiver

     Information not available.

Type 16: Bancomm GPS/IRIG Receiver

     Information not available.

Type 17: Datum Precision Time System

     Information not available.

Type 18: NIST Automated Computer Time Service

     This driver supports the NIST Automated Computer Time Service
     (ACTS). It periodically dials a prespecified telephone number,
     receives the NIST timecode data and calculates the local clock
     correction. It designed primarily for use when neither a radio
     clock nor connectivity to Internet time servers is available. For
     the best accuracy, the individual telephone line/modem delay needs
     to be calibrated using outside sources.

     The ACTS is located at NIST Boulder, CO, telephone 303 494 4774. A
     toll call from Newark, DE, costs between three and four cents,
     although it is not clear what carrier and time of day discounts
     apply. The modem dial string will differ depending on local
     telephone configuration, etc., and is specified by the phone
     command in the configuration file. The argument to this command is
     an AT command for a Hayes compatible modem.

     The accuracy produced by this driver should be in the range of a
     millisecond or two, but may need correction due to the delay
     characteristics of the individual modem involved. For undetermined
     reasons, some modems work with the ACTS echo-delay measurement
     scheme and some don't. This driver tries to do the best it can with
     what it gets. Initial experiments with a Practical Peripherals
     9600SA modem here in Delaware suggest an accuracy of a millisecond
     or two can be achieved without the scheme by using a fudge time1
     value of 65.0 ms. In either case, the dispersion for a single call
     involving ten samples is about 1.3 ms.

     The driver can operate in either of three modes, as determined by
     the mode parameter in the server configuration command. In mode 0
     (automatic) the driver operates continuously at intervals depending
     on the prediction error, as measured by the driver, usually in the
     order of several hours. In mode 1 (backup) the driver is enabled in
     automatic mode only when no other source of synchronization is
     available and when more than MAXOUTAGE (3600 s) have elapsed since
     last synchronized by other sources. In mode 2 (manual) the driver
     operates only when enabled using a fudge flags switch, as described
     below.

     For reliable call management, this driver requires a 1200-bps modem
     with a Hayes-compatible command set and control over the modem data
     terminal ready (DTR) control line. Present restrictions require the
     use of a POSIX-compatible programming interface, although other
     interfaces may work as well. The ACTS telephone number and modem
     setup string are hard-coded in the driver and may require changes
     for nonstandard modems or special circumstances.

     Fudge Factors

     Ordinarily, the propagation time correction is computed
     automatically by ACTS and the driver. When this is not possible or
     erratic due to individual modem characteristics, the fudge flag2
     switch should be set to disable the ACTS echo-delay scheme. In any
     case, the fudge time1 parameter can be used to adjust the
     propagation delay as required.

     The ACTS call interval is determined in one of three ways. In
     manual mode a call is initiated by setting fudge flag1 using
     xntpdc, either manually or via a cron job. In automatic mode this
     flag is set by the peer timer, which is controlled by the sys_poll
     variable in response to measured errors. In backup mode the driver
     is ordinarily asleep, but awakes (in automatic mode) if all other
     synchronization sources are lost. In either automatic or backup
     modes, the call interval increases as long as the measured errors
     do not exceed the value of the fudge time2 parameter.

     When the fudge flag1 is set, the ACTS calling program is activated.
     This program dials each number listed in the phones command of the
     configuration file in turn. If a call attempt fails, the next
     number in the list is dialed. The fudge flag1 and counter are reset
     and the calling program terminated if (a) a valid clock update has
     been determined, (b) no more numbers remain in the list, (c) a
     device fault or timeout occurs, or (d) fudge flag1 is reset
     manually using xntpdc.

     The NIST timecode message is transmitted at 1200 bps in the
     following format (see the driver source for more information):

     jjjjj yy-mm-dd hh:mm:ss tt l uuu mmmmm UTC(NIST) *

     jjjjj = modified Julian day
     yy-mm-dd = year, month, day
     hh:mm:ss = hours, minutes, seconds
     tt = DST indicator (see driver listing)
     l = leap-second warning (see driver listing)
     uuu = DUT1 correction (see driver listing)
     mmmmm = modem calibration (see driver listing)
     on-time = '*'

     The timecode message is transmitted continuously after a signon
     banner, which this driver ignores. The driver also ignores all but
     the yy-mm-dd, hh:mm:ss and on-time character '*' fields, although
     it checks the format of all fields of the message. A timestamp is
     captured at the '*' character, as required by the ACTS
     specification, and used as the reference time of the timecode. If a
     message with an on-time character of '#' is received, the driver
     updates the propagation delay. The driver disconnects when (a) ten
     valid messages have been received, (b) no message has been received
     for 15 s, (c) an on-time character of '#' is received. These
     messages are processed by a trimmed-mean filter to reduce timing
     noise and then by the usual NTP algorithms to develop the clock
     correction.

     The behavior of the clock selection algorithm is modified when this
     driver is in use. The algorithm is designed so that this driver
     will never be selected unless no other discipline source is
     available. This can be overridden with the prefer keyword of the
     server configuration command, in which case only this driver will
     be selected for synchronization and all other discipline sources
     will be ignored. Ordinarily, the prefer keyword would be used only
     in automatic mode ehen primary time is to be obtained via ACTS and
     backup NTP peers used only when ACTS fails.

     Call Management

     Since ACTS will be a toll call in most areas of the country, it is
     necessary to carefully manage the calling interval. The ACTS call
     program is initiated by setting fudge flag1. This flag can be set
     manually using xntpdc, by a cron job that calls xntpdc, or
     automatically by the driver itself. The fudge flag1 is reset when
     the program terminates after a time determination is comlete or
     when no more numbers remain in the alternate path list, a device
     fault or timeout has occured, or the fudge flag1 has been reset
     using xntpdc.

     In automatic and backup modes, the driver determines the call
     interval using a procedure depending on the measured prediction
     error and the fudge time2 parameter. If the error exceeds time2 for
     a number of times depending on the current interval, the interval
     is decreased, but not less than about 1000 s. If the error is less
     than time2 for some number of times, the interval is increased, but
     not more than about 18 h. With the default value of zero for fudge
     time2, the interval will increase from 1000 s to the 4000-8000-s
     range, in which the expected accuracy should be in the 1-2-ms
     range. Setting fudge time2 to a large value, like 0.1 s, may result
     in errors of that order, but increase the call interval to the
     maximum. The exact value for each configuration will depend on the
     modem and operating system involved, so some experimentation may be
     necessary.

     Manual call attempts can be made at any time by setting fudge flag1
     using xntpdc. For example, the xntpdc command

     fudge 127.127.18.1 flags 1

     will ask for a key identifier and password and, if authenticated by
     the server, will set flag1. There may be a short delay until the
     expiration of the current poll timeout.

     The flag1 can be set from a cron job in the following way.
     Construct a file with contents

     keyid 11
     passwd dialup
     fudge 127.127.18.1 flags 1
     quit

     Then, run the following program at specified times as required.

     /usr/local/bin/xntpdc <file

Type 19: Heath WWV/WWVH Receiver

     This driver supports the Heath GC-1000 Most Accurate Clock, with
     RS232C Output Accessory. This is a WWV/WWVH receiver somewhat less
     robust than other supported receivers. Its claimed accuracy is 100
     ms when actually synchronized to the broadcast signal, but this
     doesn't happen even most of the time, due to propagation
     conditions, ambient noise sources, etc. When not synchronized, the
     accuracy is at the whim of the internal clock oscillator, which can
     wander into the sunset without warning. Since the indicated
     precision is 100 ms, expect a host synchronized only to this thing
     to wander to and fro, occasionally being rudely stepped when the
     offset exceeds the default CLOCK_MAX of 128 ms.

     The internal DIPswitches should be set to operate at 1200 baud in
     MANUAL mode and the current year. The external DIPswitches should
     be set to GMT and 24-hour format. It is very important that the
     year be set correctly in the DIPswitches. Otherwise, the day of
     year will be incorrect after 28 April of a normal or leap year.

     In MANUAL mode the clock responds to a rising edge of the request
     to send (RTS) modem control line by sending the timecode.
     Therefore, it is necessary that the operating system implement the
     TIOCMBIC and TIOCMBIS ioctl system calls and TIOCM_RTS control bit.
     Present restrictions require the use of a POSIX-compatible
     programming interface, although other interfaces may work as well.

     The clock message consists of 23 ASCII printing characters in the
     following format:

     hh:mm:ss.f     dd/mm/yr<cr>

     hh:mm:ss.f = hours, minutes, seconds
     f = deciseconds ('?' when out of spec)
     dd/mm/yr = day, month, year

     The alarm condition is indicated by '?', rather than a digit, at A.
     Note that 0?:??:??.? is displayed before synchronization is first
     established and hh:mm:ss.? once synchronization is established and
     then lost again for about a day.

     Fudge Factors

     There are no special fudge factors other than the generic. A fudge
     time1 value of .07 s appears to center the clock offset residuals.

Type 20: Generic NMEA GPS Receiver

     Information not available.

Type 21: Motorola Six Gun GPS Receiver

     Information not available.

Type 22: PPS Clock Discipline

     This driver furnishes an interface for pulse-per-second (PPS)
     signals produced by a cesium clock, timing receiver or related
     equipment. It can be used to remove accumulated jitter and retime a
     secondary server when synchronized to a primary server over a
     congested, wide-area network and before redistributing the time to
     local clients. Note that this driver does not control the system
     clock if the kernel modifications described in the README.kernel
     file have been installed, but it can be useful as a monitoring
     tool.

     In order for this driver to work, the local clock must be set to
     within +-500 ms by another means, such as a radio clock or NTP
     itself. The 1-pps signal is connected via a serial port and gadget
     box consisting of a one-shot and RS232 level converter. When
     operated at 38.4 kbps with a SPARCstation IPC, this arrangement has
     a worst-case jitter less than 26 us.

     There are three ways in which this driver can be used. The first
     way uses the LDISC_PPS line discipline and works only for the
     baseboard serial ports of the Sun SPARCstation. The PPS signal is
     connected via a gadget box to the carrier detect (CD) line of a
     serial port and flag3 of the driver configured for that port is
     set. This causes the ppsclock streams module to be configured for
     that port and capture a timestamp at the on-time transition of the
     PPS signal. This driver then reads the timestamp directly by a
     designated ioctl() system call. This provides the most accurate
     time and least jitter of any other scheme. There is no need to
     configure a dedicated device for this purpose, which ordinarily is
     the device used for the associated radio clock.

     The second way uses the LDISC_CLKPPS line discipline and works for
     any architecture supporting a serial port. If after a few seconds
     this driver finds no ppsclock module configured, it attempts to
     open a serial port device /dev/pps%d, where %d is the unit number,
     and assign the LDISC_CLKPPS line discipline to it. If the line
     discipline fails, no harm is done except the accuracy is reduced
     somewhat. The pulse generator in the gadget box is adjusted to
     produce a start bit of length 26 us at 38400 bps (or 104 us at 9600
     bps). Used with the LDISC_CLKPPS line discipline, this produces an
     ASCII DEL character ('\377') followed by a timestamp at each
     seconds epoch.

     The third way involves an auxiliary radio clock driver which calls
     the PPS driver with a timestamp captured by that driver. This use
     is documented in the source code for the driver(s) involved.

     Fudge Factors

     There are no special fudge factors other than the generic and those
     explicitly defined above. The fudge time1 parameter can be used to
     compensate for miscellaneous UART and OS delays. Allow about 247 us
     for uart delays at 38400 bps and about 1 ms for SunOS streams
     nonsense.

Appendix B. Mitigation Rules

In order to provide robust backup sources, stratum-1 peers are usually
operated in a diversity configuration, in which the local server
operates with a number of remote peers in addition with one or more
radio clocks operating also as local peers. In these configurations the
suite of algorithms used in NTP to refine the data from each peer
separately and to select and weight the data from a number of peers can
be used with the entire ensemble of remote peers and local radios.
However, Because of small but significant systematic time offsets
between the peers, it is in general not possible to achieve the lowest
jitter and highest stability in these configurations. In addition, there
are a number of special configurations involving auxiliary radio clock
outputs, telephone backup services and other special cases, so that a
set of mitigation rules becomes necessary.

The mitigation rules are based on a set of special characteristics of
the various reference clock drivers configured on the server. For
instance, it is possible to designate a peer as "preferred," in which
case, all other things being equal, this peer will be selected for
synchronization over all other eligible candidates in the clock
selection procedures. The precise characterization of the prefer peer is
described below. In addition, when a pulse-per-second (PPS) signal is
connected via the PPS Clock Discipline Driver (type 22), the
corresponding peer is called the PPS peer. The manner in which this peer
operates is described below. When the Undisciplined Local Clock Driver
(type 1) is configured in the server, this becomes the local-clock peer.
When the Automated Computer Time Service Driver (type 18) is configured
in the server, this becomes the ACTS peer. Both the local-clock and ACTS
peers operates in the manner described in Appendix A. Finally, where
support is available, the PPS signal may be processed directly by the
kernel. In the following this will be called the kernel discipline.

The mitigation rules apply in the clock selection procedures following
the sanity checks, intersection algorithm and clustering algorithm. The
survivors at this point represent the subset of all peers which can
provide the most accurate, stable time. In the general case, with no
designated prefer peer, PPS peer or local-clock peer, the mitigation
rules require all survivors be averaged according to a weight depending
on the reciprocal of the dispersion, as provided in the NTP
specification.

The mitigation rules establish the choice of system peer, which
determine the stratum, reference identifier and several other system
variables which are visible to clients of the local server. In addition,
they establish which source or combination of sources control the local
clock. In detail, these rules operate as follows:

1.   If there is a prefer peer and it is the local-clock peer or the
     ACTS peer; or, if there is a prefer peer and the kernel discipline
     is active, choose the prefer peer as the system peer.

2.   If the above is not the case and there is a PPS peer, then choose
     it as the system peer and its offset as the system clock offset.

3.   If the above is not the case and there is a prefer peer (not the
     local-clock or ACTS peer in this case), then choose it as the
     system peer and its offset as the system clock offset.

4.   If the above is not the case and the peer previously chosen as the
     system peer is in the surviving population, then choose it as the
     system peer and average its offset along with the other survivors
     to determine the system clock offset. This behavior is designed to
     avoid excess jitter due to "clockhopping," when switching the
     system peer would not materially improve the time accuracy.

5.   If the above is not the case, then choose the first candidate in
     the list of survivors ranked in order of synchronization distance
     and average its offset along with the other survivors to determine
     the system clock offset. This is the default case and the only case
     considered in the current NTP specification.

The specific interpretation of the prefer peer and PPS peer require some
explanation, which is given in following sections.

B.1. Using the prefer Keyword

For the reasons stated previously, a scheme has been implemented in NTP
to provide an intelligent mitigation between various classes of peers,
one designed to provide the best quality time without compromising the
normal operation of the NTP algorithms. This scheme in its present form
is not an integral component of the NTP specification. but is likely to
be included in future versions of the specification. The scheme is based
on the "preferred peer," which is specified by including the  prefer
keyword with the associated server or peer command in the configuration
file. This keyword can be used with any peer or server, but is most
commonly used with a radio clock server.

The prefer scheme works on the set of peers that have survived the
sanity and intersection algorithms of the clock select procedures.
Ordinarily, the members of this set can be considered truechimers and
any one of them could in principle provide correct time; however, due to
various error contributions, not all can provide the most stable time.
The job of the clustering algorithm, which is invoked at this point, is
to select the best subset of the survivors providing the least variance
in the combined ensemble compared to the variance in each member of the
subset. The detailed operation of the clustering algorithm, which are
given in the specification, are not important here, other than to point
out it operates in rounds, where a survivor, presumably the worst of the
lot, is discarded in each round until one of several termination
conditions is met.

In the prefer scheme the clustering algorithm is modified so that the
prefer peer is never discarded; on the contrary, its potential removal
becomes a termination condition. If the original algorithm were about to
toss out the prefer peer, the algorithm terminates right there. The
prefer peer can still be discarded by the sanity and intersection
algorithms, of course, but it will always survive the clustering
algorithm. A preferred peer retains that designation as long as it
survives the intersection algorithm. If for some reason the prefer peer
fails to survive the intersection algorithm, either because it was
declared a falseticker or became unreachable, it loses that designation
and the clock selection remitigates as described above.

Along with this behavior, the clock select procedures are modified so
that the combining algorithm is not used when a prefer (or PPS) peer is
present. Instead, the offset of the prefer (or PPS) peer is used
exclusively as the synchronization source. In the usual case involving a
radio clock and a flock of remote stratum-1 peers, and with the radio
clock designated a prefer peer, the result is that the high quality
radio time disciplines the server clock as long as the radio itself
remains operational and with valid time, as determined from the remote
peers, sanity algorithm and intersection algorithm.

While the model does not forbid it, it does not seem useful to designate
more than one peer as preferred, since the additional complexities to
mitigate among them do not seem justified from on the air experience.
Note that the prefer peer interacts with the PPS peer discussed in
Appendix C. It also interacts with the Undisciplined Local Clock Driver
(type 1), as described in Appendix A. See the main text for the
mitigation rules applying to the general case.

B.2. Using the Pulse-per-Second (PPS) Signal

Most radio clocks are connected using a serial port operating at speeds
of 9600 bps or lower. The accuracy using typical timecode formats, where
the on-time epoch is indicated by a designated ASCII character, like
carriage-return <cr>, is limited to a millisecond at best and a few
milliseconds in typical cases. However, some radios produce a precision
pulse-per-second (PPS) signal which can be used to improve the accuracy
in typical workstation servers to the order of a few tens of
microseconds. The details of how this can be accomplished are discussed
in the README.magic file; the following discusses how this signal is
implemented and configured in a typical working server.

First, it should be pointed out that the PPS signal is inherently
ambiguous, in that it provides a precise seconds epoch, but does not
provide a way to number the seconds. In principle and most commonly,
another source of synchronization, either the timecode from an
associated radio clock, or even a set of remote peers, is available to
perform that function. In all cases a specific, configured peer or
server must be designated as associated with the PPS signal. This is
done by including the prefer keyword with the associated server or peer
command in the configuration file. This PPS signal can be associated in
this way any peer or server, but is most commonly used with the radio
clock generating the PPS signal.

The PPS signal is processed by a special PPS Clock Discipline Driver
(type 22) described in Appendix A. That description specifies the
hardware configurations in which this signal can be connected to the
server. This driver replaces the former scheme based on conditional
compilation and the PPS, CLK and PPSCLK compile-time switches.
Regardless of method, the driver, like all other drivers, is mitigated
in the manner described for the prefer peer in Appendix B. However, in
the case of the PPS peer, the behavior is slightly more complex.

First, in order for the PPS peer to be considered at all, its associated
prefer peer must have survived the sanity and intersection algorithms
and have been designated the prefer peer. This insures that the radio
clock hardware is operating correctly and that, presumably, the PPS
signal is operating correctly as well. Second, the absolute time offset
from that peer must be less than CLOCK_MAX, the gradual-adjustment
range, which is ordinarily set at 128 ms, or well within the +-0.5-s
unambiguous range of the PPS signal itself. Finally, the time offsets
generated by the PPS peer are propagated via the clock filter to the
clock selection procedures just like any other peer. Should these pass
the sanity and intersection algorithms, they will show up along with the
offsets of the prefer peer itself. Note that, unlike the prefer peer,
the PPS peer samples are not protected from discard by the clustering
algorithm. These complicated procedures insure that the PPS offsets
developed in this way are the most accurate, reliable available for
synchronization.

A PPS peer retains that designation as long as it survives the
intersection algorithm; however, like any other clock driver, it runs a
reachability algortihm on the PPS signal itself. If for some reason the
signal fails or displays gross errors, the PPS peer will either become
unreachable or stray out of the survivor population. In this case the
clock selection remitigates as described above.

Finally, the mitigation procedures described above for the prefer peer
are modified so that, if the PPS peer survives the clustering algorithm,
its offset is mitigated over the prefer peer offset; in other words in
case of ties, the PPS offset wins. See the main text for the mitigation
rules applying to the general case.

B.3. Using the Kernel Discipline

Code to implement the kernel discipline is a special feature that can be
incorporated in the kernel of some workstations as described in the
README.kernel file. The discipline provides for the control of the local
clock oscillator time and/or frequency by means of an external PPS
signal interfaced via a modem control lead. As the PPS signal is derived
from external equipment, cables, etc., which sometimes fail, a good deal
of error checking is done in the kernel to detect signal failure and
excessive noise.

In order to operate, the kernel discipline must be enabled and the
signal must be present and within nominal jitter and wander error
tolerances. In the NTP daemon the kernel is enabled only when the prefer
peer is among the survivors of the clustering algorithm, as described
above. Then, the PPS peer is designated the prefer peer as long as the
PPS signal is present and operating within tolerances. Under these
conditions the kernel disregards updates produced by the NTP daemon and
uses its internal PPS source instead. The kernel maintains a watchdog
timer for the PPS signal; if the signal has not been heard or is out of
tolerance for more than some interval, currently two minutes, the kernel
discipline is declared inoperable and operation continues as if it were
not present.
Appendix C. NTP Local Clock Discipline

Implementation of the ACTS driver caused somewhat of a shakeup in the
NTP local clock model and implementation. The model described in the
specification RFC-1305 is based on a phase-lock loop (PLL) design, which
is optimum or near optimum for the update intervals used for NTP peers
and radio clocks, ordinarily in the range 64-1024 s. However, the ACTS
driver must operate with update intervals in the range well above 1024
s, where the performance of the PLL model deteriorates. As suggested by
Judah Levine of NIST and used in his "lockclock" algorithm, a hybrid
frequency-lock loop (FLL) gives better performance at the longer update
intervals up to a maximum depending on the acceptable error bound.

In a series of experiments and simulations, it was verified that the PLL
model provides better performance in the regime less than about 1000 s,
while the FLL model provides better performance above that. The
parameters of each model were optimized by simulation for the lowest
time and frequency error using data collected on an undisciplined
computer clock oscillator over a period of about two weeks. The PLL/FLL
hybrid loop has been implemented in NTP, along with certain other
refinements described below. While it was designed primarily with ACTS
in mind, it can be used with any NTP peer or radio clock, should that
prove useful.

To take advantage of this feature for other than the ACTS driver, where
it is automatic, note that the default minimum poll interval is 64 s and
default maximum poll interval 1024 s (for the ACTS driver the default
minimum is 1024 s and default maximum 16384 s). However, using the
minpoll and/or maxpoll parameters of the server or peer commands in the
configuration file, it is possible to set the minimum poll interval as
low as 16 s and the maximum poll interval as high as 16384 s. Poll
intervals less than 64 s are useful if an exceptionally quick lock is
required, like in real-time or portable systems. Poll intervals above
1024 s, other than ACTS, may be useful to reduce traffic in some
situations, such as when charges are made on a per-packet basis.

Another modification to the stock NTP local clock discipline is to avoid
errors due to old data. From a study of the stability characteristics of
typical computer clock oscillators using both experiment and simulation,
it was determined that data used to discipline the PLL are not generally
useful if older than about 1000 s. This corresponds roughly to the knee
in the Allan variance characteristic measured for a typical workstation
oscillator. The NTP clock filter algorithm was modified to adjust the
effective length of the shift register so that samples older than about
1000 s are not used to determine the filtered offset, delay and
dispersion values. This design has the useful byproduct that the time to
acquire lock when first coming up and to declare unreachability is
independent of the poll interval.

A problem which has recurred on every occasion a leap second has been
inserted in the UTC timescale is that not all radio clocks detect and
implement the leap event. As a result, some radios sail right through
the leap, become confused for periods up to 15 minutes, then reacquire
lock. In order to cope with this, as well as other occasions where
atypically large offsets occur, the NTP clock discipline has been
modified to disregard offsets over 128 ms, unless (a) first coming up,
(b) first returning to service after a period when unsynchronized, or
(c) an interval of about 15 minutes has elapsed since the last update
less than 128 ms was received. In addition, the discipline has been
modified so that, if the first offset received after coming up is less
than 128 ms, the local clock is immediately reset to that offset without
affecting the PLL variables.

It has been the experience of some users that, when first installed in a
system, the NTP clock discipline fails to reliably lock to other peers
and servers as configured. The indications are that the daemon locks for
some period of time, but is unable to stabilize the frequency estimate.
As the result, the time offsets eventually climb above 128 ms and the
discipline unlocks again. After the 15-minute timeout, the daemon locks
again and the cycle repeats. The problem here is that the intrinsic
frequency error of the local clock exceeds the design capture range of
the PLL, 100 ppm. This particular limit was selected as a compromise
between useful maximum error indications and the tolerances found in
typical computer clock oscillators.

In spite of the tolerance assumed in the NTP specification of 100 ppm,
the NTP daemon for Unix can operate with an intrinsic frequency error of
over 380 ppm, depending on the values of tick and tickadj selected by
the tickadj program. However, with errors that large, the PLL will not
reliably lock, and the behavior noted above can occur. Formerly, the
only remedial in cases where this happens waas a somewhat painful manual
process where the nominal oscillator frequency is measured by some other
means, such as eyeball-and-wristwatch, and a specific drift file
(ntp.drift) crafted.

In order to avoid the above problem, the NTP clock discipline has been
modified to measure the frequency during periods when not locked to
another server or radio clock. Such periods occur when the time offset
wanders through and beyond the 128-ms window as described above. When
synchronization is reestablished, the working frequency used by NTP is
initialized with the measured value. Since a precise frequency
determination is not always possible under these chaotic conditions, it
may take more than one cycle of this type to get the residual error
below 100 ppm and reliable lock established.

David L. Mills <mills@udel.edu>
Electrical Engineering Department
University of Delaware
Newark, DE 19716
302 831 8247 fax 302 831 4316

3 July 1994