From: Harlan Stenn Date: Sat, 22 Dec 2001 04:27:19 +0000 (-0500) Subject: Documentation cleanup from Dave Mills. X-Git-Tag: NTP_4_1_73~211^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=202ddacfaefcda94ba3e397515275a31188c860d;p=thirdparty%2Fntp.git Documentation cleanup from Dave Mills. bk: 3c240ba7gPEEs910uSWt55uqAKrNcQ --- diff --git a/html/driver36.htm b/html/driver36.htm index 911c210199..6eed8349ac 100644 --- a/html/driver36.htm +++ b/html/driver36.htm @@ -11,7 +11,8 @@

Synopsis

Address: 127.127.36.u
-Reference ID: WWV or WWVH
+Reference ID: NONE, WVf or +WHf
Driver ID: WWV_AUDIO
Autotune Port: /dev/icom; 1200/9600 baud, 8-bits, no parity
@@ -101,18 +102,18 @@ beginning establishes the maximum (signal peak) value. The slice level is midway between these two values. The negative-going envelope transition at the slice level establishes the length of the data pulse, which in turn establish probabilities for binary -zero (P0) or binary one (P1). The values are established by linear -interpolation between the pulse lengths for P0 (300 ms) and P1 (500 -ms) so that the sum is equal to one. If the driver has not -synchronized to the minute pulse, or if the data bit amplitude, -signal/noise ratio (SNR) or length are below thresholds, the bit is -considered invalid and all three probabilities are set to zero.

- -

The difference between the P1 and P0 probabilities, or -likelihood, for each data bit is exponentially averaged in a set of -60 accumulators, one for each second, to determine the semi-static +zero (P0) and binary one (P1). The data values are established by +linear interpolation between the pulse lengths for P0 (-1) and P1 +(+1). If the driver has not synchronized to the minute pulse, or if +the data bit amplitude, signal/noise ratio (SNR) or length are +below thresholds, the bit is considered invalid and the data value +set to zero.

+ +

The difference between the P1 and P0 data values, or likelihood, +for each data bit is exponentially averaged in a set of 60 +accumulators, one for each second, to determine the semi-static miscellaneous bits, such as DST indicator, leap second warning and -DUT1 correction. In this design, an average value larger than a +DUT1 correction. In this design, a data average value larger than a positive threshold is interpreted as a hit on one and a value smaller than a negative threshold as a hit on zero. Values between the two thresholds, which can occur due to signal fades or loss of @@ -252,22 +253,23 @@ and low jitter. If the autotune function is active, the driver will rotate over all five frequencies and both WWV and WWVH stations until three good minutes are found. -

The driver then acquires second sync, which can take up to -several minutes, depending on signal quality. At the same time the -driver accumulates likelihood values for each of the nine digits of -the clock, plus the seven miscellaneous bits included in the WWV/H -transmission format. The minute units digit is decoded first and, -when five repetitions have compared correctly, the remaining eight -digits are decoded. When five repetitions of all nine digits have -decoded correctly, which normally takes 15 minutes with good -signals and up to an hour when buried in noise, and the second sync -alarm has not been raised for two minutes, the clock is set (or -verified) and is selectable to discipline the system clock.

+

At the same time the driver then acquires second sync, which can +take up to several minutes, depending on signal quality. Also at +the same time the driver accumulates likelihood values for each of +the nine digits of the clock, plus the seven miscellaneous bits +included in the WWV/H transmission format. The minute units digit +is decoded first and, when five repetitions have compared +correctly, the remaining eight digits are decoded. When five +repetitions of all nine digits have decoded correctly, which +normally takes 15 minutes with good signals and up to an hour when +buried in noise, and the second sync alarm has not been raised for +two minutes, the clock is set (or verified) and is selectable to +discipline the system clock.

As long as the clock is set or verified, the system clock offsets are provided once each second to the reference clock interface, where they are saved in a buffer. At the end of each -minute, the buffer samples are groomed by the median filter and +minute the buffer samples are groomed by the median filter and trimmed-mean averaging functions. Using these functions, the system clock can in principle be disciplined to a much finer resolution than the 125-ms sample interval would @@ -275,43 +277,48 @@ suggest, although the ultimate accuracy is probably limited by propagation delay variations as the ionspheric height varies throughout the day and night.

-

As long as signals are available, the clock frequency is -disciplined for use during times when the signals are unavailable. -The algorithm refines the frequency offset using increasingly -longer averaging intervals to 1024 s, where the precision is about -0.1 PPM. With good signals, it takes well over two hours to reach -this degree of precision; however, it can take many more hours than -this in case of marginal signals. Once reaching the limit, the -algorithm will follow frequency variations due to temperature -fluctuations and ionospheric height variations.

+

The codec clock frequency is disciplined during times when WWV/H +signals are available. The algorithm refines the frequency offset +using increasingly longer averaging intervals to 1024 s, where the +precision is about 0.1 PPM. With good signals, it takes well over +two hours to reach this degree of precision; however, it can take +many more hours than this in case of marginal signals. Once +reaching the limit, the algorithm will follow frequency variations +due to temperature fluctuations and ionospheric height +variations.

