What Is SRecord?
SRecord is a free, open-source collection of powerful command-line tools written in C++ for reading, writing, converting, manipulating, filtering, and inspecting EPROM load files – the hexadecimal and binary file formats used to program microcontrollers, FPGAs, embedded processors, and erasable programmable read-only memory (EPROM) devices.
At its core, SRecord solves a universal problem in embedded development: the world has dozens of incompatible file formats for describing memory images, and every toolchain, EPROM programmer, and microcontroller vendor has its own preference. Motorola created the S-Record format. Intel created the Intel Hex format. Texas Instruments, Atmel, Tektronix, Xilinx, Altera, and dozens of others all invented their own variations. SRecord understands nearly every one of them and can convert freely between all of them.
The package was created by Peter Miller and has been continuously improved since its first public release in March 1998, growing from a small utility into a comprehensive toolkit covering over 40 distinct file formats with an extensive set of data transformation filters.
Why SRecord Exists – The Origin Story
Peter Miller wrote SRecord out of practical necessity. In his own words from the reference manual:
“I wrote SRecord because when I was looking for programs to manipulate EPROM load files, I could not find very many. The ones that I could find only did a few of the things I needed.”
This is the fundamental truth about embedded development tooling: most hex file utilities are narrow, single-purpose tools. They convert one format to one other format, or they split a file, or they compute a checksum. Very few tools treat EPROM load file manipulation as a first-class problem deserving a general, composable solution.
SRecord was designed from the ground up with a different philosophy. It uses C++ polymorphism to provide file format flexibility. Every input format is an interchangeable module. Every transformation is a filter that can be chained with other filters. The result is that with a single SRecord command you can simultaneously read a file, crop it, fill its gaps, apply a CRC, offset its addresses, and write it back in a completely different format.
Installing and Building SRecord
System Requirements
Before building SRecord, you need the following dependencies installed:
Boost Library – SRecord uses the C++ Boost library for various utilities. On package-based systems, install libboost-devel or the equivalent package. The Boost library is available at http://boost.org/.
Libgcrypt Library – The GNU Crypt library is required for cryptographic hash filters (MD5, SHA1, SHA256, etc.). Install libgcrypt-devel or equivalent. Available through the FSF directory.
GNU Libtool – Required for building shared libraries across different systems. Available at http://www.gnu.org/software/libtool/.
GNU Groff – Optional but recommended. Used to build the documentation in PostScript and DVI formats. Version 1.14 or later is required.
GCC/G++ – The GNU C++ compiler is required. SRecord was developed specifically with GCC and GNU C++ libraries.
Space Requirements
You will need approximately 3MB of disk space to unpack and build the full SRecord package.
Configuration and Build Steps
SRecord uses the standard GNU autoconf build system. The process is straightforward:
# Step 1: Run configure to detect your system
./configure
# Step 2: Build the binaries
make
# Step 3: Run the test suite to verify your build
make sure
# Step 4: Install (defaults to /usr/local)
make installIf you want to install to a custom location, pass a prefix to configure:
./configure --prefix=/opt/srecord
make
make installAfter a successful build, you will find three executables in the bin directory: srec_cat, srec_cmp, and srec_info.
Building on Windows
SRecord can be built on Microsoft Windows platforms using either the Cygwin environment (www.cygwin.com) or the DJGPP environment (www.delorie.com/djgpp). Both provide the Unix compatibility layer needed to run SRecord’s build system. The build procedure is identical to the Linux/Unix procedure once the compatibility environment is set up.
If you want native Windows binaries using Cygwin (executables that run outside of Cygwin), you need to add -mno-cygwin to the CXX compiler line in the Makefile after running ./configure and before running make.
DJGPP always produces native binaries by default.
Testing Your Build
The SRecord package includes a comprehensive test suite that covers all file formats and filters. To run it:
make sureIf the build and configuration were successful, the output ends with:
Passed All TestsThe tests take varying amounts of time depending on your CPU. Most are fast, with a couple of slower integration tests.
Getting Help
If you encounter problems, post to the official mailing list: srecord-users@lists.sourceforge.net. When reporting issues, always include the exact version output from:
srec_cat --version
</code></pre>
<!-- /wp:code -->
<!-- wp:heading -->
<h2 class="wp-block-heading">The Three Core Tools</h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>SRecord is built around three primary programs. Every tool understands every file format and every filter.</p>
<!-- /wp:paragraph -->
<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">srec_cat - The Swiss Army Knife</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p><code>srec_cat</code> is the primary workhorse of the SRecord package. The name comes from the Unix <code>cat</code> (catenate) command, because its fundamental purpose is to join EPROM load files together. However, through its filter system, it does far more than concatenation. It reads one or more input files, applies any number of transformation filters, and writes the result to an output file in any supported format.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>The basic syntax is:</p>
<!-- /wp:paragraph -->
<!-- wp:code -->
<pre class="wp-block-code"><code>```
srec_cat [option...] filename...
</code></pre>
<!-- /wp:code -->
<!-- wp:paragraph -->
<p><strong>How data ordering works:</strong> The data from input files is not written immediately to the output. Instead, it is stored in memory until the complete EPROM image has been assembled. Data is then written to the output in ascending address order. The original ordering of data in the input is not preserved.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p><strong>Data conflict detection:</strong> Because all input data is held in memory simultaneously, <code>srec_cat</code> can detect when two input files try to write different values to the same address. A warning is issued for redundant writes (same value to the same address), and a fatal error is issued for contradictory writes (different values to the same address). This catches bugs like overlapping linker sections before they reach an EPROM.</p>
<!-- /wp:paragraph -->
<!-- wp:heading {"level":3} -->
<h3 class="wp-block-heading">srec_cmp - The Comparator</h3>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p><code>srec_cmp</code> compares two EPROM load files for equality, regardless of the order records appear within each file. This is essential because textual comparison tools like <code>diff</code> are useless for EPROM load files - identical data can appear in completely different orders depending on which tool generated the file.</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>The basic syntax is:</p>
<!-- /wp:paragraph -->
<!-- wp:code -->
<pre class="wp-block-code"><code>```
srec_cmp [option...] filename...A common use of `srec_cmp` is signature verification:
srec_cmp signature image -crop -within signatureThis verifies that the regions in `image` that correspond to the address range of `signature` match exactly.
srec_info – The Inspector
`srec_info` prints summary information about EPROM load files without modifying them. It tells you the file format, any header text present, the execution start address if any, and the complete set of address ranges containing data.
The basic syntax is:
srec_info [option...] filename...
A typical `srec_info` output looks like this:
Format: Motorola S-Record
Header: "http://srecord.sourceforge.net/"
Execution Start Address: 00000000
Data: 0000 - 0122
0456 - 0FFF
This is invaluable for understanding an unknown file. It also supports the `-guess` option to auto-detect the file format.All Supported File Formats – Deep Dive
SRecord’s comprehensive format support is one of its defining strengths. Here is every format, with details on read/write support and key characteristics.
Ascii-Hex (Read and Write)
Also known as the Ascii-Space-Hex or Ascii-Hex-Space format. Files begin with a start-of-text character (STX, 0x02). Each data byte is represented as two hexadecimal characters followed by a space or other execution character. Addresses are set using $Annnn, sequences. The file ends with an end-of-text character (ETX, 0x03). Binary data expands by approximately 3.0x in this format.
Variant forms include ascii-hex-percent (uses % as execution character), ascii-hex-comma (uses `,` or `'`), and others.
ASM (Write Only)
Produces a series of assembler DB statements containing the data. Useful for embedding binary data directly into assembler source code. The format supports multiple output styles including dot-style pseudo-ops, hexadecimal output, section-style output, A430 compliance (for IAR Embedded Workbench), and CL430 compliance (for Code Composer Essentials). This format cannot be read back in.
Atmel Generic (Read and Write)
The output format of the Atmel AVR assembler. Contains two columns: a 24-bit word address and 16-bit word data, separated by a colon. By default treated as little-endian data. Binary data expands by approximately 6.0x.
BASIC (Write Only)
Produces a series of BASIC DATA statements containing the data. Useful for embedding binary data in BASIC programs. Cannot be read back in.
Binary (Read and Write)
Raw binary files with no encoding overhead. Data is placed at the byte offset specified by addresses in the hex file. When writing binary files, holes in the data (gaps between address ranges) are filled with zero bytes. When reading binary files, all bytes including zeroes are treated as data starting at address zero (use the `-offset` filter to relocate the data in memory).
Critical warning: A program at the top of 32-bit address space (e.g., at 0xFFF00000) produces a 4GB binary file when written to disk because all the leading zero bytes are included. Always use the `-offset` filter to cancel this effect.
B-Record (Read and Write)
Files in Freescale MC68EZ328 Dragonball bootstrap b-record format. Used with the bootstrap loader of Freescale Dragonball processors.
C Array (Write Only)
Writes a C array definition containing the data. The array can be named, declared as `const` (the default, for placement in read-only memory sections), and optionally accompanied by a generated header file. A compressed variant omits padding for memory gaps. This format cannot be read back in.
COE – Xilinx Coefficient File Format (Write Only)
The `.coe` file format used by Xilinx FPGA tools. Supported for writing only.
Cosmac (Read and Write)
The RCA Cosmac Elf format, used with the RCA 1802 microprocessor, one of the earliest microprocessors. Supported for both reading and writing.
DEC Binary – XXDP (Read and Write)
The DEC Binary (XXDP) format used with Digital Equipment Corporation systems. Supported for both reading and writing, with correct handling on Windows machines.
Elektor Monitor – EMON52 (Read and Write)
The EMON52 format used by the Elektor Monitor programming environment.
Fairchild Fairbug (Read and Write)
The Fairchild Fairbug format, an older format from Fairchild Semiconductor.
Formatted Binary (Read and Write)
structured binary format distinct from raw binary.
Four Packed Code – FPC (Read and Write)
The FPC format, a compact hex encoding.
FORTH (Write Only)
Writes a FORTH input file where each line includes a byte value, an address, and a store command. Supports both RAM mode (using C!) and EEPROM mode (using EEC!)
Hexdump (Read and Write)
A human-readable hexadecimal dump format showing addresses, hex values, and ASCII equivalents. Can be written for inspection purposes and partially read back in, though the ASCII column can interfere with reading.
IDT/sim (Read and Write)
The Integrated Device Technology system integration manager (IDT/sim) binary format. Supported from SRecord 1.58 onwards.
Intel Hex (Read and Write)
The Intel hexadecimal format, also known as Intel MCS-86 Object format or IHEX. This is one of the two most widely used hex formats in embedded development, alongside Motorola S-Record. SRecord supports all three addressing variants:
- i8hex – 16-bit addressing (use
-address-length=2) - i16hex – 20-bit extended segment addressing (use
-address-length=3) - i32hex – 32-bit linear addressing (the default)
The format supports up to 255 bytes of payload per record.
Intel AOMF – Absolute Object Module Format (Read and Write)
A subset of the Intel 8051 OMF (Object Module Format). Absolute object files contain one module only, with absolute (non-relocatable) addressing. Records include module header (type 0x02), content records (type 0x06), and module end (type 0x04).
Intel 16 – INHX16 (Read and Write)
The Intel hexadecimal 16 format, also known as INHX16. Used by various PIC programmers. Identical to Intel Hex in appearance, but byte counts and addresses refer to 16-bit words rather than bytes.
Lattice Memory Initialization Format – MEM (Write Only)
The Memory Initialization Format (.mem) by Lattice Semiconductor. Supported for writing only from SRecord 1.61 onwards. Lines break every specified number of bits.
Logisim (Read and Write)
The format used by the Logisim digital logic simulator. Supported from SRecord 1.63 onwards.
MIF – Memory Initialization File (Read and Write)
The Memory Initialization File format created by Altera (now Intel) for initializing block RAM in FPGAs. Supported from SRecord 1.47 onwards. Width can be specified on the command line.
MIPS Flash (Read and Write)
The MIPS Flash file format. Supported in both big-endian and little-endian variants from SRecord 1.58 onwards.
MOS Technology (Read and Write)
The MOS Technology hexadecimal format, historically used with MOS Technology processors including the famous 6502.
Motorola S-Record (Read and Write)
The Motorola hexadecimal S-Record format is the default input and output format for all SRecord tools. It is also known as the Exorciser, Exormacs, or Exormax format.
ecords begin with ‘S’ followed by a digit indicating the record type:
- S0 – Header record (file identification)
- S1 – Data record with 16-bit address
- S2 – Data record with 24-bit address
- S3 – Data record with 32-bit address
- S4 – Symbol record (uncommon)
- S5 – Record count record
- S6 – 24-bit data count record
- S7 – End record for S3 data (execution start address, 32-bit)
- S8 – End record for S2 data (execution start address, 24-bit)
- S9 – End record for S1 data (execution start address, 16-bit)
SRecord automatically selects the smallest address length that accommodates the data. Use -address-length=3 to force S28 (24-bit), or -address-length=4 to force S37 (32-bit). The format supports up to 255 bytes of payload per record.
MsBin – Windows CE Binary Image Data Format (Read and Write)
The Windows CE Binary Image Data Format. Supported from SRecord 1.53 onwards.
Needham Electronics ASCII (Read and Write)
The format used by Needham Electronics EPROM programmers.
Ohio Scientific – OS65V (Read and Write)
The Ohio Scientific hexadecimal format, used with Ohio Scientific computers that used the 6502 processor.
PPB – Stag PROM Programmer Binary (Read and Write)
The binary format used by Stag PROM programmers.
PPX – Stag PROM Programmer Hexadecimal (Read and Write)
The hexadecimal format used by Stag PROM programmers.
Signetics (Read and Write)
The format used by Signetics (later acquired by Philips/NXP)
SPASM (Read and Write)
The format used by a variety of PIC programmers. Supported in both big-endian and little-endian variants.
Spectrum (Read and Write)
The Spectrum format.
Stewie (Read and Write)
An undocumented format loosely based on the Motorola S-Record format, apparently used in mobile phones.
Tektronix (Read and Write)
The Tektronix hexadecimal format.
Tektronix Extended (Read and Write)
The extended version of the Tektronix hexadecimal format, supporting larger address spaces.
Texas Instruments Tagged – TI-Tagged / TI-SDSMAC (Read and Write)
The Texas Instruments Tagged format, also known as TI-Tagged or TI-SDSMAC. Supported for both 8-bit and 16-bit variants.
Texas Instruments TI-TXT (Read and Write)
The TI-TXT format used with the bootstrap loader of the Texas Instruments MSP430 family of processors. The 16-bit address format ideal for embedded systems programming.
TRS-80 (Read and Write)
The Radio Shack TRS-80 object file format, a relic of the early microcomputer era.
VHDL (Write Only)
Writes a VHDL file suitable for ROM initialization in FPGA designs. Supports configurable bytes-per-word and ROM array name. Output only.
Verilog VMEM (Read and Write)
A Verilog memory initialization file suitable for loading with $readmemh(). Supports memory widths of 8, 16, 32, 64, and 128 bits. Defaults to 32-bit if unspecified.
Wilson (Read and Write)
A mystery format added for a mysterious type of EPROM writer. The name and origin are obscure.
Input Filters: The Real Power of SRecord
The filter system is what elevates SRecord from a format converter to a complete EPROM image manipulation pipeline. Filters can be applied to any input file, multiple filters can be chained together on the same input, and different filters can be applied to different inputs in the same command.
Address Manipulation Filters
**Offset Filter (`-offset`)** - Moves all data addresses up or down in memory. Positive values move data higher, negative values move lower. This is essential for producing binary output that starts at address zero, or for relocating code sections:
```bash
# Move data that starts at 0x200000 down to zero
srec_cat infile -offset -0x200000 -o outfile
```
**Crop Filter (`-crop`)** - Selects only the data within a specified address range and discards the rest. The lower bound is inclusive, the upper bound is exclusive. Multiple address ranges can be specified in a single crop:
```bash
# Keep only data from 0x200000 to 0x300000
srec_cat infile -crop 0x200000 0x300000 -o outfile
# Keep two non-contiguous ranges
srec_cat infile -crop 0x100 0x200 0x1000 0x1200 -o outfile
```
**Exclude Filter (`-exclude`)** - The logical complement of crop. Keeps all data except the specified address range.
**Split Filter (`-split`)** - Splits an image for wide data buses or memory striping. Essential when programming two 8-bit EPROMs to create a 16-bit memory bus:
```bash
# Split firmware into even and odd byte images
srec_cat firmware.hex -split 2 0 -o firmware.even.hex
srec_cat firmware.hex -split 2 1 -o firmware.odd.hex
```
**Unsplit Filter (`-unsplit`)** - Reverses the effects of the split filter, reconstructing the original image from stripes.Fill and Hole Filters
**Fill Filter (`-fill`)** - Fills any gaps (holes) in the data with a specified byte value. This is critical before computing checksums or CRCs, because holes produce different results than filled memory:
```bash
# Fill all holes with 0xFF
srec_cat infile -fill 0xFF 0x200000 0x300000 -o outfile
# Fill only the gaps within the data's own extent
srec_cat infile -fill 0xFF -over infile -o outfile
```
**Unfill Filter (`-unfill`)** - Creates holes in data where a specified byte value (commonly 0xFF) appears. Used to remove the 0xFF fill that appears when reading blank EPROM regions:
```bash
# Remove all 0xFF bytes
srec_cat infile -unfill 0xFF -o outfile
# Only remove runs of 5 or more 0xFF bytes
srec_cat infile -unfill 0xFF 5 -o outfile
```
**Random Fill Filter (`-random-fill`)** - Fills holes with random byte values instead of a constant. Useful for obfuscating the boundaries of real code in an EPROM image.Bitwise Data Filters
**AND Filter** - Bitwise AND of every data byte with a mask. Clears bits.
**OR Filter** - Bitwise OR of every data byte with a mask. Sets bits.
**XOR Filter** - Bitwise exclusive OR of every data byte with a mask. Toggles bits. Useful for simple obfuscation.
**NOT Filter** - Bitwise NOT of every data byte. Inverts all bits.
**Bit Reverse Filter (`-bit-reverse`)** - Reverses the order of bits within each byte.
**Byte Swap Filter (`-byte-swap`)** - Swaps pairs of bytes. Default swaps adjacent bytes (16-bit pairs). Can be configured for 32-bit or 64-bit swaps for endianness conversion.Checksum and CRC Filters
These filters compute a checksum or CRC over the data and insert the result at a specified memory address. They are the cornerstone of EPROM integrity verification in embedded systems.
**Checksum Negative Big/Little Endian** - Inserts the two's complement negative checksum. When summed along with the original data, the total equals zero - a classic EPROM integrity check.
**Checksum Bitnot Big/Little Endian** - Inserts the one's complement checksum. When summed with the data, the total equals all-ones-bits.
**Checksum Positive Big/Little Endian** - Inserts the simple additive checksum.
**CRC16 Big/Little Endian** - Inserts an industry-standard 16-bit CRC. Supports multiple polynomials by name or value (CCITT, XMODEM, IBM, ANSI, T10-DIF, DNP, DECT and more), selectable bit order (most-to-least or least-to-most), and augment/no-augment control.
**CRC32 Big/Little Endian** - Inserts an industry-standard 32-bit CRC. Supports CCITT (default, all-one-bits seed) and XMODEM (all-zero-bits seed) variants.
**STM32 CRC** - A specialized CRC32 variant matching the hardware CRC unit in STM32 ARM microcontrollers, which uses a different polynomial and operates word-by-word rather than byte-by-byte.
**Adler 16/32 Big/Little Endian** - Inserts an Adler checksum, a faster alternative to CRC suitable for many embedded integrity checks.
**Fletcher 16/32 Big/Little Endian** - Inserts a Fletcher checksum. The 16-bit variant supports configurable seed values and a "desired answer" feature for engineering the checksum to a specific value.Length, Minimum, and Maximum Filters
These filters insert calculated metadata about the data into the data itself - useful for embedded firmware that needs to know its own extent.
**Length Filter** - Inserts the total data length at a specified address.
**Minimum Address Filter** - Inserts the lowest address occupied by data.
**Maximum Address Filter** - Inserts the highest address occupied by data plus one.
Exclusive variants (`-exclusive-minimum`, `-exclusive-maximum`, `-exclusive-length`) exclude the filter's output address from their own calculation.Cryptographic Hash Filters
SRecord can insert full cryptographic hashes directly into EPROM images at specified addresses, enabling strong integrity verification in security-sensitive applications. Supported algorithms include MD5, RipeMD-160, SHA1, SHA224, SHA256, SHA384, SHA512, and Whirlpool/TIGER.
These require the Libgcrypt library to be installed.
Address Range Expressions
A powerful feature of SRecord is that most places where an address range is expected, you can compute it rather than hard-code it. This allows commands like:
```bash
# Offset data to start at zero without knowing the current start address
srec_cat infile -offset - -minimum-addr infile -o outfile
# Place one file immediately after another without knowing the first file's end
srec_cat infile1 infile2 -offset -maximum-addr infile1 -o outfile
```
Address ranges also support set operations: union (`-union`), intersection (`-intersect`), and difference (`-difference`). Calculated values can be rounded down, up, or to the nearest multiple with `-round-down`, `-round-up`, and `-round-nearest`.Complete srec_cat Command Reference
Output Format Options
The output format is specified after `-o outputfile` as a format flag:
| Format Flag | Description |
|---|---|
| `-Absolute_Object_Module_Format` | Intel AOMF |
| `-Ascii_Hex` | Ascii-Hex |
| `-ASM [prefix]` | Assembler DB statements |
| `-Atmel_Generic` | Atmel AVR generic |
| `-BASic` | BASIC DATA statements |
| `-B-Record` | Freescale Dragonball |
| `-Binary` | Raw binary |
| `-C-Array [id]` | C array definition |
| `-COE` | Xilinx .coe coefficient file |
| `-COsmac` | RCA Cosmac Elf |
| `-Dec_Binary` | DEC Binary XXDP |
| `-Elektor_Monitor52` | EMON52 |
| `-FAIrchild` | Fairchild Fairbug |
| `-Fast_Load` | LSI Logic Fast Load |
| `-Formatted_Binary` | Formatted Binary |
| `-FORTH` | FORTH input file |
| `-Four_Packed_Code` | FPC |
| `-HEX_Dump` | Human-readable hex dump |
| `-IDT` | IDT/sim binary |
| `-Intel` | Intel Hex (i32hex default) |
| `-Intel_HeX_16` | INHX16 |
| `-Lattice_Memory_Initialization_Format` | Lattice .mem |
| `-LOGisim` | Logisim |
| `-Memory_Initialization_File` | Altera MIF |
| `-Mips_Flash_Big_Endian` | MIPS Flash BE |
| `-Mips_Flash_Little_Endian` | MIPS Flash LE |
| `-MOS_Technologies` | MOS Technology |
| `-Motorola [width]` | Motorola S-Record (default) |
| `-MsBin` | Windows CE Binary |
| `-Needham_Hexadecimal` | Needham Electronics |
| `-Ohio_Scientific` | OS65V |
| `-PPB` | Stag Programmer Binary |
| `-PPX` | Stag Programmer Hex |
| `-SIGnetics` | Signetics |
| `-SPAsm` | SPASM (PIC) |
| `-STewie` | Stewie |
| `-Tektronix` | Tektronix |
| `-Tektronix_Extended` | Tektronix Extended |
| `-Texas_Instruments_Tagged` | TI-Tagged |
| `-Texas_Instruments_Tagged_16` | TI-SDSMAC 320 |
| `-Texas_Instruments_TeXT` | TI-TXT MSP430 |
| `-TRS80` | TRS-80 |
| `-VHdl` | VHDL |
| `-VMem [width]` | Verilog VMEM |
| `-WILson` | Wilson |Key Output Control Options
**`-Address_Length number`** - Sets the minimum number of bytes used to represent addresses in the output. Useful for forcing a specific Motorola or Intel hex variant.
**`-Line_Length number`** - Limits output line length. Defaults to under 80 characters. Important for EPROM programmers with small line buffers.
**`-Output_Block_Size number`** - Sets the exact number of data bytes per output record.
**`-Output_Block_Packing`** - Packs output records so SRecord's internal block boundaries are not visible in the output.
**`-Data_Only`** - Suppresses all output except data records. Equivalent to disabling header, data count, execution start address, and footer.
**`-HEAder string`** - Sets the header comment in formats that support it. Supports URL encoding (e.g., `%00` for NUL) for binary data in headers.
**`-Execution_Start_Address number`** - Sets the execution start address - the address a monitor jumps to after loading is complete. This is distinct from the data start address.
**`-IGnore_Checksums`** - Disables checksum validation on input. Checksums are still parsed but not checked. Output always has correct checksums.
**`-Line_Termination style`** - Forces a specific line termination style (CRLF for Windows, NL for Unix, CR for old Macintosh).
**`-CRLF`** - Shorthand for `-line-termination=crlf`.
**`@filename`** - Reads additional command-line arguments from a text file. Essential for working around operating systems with short command-line limits. Supports `#` comments.Complete srec_cmp Command Reference
`srec_cmp` accepts all the same input format and filter options as `srec_cat`. Its unique options are:
**`-Verbose`** - Provides detailed information about exactly where and how two files differ. Note that this can produce voluminous output.
**`-redundant-bytes=value`** - Controls behavior when redundant byte settings are detected: `ignore`, `warning` (default), or `error`.
**`-contradictory-bytes=value`** - Controls behavior when contradictory byte settings are detected: `ignore`, `warning`, or `error` (default).
**`-IGnore_Checksums`** - Same as in `srec_cat`.
**`-Enable_Sequence_Warnings` / `-Disable_Sequence_Warnings`** - Controls warnings about non-ascending record order.Complete srec_info Command Reference
`srec_info` accepts the same input format and filter options as `srec_cat`. Its output shows:
- **Format** - The detected or specified file format
- **Header** - Any header text embedded in the file
- **Execution Start Address** - If present
- **Data** - The address ranges containing data, with inclusive upper bounds
The `-guess` option auto-detects the file format. It is slower than specifying a format explicitly because it may scan the file multiple times.Practical Examples – End to End
Converting Between Formats
The simplest use of `srec_cat` is format conversion. Because the default input format is Motorola S-Record and you specify the output format explicitly:
# Intel Hex to Motorola S-Record
srec_cat intel-file -intel -o srec-file
# Motorola S-Record to Intel Hex
srec_cat srec-file -o intel-file -intel
# Force 32-bit addresses on Motorola output (S37 format)
srec_cat input.srec -o output.srec -address-length=4
# Force i16hex (20-bit) Intel output
srec_cat input.hex -o output-16bit.hex -intel -address-length=3Working with Binary Files
# Convert hex to raw binary
srec_cat firmware.hex -o firmware.bin -binary
# Convert binary to Motorola S-Record, starting at address 0x10000
srec_cat firmware.bin -binary -offset 0x10000 -o firmware.srec
# Read hex, cancel the memory offset, write binary starting at zero
srec_cat firmware.hex -offset --minimum-addr firmware.hex -o firmware.bin -binary
# Remove runs of zero bytes when reading a binary dump
srec_cat dump.bin -binary -unfill 0x00 512 -o cleaned.srecThe shared library is licensed under the GNU Lesser General Public License (LGPL) version 3, which is less restrictive than the GPL used for the command-line tools. This allows the library to be used in proprietary applications, subject to the LGPL’s conditions.
Full Doxygen-generated API documentation is available at http://srecord.sourceforge.net/srecord/index.html.
How to Add a New File Format
SRecord is designed to be extended. The author actively accepts patches for new formats. To contribute a new format, you need to create the following files:
**Source files to create:**
- `srecord/output/file/name.cc` — How to write the new format
- `srecord/output/file/name.h` — Class declaration for the writer
- `srecord/input/file/name.cc` — How to read the new format
- `srecord/input/file/name.h` — Class declaration for the reader
- `man/man5/srec_name.5` — Man page describing the format
**Source files to modify:**
- `srecord/srecord.h` — Add the new include
- `etc/README.man` — Mention the new format
- `srecord/arglex/tool.h` — Add command-line argument enum
- `srecord/arglex/tool.cc` — Add argument parsing
- `srecord/arglex/tool/input.cc` — Input format parsing
- `srecord/arglex/tool/output.cc` — Output format parsing
- `srecord/input/file/guess.cc` — Auto-detection
- `man/man1/srec_input.1` — Document input format
- `man/man1/srec_cat.1` — Document output format
**Key implementation principles:**- Be liberal in what you accept – Treat mandatory fields as optional where practical. Accept the widest possible interpretation of valid input. Always check checksums unless
-ignore-checksumsis set. - Be conservative in what you produce – Output must always strictly conform to the format specification. Checksums must always be correct.
- Round trip fidelity – What went in must come out. The
srec_cmptool should find no differences between original data and data that has been written and read back. - Handle holes gracefully – Do not fill holes in data unless explicitly required by the format.
A standard new format takes approximately six hours to implement and test. Contract work is available at AU$100 per hour.
How to Add a New Filter
New filters follow a similar pattern to new formats. The files to create are:
- `srecord/input/filter/name.cc` - Filter implementation
- `srecord/input/filter/name.h` - Class declaration
If the filter requires all data before it can begin (like checksum filters), derive from `srec_input_filter_message` instead of the base filter class.Key implementation principles:
- Cope with data that has holes, records out of order, and records not aligned to any boundary
- Preserve the absence of headers and execution start address records from the input
- Do not fill holes unless you are writing a fill filter
- If the filter is self-inverse (like byte-swap) or has a matching inverse (like split/unsplit), write a test to verify this property
A standard new filter takes approximately three hours to implement and test.
Version History and Evolution
SRecord has been actively maintained from 1998 to at least 2014 (version 1.63) and continues under community maintenance. The version history illustrates both the depth of the project and the breadth of its user community:
**Version 1.1 (1998-Mar-22)** - First public release.
**Version 1.2 (1998-Nov-04)** - Added Intel hex full 32-bit support and Tektronix format. Added split/unsplit filter.
**Version 1.3 (1999-May-12)** - Added AND/OR/XOR bitwise filters.
**Version 1.4 (2000-Jan-13)** - CRLF handling for files generated on PC and used on Unix.
**Version 1.5 (2000-Mar-06)** - Added MOS Technologies, Tektronix Extended, Texas Instruments Tagged, Ascii-Hex formats. Added byte-swap filter and format auto-detection.
**Version 1.6 (2000-Dec-03)** - Added CRC16 and CRC32 filters. Added VHDL output. Added negative and positive checksum filters.
**Version 1.7 (2001-Mar-19)** - PDF documentation format. Added `-address-length` option.
**Version 1.8 (2001-Apr-20)** - Added unfill filter and bitwise NOT filter.
**Version 1.9 (2001-Nov-27)** - Added DEC Binary, EMON52, Signetics, FPC, Atmel Generic, SPASM formats.
**Version 1.10 (2002-Jun-14)** - LSI Logic Fast Load format. Motorola S6 records.
**Version 1.12 (2002-Dec-06)** - Dynamic address calculation in command-line expressions.
**Version 1.13 (2003-Feb-05)** - Added ASM and BASIC output formats.
**Version 1.15 (2003-Jun-16)** - Added Fairchild, Spectrum, Formatted Binary, Cosmac, Needham formats.
**Version 1.17 (2003-Oct-12)** - Added INHX16, Verilog VMEM, Intel extended segment addressing.
**Version 1.19 (2004-Jan-03)** - Added Intel AOMF format. Added `-execution-start-address` option.
**Version 1.21 (2005-Feb-07)** - Added CRLF output option.
**Version 1.22 (2005-Aug-12)** - Added byte-swap width argument, Motorola width argument.
**Version 1.28 (2007-Mar-08)** - Freescale Dragonball bootstrap b-record format.
**Version 1.31 (2007-Apr-03)** - Texas Instruments TI-TXT (MSP430) format. Verilog data-only suppression.
**Version 1.33 (2007-May-18)** - Data generators. Set intersection and difference on address ranges. ASM/C-Array MSP430 improvements.
**Version 1.36 (2007-Aug-07)** - Fixed CRC-16 CCITT start value bug. License changed to GNU GPL version 3.
**Version 1.37 (2007-Oct-29)** - Negative expressions on command line. Simple hex dump output.
**Version 1.40 (2008-Mar-13)** - CRC32 XMODEM option. Fixed infinite loop bug in complex fill operations.
**Version 1.41 (2008-May-12)** - Six new exclusive-length/minimum/maximum filters.
**Version 1.43 (2008-Jul-06)** - Granular enable/disable for header, data-count, exec-start, and footer features.
**Version 1.44 (2008-Aug-29)** - New `-line-termination` option.
**Version 1.45 (2008-Sep-30)** - Multiple inputs within parentheses. FORTH output.
**Version 1.47 (2009-Feb-19)** - Altera Memory Initialization File (MIF) format.
**Version 1.48 (2009-Apr-19)** - Fletcher 16/32 and Adler 16/32 checksum filters.
**Version 1.50 (2009-Jul-09)** - Enhanced CRC16 with configurable bit order and polynomial. MD5, RipeMD-160, SHA1/224/256/384/512, and Whirlpool digests. Bit-reverse filter.
**Version 1.52 (2009-Sep-17)** - Little-endian and big-endian constant generators.
**Version 1.53 (2009-Nov-10)** - MsBin (Windows CE Binary Image Data) format.
**Version 1.54 (2010-Jan-29)** - Shared library installation with LGPL license.
**Version 1.56 (2010-Sep-15)** - Fletcher 16 desired-answer feature. New output block packing and size options.
**Version 1.57 (2011-Jun-09)** - Intel i8hex support. Fixed byte order for Fletcher 16.
**Version 1.58 (2011-Dec-18)** - IDT/sim, Stag PPB, Stag PPX, MIPS Flash formats. Format auto-detection improvement.
**Version 1.60 (2012-May-19)** - Additional CRC-16 polynomials with name-based selection.
**Version 1.61 (2013-Jan-04)** - Lattice .mem format. Xilinx .coe format.
**Version 1.62 (2013-Jun-05)** - URL-style escape sequences in header strings. Tektronix Extended checksum fix.
**Version 1.63 (2014-Apr-07)** - Logisim format. URL quoting for command-line strings. Generalized redundant/contradictory byte handling.
License and Legal
Command-Line Tools
The SRecord command-line tools (`srec_cat`, `srec_cmp`, `srec_info`) are licensed under the **GNU General Public License version 3** (GPL v3). The key provisions:
– You may freely use, copy, and redistribute the software
– You may modify the software, but modified versions must also be released under GPL v3
– You must provide or make available the complete corresponding source code
– There is absolutely no warranty
The GPL v3 explicitly addresses software patents, requiring that contributors grant royalty-free patent licenses to downstream users.
Shared Library
The `libsrecord` shared library is licensed under the **GNU Lesser General Public License version 3** (LGPL v3). The LGPL supplements the GPL with additional permissions that allow the library to be used in proprietary applications, provided that:
- The application uses the library through its normal interface
- Users are able to replace the library with a modified version
- The application does not incorporate modified library code into its own object files in a way that prevents modificationCopyright
The complete SRecord package is:
> Copyright © 1998–2014 Peter Miller
The software is free and open source. Commercial use, modification, and redistribution are all permitted under the terms of the respective licenses.Frequently Asked Questions
Discover more from PiEmbSysTech - Embedded Systems & VLSI Lab
Subscribe to get the latest posts sent to your email.
