Reorganization and link fix.

1 files changed, 82 insertions, 82 deletions

diff --git a/HACKING b/HACKING
index 8a0f9a9e..83000a0e 100644
--- a/HACKING
+++ b/HACKING
@@ -19,7 +19,7 @@ following things:
 2) Write a hardware entry describing the GPS for the hardware page at
    <http://gpsd.berlios.de/hardware.html>.
 
-There's a whole section on adding new drivers 
+There's a whole section on adding new drivers Later in this document.
 
 Before shipping a patch, it is a good idea to make sure the patched
 code displays no warnings when you run 'make splint'.  See
@@ -35,7 +35,7 @@ contributions with GPL attached!
 
 The reason for this policy is to avoid making people nervous about
 linking the GPSD libraries to applications that may be under other
-kicenses (such as MIT, BSD, AFL, etc.).
+licenses (such as MIT, BSD, AFL, etc.).
 
 ** Debugging
 
@@ -209,8 +209,8 @@ location data.
 2) A malicious client could use repeated probes of a target tty or
 other device to cause data loss to other users.  This is a potential
 remote exploit! Not too bad if the bytes he steals are your mouse, it
-would just get jumpy and jerky -- but suppose they're from your disk
-drive and sections drop out of a file you are retrieving for edit?
+would just get jumpy and jerky -- but suppose they're from an actual
+tty and sections drop out of a serial data stream you were relying on?
 
 The conclusion was inescapable.  Switching among and probing devices
 that gpsd already knows about can be an unprivileged operation, but 
@@ -238,80 +238,6 @@ at startup time -- or, if it doesn't exist, the system's
 lowest-numbered TTY device named in PROTO_TTY.  It may be necessary to
 change PROTO_TTY in gpsd.c for non-Linux systems.
 
-** Report-per-packet vs. accumulation across an entire cycle
-
-Considered in the abstract, the cleanest thing for a
-position/velocity/time oracle to return is a 14-tuple including
-position components in all four dimensions, velocity in three, and
-associated error estimates for all seven degrees of freedom.  This is
-what the O message in GPSD protocol attempts to deliver.
-
-Unfortunately GPS protocols are, in general, rather badly designed for
-approximating this.  For historical reasons, NMEA splits 2-D position
-info and altitude in two different messages, each issued once
-during the normal 1-second send cycle.  Some vendor binary
-protocols have similar problems.
-
-This means that gpsd may execute one of two policies.  Either it
-must issue a separate report on each sentence or packet containing PVT
-information, or it must accumulate data across an entire send cycle
-and issue a unified report at end of cycle.  Report-per-packet is
-simpler, and adds minimum reporting latency, but means that O
-responses may issue more than once per second with complementary
-sets of data that add up to a complete report.  The accumulating
-policy means there will be exactly one report per cycle and it will
-contain full PVT information, but it may have additional latency
-of up to one second.
-
-Presently gpsd implements only report-per-packet.  This works well
-with the SiRF protocol (all PVT data is in packet type 02) and with
-the Zodiac protocol (all PVT data is in the type 1000 packet).  These,
-together, account for a share of the GPS market that is 80% and rising
-in 2005.  It works less well with generic NMEA devices.
-
-The reason we have not attempted an accumulating policy is that it
-would require gpsd to know which sentences start and end the GPS send
-cycle is, so as to know when to ship the accumulated data to the
-client and clear the buffers.  Which sentence this is does, in fact,
-vary across GPS types. One of gpsd's design goals, zero configuration,
-means that we can't count on the user or administrator passing gpsd
-this information; instead, gpsd must somehow be able to autodetect it.
-
-This turns out to be hard. We can get timestamps from some (though not
-all) NMEA sentences, but there are some GPSes that change the timestamp
-during the send cycle as well as at start and end.  Thus, we can't
-use coincidence of timestamps to map the cycle.
-
-We can't even count on all send cycles of the same device looking the
-same.  Many GPSes only send GSV when they have satellite lock.
-Without knowing the GPS type in advance, it isn't predictable where in
-the send cycle the GSV will be emitted.
-
-Thus, the only information we have to go on is the wall-clock timing
-of the sentences in the send cycle.  The feature we need to look for
-is the inter-cycle pause.  And the first problem is that at some
-speeds, with some devices, there isn't one.  In particular, at 4800bps
-on an NMEA device sending GGA/RMC/VTG/GLL/GSA/GSV, the intercycle
-pause is nonexistent or too small to be detectible.  See the first
-graph in the paper on GPS latency profiling at
-<http://www.berlios.de/performance.html>. In that one, transmission
-times sometimes add to slightly more than a full 1-second cycle,
-probably due to instrumentation error; the point is, there is no
-significant gap to be detected before the next cycle.
-
-Even if we could rely on that gap to be present, the logic needed to
-detect it is of the sort that is notoriously prone to subtle timing
-failures.  For example, a system-load-induced stall in the host
-operating system's serial layer, happening at the right time shortly
-after device open, might masquerade as an intercycle gap, causing gpsd
-to lock onto the wrong sentence.
-
-With great effort and ingenuity some of these problems could be at
-least partly solved.  Unfortunately, there is every reason to suspect
-the resulting code would be complex, brittle and bug-prone.
-Presently, it doesn't seem like a good idea for a marginal improvemnt
-in 20% of GPSes.
-
 ** Autoconfiguration
 
 One of the design goals for gpsd is to be as near zero-configuration