It may happen as the hours progress around the clock that WWV and WWVH signals may appear alone, together or not at all. When the driver is first started, the NTP reference identifier appears as -NONE. When the driver has acquired one or both stations -and mitigated which one is best, it sets the station identifier in -the timecode as described below. In addition, the NTP reference -identifier is set to the station callsign. If the propagation -delays has been properly set with the fudge time1 (WWV) -and fudge time2 (WWVH) commands in the configuration file, -handover from one station to the other will be seamless.

+NONE. When the driver has mitigated which station and +frequency is best, it sets the reference identifier to the string +WVf for WWV and WHf for WWVH, where f is the +frequency in megahertz. If the propagation delays have been +properly set with the fudge time1 (WWV) and fudge +time2 (WWVH) commands in the configuration file, handover from +one station to the other is seamless.

Once the clock has been set for the first time, it will appear reachable and selectable to discipline the system clock, even if the broadcast signal fades to obscurity. A consequence of this design is that, once the clock is set, the time and frequency are disciplined only by the second sync pulse and the clock digits -themselves are driven by the clock state machine and ordinarily -never changed. However, as long as the clock is set correctly, it -will continue to read correctly after a period of signal loss, as -long as it does not drift more than 500 ms from the correct time. -Assuming the clock frequency can be disciplined within 1 PPM, the -clock could coast without signals for some 5.8 days without -exceeding that limit. If for some reason this did happen, the clock -would be in the wrong second and would never resynchronize. To -protect against this most unlikely situation, if after four days -with no signals, the clock is considered unset and resumes the -synchronization procedure from the beginning.

+themselves are driven by the clock state machine. If for some +reason the state machine drifts to the wrong second, it would never +reresynchronize. To protect against this most unlikely situation, +if after two days with no signals, the clock is considered unset +and resumes the synchronization procedure from the beginning.

+ +

However, as long as the clock has once been set correctly and +allowed to converge on the intrinsic codec clock frequency, it will +continue to read correctly after a period of signal loss. Assuming +the clock frequency can be disciplined within 1 PPM, it can coast +without signals for several days without exceeding that NTP step +threshold of 128 ms. During such periods the root dispersion +increases at 5 ms per second, which +makes the driver appears less likely for selection as time goes on. +Eventually, when the dispersion due all causes exceeds 1 s, it is +no longer suitable for synchronization at all.

To work well, the driver needs a communications receiver with good audio response at 100 Hz. Most shortwave and communications @@ -333,9 +340,7 @@ in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a serial port using a level -converter such as the CT-17. The serial port speed is presently -compiled in the program, but can be changed in the driver source -file.

+converter such as the CT-17.

Each ICOM radio is assigned a unique 8-bit ID select code, usually expressed in hex format. To activate the CI-V interface, @@ -376,22 +381,16 @@ evaluated according to a metric which considers the minute sync pulse amplitude, SNR and jitter, as well as, the data pulse amplitude and SNR. The minute pulse is evaluated at second 0, while the data pulses are evaluated at seconds 59 and 1. The results are -summarized in a scoreboard of three bits

+summarized in a scoreboard which drives the mitigation function

0x0001
-
Jitter exceeded. The difference in epoches between the last -minute sync pulse and the current one exceeds 50 ms (400 -samples).
- -
0x0002
-
Minute pulse error. For the minute sync pulse in second 0, either the amplitude or SNR is below threshold (2000 and 20 dB, respectively).
-
0x0004
+
0x0002
Minute pulse error. For both of the data pulses in seocnds 59 and 1, either the amplitude or SNR is below threshold (1000 and 10 @@ -402,7 +401,9 @@ dB, respectively).
increased by one to a maximum of six. If any bits are set, the counter is decreased by one to a minimum of zero. At the end of each minute, the frequency and station with the maximum compare -count is chosen, with ties going to the highest frequency.

+count is chosen, with ties going to the highest frequency and WWV +in order. If none of the frequency/station combinations are valid, +the one with maximum minute sync pulse is chosen.

Diagnostics

@@ -412,55 +413,33 @@ the algorithm, as well as radio propagation conditions in general. The message is produced once each minute for each frequency in turn after minute sync has been acquired.

-

wwv5 port agc wwv wwvh

+

wwv5 port status agc epoch count wwv wwvh

where port and agc are the audio port and gain, respectively, for this frequency and wwv and wwvh are two sets of fields, one each for WWV and WWVH. Each of the two fields has the format

-

ident score comp sync/snr/jitr

+

ident score comp sync/snr

where identencodes the station (C for WWV, H for WWVH) and frequency (2, 5, 10, 15 and 20), score is the scoreboard described above, comp is the compare counter, sync is the minute sync pulse amplitude, -snr the SNR of the pulse and jitr is the sample -difference between the current epoch and the last epoch. An example -is:

+snr and the SNR of the pulse. An example is:

-

wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 -22/-12.4/8846

+

