Commits (3)
  • Richard Laager's avatar
    Fix PPS documentation · c15147e9
    Richard Laager authored and Eric S. Raymond's avatar Eric S. Raymond committed
    The PPS documentation did not match the code.
    
    The code is:
      if (typepps != NULL && fabs(sys_offset) < 0.4 &&
          (!typepps->is_pps_driver ||
          sys_prefer != NULL ||
          (typesystem == NULL && sys_minsane == 0))) {
    
    Note that the sys_prefer and sys_minsane rules only apply to the driver
    named pps, not to drivers with integrated PPS support.  PPS always needs
    another source, but for integrated drivers, that source is the same
    driver.
    
    The documentation also said the PPS driver will be selected "if the PPS peer
    is designated as a prefer peer", but that is not true; no such code exists.
    c15147e9
  • Richard Laager's avatar
    Fix the PPS threshold in the PPS docs · 9118e58e
    Richard Laager authored and Eric S. Raymond's avatar Eric S. Raymond committed
    The threshold is 0.4 s, not 0.5 s.  The code and the other mentions of
    this threshold are consistent.  This brings the one outlier in line.
    9118e58e
  • Richard Laager's avatar
    Cleanup the PPS driver docs · f9f7af96
    Richard Laager authored and Eric S. Raymond's avatar Eric S. Raymond committed
    - Link to the PPSAPI docs
    - RFC 2783 is NOT an IETF Proposed Standard.  That phrase has a
      specific meaning in the IETF process.  RFC 2783 remains an
      Informational RFC.
    - Change the RFC 2783 citation style to match the style from
      includes/ntpd-body.adoc.
    - Fix the pps.html link title to match exactly that of the target
    - Drop mentions of Tru64 (Alpha) and SunOS.  These are ancient.
    f9f7af96
......@@ -8,7 +8,7 @@ Name: pps
Reference ID: PPS
Driver ID: PPS
Serial or Parallel Port: /dev/pps__u__
Requires: PPSAPI signal interface for PPS signal processing.
Requires: link:kernpps.html[PPSAPI Interface for Precision Time Signals]
== Description ==
......@@ -30,16 +30,16 @@ 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 should be specified
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 PPSAPI interface^1^, 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 Solaris, FreeBSD and Linux and proprietary versions
of Tru64 (Alpha) and SunOS. See the link:pps.html[Pulse-per-second
(PPS) Signal Interfacing] page for further information.
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
......@@ -71,10 +71,8 @@ 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. The prefer peer designates another source that can
reliably number the seconds when available. However, if no sources are
available, the system clock continues to be disciplined by the PPS
driver on an indefinite basis.
+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
......@@ -175,10 +173,9 @@ link:refclock.html[Reference Clock Drivers]
== Reference ==
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.
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 ==
......
......@@ -87,7 +87,7 @@ supporting code automatically compiled. Regardles of mechanism, the PPS signal
must be present and within nominal jitter and wander tolerances. Additionally,
the prefer peer must be a truechimer; that is, survive the sanity checks and
intersection algorithm. Finally, the offset of the system clock relative
to the prefer peer must be within ±0.5 s. The kernel maintains a
to the prefer peer must be within ±0.4 s. The kernel maintains a
watchdog timer for the PPS signal; if the signal has not been heard or
is out of tolerance for more than some interval, currently two minutes,
the kernel discipline is disabled and operation continues as if it were
......
......@@ -137,12 +137,14 @@ orphan parents as if synchronized to a server at the orphan stratum.
Note that, as described on the link:orphan.html[Orphan Mode] page, all
orphan children will select the same orphan parent for synchronization.
3. When a device driver has been configured for pulse-per-second (PPS)
signals and PPS signals are being received, it is designated the _PPS
driver._ Note that the Pulse-per-Second driver is often used
as a PPS driver, but any driver can be configure as a PPS driver if the
hardware facilities are available. The PPS driver provides precision
clock discipline only within ±0.4 s, so it is always associated with
another source or sources that provide the seconds numbering function.
signals and PPS signals are being received, it is designated _a_ PPS
driver. Note that _the_ link:driver_pps.html[driver named "pps"] is
often used as a PPS driver, but any driver can be configured as a PPS
driver if the hardware facilities are available and the driver supports
PPS functionality. PPS provides precision clock discipline only within
±0.4 s, so it is always associated with another source or sources (in
the same driver or a separate driver) that provide the seconds numbering
function.
4. When the Undisciplined Local Clock driver is configured, it
is designated the _local driver_. It can be used either as a backup
source (stratum greater than zero) should all sources fail, or as the
......@@ -233,12 +235,13 @@ peer and its offset and jitter are inherited by the corresponding system
variables. Otherwise, the combine algorithm computes these variables
from the survivor population.
3. If there is a PPS driver and the system clock offset at this point
is less than 0.4 s, and if there is a prefer peer among the survivors or
if the PPS peer is designated as a prefer peer, the PPS driver becomes
the system peer and its offset and jitter are inherited by the system
variables, thus overriding any variables already computed. Note that a
PPS driver is present only if PPS signals are actually being received
and enabled by the associated driver.
is less than 0.4 s, that PPS driver becomes the system peer and its
offset and jitter are inherited by the system variables, thus overriding
any values already computed. However, if the PPS driver is specifically
the link:driver_pps.html[driver named "pps"], which must be used with
another driver, then there must be a prefer peer among the survivors, as
the +prefer+ keyword is used to identify the source associated with the
PPS input. For an exception, see the +minsane+ option below.
If none of the above is the case, the data are disregarded and the
system variables remain as they are.
......@@ -268,8 +271,11 @@ Whether or not the GPS driver disables the PPS signal when the timecode
becomes unreliable is at the discretion of the driver. Ordinarily, the
PPS signal is disabled in this case; however, when the GPS receiver has
a precision holdover oscillator, the driver may elect to continue PPS
discipline. In this case, +minsane+ can be set to zero so the PPS
signal continues to discipline the system clock.
discipline.
To achieve the same result when using the link:driver_pps.html[separate
"pps" driver], +minsane+ can be set to zero so the PPS signal disciplines
the system clock in the absense of other sources.
'''''
......