PPS Clock Discipline


Address: 127.127.22.u
Reference ID: PPS
Driver ID: PPS
Serial or Parallel Port: /dev/ppsu
Requires: PPSAPI interface

Note: This driver supersedes an older one of the same name. The older driver operated with several somewhat archaic signal interface devices, required intricate configuration and was poorly documented. This driver operates only with the PPSAPI interface proposed as an IETF standard.


This driver furnishes an interface for the pulse-per-second (PPS) produced by a cesium clock, radio clock or related equipment. It can be used to augment the serial timecode generated by a GPS receiver, for example. It can be used to remove accumulated jitter and re-time a secondary server when synchronized to a primary server over a congested, wide-area network and before redistributing the time to local clients. The driver includes extensive signal sanity checks and grooming algorithms. A range gate and frequency discriminator reject noise and signals with incorrect frequency. A multiple-stage median filter rejects jitter due to hardware interrupt and operating system latencies. A trimmed-mean algorithm determines the best time samples. With typical workstations and processing loads, the incidental jitter can be reduced to less than a microsecond.

While this driver can discipline the time and frequency relative to the PPS source, it cannot number the seconds. For this purpose a auxiliary source is required, ordinarily a radio clock operated as a primary reference (stratum 1) source; however, another NTP time server can be used as well. For this purpose, the auxiliary source is marked as the prefer peer, as described in the Mitigation Rules and the prefer Keyword page.

The driver requires the PPSAPI interface1, which is a proposed IETF standard. The interface consists of the timepps.h header file and associated kernel support. Support for this interface is included in current versions of FreeBSD and Linux and proprietary versions for Digital/Compaq Tru64 (Alpha), Sun Solaris and Sun SunOS. See the Pulse-per-second (PPS) Signal Interfacing page for further information

The PPS source can be connected via a serial or parallel port, depending on the hardware and operating system. The port can be dedicated to the PPS source or shared with another device. A radio clock is usually connected via a serial port and the PPS source connected via a level converter to the data carrier detect (DCD) pin (DB-9 pin 1, DB-25 pin 8) of the same connector. In some systems where a parallel port and driver are available, the PPS signal can be connected directly to the ACK pin (pin 10) of the connector. Whether the PPS signal is connected via a dedicated port or shared with another device, the driver opens the device /dev/pps%d, where %d is the unit number. As with other drivers, links can be used to redirect the logical name can be redirected to the actual physical device.

Note that the PPS source is considered reachable only if the auxiliary source is the prefer peer, is reachable and is selected to discipline the system clock. The stratum assigned to the PPS source is automatically determined. If the auxiliary source is unreachable or inoperative, the stratum is set to 16; otherwise it is set to match the stratum of the auxiliary source. Since the stratum is determined dynamically, it is not possible to assign another stratum using the fudge command as in other drivers.

Fudge Factors

time1 time
Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.dd>
time2 time
Not used by this driver.
stratum number
Specifies the driver stratum, in decimal from 0 to 15, with default 0.
refid string
Specifies the driver reference identifier, an ASCII string from one to four characters, with default PPS.
flag1 0 | 1
Not used by this driver.
flag2 0 | 1
Specifies the PPS signal on-time edge: 0 for assert (default), 1 for clear.
flag3 0 | 1
Controls the kernel PPS discipline: 0 for disable (default), 1 for enable.
flag4 0 | 1
Not used by this driver.

Additional Information

Reference Clock Drivers


  1. Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like operating systems, version 1. Request for Comments RFC-2783, Internet Engineering Task Force, March 2000, 31 pp.

David L. Mills <mills@udel.edu>