wwv5 2 110d 111 5753 2 WV20 0100 6 8348/30.0/-3 WH20 0203 0 +22/-12.4

Here the radio is tuned to 20 MHz and the line-in port AGC is currently 111 at that frequency. The message contains a report for WWV (C20) and WWVH (H20). The WWV report scoreboard is 0100 and the compare count is 6, which suggests very good reception conditions, and the minute sync amplitude and SNR -are well above thresholds (2000 and 20 dB, respectively). Probably -the most sensitive indicator of reception quality is the jitter, -3 -samples, which is well below threshold (50 ms or 400 samples). -While the message shows solid reception conditions from WWV, this -is not the case for WWVH. Both the minute sync amplitude and SNR -are below thresholds and the jitter is above threshold.

- -

A sequence of five messages, one for each minute, might appear -as follows:

- -
-wwv5 2  95 C2 0107 0 164/7.2/8100  H2 0207 0 80/-5.5/7754
-wwv5 2  99 C5 0104 0 3995/21.8/395  H5 0207 0 27/-9.3/18826
-wwv5 2 239 C10 0105 0 9994/30.0/2663 H10 0207 0 54/-16.1/-529
-wwv5 2 155 C15 0103 3 3300/17.8/-1962 H15 0203 0 236/17.0/4873
-wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 22/-12.4/8846
-
- -

Clearly, the only frequencies that are available are 15 MHz and -20 MHz and propagation may be failing for 15 MHz. However, minute -sync pulses are being heard on 5 and 10 MHz, even though the data -pulses are not. This is typical of late afternoon when the maximum -usable frequency (MUF) is falling and the ionospheric loss at the -lower frequencies is beginning to decrease.

+are well above thresholds (2000 and 20 dB, respectively). While the +message shows solid reception conditions from WWV, this is not the +case for WWVH. Both the minute sync amplitude and SNR are below +thresholds.

Debugging Aids

@@ -534,16 +513,16 @@ counter, ampl the pulse amplitude, snr the SNR, offs the minute pulse offset relative to the second pulse. An example is:

-

wwv8 2 127 C15 2 9247 30.0 18843 -1 1
-wwv8 2 127 H15 0 134 -2.9 19016 193 174

+

wwv8 2 127 WV15 2 9247 30.0 18843 -1 1
+wwv8 2 127 WH15 0 134 -2.9 19016 193 174

-

Here the radio is tuned to 15 MHz and the line-in port AGC is -currently 127 at that frequency. The driver has not yet acquired -minute sync, WWV has been heard for at least two minutes, and WWVH -is in the noise. The WWV minute pulse amplitude and SNR are well -above the threshold (2000 and 6 dB, respectively) and the minute -epoch has been determined -1 sample relative to the last one and 1 -sample relative to the second sync pulse. The compare counter has +

Here the radio is tuned to WWV at 15 MHz and the line-in port +AGC is currently 127. The driver has not yet acquired minute sync, +the station has been heard for at least two minutes, and WWVH is in +the noise. The WWV minute pulse amplitude and SNR are well above +the threshold (2000 and 6 dB, respectively) and the minute epoch +has been determined -1 sample relative to the last one and 1 sample +relative to the second sync pulse. The compare counter has incrmented to two; when it gets to three, minute sync has been acquired.

@@ -552,23 +531,22 @@ been acquired and until the seconds unit digit is determined. They show the results of decoding each bit of the transmitted timecode.

-

wwv3 ss stat sigl ampl phas snr prob like

+

wwv3 ss stat sigl ssnr ampl dsnr like

where ss, stat and sigl are as above, -ampl is the subcarrier amplitude, phas the -subcarrier phase, snr the subcarrier SNR, prob -the bit probability and like the bit likelihood. An -example is:

+ssnr is the seconds sync SNR, ampl the subcarrier +amplitude, dsnr the subcarrier SNR and like the +bit likelihood. An example is:

-

wwv3 28 0123 4122 4286 0 24.8 -5545 -1735

+

wwv3 28 0123 4122 30.0 4286 24.8 -5545

Here the driver has acquired minute and second sync, but has not yet determined the seconds unit digit. However, it has just decoded bit 28 of the minute. The results show the second sync pulse amplitude well over the threshold (500), subcarrier amplitude well -above the threshold (1000), good subcarrier tracking phase and SNR -well above the threshold (10 dB). The bit is almost certainly a -zero and the likelihood of a zero in this second is very high.

+above the threshold (1000), good SNR well above the threshold (10 +dB). The bit is almost certainly a zero and the likelihood of a +zero in this second is very high.

Format wwv4 messages are produced for each of the nine BCD timecode digits until the clock has been set or verified. They @@ -601,22 +579,19 @@ oscillator frequency update, which starts at 8 s, but eventually climbs to 1024 s. They show the progress of the algorithm as it refines the frequency measurement to a precision of 0.1 PPM.

-

wwv2 ss stat sigl avint avcnt avinc jitr delt freq

+

wwv2 ss stat sigl jitr avint avcnt freq

