1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
= PPS Clock Discipline
include::include-html.ad[]
== Synopsis
["verse",subs="normal"]
Name: pps
Reference ID: PPS
Driver ID: PPS
Serial or Parallel Port: /dev/pps__u__
Requires: link:kernpps.html[PPSAPI Interface for Precision Time Signals]
== Description
This driver furnishes an interface for the pulse-per-second (PPS) signal
produced by a cesium clock, radio clock or related devices. 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 a few microseconds.
While this driver can discipline the time and frequency relative to the
PPS source, it cannot number the seconds. For this purpose an 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 must be specified
as the prefer peer, as described in the link:prefer.html[Mitigation
Rules and the +prefer+ Keyword] page.
The driver requires the link:kernpps.html[PPSAPI interface], which is
documented in RFC 2783. The interface consists of the +timepps.h+
header file and associated kernel support. Support for this interface is
included in current versions of Solaris, FreeBSD, and Linux. See the
link:pps.html[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. A serial port can be dedicated to
the PPS source or shared with another device; however, if dedicated the
data leads should not be connected, as noise or unexpected signals can
cause +ntpd+ to exit.
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 (DB25 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 to
the actual physical device.
The driver normally operates like any other driver and uses the same
mitigation algorithms and PLL/FLL clock discipline incorporated in the
daemon. If kernel PLL/FLL support is available, the kernel PLL/FLL
clock discipline can be used instead. The default behavior is not to
use the kernel PPS clock discipline, even if present. This driver
incorporates a good deal of signal processing to reduce jitter using
the median filter algorithm in the driver. As the result, performance
with +minpoll+ configured at 4 (16 s) is generally better than the
kernel PPS discipline. However, the +flag 3+ option can be used to
enable the kernel PPS discipline if necessary.
This driver is enabled only under one of two conditions (a) a prefer
peer other than this driver is among the survivors of the mitigation
algorithms or (b) there are no survivors and the +minsane+ option of the
+tos+ command is 0. In typical usage, the prefer peer designates another
source that can reliably number the seconds when available.
A scenario where the latter behavior can be most useful is a planetary
orbiter fleet, for instance in the vicinity of Mars, where contact
between orbiters and Earth occurs only one or two times per Sol (Mars day).
These orbiters have a precise timing reference based on an Ultra Stable
Oscillator (USO) with accuracy on the order of a Cesium oscillator. A
PPS signal is derived from the USO and can be disciplined from Earth on
rare occasion or from another orbiter via NTP. In the above scenario the
PPS signal disciplines the spacecraft clock between NTP updates.
In a similar scenario a PPS signal can be used to discipline the clock
between updates produced by the modem driver. This would provide precise
synchronization without needing the Internet at all.
== Driver Options
+unit+ 'number'::
The driver unit number, defaulting to 0. Used as a distinguishing
suffix in the driver device name.
+time1+ 'time'::
Specifies the time offset calibration factor, in seconds and fraction,
with default 0.0.
+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 PPS capture on the rising (assert) pulse edge if 0 (default)
or falling (clear) pulse edge if 1.
+flag3 {0 | 1}+::
Controls the kernel PPS discipline: 0 for disable (default), 1 for
enable.
+flag4 {0 | 1}+::
Record a timestamp once for each second if 1. Useful for constructing
Allan deviation plots.
+subtype+::
Not used by this driver.
+mode+::
Not used by this driver.
+path+::
Not used by this driver.
+ppspath+::
Overrides the default PPS device path.
+baud+ 'number'::
Not used by this driver.
== Configuration Example
----------------------------------------------------------------------------
refclock pps unit 0 flag2 1 # Capture PPS on trailing edge of pps0
----------------------------------------------------------------------------
This driver does not need to be configured explicitly in order to be
active; thus no "refclock pps" is required unless you need to set a
driver option. It is initialized by whatever other driver is using
it, which will be one of generic, nmea, or spectracom.
== Clockstats
If clockstats is enabled, the driver will log a few counters. Examples:
----------------------------------------------------------------------------
57378 3313.351 PPS(0) 423681 64 0 0 0
57378 3377.352 PPS(0) 423745 64 0 0 0
57378 3441.352 PPS(0) 423809 64 0 0 0
57378 3505.351 PPS(0) 423873 64 0 0 0
----------------------------------------------------------------------------
.Clockstats
[cols="10%,20%,70%",options="header"]
|=============================================================================
|Column|Sample |Meaning
|1 |57378 |MJD
|2 |3505.351 |Time of day in seconds
|3 |PPS(0) |Clock identification
|4 |423873 |Total number of PPS pulses the kernel has seen
|5 |64 |Number of PPS pulses the driver processed
This should be the difference between col 4 and
col 4 from the previous line
|6 |0 |ntpd doesn't know the time yet
|7 |0 |Error from Kernel
|8 |0 |Number of times there was no pulse ready
|=============================================================================
The clock identification is normally the driver type and unit, but if
your ntpd was built in strict Classic compatibility mode it will
be a magic clock address expressing the same information in a more
opaque way.
== Additional Information
link:refclock.html[Reference Clock Drivers]
== Reference
RFC 2783::
Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl, _Pulse-Per-Second
API for Unix-like Operating Systems, Version 1.0_, RFC 2783
== Author
David L. Mills <mills@udel.edu>
'''''
include::includes/footer.adoc[]
|
