More documentation of our assumptions about time sources.

2 files changed, 63 insertions, 28 deletions

diff --git a/gpsd.xml b/gpsd.xml
index ca80ce78..3341dd34 100644
--- a/gpsd.xml
+++ b/gpsd.xml
@@ -1653,25 +1653,37 @@ accuracy limit,the satellites only emit navigation messages at
 <application>gpsd</application> reports in time/position/velocity
 messages are normally accurate only to 1/100th of a second.</para>
 
+<para>If your GPS uses a SiRF chipset at firmware level 231, reported
+UTC time may be off by the difference between whatever default
+leap-second offset has been compiled in and whatever leap-second
+correction is currently applicable, from startup until complete
+subframe information is received.  Firmware levels 232 and up don't
+have this problem.  You may run <application>gpsd</application> at
+debug level 4 to see the chipset type and firmware revision
+level.</para>
+
+<para>There are exactly two circumstances under which
+<application>gpsd</application> relies on the host-system
+clock:</para>
+
 <para>GPS date reporting has a Y2K-like problem for which
 <application>gpsd</application> cannot fully compensate; GPS dates are
 shipped as (week, second) pairs in which the week part is a 10 or
 13-bit counter. When the counter rolls over, a GPS receiver may see
 and report a date 1024 or 8192 weeks in the past.
 <application>gpsd</application> will detect and compensate for
-rollovers while it is running, but cannot recover if the receiver 
-starts up already confused about the date.</para>
-
-<para>To interpret the 2-digit years shipped in NMEA sentences,
-<application>gpsd</application> needs to know the base century and may
-not have it in advance of a GPZDA sentence. If the system clock at
-daemon startup time was at or later than the GPS epoch of 6 Jan 1981
-00:00:00 (excluding negative, 0, and small positive values), it is
-used to compute the base century.  (This is the
-<emphasis>only</emphasis> way in which <application>gpsd</application>
-relies on the system clock.)  Note that this computation may lead to
-errors if the daemon is started up before a transition but continues
-running after it wuthout a ZDA.</para>
+rollovers while it is running, but relies on the system clock to
+correct the epoch.</para>
+
+<para>If you are using an NMEA-only GPS (that is, not using SiRF or
+Garmin or Zodiac binary mode) and the GPS does not emit GPZDA at the
+start of its update cycle (which most consumer-grade NMEA GPSes do
+not) then <application>gpsd</application> century part of the dates
+<application>gpsd</application> delivers will be wrong. Additionally,
+near the century turnover, a range of dates as wide in seconds as the
+accuracy of your system clock may be referred to the wrong
+century.</para>
+
 </refsect1>
 
 <refsect1 id='ntp'><title>USE WITH NTP</title>
@@ -1834,14 +1846,6 @@ result of inadequacies in NMEA and the vendor binary GPS protocols,
 which often do not give clients any way to query the values of control
 settings in order to be able to restore them later.</para>
 
-<para>If your GPS uses a SiRF chipset at firmware level 231, reported
-UTC time may be off by the difference between 13 seconds and whatever
-leap-second correction is currently applicable, from startup until
-complete subframe information is received (normally about six
-seconds).  Firmware levels 232 and up don't have this problem.  You
-may run <application>gpsd</application> at debug level 4 to see the
-chipset type and firmware revision level.</para>
-
 <para>When using SiRF chips, the VDOP/TDOP/GDOP figures and associated
 error estimates are computed by <application>gpsd</application> rather
 than reported by the chip.  The computation does not exactly match
@@ -1851,12 +1855,6 @@ using parameters <application>gpsd</application> cannot see.</para>
 <para>Autobauding on the Trimble GPSes can take as long as 5 seconds
 if the device speed is not matched to the GPS speed.</para>
 
-<para>If you are using an NMEA-only GPS (that is, not using SiRF or
-Garmin or Zodiac binary mode) and the GPS does not emit GPZDA at the
-start of its update cycle (which most consumer-grade NMEA GPSes do
-not) and it is after 2099, then the century part of the dates
-<application>gpsd</application> delivers will be wrong.</para>
-
 <para>Generation of position error estimates (eph, epv, epd, eps, epc)
 from the incomplete data handed back by GPS reporting protocols
 involves both a lot of mathematical black art and fragile
diff --git a/timebase.c b/timebase.c
index 02bd21fe..3b918908 100644
--- a/timebase.c
+++ b/timebase.c
@@ -4,7 +4,8 @@ All of gpsd's assumptions about time and GPS time reporting live in this file.
 
 This is a work in progress.  Currently GPSD requires that the host system 
 clock be accurate to within one second.  We are attempting to relax this
-to "accurate within one GPS rollover period".
+to "accurate within one GPS rollover period" for receivers reporting
+GPS week+TOW.
 
 Date and time in GPS is represented as number of weeks from the start
 of zero second of 6 January 1980, plus number of seconds into the
@@ -35,6 +36,42 @@ e.g. accurate to within 512 weeks.  Many NMEA GPSes have a wired-in
 assumption about the UTC time of the last rollover and will thus report
 incorrect times outside the rollover period they were designed in.
 
+These conditions leave gpsd in a serious hole.  Actually there are several
+interrelated problems:
+
+1) Every NMEA device has some assumption about base epoch (date of
+last rollover) that we don't have access to.  Thus, there's no way to
+check whether a rollover the device wasn't prepared for has occurred
+before gpsd startup time (making the reported UTC date invalid)
+without some other time source.  (Some NMEA devices may keep a
+rollover count in RAM and avoid the problem; we can't tell when that's
+happening, either.)
+
+2) Many NMEA devices - in fact, all that don't report ZDA - never tell
+us what century they think it is. Those that do report century are
+still subject to rollover problems. We need an external time reference
+for this, too.
+
+3) Supposing we're looking at a binary protocol that returns week/tow,
+we can't know which rollover period we're in without an external time
+source.
+
+4) Only one external time source, the host system clock, is reliably
+available.
+
+5) Another source *may* be available - the GPS leap second count, if we can
+get the device to report it. The latter is not a given; SiRFs before 
+firmware rev 2.3.2 don't report it unless special subframe data reporting
+is enabled, which requires 38400bps. Evermore GPSes can't be made to
+report it at all.  
+
+Conclusion: if the system clock isn't accurate enough that we can deduce 
+what rollover period we're in, we're utterly hosed. Furthermore, if it's
+not accurate to within a second and only NMEA devices are reporting, 
+we don't know what century it is! 
+
+Therefore, we must assume the system clock is reliable.
+
 This file is Copyright (c) 2010 by the GPSD project
 BSD terms apply: see the file COPYING in the distribution root for details.