d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
eae8e50443
freebsd-dev/usr.sbin/xntpd/doc/README.refclock
Jordan K. Hubbard dd77c4bc54 Support for the Boeder DCF77 Receiver 
Submitted by: Vincenzo Capuano <VCAPUANO@VMPROFS.ESOC.ESA.DE>
1995-07-21 13:04:07 +00:00

1422 lines
71 KiB
Plaintext
Raw Blame History

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)
127.127.8.40-43 16
RAW DCF77 100/200ms pulses (Boeder DCF77 receiver / 5ms)
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
Reference in New Issue View Git Blame Copy Permalink