where ss, stat and sigl are as above, -avint is the averaging interval, avcnt the -averaging interval counter, avinc the interval increment, -jitr the sample change between the beginning and end of -the interval, delt the computed frequency change and -freq the current frequency (PPM). An example is:

+jitr the jitter, avint the averaging interval, +avcnt the averaging interval counter and freq the +current frequency (PPM). An example is:

-

wwv2 22 030f 5795 256 256 4 0 0.0 66.7

+

wwv2 22 030f 5795 7433 11 256 3 49.0

Here the driver has acquired minute and second sync and set the clock. The averaging interval has increased to 256 s on the way to -1024 s, has stayed at that interval for 4 averaging intervals, has -measured no change in frequency and the current frequency is 66.7 -PPM.

+1024 s, has stayed at that interval for 3 averaging intervals and +the current frequency is 49.0 PPM.

If the CI-V interface for ICOM radios is active, a debug level greater than 1 will produce a trace of the CI-V command and diff --git a/html/howto.htm b/html/howto.htm index 6e082425ca..525ccc1ca2 100644 --- a/html/howto.htm +++ b/html/howto.htm @@ -1,195 +1,263 @@ - -How to Write a Reference Clock Driver -

-How to Write a Reference Clock Driver -

- -from Pogo, Walt Kelly - -

You need a little magic. -

- + + + + +How to Write a Reference Clock Driver + + +

How to Write a Reference Clock Driver

+ +giffrom Pogo, +Walt Kelly + +

You need a little magic.
+

+ +

Description

-

Reference clock support maintains the fiction that the clock is -actually an ordinary peer in the NTP tradition, but operating at a -synthetic stratum of zero. The entire suite of algorithms used to filter -the received data, select the best clocks or peers and combine them to -produce a local clock correction operate just like ordinary NTP peers. -In this way, defective clocks can be detected and removed from the peer -population. As no packets are exchanged with a reference clock; however, -the transmit, receive and packet procedures are replaced with separate -code to simulate them. - -

Radio and modem reference clocks by convention have addresses in the -form 127.127.t.u, where t is the clock -type and u in the range 0-3 is used to distinguish multiple -instances of clocks of the same type. Most clocks require a serial port -or special bus peripheral. The particular device is normally specified -by adding a soft link /dev/devicedd to the particular -hardware device involved, where d corresponds to the -unit number. - -

The best way to understand how the clock drivers work is to study the -ntp_refclock.c module and one of the drivers already -implemented, such as refclock_wwvb.c. Routines -refclock_transmit() and refclock_receive() maintain -the peer variables in a state analogous to a network peer and pass -received data on through the clock filters. Routines -refclock_peer() and refclock_unpeer() are called to -initialize and terminate reference clock associations, should this ever -be necessary. A set of utility routines is included to open serial +

NTP reference clock support maintains the fiction that the clock +is actually an ordinary peer in the NTP tradition, but operating at +a synthetic stratum of zero. The entire suite of algorithms used to +filter the received data, select the best clocks or peers and +combine them to produce a system clock correction operate just like +ordinary NTP peers. In this way, defective clocks can be detected +and removed from the peer population. As no packets are exchanged +with a reference clock; however, the transmit, receive and packet +procedures are replaced with separate code to simulate them.

+ +

It is important to understand how the NTP clock driver interface +works. The driver assumes three timescales: standard time +maintained by a distant laboratory such as USNO or NIST, reference +time maintained by the external radio and the system time +maintained by NTP. The radio synchronizes reference time and +frequency to standard time via radio, satellite or modem. As the +transmission means may not always be reliable, most radios continue +to provide clock updates for some time after signal loss using an +internal reference oscillator. In such cases the radio may or may +not reveal the time since last synchronized and/or the estimated +time error.

+ +

All three timescales run only in Coordinated Universal +Time (UTC), 24-hour format, and are not adjusted for local timezone +or standard/daylight time. The local timezone, standard/daylight +indicator and year, if provided, are ignored. However, it is +important to determine whether a leap second is to be inserted in +the UTC timescale in the near future so NTP can insert it in the +system timescale at the appropriate epoch.

+ +

The NTP clock driver synchronizes the system time and frequency +to the radio via serial or parallel port, PPS signal or other +means. The driver routinely checks the radio timecode string or +status indicators to determine whether it is operating correctly or +not. If it is, the driver decodes the radio timecode in days, +hours, minutes, seconds and nanoseconds and provides these data +with the NTP receive timestamp corresponding to the on-time epoch +of the timecode. The driver interface computes the difference +between the timecode time and NTP timestamp and saves the +difference in a circular buffer for later processing. Once each +poll interval, usually 64 s, the driver provides ancillary data +including leap bits and last reference time to the interface. The +interface processes the circular buffer using a median/trimmed mean +algorithm to extract the best estimate and provides this and the +ancillary data to the clock filter as with ordinary NTP peers.

+ +

