diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/README.refclock')
| -rw-r--r-- | usr.sbin/xntpd/doc/README.refclock | 1416 |
1 files changed, 1416 insertions, 0 deletions
diff --git a/usr.sbin/xntpd/doc/README.refclock b/usr.sbin/xntpd/doc/README.refclock new file mode 100644 index 0000000..1b9a510 --- /dev/null +++ b/usr.sbin/xntpd/doc/README.refclock @@ -0,0 +1,1416 @@ + 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 |
