Kernel Programming Interface for Precision Time Signals

Last update: May 4, 2022 17:05 UTC (dbea9b7d4)

The technical report ¹ describes a proposed application programming interface (API) for external precision time signals, such as the pulse-per-second (PPS) signal generated by some radio clocks and cesium oscillators. The report argues for a generic capability in the ubiquitous Unix kernel, which could be used for a wide variety of measurement applications, including network time synchronization and experiments involving performance measurement and evaluation of computer networks and transmission systems. The hardware to do this requires only a serial port and a modem control lead, such as the data carrier detect (DCD) lead, which can be driven by an external source via a level converter/pulse generator.

Support for this API has been implemented in the NTP Version 4 software distribution. The /usr/include/sys/timepps.h header file defines the API interface routines and data structures. The API obsoletes previous APIs based on the tty_clock and ppsclock line disciplines and streams modules, which are no longer supported. The API used by the PPS Clock Discipline driver (type 22) to support PPS signals via either a serial port or parallel port, depending on the operating system. The API is supported in stock FreeBSD from 3.4 and with the addition of the PPSkit kernel software in Linux. Limited support for Solaris from 2.8 is available using the timepps.h.solaris header file included in this distribution. Copy this file to /usr/include/sys before configuring the distributution.

The API is normally used in conjunction with the precision time kernel modifications described in the Kernel Model for Precision Timekeeping page.

---

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