View source for SREC (file format)

'''Motorola S-record''' is a file format, created by [[Motorola]], that conveys binary information as [[hexadecimal|hex]] values in [[ASCII]] text form. This file format may also be known as '''SRECORD''', '''SREC''', '''S19''', '''S28''', '''S37'''. It is commonly used for programming [[flash memory]] in microcontrollers, [[EPROM]]s, [[EEPROM]]s, and other types of programmable logic devices. In a typical application, a compiler or assembler converts a program's source code (such as C or assembly language) to machine code and outputs it into a HEX file. The HEX file is then imported by a programmer to "burn" the machine code into [[non-volatile memory]], or is transferred to the target system for loading and execution.
==Overview==
[[File:Motorola SREC Chart.png|thumb|A quick reference chart for the Motorola SREC format. (Note that in the record example image the word "bytes" is alternatively used to specify characters.)
{| class="wikitable"
!Filename extension
|<code>.s19</code>, <code>.s28</code>, <code>.s37</code>, <code>.s</code>, <code>.s1</code>, <code>.s2</code>, <code>.s3</code>, <code>.sx</code>, <code>.srec</code>, <code>.exo</code>, <code>.mot</code>, <code>.mxt</code>
|-
!Developed by
|Motorola
|}
]]
===History===
The S-record format was created in the mid-1970s for the [[Motorola 6800]] processor. [[Programming tool|Software development tools]] for that and other [[embedded processor]]s would make executable code and data in the S-record format. PROM programmers would then read the S-record format and "burn" the data into the PROMs or EPROMs used in the embedded system.
===Other hex formats===
There are other ASCII encoding with a similar purpose. [[BPNF]], [[BHLF]], and [[B10F]] were early binary formats, but they are neither compact nor flexible. Hexadecimal formats are more compact because they represent 4 bits rather than 1 bit per character. Many, such as S-record, are more flexible because they include address information so they can specify just a portion of a PROM. [[Intel HEX]] format was often used with Intel processors. [[TekHex]] is another hex format that can include a symbol table for debugging.
==Format==
===Record structure===
{| class="wikitable" style="text-align:center"
|-
| style='background: #FFCCCC' | S || style='background: #FFCCCC' | Type || style='background: #CCFFCC' | Byte Count || style='background: #CCCCFF' | Address || style='background: #CCFFFF' | Data || style='background: #CCCCCC' | Checksum
|}
An SREC format file consists of a series of ASCII text records. The records have the following structure from left to right:
# ''Record start'' - each record begins with an uppercase letter "S" character (ASCII 0x53) which stands for "Start-of-Record".<ref>{{cite book |title=MCM6830L7 MIKBUG / MINIBUG ROM |author-first1=Mike |author-last1=Wiles |author-first2=Andre |author-last2=Felix |editor-first=Michael |editor-last=Holley |date=2000-10-21 |orig-year=1975 |type=Engineering note |id=Note 100 |publisher=[[Motorola Semiconductor Products, Inc.]] |url=http://www.swtpc.com/mholley/MP_A/MikbugEn100.pdf |access-date=2019-06-16 |url-status=dead |archive-url=https://web.archive.org/web/20190616115550/http://www.swtpc.com/mholley/MP_A/MikbugEn100.pdf |archive-date=2019-06-16}} (23 pages)</ref>
# ''Record type'' - single numeric digit "0" to "9", defining the type of record.
# ''Byte count'' - two hex digits, indicating the number of bytes (hex digit pairs) that follow in the rest of the record (address + data + checksum). This field has a minimum value of 3 for 16-bit address field plus 1 checksum byte, and a maximum value of 255 (0xFF).
# ''Address'' - four / six / eight hex digits as determined by the record type. The address bytes are arranged in [[Endianness|big endian]] format.
# ''Data'' - a sequence of 2''n'' hex digits, for ''n'' bytes of the data. For S1/S2/S3 records, a maximum of 32 bytes per record is typical since it will fit on an 80 character wide terminal screen, though 16 bytes would be easier to visually decode each byte at a specific address.
# ''Checksum'' - two hex digits, the [[least significant byte]] of [[ones' complement]] of the sum of the values represented by the two hex digit pairs for the byte count, address and data fields. See example section for a detailed checksum example.
===Text line terminators===
SREC records are separated by one or more ASCII line termination characters so that each record appears alone on a text line. This enhances legibility by visually [[delimiter|delimiting]] the records and it also provides padding between records that can be used to improve machine [[parsing]] efficiency.