The audio drivers are designed to look like a typical external +radio in that the reference oscillator is derived from the audio +codec oscillator and separate from the system clock oscillator. In +the WWV and IRIG drivers, the codec oscillator is disciplined in +frequency to the standard timescale via radio or local sources and +can be assumed to have the same reliability and accuracy as an +external radio. In these cases the driver continues to provide +updates to the clock filter even if the WWV or IRIG signals are +lost. However, the interface is provided the last reference time +when the signals were received and increases the dispersion as +expected with an ordinary peer.

+ +

The best way to understand how the clock drivers work is to +study the ntp_refclock.c module and one of the drivers +already implemented, such as refclock_wwvb.c. Routines +refclock_transmit() and refclock_receive() +maintain the peer variables in a state analogous to a network peer +and pass received data on through the clock filters. Routines +refclock_peer() and refclock_unpeer() initialize and +terminate reference clock associations, should this ever be +necessary. A set of utility routines is included to open serial devices, process sample data, edit input lines to extract embedded -timestamps and to perform various debugging functions. +timestamps and to perform various debugging functions.

-

The main interface used by these routines is the -refclockproc structure, which contains for most drivers the +

The main interface used by these routines is the +refclockproc structure, which contains for most drivers the decimal equivalents of the year, day, month, hour, second and -millisecond/microsecond decoded from the ASCII timecode. Additional -information includes the receive timestamp, exception report, statistics -tallies, etc. The support routines are passed a pointer to the -peer structure, which is used for all peer-specific processing -and contains a pointer to the refclockproc structure, which in -turn contains a pointer to the unit structure, if used. For legacy -purposes, a table typeunit[type][unit] contains the peer -structure pointer for each configured clock type and unit. - -

The reference clock interface supports auxiliary functions to support -in-stream timestamping, pulse-per-second (PPS) interfacing and precision -time kernel support. In most cases the drivers do not need to be aware -of them, since they are detected at autoconfigure time and loaded -automatically when the device is opened. These include the -tty_clk and ppsclock STREAMS modules and -ppsapi PPS interface described in the Line -Disciplines and Streams Modules page. The tty_clk module -reduces latency errors due to the operating system and serial port code -in slower systems. The ppsclock module is an interface for the -PPS signal provided by some radios. The ppsapi PPS interface -replaces the ppsclock STREAMS module and is expected to become -the IETF standard cross-platform interface for PPS signals. In either -case, the PPS signal can be connected via a level converter/pulse -generator described in the Gadget Box PPS Level -Converter and CHU Modem page. +nanosecond decoded from the radio timecode. Additional information +includes the receive timestamp, reference timestamp, exception +reports, statistics tallies, etc. The support routines are passed a +pointer to the peer structure, which is used for all +peer-specific processing and contains a pointer to the +refclockproc structure, which in turn contains a pointer to +the unit structure, if used. For legacy purposes, a table +typeunit[type][unit] contains the peer structure pointer for +each configured clock type and unit. This structure should not be +used for new implementations.

+ +

The reference clock interface supports auxiliary functions to +support in-stream timestamping, pulse-per-second (PPS) interfacing +and precision time kernel support. In most cases the drivers do not +need to be aware of them, since they are detected at autoconfigure +time and loaded automatically when the device is opened. These +include the tty_clk STREAMS module and ppsapi PPS +interface described in the Line Disciplines and +Streams Modules page. The tty_clk module reduces +latency errors due to the operating system and serial port code in +slower systems. The ppsapi PPS interface replaces the +ppsclock STREAMS module and is expected to become the IETF +standard cross-platform interface for PPS signals. In either case, +the PPS signal can be connected via a level converter/pulse +generator described in the Gadget Box PPS +Level Converter and CHU Modem page.

+ +

Radio and modem reference clocks by convention have addresses in +the form 127.127.t.u, where t is the +clock type and u in the range 0-3 is used to distinguish +multiple instances of clocks of the same type. Most clocks require +a serial or parallel port or special bus peripheral. The particular +device is normally specified by adding a soft link +/dev/devicedd to the particular hardware device +involved, where d corresponds to the unit +number.

By convention, reference clock drivers are named in the form refclock_xxxx.c, where xxxx is a unique -string. Each driver is assigned a unique type number, long-form driver -name, short-form driver name, and device name. The existing assignments -are in the Reference Clock Drivers page -and its dependencies. All drivers supported by the particular hardware -and operating system are automatically detected in the autoconfigure -phase and conditionally compiled. They are configured when the daemon is -started according to the configuration file, as described in the Configuration Options page. - -

The standard clock driver interface includes a set of common support -routines some of which do such things as start and stop the device, open -the serial port, and establish special functions such as PPS signal -support. Other routines read and write data to the device and process -time values. Most drivers need only a little customizing code to, for -instance, transform idiosyncratic timecode formats to standard form, -poll the device as necessary, and handle exception conditions. A -standard interface is available for remote debugging and monitoring -programs, such as ntpq and ntpdc, as well as -the filegen facility, which can be used to record device -status on a continuous basis. +string. Each driver is assigned a unique type number, long-form +driver name, short-form driver name and device name. The existing +assignments are in the Reference Clock +Drivers page and its dependencies. All drivers supported by the +particular hardware and operating system are automatically detected +in the autoconfigure phase and conditionally compiled. They are +configured when the daemon is started according to the +configuration file, as described in the +Configuration Options page.

