Added srec(5) manual page.

5 files changed, 319 insertions, 16 deletions

diff --git a/Makefile.am b/Makefile.am
index b9d5338c..47fdf76d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -113,7 +113,8 @@ man_MANS = \
 	gpsfake.1 \
 	sirfmon.1 \
 	rtcmdecode.1 \
-	rtcm.5
+	rtcm.5 \
+	srec.5
 
 gpsd.8: gpsd.xml
 	-$(XMLTO) man gpsd.xml
@@ -145,6 +146,9 @@ rtcmdecode.1: rtcmdecode.xml
 rtcm.5: rtcm.xml
 	-$(XMLTO) man rtcm.xml
 
+srec.5: srec.xml
+	-$(XMLTO) man srec.xml
+
 #
 # Do a release with a tar.gz and a tar.bz2
 #
@@ -179,6 +183,7 @@ EXTRA_DIST = \
 	sirfmon.xml \
 	rtcmdecode.xml \
 	rtcm.xml \
+	srec.xml \
 	$(man_MANS) \
 	xgps.ad \
 	xgpsspeed.ad \
diff --git a/TODO b/TODO
index 55d97ec9..17d648c9 100644
--- a/TODO
+++ b/TODO
@@ -96,13 +96,9 @@ GPS device that can report pseudoranges etc.  This belongs in the
 daemon because the device drivers are already doing the
 packet-cracking needed to get the data off the chips.
 
-*** Decide what to do about RTCM support.
+*** RTCM support.
 
-With WAAS and EGNOS delivering differential-GPS corrections in-band 
-to most modern GPSes (and, in particular, to SiRF GPSses) there may
-no longer be any point to supporting out-of-band RTCM104 and DGPSIP.
-
-If there is still a point to this, here is the elegant way to do it:
+We have an RTCM packet decoder.  Here's the plan for the rest of it:
 
 1) Add code to packet.c that can recognize RTCM104 data packets.  This
    would be the hard part -- that format is *nasty*.
@@ -125,9 +121,6 @@ If there is still a point to this, here is the elegant way to do it:
    Now any GPS-packet and RTCM data sources given on the command line
    can be remote as well as local.
 
-6) Write a rtcmmon equivalent to sirfmon that disassembles and dumps
-   RTCM packets.
-
 *** Do the research to figure out just what is going on with status bits
 
 NMEA actually has *four* kinds of validity bits: Mode, Status, the
diff --git a/rtcm.xml b/rtcm.xml
index 456b7107..bfa3d5eb 100644
--- a/rtcm.xml
+++ b/rtcm.xml
@@ -6,7 +6,7 @@
 <refmeta>
 <refentrytitle>rtcm</refentrytitle>
 <manvolnum>5</manvolnum>
-<refmiscinfo class='date'>12 Feb 2005</refmiscinfo>
+<refmiscinfo class='date'>12 Jul 2005</refmiscinfo>
 </refmeta>
 <refnamediv id='name'>
 <refname>rtcm</refname>
@@ -168,10 +168,10 @@ correction data.</para>
 values:</para>
 
 <literallayout>
-0	1-sigma error &lt;= 1m
-1		"     &lt;= 4m
-2		"     &lt;= 8m
-3		"     &gt;  8m
+0	1-sigma error	&lt;= 1m
+1	1-sigma error	&lt;= 4m
+2	1-sigma error	&lt;= 8m
+3	1-sigma error	&gt;  8m
 </literallayout>
 
 <para>&lt;iod&gt; is Issue of Data, matching the IOD for the current ephemeris
@@ -374,7 +374,7 @@ serial data stream which is a word boundary.
 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 </para>
 </refsect1>
 
