1 files changed, 308 insertions, 0 deletions
diff --git a/man/srec.xml b/man/srec.xml
new file mode 100644
index 00000000..0e4e5be8
--- /dev/null
+++ b/man/srec.xml
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+This file is Copyright (c) 2010 by the GPSD project
+BSD terms apply: see the file COPYING in the distribution root for -details.
+-->
+<!DOCTYPE refentry PUBLIC
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<refentry id='srec.5'>
+<refentryinfo><date>15 Jul 2005</date></refentryinfo>
+<refmeta>
+<refentrytitle>srec</refentrytitle>
+<manvolnum>5</manvolnum>
+<refmiscinfo class="source">The GPSD Project</refmiscinfo>
+<refmiscinfo class="manual">GPSD Documentation</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 big-endian hexadecimal integer, 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 big-endian hexadecimal integer, 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 big-endian hexadecimal integer 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 big-endian 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 big-endian 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 big-endian 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 big-endian 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 big-endian 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 big-endian 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 big-endian 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>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgpsmm</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 GPSD
+project, which added endianness clarifications.</para>
+
+</refsect1>
+</refentry>