[Git][NTPsec/ntpsec][master] 2 commits: Fix comment glitches.
Eric S. Raymond
gitlab at mg.gitlab.com
Tue Aug 29 19:50:30 UTC 2017
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
943a6b1a by Eric S. Raymond at 2017-08-29T15:50:14-04:00
Fix comment glitches.
- - - - -
c48ba0f1 by Eric S. Raymond at 2017-08-29T15:50:14-04:00
New documentation page om rollover problems
Driver pages about those only emitting 2-digit years now have warnings
attached. More drivers now have eprecation marks for this reason.
- - - - -
14 changed files:
- docs/driver_arbiter.txt
- docs/driver_generic.txt
- docs/driver_jjy.txt
- docs/driver_modem.txt
- docs/driver_neoclock.txt
- docs/driver_oncore.txt
- docs/driver_spectracom.txt
- docs/driver_trimble.txt
- docs/driver_truetime.txt
- docs/includes/special.txt
- docs/refclock.txt
- + docs/rollover.txt
- libparse/README
- libparse/clk_computime.c
Changes:
=====================================
docs/driver_arbiter.txt
=====================================
--- a/docs/driver_arbiter.txt
+++ b/docs/driver_arbiter.txt
@@ -15,6 +15,9 @@ This refclock is deprecated and obsolete. The NTPsec maintainers plan
to remove it in a future release. If you have a requirement for it,
please make this known to us.
+This driver reports only two-digit years, and may thus be subject to
+both lingering Y2K effects and issues near future century rollovers.
+
== Description ==
This driver supports the Arbiter 1088A/B Satellite Controlled Clock. The
=====================================
docs/driver_generic.txt
=====================================
--- a/docs/driver_generic.txt
+++ b/docs/driver_generic.txt
@@ -19,8 +19,10 @@ types/configurations by plugging type-specific packet-parsing
routine into a generic drive framework.
Note that some of these subtypes below are to support equipment that
-has not been commercially available for a long time, and may be
-removed in a future release. See
+has not been commercially available for a long time, report only
+2-digit years (thus being subject to lingering Y2K problems and
+possible fture issues near century boundaries). and may be removed in
+a future release. See
https://www.ntpsec.org/removal-plan.html[Feature removals] for a
discussion of this issue.
=====================================
docs/driver_jjy.txt
=====================================
--- a/docs/driver_jjy.txt
+++ b/docs/driver_jjy.txt
@@ -9,6 +9,10 @@ Serial Port: +/dev/jjyu+; See corresponding receiver
== Description ==
+Warning: some modes of this driver report only two-digit years, and
+may thus be subject to both lingering Y2K effects and problems near
+future century rollovers.
+
This driver supports the following the JJY receivers and the GPS clock
sold in Japan, and the time service through a telephone line.
=====================================
docs/driver_modem.txt
=====================================
--- a/docs/driver_modem.txt
+++ b/docs/driver_modem.txt
@@ -11,6 +11,10 @@ Requires: a dial-out device.
== Description ==
+Warning: the ACTS mode of this driver reports only two-digit years,
+and may thus be subject to both lingering Y2K effects and problems
+near future century rollovers.
+
This driver supports the US (NIST and USNO) and European (PTB (Germany),
NPL (UK), etc.) modem time services, as well as Spectracom GPS receivers
connected via a modem. The driver periodically dials a number from a
=====================================
docs/driver_neoclock.txt
=====================================
--- a/docs/driver_neoclock.txt
+++ b/docs/driver_neoclock.txt
@@ -11,6 +11,10 @@ image:pic/neoclock4x.gif[float="right",link="http://www.linum.com"]
== Description ==
+Warning: the ACTS mode of this driver reports only two-digit years,
+and may thus be subject to both lingering Y2K effects and problems
+near future century rollovers.
+
The refclock_neoclock4x driver supports the NeoClock4X receiver
available from http://www.linum.com[Linum Software GmbH]. The receiver
is available as a http://www.dcf77.de[DCF77] or TDF receiver. Both
=====================================
docs/driver_oncore.txt
=====================================
--- a/docs/driver_oncore.txt
+++ b/docs/driver_oncore.txt
@@ -15,6 +15,9 @@ been end-of-lifed. The NTPsec maintainers plan to remove it in a
future release. If you have a requirement for it, please make this
known to us.
+This driver reports only two-digit years, and may thus be subject to
+both lingering Y2K effects and issues near future century rollovers.
+
== Description ==
This driver supports most models of the
=====================================
docs/driver_spectracom.txt
=====================================
--- a/docs/driver_spectracom.txt
+++ b/docs/driver_spectracom.txt
@@ -9,6 +9,15 @@ Serial Port: +/dev/spectracom+'u'; 9600bps 8N1
Features: Optional PPS signal processing, +tty_clk+
Requires: Optional PPS signal processing requires the PPSAPI signal interface.
+== Deprecation warning ==
+
+This refclock is deprecated and obsolete. The NTPsec maintainers plan
+to remove it in a future release. If you have a requirement for it,
+please make this known to us.
+
+This driver reports only two-digit years, and may thus be subject to
+both lingering Y2K effects and issues near future century rollovers.
+
== Description ==
This driver supports the "Type 2" format emitted by Spectracom time
=====================================
docs/driver_trimble.txt
=====================================
--- a/docs/driver_trimble.txt
+++ b/docs/driver_trimble.txt
@@ -11,6 +11,15 @@ Name: trimble
Reference ID: GPS
Serial Port: /dev/trimble__u__; 9600bps 8N1/8O1
+== Deprecation warning ==
+
+This refclock is deprecated and obsolete. The NTPsec maintainers plan
+to remove it in a future release. If you have a requirement for it,
+please make this known to us.
+
+This driver reports only two-digit years, and may thus be subject to
+both lingering Y2K effects and issues near future century rollovers.
+
== Description ==
The *refclock trimble* driver supports
=====================================
docs/driver_truetime.txt
=====================================
--- a/docs/driver_truetime.txt
+++ b/docs/driver_truetime.txt
@@ -14,6 +14,9 @@ This refclock is deprecated and obsolete. The NTPsec maintainers plan
to remove it in a future release. If you have a requirement for it,
please make this known to us.
+This driver reports only two-digit years, and may thus be subject to
+both lingering Y2K effects and issues near future century rollovers.
+
== Description ==
This driver supports several models models of Kinemetrics/TrueTime
=====================================
docs/includes/special.txt
=====================================
--- a/docs/includes/special.txt
+++ b/docs/includes/special.txt
@@ -11,4 +11,5 @@
* link:clock.html[Clock State Machine]
* link:leap.html[Leap Second Processing]
* link:leapsmear.html[Leap Smearing]
+* link:rollover.html[Rollover issues in time sources]
=====================================
docs/refclock.txt
=====================================
--- a/docs/refclock.txt
+++ b/docs/refclock.txt
@@ -162,21 +162,21 @@ the 6021 in the generic parse driver.
|====================================================================
| Name | Flags | Driver
|link:driver_local.html[local] | - | Undisciplined Local Clock
-|link:driver_spectracom.html[spectracom]| - | Generic Spectracom Receivers
+|link:driver_spectracom.html[spectracom]| D | Generic Spectracom Receivers
|link:driver_truetime.html[truetime] | D | TrueTime GPS/GOES Receivers
|link:driver_generic.html[generic] | T | Generic Reference Driver (Parse)
|link:driver_magnavox.html[magnavox] | D | MX4200 and compatible GPS receivers
-|link:driver_arbiter.html[arbiter] | - | Arbiter 1088A/B GPS Receiver
+|link:driver_arbiter.html[arbiter] | D | Arbiter 1088A/B GPS Receiver
|link:driver_modem.html[modem] | - | NIST/USNO/PTB Modem Time Services
|link:driver_nmea.html[nmea] | T | Generic NMEA GPS Receiver
|link:driver_pps.html[pps] | T | PPS Clock Discipline
|link:driver_hpgps.html[hpgps] | T | Hewlett Packard GPS Receivers
|link:driver_shm.html[shm] | T | Shared Memory Driver
-|link:driver_trimble.html[trimble] | T | Trimble Palisade/Thunderbolt/Acutime GPSes
+|link:driver_trimble.html[trimble] | D | Trimble Palisade/Thunderbolt/Acutime GPSes
|link:driver_oncore.html[oncore] | D | Motorola UT Oncore GPS
|link:driver_jjy.html[jjy] | T | JJY Receivers
|link:driver_zyfer.html[zyfer] | - | Zyfer GPStarplus Receiver
-|link:driver_neoclock.html[neoclock] | - | NeoClock4X DCF77 / TDF Receiver
+|link:driver_neoclock.html[neoclock] | D | NeoClock4X DCF77 / TDF Receiver
|link:driver_gpsd.html[gpsd] | T | GPSD client protocol
|==========================================================================
=====================================
docs/rollover.txt
=====================================
--- /dev/null
+++ b/docs/rollover.txt
@@ -0,0 +1,286 @@
+= Rollover issues ib time sources =
+
+'''''
+
+== Table of Contents ==
+
+* link:#intro[Introduction]
+* link:#terminology[Terminology]
+* link:#cycles[Major cycles of interest]
+* link:#gps_pivots[GPS pivot dates]
+* link:#mtp_pivots[NTP pivot dates]
+
+[[intro]]
+== Introduction ==
+
+All time-handling software and hardware suffers from a fundamental
+problem: finite-sized data representations for times means that,
+sooner or later, your time counter is going to roll over to zero. If
+you are lucky, the space you have to represent time is large enough
+that you can expect not to observe a rollover during the expected
+lifetime of the universe (or whatever portion of it concerns you).
+On real-world hardware you will seldom be that lucky.
+
+This page discusses calendar cycles related to NTP, the ways they
+interact, the consequences of rollover, and common workarounds for
+rollover problems.
+
+[[terminology]]
+== Terminology ==
+
+Every calendar cycle has at least three basic properties: a start date
+(usually referred to a solar astronomical date in the Gregorian
+calendar), a unit (such as seconds) and a rollover time or cycle
+length in that unit. It also matters what the calendar does about
+leap seconds.
+
+As an important example, the basic time representation used on
+computers running Unix has a start date of 1970-01-01T00:00:00
+(midnight of Janary 1st 1970), a unit of seconds, and a rollover time
+of either 2^31^ seconds or 2^63^ seconds, depending on the word size
+of the hardware. Negative times represent seconds before the start
+date.
+
+The start date is often called the "epoch", and a rollover period may
+be called an "era". Beware that eras are often numbered zero-origin;
+it is likely that Unix software will refer to dates immediately before
+the 2038 rollover as "era 0", not "era 1".
+
+Rollover problems arise when a counter wraps to zero, so that a system
+behaves or reports as though time has warped into the far past. The
+consequences can range from trivial to catastrophic; time-dependent
+software enters previously unexplored regions of its behavior space
+and may crash or deliver nonsensical results. Because these edge
+cases are difficult to test, they are defect attractors even when
+system designers have been careful and conscientious.
+
+[[cycles]]
+== Major cycles of interest ==
+
+For purposes related to NTP there are four major cyclic calendars of
+interest: two-digit years, Unix time, NTP time, GPS time (because GPSes
+are so often used as primary time sources).
+
+=== Two-digit year reports ===
+
+A well-known historical rollover problem was "Y2K", which derived from
+the use of two-digit decimal year counters in mainframe software
+(written when storage was so extensive that longer counters would have
+been dramatically more expensive). Expensive preparation and
+mitigation work prevented any major disasters in the year 2000, but
+this was in part because there were many fewer vulnerable systems than
+there later became.
+
+Alas, Y2K-like problems are not dead. Some will persist as long
+as bad old time-source hardware that only reports two-digit years
+is in service.
+
+Many GPSes have this problem due to NMEA0183's inadequacies as a
+reporting format (and analogous problems in various proprietary GPS
+protocols). Unless the device ships a particular $GZDA sentence
+(which many do not) the year parts of time stamps are the low two
+digits only.
+
+Dedicated non-GPS reference-clock hardware designed in the 20th
+century frequently also reports only two-digit year dates - for
+example, the Arbiter and Spectracom devices supported by this
+distribution. This problem may persist in post-2000 devices that
+are designed for compatility to use the same reporting protocols,
+such as Spectracom's "Type 2".
+
+For any device with a two-digit year report, Y2K-like hilarity can
+ensue near any century boundary. There is an internal workaround, in
+{ntpdman}, but prudent time admimistrators should be aware that such
+workarounds are defect attractors and monitor such hardware carefully,
+especially near century boundaries. Warnings have been attached to the
+documentation of NTP clock drivers that may have a vulnerability here.
+
+=== Unix time ===
+
+The basics of Unix time have already been described.
+
+32-bit Unix time will roll over at 2038-01-19T03:14:08, beginning its
+second era. It will not roll over to zero but rather to the minimum
+*negative* Unix time, which will report as 1901-12-13T20:45:52.
+
+Unix time is leap-second-corrected. When a leap second is inserted,
+the Unix counter stutters - increases during the leap second, then
+drops back a second so that the same counter value represents two
+distinct times. If a leap second were to be deleted, the counter
+would skip that second.
+
+Thw possibility of stutter or skip also means that in order to compute
+elapsed time in seconds between two Unix times, you need to know
+the leap-second offset at each time. It is not guaranteed that
+these offsets are the same if the interval crosses midnight at the
+end of any calendar month. To date in 2017, IERS (the International
+Earth Rotation service) has performed all corrections just after
+midnight of June 31 and December 31 respectively.
+
+The purpose of leap-second correction is to keep Unix time
+synchronized to the solar calendar. With it, Unix time after
+1972-01-01T00:00:00 (the start date of UTC, Universal Coordinated
+Time) coincides with UTC. Unix time before 1972 was an approximation
+of GMT (Greenwich Mean Time) without leap seconds.
+
+On POSIX-compliant Unix systems (which is now effecively all) Unix
+time can be retrieved with nanosecond precision; some older versions
+supported only millisecond precision. The subseconds counter is not
+involved in any of the rollover or leap-second issues thith the
+seconds counter.
+
+The Unix 32-bit rollover may fizzle the way Y2K did, and will if a
+large enough percentage of 32-bit computers are replaced with 64-bit
+systems (the time counters on those won't roll over for approximately
+292 billion years, which is twenty times the lifetime of the universe
+so far). There is, however, reason for worry; various Unix
+filesystems, binary file formats, and databases even on 64-bit systems
+use 32-bit fields. A more serious worry is embedded 32-bit hardware
+quietly ticking away in life-critical systems everywhere from medical
+devices to avionics.
+
+=== NTP time ===
+
+NTP time has a 32-bit cycle with an epoch of 1900-01-01T00:00:00. NTP
+time is unsigned; the cycle is thus twice that from a signed 32-bit
+counter and the era 1 rollover will be on 2036-01-08. A detailed
+discussion can be found at
+https://www.eecis.udel.edu/~mills/y2k.html[The NTP Era and Era
+Numbering]. NTP time has a subsecond part in units of 2^-32^
+seconds, which does not participate in the seconds counter's rollover
+problems.
+
+NTP time is leap-second corrected, and the reference implementation
+may exhibit stutter or skip. There is a controversial technique
+called https://developers.google.com/time/smear["leap smearing"] used
+by some servers that avoids these by changing the length of the issued
+second slightly near scheduled corrections.
+
+=== GPS time ===
+
+Raw GPS time is expressed as weeks since the GPS epoch
+1980-01-06T00:00:00, and seconds within the week. Due to cost
+constraints at the time the system was designed, the week counters are
+only 10 bits long; thus, GPS time has a period of 1024 weeks (a bit
+over 19 years) footnote:[It is planned that future GPS satellites will
+increase the week counter length to 13 bits, for a period of 8192
+weeks or more than 157 years]. At time of writing, one GPS rollover
+has occurred at 1999-08-22T00:00:00 and the next will occur on
+2019-05-06.
+
+(GPS was originally designed for military geolocation, not time
+service. It does not seem to have occurred to the originators that
+long-service GPS clocks would ever be built.)
+
+Raw GPS time does not include subseconds, but does ship a
+top-of-second notification accurate to 50ns. Receivers are expected
+to compose this with message data to report time at subsecond
+precision. Many, however, do not, and those that do are often
+inaccurate; consumer-grade hardware often has jitter of over a tenth
+of a second (100ms). On the other hand, carefully designed GPSes
+easily deliver 1ms accuracy, and some do 20 times better than that. A
+more detailed discussion of accuracy budgets see the
+http://www.catb.org/gpsd/time-service-intro.html[Introduction to Time
+Service].
+
+Raw GPS time is not leap-second corrected, but the satellite messages
+include a leap-second offset field in a special update approximately
+every 20 minutes. If the receiver firmware is not carefully designed
+there will be a window between device boot time and the next
+leap-second update, and around leap-second correctipns, during which
+the reported second will be incorrect.
+
+The qualifications about careful design are important because GPS
+firmware - especially in inexpensive consumer-grade devices - is
+often low-quality and poorly tested due to vendors trying to squeeze
+every possible dime out of their costs. Even major vendors like
+SiRF have a history of embarrassing firmware glitches, and the
+semi-anonymous outfits in Shenzhen and on Taiwan are worse.
+
+The worst impact of careless, low-budget design when using a GPS as
+an NTP clock is not around either jitter or leap-second corrections,
+but rather the behavior near GPS and century rollovers.
+
+[gps_pivots]
+== GPS pivot dates and rollover compensation ==
+
+To yield a UTC date, the weeks+second information from the GPS satellites
+has to be used as an offset to a base date.
+
+The most naive way to do this would to simply use the zero date of the
+current era (1024-week cycle) as the base. Some very early GPS equipment
+seems to have worked this way, but it has the drawback that the device
+time-warps at the next GPS era rollover - which, if your device first ship
+is only a few years before that rollover, is a serious drawback.
+
+There is a relatively simple way to extend the useful life of a GPS
+used as a clock. That is to choose a pivot date in GPS weeks. When
+your device reports a week number *before* the pivot, you assume that
+a GPS rollover has occurred and add 1024 weeks to the base date.
+
+This technique will postpones time-warping to a full 1024 weeks after
+the pivot date - which the vendor typically makes the release date
+of the device firmware. But it won't do any better than that; without the
+ability to change the base date, the device will ship incorrect
+reports forever afterwards.
+
+This where careless, low-budget design begins to matter. GPS vendors
+do not document even the fact that they use base or pivot dates, let
+alone what the base and pivot dates for their devices are. As of 2017,
+NTP's developers no not know of any devices for which you can even
+query these parameters, let alone set them. The best you can generally
+do (and on only some devices) is get the firmware release date; from this,
+you can assume that you will get non-timewarped reports for 1024 weeks
+after that and probably be right.
+
+This is not entirely the GPS vendors' fault. The truth is, GPS
+reporting protocols are an awful mess. The closest thing to a
+standard is NMEA0183, originally designed for a different purpose; it
+is poorly specified and has no standard device-control functions at
+all, let alone any for querying base and pivot dates.
+http://www.catb.org/gpsd/[GPSD], the ubiquitous open-source GPS
+manager daemon that shares some developers with NTPsec, works around a
+lot of the general messiness, but can't solve this problem
+because the device capabilities to address it are simply absent.
+
+Finally, when you buy a GPS you do not know - and often will not be
+able to discover - how far in the past its hidden pivot date is. This
+means that time service operators using a GPS as a local Stratum 0
+need to be aware of the possibility that their device could roll over
+at any time (but especially near the zeo dats of a GPS era) and be
+ready to compensate by dropping in a device with a newer pivot date.
+
+[ntp_pivots]
+== NTP pivot dates ==
+
+For purposes of this discussion, a 'resolved' timestamp is one that
+has been mapped from a 32-bit seconds offset in some era to a full
+64-bit timestamp implicitly based in some known era.
+
+When {ntpdman} receives a unresolved timestamp from an upstream server
+that timestamp could be based in any era prior to the current
+wall-clock date - but, by definition, we may not know the wall-clock
+date with confidence yet (not having achieved sync).
+
+To resolve this ambiguity, NTP also uses an internal pivot date. It
+chooses the era that would minimize the absolute value of the time
+difference between the resolved timestamp and its internal pivot date.
+
+This resolution technique is part of the NTP specification. It will
+normally resolve to the current era, but may in cases where the pivot
+is within a half-cycle of a rollover time resolve to either the
+previous or the next era.
+
+An {ntpdman} instance's pivot date will be the date it was compiled
+and built.
+
+It is fairly easy to see that this guarantees correct resolution if the
+pivot dates of the communicating ntpds are within a half-cycle
+(88 years) of each other, even if there is a rollover between the pivot
+dates.
+
+'''''
+
+image::pic/pogo1a.gif[align="center"]
+
+include::includes/footer.txt[]
=====================================
libparse/README
=====================================
--- a/libparse/README
+++ b/libparse/README
@@ -18,7 +18,7 @@ selects the clock type which determines how I/O is done, the tty
parameters and the NTP parameters.
refclock_parse operates on an abstract reference clock that delivers
-time stamps and statuses. Offsets and sychron- isation information is
+time stamps and statuses. Offsets and sychronization information is
derived from this data and passed on to refclock_receive of ntpd which
uses that data for syncronisation.
=====================================
libparse/clk_computime.c
=====================================
--- a/libparse/clk_computime.c
+++ b/libparse/clk_computime.c
@@ -29,7 +29,8 @@
* Parse T: : : : : : : rn
*
* T Startcharacter "T" specifies start of the timestamp
- * YY Year MM Month 1-12
+ * YY Year
+ * MM Month 1-12
* MD Day of the month
* WD Day of week
* HH Hour
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/f54d6919c53317b87a233bc64d22a266272d9ae7...c48ba0f1a21e94b5d0321a433f04c9deb5a6d5b4
---
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/f54d6919c53317b87a233bc64d22a266272d9ae7...c48ba0f1a21e94b5d0321a433f04c9deb5a6d5b4
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/20170829/2089ee16/attachment.html>
More information about the vc
mailing list