Reference Clock Drivers

Last update: June 21, 2022 20:05 UTC (09eee53b7)

webp

Master Time Facility at the UDel Internet Research Laboratory

Table of Contents

Reference Clock Drivers

Support for most of the commonly available radio and modem reference clocks is included in the default configuration of the NTP daemon for Unix ntpd. Individual clocks can be activated by configuration file commands, specifically the server and fudge commands described in the ntpd program manual page. The following discussion presents Information on how to select and configure the device drivers in a running Unix system.

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.

Radio and modem 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, but some can work directly from the audio codec found in some workstations. The particular device is normally specified by adding a soft link /dev/device_u_ to the particular hardware device involved, where _u corresponds to the unit number above.

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.

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 Audio Drivers page.

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 Undisciplined Local Clock page and respect the stratum limit.

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 External Clock Discipline and the Local Clock Driver page.

Driver Calibration

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 Stations, Frequencies and Geographic Coordinates page. Receiver coordinates can be obtained or estimated from various sources. The actual calculations are beyond the scope of this document.

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 enable calibrate configuration command in the Miscellaneous Options page is useful for this purpose. The calibration function can also be enabled and disabled using the ntpdc program utility.

Most clock drivers use the time1 value specified in the fudge configuration command to provide the calibration correction when this cannot be provided by the clock or interface. When the calibration function is enabled, the time1 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 time1 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 fudge time1 values for all clock drivers are adjusted.

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 time1 values displayed by the ntpq utility and clockvar command. Finally, disable the calibration function to avoid possible future disruptions due to misbehaving clocks or drivers.

Performance Enhancements

In general, performance can be improved, especially when more than one clock driver is supported, to use the prefer peer function described in the Mitigation Rules and the prefer Keyword 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 Pulse-per-second (PPS) Signal Interfacing page.

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 Kernel Model for Precision Timekeeping page. Special line discipline and streams modules for use in capturing precision timestamps are described in the Line Disciplines and Streams Drivers page.

Comprehensive List of Clock Drivers

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. For those drivers without specific documentation, please contact the author listed in the Copyright Notice page.

* 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.