freebsd-dev/contrib/ntp/html/refclock.htm
2002-11-04 19:36:11 +00:00

203 lines
12 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>Reference Clock Drivers</title>
</head>
<body>
<h3>Reference Clock Drivers</h3>
<img align="left" src="pic/stack1a.jpg" alt="gif">
Master Time Facility at the <a
href="http://www.eecis.udel.edu/%7Emills/lab.htm"> UDel Internet Research
Laboratory</a>: <br clear="left">
<hr>
<p>Support for most of the commonly available radio and modem reference clocks
is included in the default configuration of the NTP daemon for Unix <tt>ntpd</tt>.
Individual clocks can be activated by configuration file commands, specifically
the <tt> server</tt> and <tt>fudge</tt> commands described in the <a
href="ntpd.htm"><tt>ntpd</tt> program manual page</a>. The following discussion
presents Information on how to select and configure the device drivers in
a running Unix system.</p>
<p>Many radio reference clocks can be set to display local time as adjusted
for timezone and daylight saving mode. For use with NTP the clock must be
set for Coordinated Universal Time (UTC) only. Ordinarily, these adjustments
are performed by the kernel, so the fact that the clock runs on UTC will
be transparent to the user.</p>
<p>Radio and modem clocks by convention have addresses in the form 127.127.<i>t.u</i>,
where <i>t</i> is the clock type and <i>u</i> 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, but some can work directly from the audio codec found in some
workstations. The particular device is normally specified by adding a soft
link <tt>/dev/device<i>u</i></tt> to the particular hardware device involved,
where <i><tt>u</tt></i> correspond to the unit number above.</p>
<p>Most clock drivers communicate with the reference clock using a serial
port, usually at 9600 bps. There are several application program interfaces
(API) used in the various Unix and NT systems, most of which can be detected
at configuration time. Thus, it is important that the NTP daemon and utilities
be compiled on the target system or clone. In some cases special features
are available, such as timestamping in the kernel or pulse-per-second (PPS)
interface. In most cases these features can be detected at configuration
time as well; however, the kernel may have to be recompiled in order for
them to work.</p>
<p>The audio drivers are a special case. These include support for the NIST
time/frequency stations WWV and WWVH, the Canadian time/frequency station
CHU and generic IRIG signals. Currently, support for the Solaris and SunOS
audio API is included in the distribution. It is left to the volunteer corps
to extend this support to other systems. Further information on hookup, debugging
and monitoring is given in the <a href="audio.htm">Audio Drivers</a> page.</p>
<p>The local clock driver is also a special case. A server configured with
this driver can operate as a primary server to synchronize other clients
when no other external synchronization sources are available. If the server
is connected directly or indirectly to the public Internet, there is some
danger that it can adversely affect the operation of unrelated clients. Carefully
read the <a href="driver1.htm">Undisciplined Local Clock</a> page and respect
the stratum limit.</p>
<p>The local clock driver also supports an external synchronization source
such as a high resolution counter disciplined by a GPS receiver, for example.
Further information is on the <a href="extern.htm">External Clock Discipline
and the Local Clock Driver</a> page.</p>
<h4>Driver Calibration</h4>
<p>Some drivers depending on longwave and shortwave radio services need to
know the radio propagation time from the transmitter to the receiver, which
can amount to some tens of milliseconds. This must be calculated for each
specific receiver location and requires the geographic coordinates of both
the transmitter and receiver. The transmitter coordinates for various radio
services are given in the <a href="qth.htm">Stations, Frequencies and Geographic
Coordinates</a> page. Receiver coordinates can be obtained or estimated from
various sources. The actual calculations are beyond the scope of this document.</p>
<p>When more than one clock driver is supported, it is often the case that
each shows small systematic offset differences relative to the rest. To reduce
the effects of jitter when switching from one driver to the another, it is
useful to calibrate the drivers to a common ensemble offset. The <tt>enable
calibrate</tt> configuration command in the <a href="miscopt.htm">Miscellaneous
Options</a> page is useful for this purpose. The calibration function can
also be enabled and disabled using the <tt>ntpdc</tt> program utility.</p>
<p>Most clock drivers use the <tt>time1</tt> value specified in the <tt>fudge</tt>
configuration command to provide the calibration correction when this cannot
be provided by the clock or interface. When the calibration function is enabled,
the <tt>time1</tt> value is automatically adjusted to match the offset of
the remote server or local clock driver selected for synchronization. Ordinarily,
the NTP selection algorithm chooses the best from among all sources, usually
the best radio clock determined on the basis of stratum, synchronization
distance and jitter. The calibration function adjusts the <tt>time1</tt>
values for all clock drivers except this source so that their indicated offsets
tend to zero. If the selected source is the kernel PPS discipline, the <tt>fudge
time1</tt> values for all clock drivers are adjusted.</p>
<p>The adjustment function is an exponential average designed to improve
accuracy, so the function takes some time to converge. The recommended procedure
is to enable the function, let it run for an hour or so, then edit the configuration
file using the <tt> time1</tt> values displayed by the <tt>ntpq</tt> utility
and <tt> clockvar</tt> command. Finally, disable the calibration function
to avoid possible future disruptions due to misbehaving clocks or drivers.</p>
<h4>Performance Enhancements</h4>
<p>In general, performance can be improved, especially when more than one
clock driver is supported, to use the prefer peer function described in the
<a href="prefer.htm">Mitigation Rules and the <tt> prefer</tt> Keyword</a>
page. The prefer peer is ordinarily designated the remote peer or local clock
driver which provides the best quality time. All other things equal, only
the prefer peer source is used to discipline the system clock and jitter-producing
"clockhopping" between sources is avoided. This is valuable when more than
one clock driver is present and especially valuable when the PPS clock driver
(type 22) is used. Support for PPS signals is summarized in the <a
href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a> page.</p>
<p>Where the highest performance is required, generally better than one millisecond,
additional hardware and/or software functions may be required. Kernel modifications
for precision time are described in the <a href="kern.htm">A Kernel Model
for Precision Timekeeping</a> page. Special line discipline and streams modules
for use in capturing precision timestamps are described in the <a
href="ldisc.htm">Line Disciplines and Streams Drivers</a> page.</p>
<h4>Comprehensive List of Clock Drivers</h4>
<p>Following is a list showing the type and title of each driver currently
implemented. The compile-time identifier for each is shown in parentheses.
Click on a selected type for specific description and configuration documentation,
including the clock address, reference ID, driver ID, device name and serial
line speed, and features (line disciplines, etc.). For those drivers without
specific documentation, please contact the author listed in the <a
href="copyright.htm">Copyright Notice</a> page.</p>
<p><a href="driver1.htm">Type 1</a> Undisciplined Local Clock (<tt>LOCAL</tt>)<br>
<a href="driver2.htm">Type 2</a> Trak 8820 GPS Receiver (<tt>GPS_TRAK</tt>)<br>
<a href="driver3.htm">Type 3</a> PSTI/Traconex 1020 WWV/WWVH Receiver (<tt>WWV_PST</tt>)<br>
<a href="driver4.htm">Type 4</a> Spectracom WWVB and GPS Receivers (<tt>WWVB_SPEC</tt>)<br>
<a href="driver5.htm">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers (<tt>TRUETIME</tt>)<br>
<a href="driver6.htm">Type 6</a> IRIG Audio Decoder (<tt>IRIG_AUDIO</tt>)<br>
<a href="driver7.htm">Type 7</a> Radio CHU Audio Demodulator/Decoder (<tt>CHU</tt>)<br>
<a href="driver8.htm">Type 8</a> Generic Reference Driver (<tt>PARSE</tt>)<br>
<a href="driver9.htm">Type 9</a> Magnavox MX4200 GPS Receiver (<tt>GPS_MX4200</tt>)<br>
<a href="driver10.htm">Type 10</a> Austron 2200A/2201A GPS Receivers (<tt>GPS_AS2201</tt>)<br>
<a href="driver11.htm">Type 11</a> Arbiter 1088A/B GPS Receiver (<tt>GPS_ARBITER</tt>)<br>
<a href="driver12.htm">Type 12</a> KSI/Odetics TPRO/S IRIG Interface (<tt>IRIG_TPRO</tt>)<br>
Type 13 Leitch CSD 5300 Master Clock Controller (<tt>ATOM_LEITCH</tt>)<br>
Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)<br>
<a href="driver5.htm">Type 15</a> * TrueTime generic receivers<br>
<a href="driver16">Type 16</a> Bancomm GPS/IRIG Receiver (<tt>GPS_BANCOMM</tt>)<br>
Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)<br>
<a href="driver18.htm">Type 18</a> NIST Modem Time Service (<tt>ACTS_NIST</tt>)<br>
<a href="driver19.htm">Type 19</a> Heath WWV/WWVH Receiver (<tt>WWV_HEATH</tt>)<br>
<a href="driver20.htm">Type 20</a> Generic NMEA GPS Receiver (<tt>NMEA</tt>)<br>
Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)<br>
<a href="driver22.htm">Type 22</a> PPS Clock Discipline (<tt>PPS</tt>)<br>
<a href="driver23.htm">Type 23</a> PTB Modem Time Service (<tt>ACTS_PTB</tt>)<br>
<a href="driver24.htm">Type 24</a> USNO Modem Time Service (<tt>ACTS_USNO</tt>)<br>
<a href="driver5.htm">Type 25</a> * TrueTime generic receivers<br>
<a href="driver26.htm">Type 26</a> Hewlett Packard 58503A GPS Receiver (<tt>GPS_HP</tt>)<br>
<a href="driver27.htm">Type 27</a> Arcron MSF Receiver (<tt>MSF_ARCRON</tt>)<br>
<a href="driver28.htm">Type 28</a> Shared Memory Driver (<tt>SHM</tt>)<br>
<a href="driver29.htm">Type 29</a> Trimble Navigation Palisade GPS (<tt>GPS_PALISADE</tt>)<br>
<a href="driver30.htm">Type 30</a> Motorola UT Oncore GPS (<tt>GPS_ONCORE</tt>)<br>
Type 31 Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)<br>
<a href="driver32.htm">Type 32</a> Chrono-log K-series WWVB receiver (<tt>CHRONOLOG</tt>)<br>
<a href="driver33.htm">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>)<br>
<a href="driver34.htm">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>)<br>
<a href="driver35.htm">Type 35</a> Conrad Parallel Port Radio Clock (<tt>PCF</tt>)<br>
<a href="driver36.htm">Type 36</a> Radio WWV/H Audio Demodulator/Decoder
(<tt>WWV</tt>)<br>
<a href="driver37.htm">Type 37</a> Forum Graphic GPS Dating station (<tt>FG</tt>)<br>
<a href="driver38.htm">Type 38</a> hopf GPS/DCF77 6021/komp for Serial Line
(<tt>HOPF_S</tt>)<br>
<a href="driver39.htm">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus (<tt>HOPF_P</tt>)<br>
<a href="driver40.htm">Type 40</a> JJY Receivers (<tt>JJY</tt>)<br>
<a href="driver44.htm">Type 44</a> NeoClock4X DCF77 / TDF receiver<br>
</p>
<p>* All TrueTime receivers are now supported by one driver, type 5. Types
15 and 25 will be retained only for a limited time and may be reassigned
in future.</p>
<p>Additional Information</p>
<p><a href="prefer.htm">Mitigation Rules and the <tt>prefer</tt> Keyword</a><br>
<a href="rdebug.htm">Debugging Hints for Reference Clock Drivers</a><br>
<a href="kern.htm">A Kernel Model for Precision Timekeeping</a><br>
<a href="ldisc.htm">Line Disciplines and Streams Drivers</a><br>
<a href="audio.htm">Reference Clock Audio Drivers</a><br>
<a href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a><br>
<a href="howto.htm">How To Write a Reference Clock Driver</a></p>
<hr> <a href="index.htm"><img align="left" src="pic/home.gif" alt="gif">
</a>
<address><a href="mailto:mills@udel.edu">David L. Mills &lt;mills@udel.edu&gt;</a></address>
<br>
</body>
</html>