+ +

The standard clock driver interface includes a set of common +support routines some of which do such things as start and stop the +device, open the serial port, and establish special functions such +as PPS signal support. Other routines read and write data to the +device and process time values. Most drivers need only a little +customizing code to, for instance, transform idiosyncratic timecode +formats to standard form, poll the device as necessary, and handle +exception conditions. A standard interface is available for remote +debugging and monitoring programs, such as ntpq and +ntpdc, as well as the filegen facility, which can be +used to record device status on a continuous basis.

The general organization of a typical clock driver includes a -receive-interrupt routine to read a timecode from the I/O buffer and -convert to internal format, generally in days, hours, minutes, seconds -and fraction. Some timecode formats include provisions for leap-second -warning and determine the clock hardware and software health. The -interrupt routine then calls refclock_process() with these data -and the timestamp captured at the on-time character of the timecode. -This routine saves each sample as received in a circular buffer, which -can store from a few up to 60 samples, in cases where the timecodes -arrive one per second. - -

The refclock_transmit() routine in the interface is called -by the system at intervals defined by the poll interval in the peer -structure, generally 64 s. This routine in turn calls the transmit poll -routine in the driver. In the intended design, the driver calls the -refclock_receive() to process the offset samples that have -accumulated since the last poll and produce the final offset and -variance. The samples are processed by recursively discarding median -outlyers until about 60 percent of samples remain, then averaging the -surviving samples. When a reference clock must be explicitly polled to -produce a timecode, the driver can reset the poll interval so that the -poll routine is called a specified number of times at 1-s intervals. - -

The interface code and this documentation have been developed over -some time and required not a little hard work converting old drivers, -etc. Should you find success writing a driver for a new radio or modem -service, please consider contributing it to the common good. Send the -driver file itself and patches for the other files to Dave Mills -(mills@udel.edu). +receive-interrupt routine to read a timecode from the I/O buffer +and convert to internal format, generally in days, hours, minutes, +seconds and fraction. Some timecode formats include provisions for +leap-second warning and determine the clock hardware and software +health. The interrupt routine then calls +refclock_process() with these data and the timestamp captured +at the on-time character of the timecode. This routine saves each +sample as received in a circular buffer, which can store from a few +up to 60 samples, in cases where the timecodes arrive one per +second.

+ +

The refclock_transmit() routine in the interface is +called by the system at intervals defined by the poll interval in +the peer structure, generally 64 s. This routine in turn calls the +transmit poll routine in the driver. In the intended design, the +driver calls the refclock_receive() to process the offset +samples that have accumulated since the last poll and produce the +final offset and variance. The samples are processed by recursively +discarding median outlyers until about 60 percent of samples +remain, then averaging the surviving samples. When a reference +clock must be explicitly polled to produce a timecode, the driver +can reset the poll interval so that the poll routine is called a +specified number of times at 1-s intervals.

+ +

The interface code and this documentation have been developed +over some time and required not a little hard work converting old +drivers, etc. Should you find success writing a driver for a new +radio or modem service, please consider contributing it to the +common good. Send the driver file itself and patches for the other +files to Dave Mills (mills@udel.edu).

Conventions, Fudge Factors and Flags

-

Most drivers support manual or automatic calibration for systematic -offset bias using values encoded in the fudge configuration -command. By convention, the time1 value defines the calibration -offset in seconds. For those drivers that support statistics collection -using the filegen utility and the clockstats file, the -flag4 switch enables the utility. When a PPS signal is -available, a special automatic calibration facility is provided. If the -flag1 switch is set and the PPS signal is actively disciplining -the system time, the calibration value is automatically adjusted to -maintain a residual offset of zero. Should the PPS signal or the prefer -peer fail, the adjustment is frozen and the remaining drivers continue -to discipline the system clock with a minimum of residual error. +

Most drivers support manual or automatic calibration for +systematic offset bias using values encoded in the fudge +configuration command. By convention, the time1 value +defines the calibration offset in seconds. For those drivers that +support statistics collection using the filegen utility +and the clockstats file, the flag4 switch enables +the utility. When a PPS signal is available, a special automatic +calibration facility is provided. If the flag1 switch is +set and the PPS signal is actively disciplining the system time, +the calibration value is automatically adjusted to maintain a +residual offset of zero. Should the PPS signal or the prefer peer +fail, the adjustment is frozen and the remaining drivers continue +to discipline the system clock with a minimum of residual +error.

Files Which Need to be Changed

-

A new reference clock implementation needs to supply, in addition to -the driver itself, several changes to existing files. +

A new reference clock implementation needs to supply, in +addition to the driver itself, several changes to existing +files.

+
./include/ntp.h
-
./include/ntp.h
The reference clock type defines are used in many places. Each driver is assigned a unique type number. Unused numbers are clearly marked in the list. A unique REFCLK_xxxx -identification code should be recorded in the list opposite its assigned -type number. +identification code should be recorded in the list opposite its +assigned type number.
+ +
./libntp/clocktypes.c
-

