1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!-- 3This file is Copyright (c) 2010 by the GPSD project 4BSD 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 24binary data. This format is commonly used for firmware uploads to 25GPSes, industrial robots, and other kinds of microcontroller-driven 26hardware. It has several convenient properties, including 27inspectability, easy editing with any text editor, and checksumming 28for verification of transmission across noisy serial lines.</para> 29 30<para>An S-record file consists of a sequence of specially formatted 31ASCII character strings. An S-record will be less than or equal to 78 32bytes in length.</para> 33 34<para>The order of S-records within a file is of no significance and 35no 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 49describe the type of record (S0, S1, S2, S3, S5, S7, S8, or 50S9).</para></listitem> 51</varlistentry> 52 53<varlistentry> 54<term>count</term> 55<listitem><para>A char[2] field. These characters when paired and 56interpreted as a big-endian hexadecimal integer, display the count of remaining 57character 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 63interpreted as a big-endian hexadecimal integer, display the address 64at which the data field is to be loaded into memory. The length of the 65field depends on the number of bytes necessary to hold the address. A 662-byte address uses 4 characters, a 3-byte address uses 6 characters, 67and 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 73interpreted as hexadecimal values represent the memory loadable data 74or 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 80interpreted as a big-endian hexadecimal integer display the least 81significant byte of the ones complement of the sum of the byte values 82represented by the pairs of characters making up the count, the 83address, 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 88different record terminator(s) or delay characters are needed during 89transmission to the target system it is the responsibility of the 90transmitting 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 99is unused and will be filled with zeros (0x0000). The header 100information within the data field is divided into the following 101subfields.</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 111associated characters, when paired, represent one byte hexadecimal 112values in the case of the version and revision numbers, or represent 113the hexadecimal values of the ASCII characters comprising the module 114name 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 121field is interpreted as a 2-byte big-endian address. The data field is 122composed 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 128field is interpreted as a 3-byte big-endian address. The data field is 129composed 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 135field is interpreted as a 4-byte big-endian address. The data field is 136composed 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 142field is interpreted as a 2-byte big-endian value and contains the 143count of S1, S2, and S3 records previously transmitted. There is no 144data 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 150field contains the starting execution address and is interpreted as a 1514-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 157field contains the starting execution address and is interpreted as a 1583-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 164field contains the starting execution address and is interpreted as a 1652-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 185record 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 191record.</para></listitem> 192 193<listitem><para>06 Hexadecimal 06 (decimal 6), indicating that six 194character pairs (or ASCII bytes) follow.</para></listitem> 195 196<listitem><para>00 00 Four character 2-byte address field, zeroes in 197this 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 208be loaded at a 2-byte address.</para></listitem> 209 210<listitem><para>13 Hexadecimal 13 (decimal 19), indicating that 211nineteen character pairs, representing a 2 byte address, 16 bytes of 212binary data, and a 1 byte checksum, follow. </para></listitem> 213 214<listitem><para>00 00 Four character 2-byte address field; hexidecimal 215address 0x0000, where the data which follows is to be 216loaded.</para></listitem> 217 218<listitem><para>28 5F 24 5F 22 12 22 6A 00 04 24 29 00 08 23 7C 219Sixteen 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 226pairs and are ended with checksums of 13 and 52, respectively. The 227fourth S1 record contains 07 character pairs and has a checksum of 22892.</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 234indicating the number of S1 records </para></listitem> 235 236<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three 237character pairs follow.</para></listitem> 238 239<listitem><para>00 04 Hexadecimal 0004 (decimal 4), indicating that 240there 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 250record.</para></listitem> 251 252<listitem><para>03 Hexadecimal 03 (decimal 3), indicating that three 253character pairs follow. </para></listitem> 254 255<listitem><para>00 00 The address field, hexadecimal 0 (decimal 0) 256indicating 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>libgpsmm</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 304from an old Unix manual page. Now maintained by the GPSD 305project, which added endianness clarifications.</para> 306 307</refsect1> 308</refentry> 309