srec.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for -details.
   5 -->
   6 <!DOCTYPE refentry PUBLIC
   7    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   8    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   9 <refentry id='srec.5'>
  10 <refentryinfo><date>15 Jul 2005</date></refentryinfo>
  11 <refmeta>
  12 <refentrytitle>srec</refentrytitle>
  13 <manvolnum>5</manvolnum>
  14 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  15 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  16 </refmeta>
  17 <refnamediv id='name'>
  18 <refname>srec</refname>
  19 <refpurpose>Motorola S-record record and file format</refpurpose>
  20 </refnamediv>
  21 <refsect1 id='description'><title>DESCRIPTION</title>
  22
  23 <para>Motorola S-records are a form of simple ASCII encoding for
  24 binary data.  This format is commonly used for firmware uploads to
  25 GPSes, industrial robots, and other kinds of microcontroller-driven
  26 hardware.  It has several convenient properties, including
  27 inspectability, easy editing with any text editor, and checksumming
  28 for verification of transmission across noisy serial lines.</para>
  29
  30 <para>An S-record file consists of a sequence of specially formatted
  31 ASCII character strings. An S-record will be less than or equal to 78
  32 bytes in length.</para>
  33
  34 <para>The order of S-records within a file is of no significance and
  35 no particular order may be assumed.</para>
  36
  37 <para>The general format of an S-record follows:</para>
  38
  39 <screen>
  40 +-------------------//------------------//-----------------------+
  41 | type | count | address  |            data           | checksum |
  42 +-------------------//------------------//-----------------------+
  43 </screen>
  44
  45 <variablelist>
  46 <varlistentry>
  47 <term>type</term>
  48 <listitem><para>A char[2] field. These characters
  49 describe the type of record (S0, S1, S2, S3, S5, S7, S8, or
  50 S9).</para></listitem>
  51 </varlistentry>
  52
  53 <varlistentry>
  54 <term>count</term>
  55 <listitem><para>A char[2] field. These characters when paired and
  56 interpreted as a big-endian hexadecimal integer, display the count of remaining
  57 character pairs in the record.</para></listitem>
  58 </varlistentry>
  59
  60 <varlistentry>
  61 <term>address</term>
  62 <listitem><para>A char[4,6, or 8] field. These characters grouped and
  63 interpreted as a big-endian hexadecimal integer, display the address
  64 at which the data field is to be loaded into memory. The length of the
  65 field depends on the number of bytes necessary to hold the address. A
  66 2-byte address uses 4 characters, a 3-byte address uses 6 characters,
  67 and a 4-byte address uses 8 characters.</para></listitem>
  68 </varlistentry>
  69
  70 <varlistentry>
  71 <term>data</term>
  72 <listitem><para>A char [0-64] field. These characters when paired and
  73 interpreted as hexadecimal values represent the memory loadable data
  74 or descriptive information.</para></listitem>
  75 </varlistentry>
  76
  77 <varlistentry>
  78 <term>checksum</term>
  79 <listitem><para>A char[2] field. These characters when paired and
  80 interpreted as a big-endian hexadecimal integer display the least
  81 significant byte of the ones complement of the sum of the byte values
  82 represented by the pairs of characters making up the count, the
  83 address, and the data fields.</para></listitem>
  84 </varlistentry>
  85 </variablelist>
  86
  87 <para>Each record is terminated with a line feed. If any additional or
  88 different record terminator(s) or delay characters are needed during
  89 transmission to the target system it is the responsibility of the
  90 transmitting program to provide them.</para>
  91
  92 <para>There are 9 record types, as follows:</para>
  93
  94 <variablelist>
  95 <varlistentry>
  96 <term>S0</term>
  97 <listitem>
  98 <para>The type of record is 'S0' (0x5330). The address field
  99 is unused and will be filled with zeros (0x0000). The header
 100 information within the data field is divided into the following
 101 subfields.</para>
 102
 103 <orderedlist>
 104 <listitem><para>mname is char[20] and is the module name.</para></listitem>
 105 <listitem><para>ver is char[2] and is the version number.</para></listitem>
 106 <listitem><para>rev is char[2] and is the revision number.</para></listitem>
 107 <listitem><para>description is char[0-36] and is a text comment.</para></listitem>
 108 </orderedlist>
 109
 110 <para>Each of the subfields is composed of ASCII bytes whose
 111 associated characters, when paired, represent one byte hexadecimal
 112 values in the case of the version and revision numbers, or represent
 113 the hexadecimal values of the ASCII characters comprising the module
 114 name and description.</para>
 115 </listitem>
 116 </varlistentry>
 117
 118 <varlistentry>
 119 <term>S1</term>
 120 <listitem><para>The type of record field is 'S1' (0x5331). The address
 121 field is interpreted as a 2-byte big-endian address. The data field is
 122 composed of memory loadable data.</para></listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term>S2</term>
 127 <listitem><para>The type of record field is 'S2' (0x5332). The address
 128 field is interpreted as a 3-byte big-endian address. The data field is
 129 composed of memory loadable data.</para></listitem>
 130 </varlistentry>
 131
 132 <varlistentry>
 133 <term>S3</term>
 134 <listitem><para>The type of record field is 'S3' (0x5333). The address
 135 field is interpreted as a 4-byte big-endian address. The data field is
 136 composed of memory loadable data.</para></listitem>
 137 </varlistentry>
 138
 139 <varlistentry>
 140 <term>S5</term>
 141 <listitem><para>The type of record field is 'S5' (0x5335). The address
 142 field is interpreted as a 2-byte big-endian value and contains the
 143 count of S1, S2, and S3 records previously transmitted. There is no
 144 data field.</para></listitem>
 145 </varlistentry>
 146
 147 <varlistentry>
 148 <term>S7</term>
 149 <listitem><para>The type of record field is 'S7' (0x5337). The address
 150 field contains the starting execution address and is interpreted as a
 151 4-byte big-endian address. There is no data field.</para></listitem>
 152 </varlistentry>
 153
 154 <varlistentry>
 155 <term>S8</term>
 156 <listitem><para>The type of record field is 'S8' (0x5338). The address
 157 field contains the starting execution address and is interpreted as a
 158 3-byte big-endian address. There is no data field.</para></listitem>
 159 </varlistentry>
 160
 161 <varlistentry>
 162 <term>S9</term>
 163 <listitem><para>The type of record field is 'S9' (0x5339). The address
 164 field contains the starting execution address and is interpreted as a
 165 2-byte big-endian address. There is no data field.</para></listitem>
 166 </varlistentry>
 167 </variablelist>
 168
 169 </refsect1>
 170 <refsect1 id='example'><title>EXAMPLE</title>
 171
 172 <para>Shown below is a typical S-record format file.</para>
 173
 174 <programlisting>
 175   S00600004844521B
 176   S1130000285F245F2212226A000424290008237C2A
 177   S11300100002000800082629001853812341001813
 178   S113002041E900084E42234300182342000824A952
 179   S107003000144ED492
 180   S5030004F8
 181   S9030000FC
 182 </programlisting>
 183
 184 <para>The file consists of one S0 record, four S1 records, one S5
 185 record and an S9 record.</para>
 186
 187 <para>The S0 record is comprised as follows:</para>
 188
 189 <itemizedlist>
 190 <listitem><para>S0 S-record type S0, indicating it is a header
 191 record.</para></listitem>
 192
 193 <listitem><para>06 Hexadecimal 06 (decimal 6), indicating that six
 194 character pairs (or ASCII bytes) follow.</para></listitem>
 195
 196 <listitem><para>00 00 Four character 2-byte address field, zeroes in
 197 this example.</para></listitem>
 198
 199 <listitem><para>48 44 52 ASCII H, D, and R - "HDR".</para></listitem>
 200
 201 <listitem><para>1B The checksum.</para></listitem>
 202 </itemizedlist>
 203
 204 <para> The first S1 record is comprised as follows:</para>
 205
 206 <itemizedlist>
 207 <listitem><para>S1 S-record type S1, indicating it is a data record to
 208 be loaded at a 2-byte address.</para></listitem>
 209
 210 <listitem><para>13 Hexadecimal 13 (decimal 19), indicating that
 211 nineteen character pairs, representing a 2 byte address, 16 bytes of
 212 binary data, and a 1 byte checksum, follow.  </para></listitem>
 213
 214 <listitem><para>00 00 Four character 2-byte address field; hexidecimal
 215 address 0x0000, where the data which follows is to be
 216 loaded.</para></listitem>
 217
 218 <listitem><para>28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C
 219 Sixteen character pairs representing the actual binary data.
 220 </para></listitem>
 221
 222 <listitem><para>2A The checksum.</para></listitem>
 223 </itemizedlist>
 224
 225 <para>The second and third S1 records each contain 0x13 (19) character
 226 pairs and are ended with checksums of 13 and 52, respectively. The
 227 fourth S1 record contains 07 character pairs and has a checksum of
 228 92.</para>
 229
 230 <para>The S5 record is comprised as follows:</para>
 231
 232 <itemizedlist>
 233 <listitem><para>S5 S-record type S5, indicating it is a count record
 234 indicating the number of S1 records </para></listitem>
 235
 236 <listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three
 237 character pairs follow.</para></listitem>
 238
 239 <listitem><para>00 04 Hexadecimal 0004 (decimal 4), indicating that
 240 there are four data records previous to this record.</para></listitem>
 241
 242 <listitem><para>F8 The checksum.</para></listitem>
 243 </itemizedlist>
 244
 245
 246 <para>The S9 record is comprised as follows:</para>
 247
 248 <itemizedlist>
 249 <listitem><para>S9 S-record type S9, indicating it is a termination
 250 record.</para></listitem>
 251
 252 <listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three
 253 character pairs follow.  </para></listitem>
 254
 255 <listitem><para>00 00 The address field, hexadecimal 0 (decimal 0)
 256 indicating the starting execution address.  </para></listitem>
 257
 258 <listitem><para>FC The checksum.</para></listitem>
 259 </itemizedlist>
 260
 261 </refsect1>
 262 <refsect1 id='notes'><title>NOTES</title>
 263
 264 <itemizedlist>
 265   <listitem><para> There isn't any evidence that Motorola ever
 266     made use of the header information within the data field of the S0
 267     record, as described above. This may have been used by some third
 268     party vendors.</para></listitem>
 269
 270 <listitem><para>The Unix manual page on S-records is the only place that a
 271     78-byte limit on total record length or 64-byte limit on data
 272     length is documented. These values shouldn't be trusted for the
 273     general case.</para></listitem>
 274
 275 <listitem><para> The count field can have values in the range of 0x3
 276     (2 bytes of address + 1 byte checksum = 3, a not very useful
 277     record) to 0xff; this is the count of remaining character
 278     <emphasis>pairs</emphasis>, including checksum.  </para></listitem>
 279
 280 <listitem><para> If you write code to convert S-Records, you should
 281     always assume that a record can be as long as 514 (decimal)
 282     characters in length (255 * 2 = 510, plus 4 characters for the
 283     type and count fields), plus any terminating character(s).  That
 284     is, in establishing an input buffer in C, you would declare it to
 285     be an array of 515 chars, thus leaving room for the terminating
 286     null character.  </para></listitem>
 287 </itemizedlist>
 288
 289 </refsect1>
 290 <refsect1 id='see_also'><title>SEE ALSO</title>
 291 <para>
 292 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 293 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 294 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 295 <citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 296 <citerefentry><refentrytitle>gpsfake</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 297 <citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 298 </para>
 299 </refsect1>
 300
 301 <refsect1 id='maintainer'><title>AUTHOR</title>
 302
 303 <para>From an anonymous web page, itself claiming to have been derived
 304 from an old Unix manual page. Now maintained by the the GPSD
 305 project, which added endianness clarifications.
 306 There is a project page for <application>gpsd</application> <ulink
 307 url="http://gpsd.berlios.de/">here</ulink>.</para>
 308
 309 </refsect1>
 310 </refentry>