./libntp/clocktypes.c
The ./libntp/clktype array is used by certain display functions. A unique short-form name of the driver should be entered -together with its assigned identification code. +together with its assigned identification code.
+ +
./ntpd/ntp_control.c
-

./ntpd/ntp_control.c
The clocktypes array is used for certain control -message displays functions. It should be initialized with the reference -clock class assigned to the driver, as per the NTP specification -RFC-1305. See the ./include/ntp_control.h header file for -the assigned classes. - -

./ntpd/refclock_conf.c -
This file contains a list of external structure definitions which -are conditionally defined. A new set of entries should be installed -similar to those already in the table. The refclock_conf -array is a set of pointers to transfer vectors in the individual -drivers. The external name of the transfer vector should be initialized -in correspondence with the type number. - -

./acconfig.h -
This is a configuration file used by the autoconfigure scheme. Add -two lines in the form: - -

+message displays functions. It should be initialized with the
+reference clock class assigned to the driver, as per the NTP
+specification RFC-1305. See the ./include/ntp_control.h
+header file for the assigned classes.
+ +
./ntpd/refclock_conf.c
+ +
This file contains a list of external structure definitions +which are conditionally defined. A new set of entries should be +installed similar to those already in the table. The +refclock_conf array is a set of pointers to transfer vectors +in the individual drivers. The external name of the transfer vector +should be initialized in correspondence with the type number.
+ +
./acconfig.h
+ +
This is a configuration file used by the autoconfigure scheme. +Add two lines in the form: + +
   /* Define if we have a FOO clock */
   #undef FOO
-

where FOO is the define used to cause the driver to be included in -the distribution. +

where FOO is the define used to cause the driver to be included +in the distribution.

+
+ +
./configure.in
-

./configure.in -
This is a configuration file used by the autoconfigure scheme. Add -lines similar to the following: +
This is a configuration file used by the autoconfigure scheme. +Add lines similar to the following: -

+
   AC_MSG_CHECKING(FOO clock_description)
   AC_ARG_ENABLE(FOO, [  --enable-FOO        clock_description],
       [ntp_ok=$enableval], [ntp_ok=$ntp_eac])
@@ -201,24 +269,29 @@ lines similar to the following:
 

 
 
(Note that $ntp_eac is the value from --
-{dis,en}able-all-clocks for non-PARSE clocks and
-$ntp_eacp is the value from --{dis,en}able-parse-
+{dis,en}able-all-clocks for non-PARSE clocks and 
+$ntp_eacp is the value from --{dis,en}able-parse-
 clocks for PARSE clocks. See the documentation on the autoconf
-and automake tools from the GNU distributions.)
+and automake tools from the GNU distributions.)

+
+ +
./ntpd/Makefile.am
-

./ntpd/Makefile.am -

This is the makefile prototype used by the autoconfigure scheme. -Add the driver file name to the entries already in the -ntpd_SOURCES list. +

+

This is the makefile prototype used by the autoconfigure scheme. +Add the driver file name to the entries already in the +ntpd_SOURCES list.

Patches to automake-1.0 are required for the autoconfigure scripts to work properly. The file automake- -1.0.patches can be used for this purpose. +1.0.patches can be used for this purpose.

+
-

./ntpd/Makefile.am -
Do the following sequence of commands: +
./ntpd/Makefile.am
-

+
Do the following sequence of commands: 
+
+
   automake
   autoconf
   autoheader
@@ -226,95 +299,122 @@ autoconfigure scripts to work properly. The file automake-
 

 
 
or simply run make, which will do this command sequence
-automatically.
-
+automatically.

+
-

Interface Routine Overview

+

Interface Routine Overview

-
refclock_newpeer - initialize and start a reference -clock -
This routine allocates and initializes the interface structure which -supports a reference clock in the form of an ordinary NTP peer. A -driver-specific support routine completes the initialization, if used. -Default peer variables which identify the clock and establish its -reference ID and stratum are set here. It returns one if success and -zero if the clock address is invalid or already running, insufficient -resources are available or the driver declares a bum rap. -

refclock_unpeer - shut down a clock -
This routine is used to shut down a clock and return its resources -to the system. - -

refclock_transmit - simulate the transmit procedure -
This routine implements the NTP transmit procedure for a reference -clock. This provides a mechanism to call the driver at the NTP poll -interval, as well as provides a reachability mechanism to detect a -broken radio or other madness. - -

refclock_sample - process a pile of samples from the -clock -
This routine converts the timecode in the form days, hours, minutes, -seconds, milliseconds/microseconds to internal timestamp format. It then -calculates the difference from the receive timestamp and assembles the -samples in a shift register. It implements a recursive median filter to -suppress spikes in the data, as well as determine a rough dispersion -estimate. A configuration constant time adjustment -fudgetime1 can be added to the final offset to compensate -for various systematic errors. The routine returns one if success and -zero if failure due to invalid timecode data or very noisy offsets. - -

