### PPS Clock Discipline

#### Synopsis

Address: 127.127.22.u
Reference ID: ATOM
Driver ID: ATOM-PPS
Serial Port: `/dev/ppsu`; 9600 baud, 8-bits, no parity
Features: `tty_clk`, `ppsclock`

#### Description

This driver furnishes an interface for pulse-per-second (PPS) signals produced by a cesium clock, radio clock or related equipment. It can be used to remove accumulated jitter and retime a secondary server when synchronized to a primary server over a congested, wide-area network and before redistributing the time to local clients.

In order for this driver to work, the local clock must be set to within +-500 ms by another means, such as a radio clock or NTP itself. The PPS signal is connected via a serial port and gadget box consisting of a one-shot and RS232 level converter. When operated at 38.4 kbps with a SPARCstation IPC, this arrangement has a worst-case jitter less than 26 us.

There are three ways in which this driver can be used. The first way uses the `LDISC_CLKPPS` line discipline and works only for the baseboard serial ports of the Sun SPARCstation running SunOS 4.x. In order to use this option, the -DPPS flag must be included in the `DEFS_LOCAL` line of the distribution configuration file `./Config.local`. The PPS signal is connected via the gadget box to the carrier detect (DCD) line of a serial port. The signal is activated by a `fudge flag3 1` command following the `server` command in the configuration file. This causes the `ppsclock` streams module to be configured for that port and to capture a timestamp at the on-time transition of the PPS signal. This driver then reads the timestamp directly by a designated `ioctl()` system call. This provides the most accurate time and least jitter of any other scheme. There is no need to configure a dedicated device for this purpose, which ordinarily is the device used for the associated radio clock.

The second way uses the `LDISC_CLKPPS` line discipline and works for any architecture supporting a serial port. In order to use this option, the -DCLK flag must be included in the `DEFS_LOCAL` line of the distribution configuration file `./Config.local`. If after a few seconds this driver finds no `ppsclock` module configured, it attempts to open a serial port device `/dev/pps%d`, where `%d` is the unit number, and assign the LDISC_CLKPPS line discipline to it. If the line discipline fails, no harm is done except the accuracy is reduced somewhat. The pulse generator in the gadget box must be adjusted to produce a start bit of length 26 usec at 38400 bps. Used with the `LDISC_CLKPPS` line discipline, this produces an ASCII DEL character ('\377') followed by a timestamp at the on-time transition of the PPS signal.

The third way involves an auxiliary radio clock driver which calls the PPS driver with a timestamp captured by that driver. This use is documented in the source code for the driver(s) involved.

#### Fudge Factors

`time1 time`
  Specifies the time offset calibration factor, in seconds and fraction, with default 0.0. This parameter can be used to compensate for the UART and OS delays. Allow about 247 us for UART delays at 38400 bps and about 1 ms for SunOS streams nonsense.

`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 `ATOM`.

`flag1 0 | 1`
  Not used by this driver.

`flag2 0 | 1`
  Not used by this driver.

`flag3 0 | 1`
  Enable `ppsclock` line discipline/streams module if set.

`flag4 0 | 1`
  Not used by this driver.

  Additional Information

  Reference Clock Drivers