[Git][NTPsec/ntpsec][master] 3 commits: Fix PPS documentation
Eric S. Raymond
gitlab at mg.gitlab.com
Mon Jan 21 11:10:54 UTC 2019
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
c15147e9 by Richard Laager at 2019-01-21T11:07:32Z
Fix PPS documentation
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.
- - - - -
9118e58e by Richard Laager at 2019-01-21T11:07:32Z
Fix the PPS threshold in the PPS docs
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.
- - - - -
f9f7af96 by Richard Laager at 2019-01-21T11:07:32Z
Cleanup the PPS driver docs
- 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.
- - - - -
3 changed files:
- docs/driver_pps.adoc
- docs/pps.adoc
- docs/prefer.adoc
Changes:
=====================================
docs/driver_pps.adoc
=====================================
@@ -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 ==
=====================================
docs/pps.adoc
=====================================
@@ -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
=====================================
docs/prefer.adoc
=====================================
@@ -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.
'''''
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/ee8ff57b0467d4740ef3e24ba11b1cc9002cf76b...f9f7af96de0cc4c2a87a45d53b02868cbf3d3074
--
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/ee8ff57b0467d4740ef3e24ba11b1cc9002cf76b...f9f7af96de0cc4c2a87a45d53b02868cbf3d3074
You're receiving this email because of your account on gitlab.com.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20190121/7e599635/attachment-0001.html>
More information about the vc
mailing list