Programs that create HEX records typically use line termination characters that conform to the conventions of their [[operating system]]s. For example, Linux programs use a single LF character ([[Newline|line feed]], 0x0A as ASCII character value) character to terminate lines, whereas Windows programs use a CR character ([[carriage return]], 0x0D as ASCII character value) followed by a LF character.
===Record types===
The following table describes 10 possible S-records. S4 is reserved and not currently defined. S6 was originally reserved but was later redefined.
{| class="wikitable"
|-
! Record<br>field
! Record<br>purpose
! Address<br>field
! Data<br>field
! Record<br>description
|-
| align="center" | ''S0''
| Header
| 16-bit<br>"0000"
| {{Na}}
| This record contains vendor specific ASCII text comment represented as a series of hex digit pairs. It is common to see the data for this record in the format of a [[null-terminated string]]. The text data can be anything including a mixture of the following information: file/module name, version/revision number, date/time, product name, vendor name, memory designator on PCB, copyright notice. It is common to see: 48 44 52 which is the ASCII H, D, and R - "HDR".<ref name="Tareski_2018"/>
|-
| align="center" | ''S1''
| Data
| 16-bit<br>Address
| {{Ya}}
| This record contains data that starts at the 16-bit address field.<ref name="SREC-Unix"/> This record is typically used for 8-bit microcontrollers, such as AVR, PIC, 8051, 68xx, 6502, 80xx, Z80. The number of bytes of data contained in this record is "Byte Count Field" minus 3 (that is, 2 bytes for "16-bit Address Field" and 1 byte for "Checksum Field").
|-
| align="center" | ''S2''
| Data
| 24-bit<br>Address
| {{Ya}}
| This record contains data that starts at a 24-bit address.<ref name="SREC-Unix"/> The number of bytes of data contained in this record is "Byte Count Field" minus 4 (that is, 3 bytes for "24-bit Address Field" and 1 byte for "Checksum Field").
|-
| align="center" | ''S3''
| Data
| 32-bit<br>Address
| {{Ya}}
| This record contains data that starts at a 32-bit address.<ref name="SREC-Unix"/> This record is typically used for 32-bit microcontrollers, such as ARM and 680x0. The number of bytes of data contained in this record is "Byte Count Field" minus 5 (that is, 4 bytes for "32-bit Address Field" and 1 byte for "Checksum Field").
|-
| align="center" | ''S4''
| Reserved
| {{n/a}}
| {{n/a}}
| This record is reserved.
|-
| align="center" | ''S5''
| Count
| 16-bit<br>Count
| {{Na}}
| This optional record contains a 16-bit count of S1/S2/S3 records.<ref name="SREC-Unix"/> This record is used if the record count is less than or equal to 65,535 (0xFFFF), otherwise S6 record would be used.
|-
| align="center" | ''S6''
| Count
| 24-bit<br>Count
| {{Na}}
| This optional record contains a 24-bit count of S1/S2/S3 records. This record is used if the record count is less than or equal to 16,777,215 (0xFFFFFF). If less than 65,536 (0x10000), then S5 record would be used. '''NOTE:''' This newer record is the most recent change (it may not be official).<ref name="SREC-Unix"/>
|-
| align="center" | ''S7''
| Start Address<br>(Termination)
| 32-bit<br>Address
| {{Na}}
| This record contains the starting execution location at a 32-bit address.<ref name="SREC-Unix"/><ref name="SREC-term"/> This is used to terminate a series of S3 records. If a SREC file is only used to program a memory device and the execution location is ignored, then an address of zero could be used.
|-
| align="center" | ''S8''
| Start Address<br>(Termination)
| 24-bit<br>Address
| {{Na}}
| This record contains the starting execution location at a 24-bit address.<ref name="SREC-Unix"/><ref name="SREC-term"/> This is used to terminate a series of S2 records. If a SREC file is only used to program a memory device and the execution location is ignored, then an address of zero could be used.
|-
| align="center" | ''S9''
| Start Address<br>(Termination)
| 16-bit<br>Address
| {{Na}}
| This record contains the starting execution location at a 16-bit address.<ref name="SREC-Unix"/><ref name="SREC-term"/> This is used to terminate a series of S1 records. If a SREC file is only used to program a memory device and the execution location is ignored, then an address of zero could be used.
|}
===Record order===
Although some Unix documentation states "the order of S-records within a file is of no significance and no particular order may be assumed",<ref name="SREC-Unix"/> in practice most software has ordered the SREC records. The typical record order starts with a (sometimes optional) S0 header record, continues with a sequence of one or more S1/S2/S3 data records, may have one optional S5/S6 count record, and ends with one appropriate S7/S8/S9 termination record.
; S19-style 16-bit address records
# S0
# S1 (one or more records)
# S5 (optional record)
# S9
; S28-style 24-bit address records
# S0
# S2 (one or more records)
# S5 (optional record)
# S8
; S37-style 32-bit address records
# S0
# S3 (one or more records)
# S5 (optional record)
# S7
===Limitations===
''Record length'' - Unix manual page documentation states, "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". The manual page further limits the number of characters in the data field to 64 (or 32 data bytes).<ref name="SREC-Unix"/> A record with an 8-hex-character address and 64 data characters would be 78 (2 + 2 + 8 + 64 + 2) characters long (this count ignores possible end-of-line or string termination characters). The file could be printed on an 80-character wide teleprinter. A note at the bottom of the manual page states, "This [manual page] 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".<ref name="SREC-Unix"/> If that limitation is ignored, the maximum length of an S-record is 514 characters: 2 for Record Type field + 2 for Byte Count field (whose value would be 0xFF=255) + 2 * 255 for Address, Data, and Checksum fields. Additional buffer space may be required for the line and string terminators. Using long line lengths has problems: "The Motorola S-record format definition permits up to 255 bytes of payload, or lines of 514 characters, plus the line termination. All EPROM programmers should have sufficiently large line buffers to cope with records this big. Few do."<ref name="sf"/>

