diff options
author | Eric S. Raymond <esr@thyrsus.com> | 2005-07-15 03:09:57 +0000 |
---|---|---|
committer | Eric S. Raymond <esr@thyrsus.com> | 2005-07-15 03:09:57 +0000 |
commit | ad307e123bbbae299a9d47ac8e4f3a42cdd00aed (patch) | |
tree | 81edfe94270f266dc8e04b3b3bb0c8e4ecf86497 /srec.xml | |
parent | 86d24775b92c7b1d9af8b743562254e764c665cd (diff) | |
download | gpsd-ad307e123bbbae299a9d47ac8e4f3a42cdd00aed.tar.gz |
Added srec(5) manual page.
Diffstat (limited to 'srec.xml')
-rw-r--r-- | srec.xml | 302 |
1 files changed, 302 insertions, 0 deletions
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> |