contrib/ntp/html/refclock.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2 <html>
   3 <head>
   4 <meta name="generator" content="HTML Tidy, see www.w3.org">
   5 <title>Reference Clock Drivers</title>
   6 </head>
   7 <body>
   8 <h3>Reference Clock Drivers</h3>
   9
  10 <img align="left" src="pic/stack1a.jpg" alt="gif">Master Time
  11 Facility at the <a href="http://www.eecis.udel.edu/~mills/lab.htm">
  12 UDel Internet Research Laboratory</a>: <br clear="left">
  13 <hr>
  14 <p>Support for most of the commonly available radio and modem
  15 reference clocks is included in the default configuration of the
  16 NTP daemon for Unix <tt>ntpd</tt>. Individual clocks can be
  17 activated by configuration file commands, specifically the <tt>
  18 server</tt> and <tt>fudge</tt> commands described in the <a href=
  19 "ntpd.htm"><tt>ntpd</tt> program manual page</a>. The following
  20 discussion presents Information on how to select and configure the
  21 device drivers in a running Unix system.</p>
  22
  23 <p>Many radio reference clocks can be set to display local time as
  24 adjusted for timezone and daylight saving mode. For use with NTP
  25 the clock must be set for Coordinated Universal Time (UTC) only.
  26 Ordinarily, these adjustments are performed by the kernel, so the
  27 fact that the clock runs on UTC will be transparent to the
  28 user.</p>
  29
  30 <p>Radio and modem clocks by convention have addresses in the form
  31 127.127.<i>t.u</i>, where <i>t</i> is the clock type and <i>u</i>
  32 is a unit number in the range 0-3 used to distinguish multiple
  33 instances of clocks of the same type. Most of these clocks require
  34 support in the form of a serial port or special bus peripheral, but
  35 some can work directly from the audio codec found in some
  36 workstations. The particular device is normally specified by adding
  37 a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware
  38 device involved, where <i><tt>u</tt></i> correspond to the unit
  39 number above.</p>
  40
  41 <p>Most clock drivers communicate with the reference clock using a
  42 serial port, usually at 9600 bps. There are several application
  43 program interfaces (API) used in the various Unix and NT systems,
  44 most of which can be detected at configuration time. Thus, it is
  45 important that the NTP daemon and utilities be compiled on the
  46 target system or clone. In some cases special features are
  47 available, such as timestamping in the kernel or pulse-per-second
  48 (PPS) interface. In most cases these features can be detected at
  49 configuration time as well; however, the kernel may have to be
  50 recompiled in order for them to work.</p>
  51
  52 <p>The audio drivers are a special case. These include support for
  53 the NIST time/frequency stations WWV and WWVH, the Canadian
  54 time/frequency station CHU and generic IRIG signals. Currently,
  55 support for the Solaris and SunOS audio API is included in the
  56 distribution. It is left to the volunteer corps to extend this
  57 support to other systems. Further information on hookup, debugging
  58 and monitoring is given in the <a href="audio.htm">Audio
  59 Drivers</a> page.</p>
  60
  61 <p>The local clock driver is also a special case. A server
  62 configured with this driver can operate as a primary server to
  63 synchronize other clients when no other external synchronization
  64 sources are available. If the server is connected directly or
  65 indirectly to the public Internet, there is some danger that it can
  66 adversely affect the operation of unrelated clients. Carefully read
  67 the <a href="driver1.htm">Undisciplined Local Clock</a> page and
  68 respect the stratum limit.</p>
  69
  70 <p>The local clock driver also supports an external synchronization
  71 source such as a high resolution counter disciplined by a GPS
  72 receiver, for example. Further information is on the <a href=
  73 "extern.htm">External Clock Discipline and the Local Clock
  74 Driver</a> page.</p>
  75
  76 <h4>Driver Calibration</h4>
  77
  78 <p>Some drivers depending on longwave and shortwave radio services
  79 need to know the radio propagation time from the transmitter to the
  80 receiver, which can amount to some tens of milliseconds. This must
  81 be calculated for each specific receiver location and requires the
  82 geographic coordinates of both the transmitter and receiver. The
  83 transmitter coordinates for various radio services are given in the
  84 <a href="qth.htm">Stations, Frequencies and Geographic
  85 Coordinates</a> page. Receiver coordinates can be obtained or
  86 estimated from various sources. The actual calculations are beyond
  87 the scope of this document.</p>
  88
  89 <p>When more than one clock driver is supported, it is often the
  90 case that each shows small systematic offset differences relative
  91 to the rest. To reduce the effects of jitter when switching from
  92 one driver to the another, it is useful to calibrate the drivers to
  93 a common ensemble offset. The <tt>enable calibrate</tt>
  94 configuration command in the <a href="miscopt.htm">Miscellaneous
  95 Options</a> page is useful for this purpose. The calibration
  96 function can also be enabled and disabled using the <tt>ntpdc</tt>
  97 program utility.</p>
  98
  99 <p>Most clock drivers use the <tt>time1</tt> value specified in the
 100 <tt>fudge</tt> configuration command to provide the calibration
 101 correction when this cannot be provided by the clock or interface.
 102 When the calibration function is enabled, the <tt>time1</tt> value
 103 is automatically adjusted to match the offset of the remote server
 104 or local clock driver selected for synchronization. Ordinarily, the
 105 NTP selection algorithm chooses the best from among all sources,
 106 usually the best radio clock determined on the basis of stratum,
 107 synchronization distance and jitter. The calibration function
 108 adjusts the <tt>time1</tt> values for all clock drivers except this
 109 source so that their indicated offsets tend to zero. If the
 110 selected source is the kernel PPS discipline, the <tt>fudge
 111 time1</tt> values for all clock drivers are adjusted.</p>
 112
 113 <p>The adjustment function is an exponential average designed to
 114 improve accuracy, so the function takes some time to converge. The
 115 recommended procedure is to enable the function, let it run for an
 116 hour or so, then edit the configuration file using the <tt>
 117 time1</tt> values displayed by the <tt>ntpq</tt> utility and <tt>
 118 clockvar</tt> command. Finally, disable the calibration function to
 119 avoid possible future disruptions due to misbehaving clocks or
 120 drivers.</p>
 121
 122 <h4>Performance Enhancements</h4>
 123
 124 <p>In general, performance can be improved, especially when more
 125 than one clock driver is supported, to use the prefer peer function
 126 described in the <a href="prefer.htm">Mitigation Rules and the <tt>
 127 prefer</tt> Keyword</a> page. The prefer peer is ordinarily
 128 designated the remote peer or local clock driver which provides the
 129 best quality time. All other things equal, only the prefer peer
 130 source is used to discipline the system clock and jitter-producing
 131 "clockhopping" between sources is avoided. This is valuable when
 132 more than one clock driver is present and especially valuable when
 133 the PPS clock driver (type 22) is used. Support for PPS signals is
 134 summarized in the <a href="pps.htm">Pulse-per-second (PPS) Signal
 135 Interfacing</a> page.</p>
 136
 137 <p>Where the highest performance is required, generally better than
 138 one millisecond, additional hardware and/or software functions may
 139 be required. Kernel modifications for precision time are described
 140 in the <a href="kern.htm">A Kernel Model for Precision
 141 Timekeeping</a> page. Special line discipline and streams modules
 142 for use in capturing precision timestamps are described in the <a
 143 href="ldisc.htm">Line Disciplines and Streams Drivers</a> page.</p>
 144
 145 <h4>Comprehensive List of Clock Drivers</h4>
 146
 147 <p>Following is a list showing the type and title of each driver
 148 currently implemented. The compile-time identifier for each is
 149 shown in parentheses. Click on a selected type for specific
 150 description and configuration documentation, including the clock
 151 address, reference ID, driver ID, device name and serial line
 152 speed, and features (line disciplines, etc.). For those drivers
 153 without specific documentation, please contact the author listed in
 154 the <a href="copyright.htm">Copyright Notice</a> page.</p>
 155
 156 <p><a href="driver1.htm">Type 1</a> Undisciplined Local Clock
 157 (<tt>LOCAL</tt>)<br>
 158 <a href="driver2.htm">Type 2</a> Trak 8820 GPS Receiver
 159 (<tt>GPS_TRAK</tt>)<br>
 160 <a href="driver3.htm">Type 3</a> PSTI/Traconex 1020 WWV/WWVH
 161 Receiver (<tt>WWV_PST</tt>)<br>
 162 <a href="driver4.htm">Type 4</a> Spectracom WWVB and GPS Receivers
 163 (<tt>WWVB_SPEC</tt>)<br>
 164 <a href="driver5.htm">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers
 165 (<tt>TRUETIME</tt>)<br>
 166 <a href="driver6.htm">Type 6</a> IRIG Audio Decoder
 167 (<tt>IRIG_AUDIO</tt>)<br>
 168 <a href="driver7.htm">Type 7</a> Radio CHU Audio
 169 Demodulator/Decoder (<tt>CHU</tt>)<br>
 170 <a href="driver8.htm">Type 8</a> Generic Reference Driver
 171 (<tt>PARSE</tt>)<br>
 172 <a href="driver9.htm">Type 9</a> Magnavox MX4200 GPS Receiver
 173 (<tt>GPS_MX4200</tt>)<br>
 174 <a href="driver10.htm">Type 10</a> Austron 2200A/2201A GPS
 175 Receivers (<tt>GPS_AS2201</tt>)<br>
 176 <a href="driver11.htm">Type 11</a> Arbiter 1088A/B GPS Receiver
 177 (<tt>GPS_ARBITER</tt>)<br>
 178 <a href="driver12.htm">Type 12</a> KSI/Odetics TPRO/S IRIG
 179 Interface (<tt>IRIG_TPRO</tt>)<br>
 180 Type 13 Leitch CSD 5300 Master Clock Controller
 181 (<tt>ATOM_LEITCH</tt>)<br>
 182 Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)<br>
 183 <a href="driver5.htm">Type 15</a> * TrueTime generic receivers<br>
 184 <a href="driver16">Type 16</a> Bancomm GPS/IRIG Receiver
 185 (<tt>GPS_BANCOMM</tt>)<br>
 186 Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)<br>
 187 <a href="driver18.htm">Type 18</a> NIST Modem Time Service
 188 (<tt>ACTS_NIST</tt>)<br>
 189 <a href="driver19.htm">Type 19</a> Heath WWV/WWVH Receiver
 190 (<tt>WWV_HEATH</tt>)<br>
 191 <a href="driver20.htm">Type 20</a> Generic NMEA GPS Receiver
 192 (<tt>NMEA</tt>)<br>
 193 Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)<br>
 194 <a href="driver22.htm">Type 22</a> PPS Clock Discipline
 195 (<tt>PPS</tt>)<br>
 196 <a href="driver23.htm">Type 23</a> PTB Modem Time Service
 197 (<tt>ACTS_PTB</tt>)<br>
 198 <a href="driver24.htm">Type 24</a> USNO Modem Time Service
 199 (<tt>ACTS_USNO</tt>)<br>
 200 <a href="driver5.htm">Type 25</a> * TrueTime generic receivers<br>
 201 <a href="driver26.htm">Type 26</a> Hewlett Packard 58503A GPS
 202 Receiver (<tt>GPS_HP</tt>)<br>
 203 <a href="driver27.htm">Type 27</a> Arcron MSF Receiver
 204 (<tt>MSF_ARCRON</tt>)<br>
 205 <a href="driver28.htm">Type 28</a> Shared Memory Driver
 206 (<tt>SHM</tt>)<br>
 207 <a href="driver29.htm">Type 29</a> Trimble Navigation Palisade GPS
 208 (<tt>GPS_PALISADE</tt>)<br>
 209 <a href="driver30.htm">Type 30</a> Motorola UT Oncore GPS
 210 (<tt>GPS_ONCORE</tt>)<br>
 211 Type 31 Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)<br>
 212 <a href="driver32.htm">Type 32</a> Chrono-log K-series WWVB
 213 receiver <a href="driver33.htm">Type 33</a> Dumb Clock <a href=
 214 "driver34.htm">Type 34</a> Ultralink WWVB Receivers<br>
 215 <a href="driver35.htm">Type 35</a> Conrad Parallel Port Radio Clock
 216 (<tt>PCF</tt>)<br>
 217 <a href="driver36.htm">Type 36</a> Radio WWV/H Audio
 218 Demodulator/Decoder(<tt>WWV</tt>)<br>
 219 <a href="driver37.htm">Type 37</a> Forum Graphic GPS Dating station
 220 (<tt>FG</tt>)<br>
 221 <a href="driver38.htm">Type 38</a> hopf GPS/DCF77 6021/komp for
 222 Serial Line (<tt>HOPF_S</tt>)<br>
 223 <a href="driver39.htm">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus
 224 (<tt>HOPF_P</tt>)</p>
 225
 226 <p>* All TrueTime receivers are now supported by one driver, type
 227 5. Types 15 and 25 will be retained only for a limited time and may
 228 be reassigned in future.</p>
 229
 230 <p>Additional Information</p>
 231
 232 <p><a href="prefer.htm">Mitigation Rules and the <tt>prefer</tt>
 233 Keyword</a><br>
 234 <a href="rdebug.htm">Debugging Hints for Reference Clock
 235 Drivers</a><br>
 236 <a href="kern.htm">A Kernel Model for Precision Timekeeping</a><br>
 237 <a href="ldisc.htm">Line Disciplines and Streams Drivers</a><br>
 238 <a href="audio.htm">Reference Clock Audio Drivers</a><br>
 239 <a href="pps.htm">Pulse-per-second (PPS) Signal Interfacing</a><br>
 240 <a href="howto.htm">How To Write a Reference Clock Driver</a></p>
 241
 242 <hr>
 243 <a href="index.htm"><img align="left" src="pic/home.gif" alt=
 244 "gif"></a>
 245
 246 <address><a href="mailto:mills@udel.edu">David L. Mills
 247 &lt;mills@udel.edu&gt;</a></address>
 248 </body>
 249 </html>
 250