''Data field'' - Some documentation recommends a maximum of 32 bytes of data (64 hex characters) in this field.<ref name="SREC-Unix"/> The minimum amount of data for S0/S1/S2/S3 records is zero. The maximum amount of data varies depending on the size of the address field. Since the Byte Count field can't be higher than 255 (0xFF), then the maximum number of bytes of data is calculated by 255 minus (1 byte for checksum field) minus (number of bytes in the address field). S0/S1 records support up to 252 bytes of data. S2 record supports up to 251 bytes of data. S3 record supports up to 250 bytes of data.

''Comments'' - The SREC file format does not support comments. Some software ignores all text lines that do not start with "S" and ignores all text after the checksum field; that extra text is sometimes used (incompatibly) for comments. For example, the CCS PIC compiler supports placing a ";" comment line at the top or bottom of an [[Intel HEX]] file, and its manuals states "some programmers (MPLAB in particular) do not like comments at the top of the hex file", which is why the compiler has the option of placing the comment at the bottom of the hex file.<ref name="CCS_2014"/>
==Examples==
; Color legend
{{legend inline| #FFCCCC |Record type}}
{{legend inline| #CCFFCC |Byte count}}
{{legend inline| #CCCCFF |Address}}
{{legend inline| #CCFFFF |Data}}
{{legend inline| #CCCCCC |Checksum}}
===Checksum calculation===
The following example record:
 {{SREC HEX|1|13|7AF0|0A0A0D00000000000000000000000000|61}}
is decoded to show how the checksum value is calculated as follows:
# Add: Add each byte 0x13 + 0x7A + 0xF0 + 0x0A + 0x0A + 0x0D + 0x00 + ... + 0x00 = 0x19E total.
# Mask: Keep the least significant byte of the total = 0x9E.
# Complement: Compute [[ones' complement]] of least significant byte = 0x61.
===16-bit memory address===
 {{SREC HEX|0|0F|0000|68656C6C6F20202020200000|3C}}
 {{SREC HEX|1|1F|0000|7C0802A6900100049421FFF07C6C1B787C8C23783C60000038630000|26}}
 {{SREC HEX|1|1F|001C|4BFFFFE5398000007D83637880010014382100107C0803A64E800020|E9}}
 {{SREC HEX|1|11|0038|48656C6C6F20776F726C642E0A00|42}}
 {{SREC HEX|5|03|0003||F9}}
 {{SREC HEX|9|03|0000||FC}}
==See also==
* [[Binary-to-text encoding]], a survey and comparison of encoding algorithms
* [[Intel hex format]]
* [[MOS Technology file format]]
* [[Tektronix hex format]]
==References==
{{Reflist|refs=
<ref name="Tareski_2018">{{Cite web |title=Motorola S-record description |author-last=Tareski |author-first=Val |website=www.amelek.gda.pl |url=http://www.amelek.gda.pl/avr/uisp/srecord.htm |access-date=2018-06-26}}</ref>
<ref name="SREC-Unix">{{cite web |title=Motorola S-records from Unix man pages |url=http://www.amelek.gda.pl/avr/uisp/srecord.htm |access-date=2014-06-30}}</ref>
<ref name="SREC-term">{{cite book |title=M68000 Family Programmer's Reference Manual |version=Revision 1 |publisher=[[Motorola]] ([[Freescale]]) |date=1992 |pages=C-1–C-5 |chapter=Appendix C |isbn=978-0-13723289-5 |url=http://www.freescale.com/files/archives/doc/ref_manual/M68000PRM.pdf}}</ref>
<ref name="sf">{{cite web |title=srec_examples |work=sourceforge.net |url=http://srecord.sourceforge.net/man/man1/srec_examples.html}}</ref>
<ref name="CCS_2014">{{citation |title=CCS Compiler Reference Manual PCB/PCM/PCH |publisher=[[Custom Computer Services, Inc.]] |date=May 2014 |page=107 |url=http://www.ccsinfo.com/downloads/ccs_c_manual.pdf |access-date=2015-02-08}}</ref>
<ref name="Xilinx_2010_EXO">{{cite web |title=AR#476 PROMGen - Description of PROM/EEPROM file formats: MCS, EXO, HEX, and others |at=Motorola EXORmacs - File Format Code 87 |date=2010-03-08 |publisher=[[Xilinx]] |url=https://www.xilinx.com/support/answers/476.html |access-date=2020-03-03 |url-status=live |archive-url=https://web.archive.org/web/20200303085851/https://www.xilinx.com/support/answers/476.html |archive-date=2020-03-03}}</ref>
}}
== External links ==
* [http://srecord.sourceforge.net/ SRecord] is a collection of tools for manipulating SREC format files.
* [http://www.keil.com/download/docs/4.asp BIN2MOT], BINARY to Motorola S-Record file converter utility.
* [https://github.com/BigWinston/SRecordizer/wiki SRecordizer] is a tool for viewing, editing, and error checking S19 format files.
* [https://pypi.python.org/pypi/bincopy bincopy] is a Python package for manipulating SREC format files.
* [https://github.com/arkku/srec kk_srec] is a C library and program for reading the SREC format.
{{DEFAULTSORT:Srec (File Format)}}
[[Category:Binary-to-text encoding formats]]
[[Category:Embedded systems]]
[[Category:Computer file formats]]