@@ -468,10 +394,10 @@ initializer method is called immediately.
 
 Note: it is not necessary to add a driver just because your GPS wants
 some funky initialization string.  Simply ship the string in the
-initializer for the NMEA driver.  Because vendor control strings live
-in vendor-specific namespaces (PSRF for SiRF, PGRM for Garmin, etc.)
-your initializing control string will almost certainly be ignored by
-anything not specifically watching for it.
+initializer for the default NMEA driver.  Because vendor control
+strings live in vendor-specific namespaces (PSRF for SiRF, PGRM for
+Garmin, etc.)  your initializing control string will almost certainly
+be ignored by anything not specifically watching for it.
 
 Another good thing to send from the NMEA initializer is probe strings.
 These are strings which should elicit an identifying response from
@@ -571,6 +497,80 @@ If your GPS is SiRF-based, it's easy to capture packets using the
 
 Things we've considered doing and rejected.
 
+*** Accumulating fix data across an entire cycle
+
+Considered in the abstract, the cleanest thing for a
+position/velocity/time oracle to return is a 14-tuple including
+position components in all four dimensions, velocity in three, and
+associated error estimates for all seven degrees of freedom.  This is
+what the O message in GPSD protocol attempts to deliver.
+
+Unfortunately GPS protocols are, in general, rather badly designed for
+approximating this.  For historical reasons, NMEA splits 2-D position
+info and altitude in two different messages, each issued once
+during the normal 1-second send cycle.  Some vendor binary
+protocols have similar problems.
+
+This means that gpsd may execute one of two policies.  Either it
+must issue a separate report on each sentence or packet containing PVT
+information, or it must accumulate data across an entire send cycle
+and issue a unified report at end of cycle.  Report-per-packet is
+simpler, and adds minimum reporting latency, but means that O
+responses may issue more than once per second with complementary
+sets of data that add up to a complete report.  The accumulating
+policy means there will be exactly one report per cycle and it will
+contain full PVT information, but it may have additional latency
+of up to one second.
+
+Presently gpsd implements only report-per-packet.  This works well
+with the SiRF protocol (all PVT data is in packet type 02) and with
+the Zodiac protocol (all PVT data is in the type 1000 packet).  These,
+together, account for a share of the GPS market that is 80% and rising
+in 2005.  It works less well with generic NMEA devices.
+
+The reason we have not attempted an accumulating policy is that it
+would require gpsd to know which sentences start and end the GPS send
+cycle is, so as to know when to ship the accumulated data to the
+client and clear the buffers.  Which sentence this is does, in fact,
+vary across GPS types. One of gpsd's design goals, zero configuration,
+means that we can't count on the user or administrator passing gpsd
+this information; instead, gpsd must somehow be able to autodetect it.
+
+This turns out to be hard. We can get timestamps from some (though not
+all) NMEA sentences, but there are some GPSes that change the timestamp
+during the send cycle as well as at start and end.  Thus, we can't
+use coincidence of timestamps to map the cycle.
+
+We can't even count on all send cycles of the same device looking the
+same.  Many GPSes only send GSV when they have satellite lock.
+Without knowing the GPS type in advance, it isn't predictable where in
+the send cycle the GSV will be emitted.
+
+Thus, the only information we have to go on is the wall-clock timing
+of the sentences in the send cycle.  The feature we need to look for
+is the inter-cycle pause.  And the first problem is that at some
+speeds, with some devices, there isn't one.  In particular, at 4800bps
+on an NMEA device sending GGA/RMC/VTG/GLL/GSA/GSV, the intercycle
+pause is nonexistent or too small to be detectible.  See the first
+graph in the paper on GPS latency profiling at
+<http://gpsd.berlios.de/performance.html>. In that one, transmission
+times sometimes add to slightly more than a full 1-second cycle,
+probably due to instrumentation error; the point is, there is no
+significant gap to be detected before the next cycle.
+
+Even if we could rely on that gap to be present, the logic needed to
+detect it is of the sort that is notoriously prone to subtle timing
+failures.  For example, a system-load-induced stall in the host
+operating system's serial layer, happening at the right time shortly
+after device open, might masquerade as an intercycle gap, causing gpsd
+to lock onto the wrong sentence.
+
+With great effort and ingenuity some of these problems could be at
+least partly solved.  Unfortunately, there is every reason to suspect
+the resulting code would be complex, brittle and bug-prone.
+Presently, it doesn't seem like a good idea for a marginal improvemnt
+in 20% of GPSes.
+
 *** Allowing clients to ship arbitrary control strings to a GPS
 
 Tempting -- it would allow us to do sirfmon-like things with the