diff --git a/srec.xml b/srec.xml
new file mode 100644
index 00000000..f58ab334
--- /dev/null
+++ b/srec.xml
@@ -0,0 +1,302 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC 
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "docbook/docbookx.dtd">
+<refentry id='srec.5'>
+<refmeta>
+<refentrytitle>srec</refentrytitle>
+<manvolnum>5</manvolnum>
+<refmiscinfo class='date'>15 Jul 2005</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>srec</refname>
+<refpurpose>Motorola S-record record and file format</refpurpose>
+</refnamediv>
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para>Motorola S-records are a form of simple ASCII encoding for
+binary data.  This format is commonly used for firmware uploads to
+GPSes, industrial robots, and other kinds of microcontroller-driven
+hardware.  It has several convenient properties, including
+inspectability, easy editing with any text editor, and checksumming
+for verification of transmission across noisy serial lines.</para>
+
+<para>An S-record file consists of a sequence of specially formatted
+ASCII character strings. An S-record will be less than or equal to 78
+bytes in length.</para>
+
+<para>The order of S-records within a file is of no significance and
+no particular order may be assumed.</para>
+
+<para>The general format of an S-record follows:</para>
+
+<screen>
++-------------------//------------------//-----------------------+
+| type | count | address  |            data           | checksum |
++-------------------//------------------//-----------------------+
+</screen>
+
+<variablelist>
+<varlistentry>
+<term>type</term> 
+<listitem><para>A char[2] field. These characters
+describe the type of record (S0, S1, S2, S3, S5, S7, S8, or
+S9).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>count</term>
+<listitem><para>A char[2] field. These characters when paired and
+interpreted as a hexadecimal value, display the count of remaining
+character pairs in the record.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>address</term>
+<listitem><para>A char[4,6, or 8] field. These characters grouped and
+interpreted as a hexadecimal value, display the address at which the
+data field is to be loaded into memory. The length of the field
+depends on the number of bytes necessary to hold the address. A 2-byte
+address uses 4 characters, a 3-byte address uses 6 characters, and a
+4-byte address uses 8 characters.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>data</term>
+<listitem><para>A char [0-64] field. These characters when paired and
+interpreted as hexadecimal values represent the memory loadable data
+or descriptive information.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>checksum</term>
+<listitem><para>A char[2] field. These characters when paired and
+interpreted as a hexadecimal value display the least significant byte
+of the ones complement of the sum of the byte values represented by
+the pairs of characters making up the count, the address, and the data
+fields.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Each record is terminated with a line feed. If any additional or
+different record terminator(s) or delay characters are needed during
+transmission to the target system it is the responsibility of the
+transmitting program to provide them.</para>
+
+<para>There are 9 record types, as follows:</para>
+
+<variablelist>
+<varlistentry>
+<term>S0</term>
+<listitem>
+<para>The type of record is 'S0' (0x5330). The address field
+is unused and will be filled with zeros (0x0000). The header
+information within the data field is divided into the following
+subfields.</para>
+
+<orderedlist>
+<listitem><para>mname is char[20] and is the module name.</para></listitem>
+<listitem><para>ver is char[2] and is the version number.</para></listitem>
+<listitem><para>rev is char[2] and is the revision number.</para></listitem>
+<listitem><para>description is char[0-36] and is a text comment.</para></listitem>
+</orderedlist>
+
+<para>Each of the subfields is composed of ASCII bytes whose
+associated characters, when paired, represent one byte hexadecimal
+values in the case of the version and revision numbers, or represent
+the hexadecimal values of the ASCII characters comprising the module
+name and description.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S1</term>
+<listitem><para>The type of record field is 'S1' (0x5331). The address field is
+interpreted as a 2-byte address. The data field is composed of memory loadable
+data.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S2</term>
+<listitem><para>The type of record field is 'S2' (0x5332). The address field is
+interpreted as a 3-byte address. The data field is composed of memory loadable
+data.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S3</term>
+<listitem><para>The type of record field is 'S3' (0x5333). The address field is
+interpreted as a 4-byte address. The data field is composed of memory loadable
+data.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S5</term>
+<listitem><para>The type of record field is 'S5' (0x5335). The address field is
+interpreted as a 2-byte value and contains the count of S1, S2, and S3 records
+previously transmitted. There is no data field.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S7</term>
+<listitem><para>The type of record field is 'S7' (0x5337). The address
+field contains the starting execution address and is interpreted as a
+4-byte address. There is no data field.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S8</term>
+<listitem><para>The type of record field is 'S8' (0x5338). The address
+field contains the starting execution address and is interpreted as a
+3-byte address. There is no data field.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>S9</term>
+<listitem><para>The type of record field is 'S9' (0x5339). The address
+field contains the starting execution address and is interpreted as a
+2-byte address. There is no data field.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1>
+<refsect1 id='example'><title>EXAMPLE</title>
+
+<para>Shown below is a typical S-record format file.</para>
+
+<programlisting>
+  S00600004844521B
+  S1130000285F245F2212226A000424290008237C2A
+  S11300100002000800082629001853812341001813
+  S113002041E900084E42234300182342000824A952
+  S107003000144ED492
+  S5030004F8
+  S9030000FC
+</programlisting>
+
+<para>The file consists of one S0 record, four S1 records, one S5
+record and an S9 record.</para>
+
+<para>The S0 record is comprised as follows:</para>
+
+<itemizedlist>
+<listitem><para>S0 S-record type S0, indicating it is a header 
+record.</para></listitem>
+
+<listitem><para>06 Hexadecimal 06 (decimal 6), indicating that six
+character pairs (or ASCII bytes) follow.</para></listitem>
+
+<listitem><para>00 00 Four character 2-byte address field, zeroes in 
+this example.</para></listitem>
+
+<listitem><para>48 44 52 ASCII H, D, and R - "HDR".</para></listitem>
+
+<listitem><para>1B The checksum.</para></listitem>
+</itemizedlist>
+
+<para> The first S1 record is comprised as follows:</para>
+
+<itemizedlist>
+<listitem><para>S1 S-record type S1, indicating it is a data record to
+be loaded at a 2-byte address.</para></listitem>
+
+<listitem><para>13 Hexadecimal 13 (decimal 19), indicating that
+nineteen character pairs, representing a 2 byte address, 16 bytes of
+binary data, and a 1 byte checksum, follow.  </para></listitem>
+
+<listitem><para>00 00 Four character 2-byte address field; hexidecimal
+address 0x0000, where the data which follows is to be
+loaded.</para></listitem>
+
+<listitem><para>28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C
+Sixteen character pairs representing the actual binary data.
+</para></listitem>
+
+<listitem><para>2A The checksum.</para></listitem>
+</itemizedlist>
+
+<para>The second and third S1 records each contain 0x13 (19) character
+pairs and are ended with checksums of 13 and 52, respectively. The
+fourth S1 record contains 07 character pairs and has a checksum of
+92.</para>
+
+<para>The S5 record is comprised as follows:</para>
+
+<itemizedlist>
+<listitem><para>S5 S-record type S5, indicating it is a count record
+indicating the number of S1 records </para></listitem>
+
+<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three
+character pairs follow.</para></listitem>
+
+<listitem><para>00 04 Hexadecimal 0004 (decimal 4), indicating that
+there are four data records previous to this record.</para></listitem>
+
+<listitem><para>F8 The checksum.</para></listitem>
+</itemizedlist>
+
+
+<para>The S9 record is comprised as follows:</para>
+
+<itemizedlist>
+<listitem><para>S9 S-record type S9, indicating it is a termination
+record.</para></listitem>
+
+<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three
+character pairs follow.  </para></listitem>
+
+<listitem><para>00 00 The address field, hexadecimal 0 (decimal 0)
+indicating the starting execution address.  </para></listitem>
+
+<listitem><para>FC The checksum.</para></listitem>
+</itemizedlist>
+
+</refsect1>
+<refsect1 id='notes'><title>NOTES</title>
+
+<itemizedlist>
+  <listitem><para> There isn't any evidence that Motorola ever
+    made use of the header information within the data field of the S0
+    record, as described above. This may have been used by some third
+    party vendors.</para></listitem>
+
+<listitem><para>The Unix manual page on S-records is the only place that a
+    78-byte limit on total record length or 64-byte limit on data
+    length is documented. These values shouldn't be trusted for the
+    general case.</para></listitem>
+
+<listitem><para> The count field can have values in the range of 0x3
+    (2 bytes of address + 1 byte checksum = 3, a not very useful
+    record) to 0xff; this is the count of remaining character
+    <emphasis>pairs</emphasis>, including checksum.  </para></listitem>
+
+<listitem><para> If you write code to convert S-Records, you should
+    always assume that a record can be as long as 514 (decimal)
+    characters in length (255 * 2 = 510, plus 4 characters for the
+    type and count fields), plus any terminating character(s).  That
+    is, in establishing an input buffer in C, you would declare it to
+    be an array of 515 chars, thus leaving room for the terminating
+    null character.  </para></listitem>
+</itemizedlist>
+
+</refsect1>
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>xgps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+</para>
+</refsect1>
+
+<refsect1 id='maintainer'><title>AUTHOR</title> 
+
+<para>From an anonymous web page, itself claiming to have been derived
+from an old Unix manual page. Now maintained by the the GPSD project.
+There is a project page for <application>gpsd</application> <ulink
+url="http://gpsd.berlios.de/">here</ulink>.</para>
+
+</refsect1>
+</refentry>
diff --git a/www/index.html.in b/www/index.html.in
index 5fb943b3..71b3b380 100644
--- a/www/index.html.in
+++ b/www/index.html.in
@@ -168,6 +168,9 @@ and fix latency.</dd>
 
 <dt><a href="rtcm.html">rtcm.5</a></dt>
 <dd>The <code>rtcmdecode</code> RTCM104 decoder dump format.</dd>
+
+<dt><a href="srec.html">srec.5</a></dt>
+<dd>The <code>src</code> Motorola S-record and file format.</dd>
 -->
 </dl>