Note that no provision is included for the year, as provided by some -(but not all) radio clocks. Ordinarily, the year is implicit in the Unix -file system and hardware/software clock support, so this is ordinarily -not a problem. Nevertheless, the absence of the year should be -considered more a bug than a feature and may be supported in future. - -

refclock_receive - simulate the receive and packet -procedures -
This routine simulates the NTP receive and packet procedures for a -reference clock. This provides a mechanism in which the ordinary NTP -filter, selection and combining algorithms can be used to suppress -misbehaving radios and to mitigate between them when more than one is -available for backup. - -

refclock_gtlin - groom next input line and extract -timestamp +clock
+ +
This routine allocates and initializes the interface structure +which supports a reference clock in the form of an ordinary NTP +peer. A driver-specific support routine completes the +initialization, if used. Default peer variables which identify the +clock and establish its reference ID and stratum are set here. It +returns one if success and zero if the clock address is invalid or +already running, insufficient resources are available or the driver +declares a bum rap.
+ +
refclock_unpeer - shut down a clock
+ +
This routine is used to shut down a clock and return its +resources to the system.
+ +
refclock_transmit - simulate the transmit +procedure
+ +
This routine implements the NTP transmit procedure for a +reference clock. This provides a mechanism to call the driver at +the NTP poll interval, as well as provides a reachability mechanism +to detect a broken radio or other madness.
+ +
refclock_sample - process a pile of samples from the +clock
+ +
This routine converts the timecode in the form days, hours, +minutes, seconds, milliseconds/microseconds to internal timestamp +format. It then calculates the difference from the receive +timestamp and assembles the samples in a shift register. It +implements a recursive median filter to suppress spikes in the +data, as well as determine a rough dispersion estimate. A +configuration constant time adjustment fudgetime1 can be +added to the final offset to compensate for various systematic +errors. The routine returns one if success and zero if failure due +to invalid timecode data or very noisy offsets. + +

Note that no provision is included for the year, as provided by +some (but not all) radio clocks. Ordinarily, the year is implicit +in the Unix file system and hardware/software clock support, so +this is ordinarily not a problem. Nevertheless, the absence of the +year should be considered more a bug than a feature and may be +supported in future.

+
+ +
refclock_receive - simulate the receive and packet +procedures
+ +
This routine simulates the NTP receive and packet procedures +for a reference clock. This provides a mechanism in which the +ordinary NTP filter, selection and combining algorithms can be used +to suppress misbehaving radios and to mitigate between them when +more than one is available for backup.
+ +
refclock_gtlin - groom next input line and extract +timestamp
+
This routine processes the timecode received from the clock and -removes the parity bit and control characters. If a timestamp is present -in the timecode, as produced by the tty_clk line -discipline/streams module, it returns that as the timestamp; otherwise, -it returns the buffer timestamp. The routine return code is the number -of characters in the line. - -

refclock_open - open serial port for reference clock -
This routine opens a serial port for I/O and sets default options. -It returns the file descriptor if success and zero if failure. - -

refclock_ioctl - set serial port control functions -
This routine attempts to hide the internal, system-specific details -of serial ports. It can handle POSIX (termios), SYSV -(termio) and BSD (sgtty) interfaces with +removes the parity bit and control characters. If a timestamp is +present in the timecode, as produced by the tty_clk line +discipline/streams module, it returns that as the timestamp; +otherwise, it returns the buffer timestamp. The routine return code +is the number of characters in the line.
+ +
refclock_open - open serial port for reference +clock
+ +
This routine opens a serial port for I/O and sets default +options. It returns the file descriptor if success and zero if +failure.
+ +
refclock_ioctl - set serial port control +functions
+ +
This routine attempts to hide the internal, system-specific +details of serial ports. It can handle POSIX (termios), +SYSV (termio) and BSD (sgtty) interfaces with varying degrees of success. The routine sets up the tty_clk, chu_clk and ppsclock streams module/line discipline, -if compiled in the daemon and requested in the call. The routine returns -one if success and zero if failure. +if compiled in the daemon and requested in the call. The routine +returns one if success and zero if failure.
+ +
refclock_control - set and/or return clock values
-

refclock_control - set and/or return clock values -
This routine is used mainly for debugging. It returns designated -values from the interface structure that can be displayed using ntpdc -and the clockstat command. It can also be used to initialize -configuration variables, such as fudgetimes, fudgevalues, -reference ID and stratum. +
This routine is used mainly for debugging. It returns +designated values from the interface structure that can be +displayed using ntpdc and the clockstat command. It can also be +used to initialize configuration variables, such as fudgetimes, +fudgevalues, reference ID and stratum.
-

refclock_buginfo - return debugging info -
This routine is used mainly for debugging. It returns designated -values from the interface structure that can be displayed using -ntpdc and the clkbug command. +
refclock_buginfo - return debugging info
+
This routine is used mainly for debugging. It returns +designated values from the interface structure that can be +displayed using ntpdc and the clkbug +command.
-
David L. Mills <mills@udel.edu> -
+
+
gif
+ +
++"gif" + +
David L. Mills +<mills@udel.edu>
+ + +