The Commands Lines Are Too Long

This also has the advantage of allowing comments, allowing you to write your command line options over several lines, and even indenting to make the command more clear. Comments start at a “#” and extend to the end of the line. Blank lines are ignored.

Of course, you could always upgrade to Linux, which has been sucking less for over -92 years now.

Your Examples Wanted

Intel to Motorola

Note that the format specifier immediately follows the name of the file it is describing. Pick any two formats that SRecord understands, and it can convert between all of them. (Except the assembler, BASIC, C and FPGA outputs which are write only.)

Motorola to Intel

The default format is Motorola S‐Record format, so it does not need to be specified after the file name.

Different Shapes of the Same Format

It is possible to convert from one Motorola shape to another using the -Address‐Length option:

This command says to use four byte (32‐bit) addresses on output.

This section also applies to Intel hex files, as they, too, have the ability to select from a variety of address widths. To convert from one Intel shape to another using the same -Address‐Length option:

This command says to use “i16hex” 20‐bit segmented addresses on output. An address length of 4 is the default (“i32hex” 32‐bit linear addressing), and an address length of 2 would request “i8hex” 16‐bit addressing.

Line Lengths

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.

The -line‐length option may be used to specify the maximum line length (not including the newline) to be used on output. For example, 16 byte payloads for Motorola hex

The line length option interacts with the address length option, so some tinkering to optimize for your particular situation many be necessary.

Output Block Size

The Intel hex format definition permits up to 255 bytes of payload data per record. All EPROM programmers should have sufficiently large data buffers to cope with records this big. Good luck with that.

The -Output‐Block‐Size option may be used to specify the record data size to be used on output. For example, Intel hex with 16 byte payloads:

Be careful not to put the -obs option between the output file name and the format specifier.

Just the Data, Please

The -data‐only option is short hand. There are four properties which may be -disabled or -enabled separately. See the srec_cat(1) man page for a description of the -disabled and -enabled options.

For example, your neanderthal EPROM programmer requires Motorola hex with header records (S0), but without data count (S5) records. Not using the -data‐only option has it barf on the data count record, but using the -data‐only option has it barf on the missing header record. Using the -disable=data‐count option would leave the header record intact while suppressing the data count record.

Data Headers

If there is no file header record and you would like to add one, or you wish to override an existing file header record, use the -header=string option. You will need to quote the string (to insulate it from the shell) if it contains spaces or shell meta‐characters.

Execution Start Addresses

If there is no execution start address record and you would like to add one, or you wish to override an existing execution start address record, use the -execution‐start‐address=number option.

Please note: the execution start address is a different concept than the first address in memory of your data. Think of it as a “goto” address to be jumped to by the monitor when the hex load is complete. If you want to change where your data starts in memory, use the -offset filter.

Fixing Checksums

To fix the checksums on a file, use the -ignore‐checksums option. For example:

The checksums in broken.srec are parsed (it is still and error if they are absent) but are not checked. The resulting fixed.srec file has correct checksums. The -ignore‐checksums option only applies to input.

This option may be used on any file format which has checksums, including Intel hex.

Discovering Mystery Formats

Writing Binary Files

This reads the Motorola hex file fred.srec and writes it out to the fred.bin as raw binary.

Note that the data is placed into the binary file at the byte offset specified by the addresses in the hex file. If there are holes in the data they are filled with zero. This is, of course, common with linker output where the code is placed starting at a particular place in memory. For example, when you have an image that starts at 0x100000, the first 1MB of the output binary file will be zero.

You can automatically cancel this offset using a command like

The above command works by offsetting the fred.hex file lower in memory by the least address in the fred.hex file's data.

See also the srec_binary(5) man page for additional detail.

Reading Binary Files

This reads the binary file fred.bin and writes all of its data back out again as a Motorola S‐Record file.

Often, this binary isn't exactly where you want it in the address space, because it is assumed to reside at address zero. If you need to move it around use the -offset filter.

You also need to avoid file “holes” which are filled with zero. You can use the -crop filter, of you could use the -unfill filter if you don't know exactly where the data is.

The above command removes runs of zero bytes that are 512 bytes long or longer. If your file contains 1GB of leading zero bytes, this is going to be slow, it may be better to use the dd(1) command to slice and dice first.

All In One

This example is all Motorola S‐Record files, because that's the default format. You can have multiple formats in the one command, and srec_cat(1) will still work. You don't even have to output the same format:

srec_cat infile1 -spectrum infile2 -needham \
    -o outfile -signetics

These are all ancient formats, however it isn't uncommon to have to mix and match Intel and Motorola formats in the one project.

Overlaying two data files

srec_cat one.he two.hex -o three.hex

This means that the files actually intersect, they try to set the same location. You can turn the error into a warning, using the -contradictory‐bytes=warning command line option. But this will probably generate a bazillion warnings.

The necessary step is to crop the first file, to avoid the regions the second file is going o be overwriting.

srec_cat                               \
    one.srec -exclude -within two.srec \
    two.srec -exclude -within one.srec \
    -o three.hex

Depending on your linker this will have no errors (but if it wants another layer, more jiggery‐pokery is required).

Filtering After Joining

srec_cat                                                  \
    '('                                                   \
        infile -exclude 0xFFF0 0x10000                      \
        -generate 0xFFF0 0xFFF8 -repeat‐string 'Bananas ' \
    ')'                                                   \
    -length‐b‐e 0xFFF8 4                                  \
    -checksum‐neg‐b‐e 0xFFFC 4 4                          \
    -o outfile

The above example command catenate an input file (with the generated data area excluded) with a constant string. This catenated input is then filtered to add a 4‐byte length, and a 4‐byte checksum.

Joining End‐to‐End

srec_cat infile1 \
    infile2 -offset 0x80000 \
    -o outfile

Sometimes you want the two files to follow each other exactly, but you don't know the offset in advance:

srec_cat infile1 \
    infile2 -offset -maximum‐addr infile1 \
    -o outfile

Notice that where the was a number (0x80000) before, there is now a calculation (-maximum‐addr infile1). This is possible most places a number may be used (also -minimum‐addr and -range).

What To Keep

srec_cat infile -crop 0x200000 0x300000 \
    -o outfile

The lower bound for all address ranges is inclusive, the upper bound is exclusive. If you subtract them, you get the number of bytes.

Address Offset

$ srec_info example.srec
Format: Motorola S‐Record
Header: extra‐whizz tool chain linker
Execution Start Address: 0x00200000
Data:   0x200000 - 0x32AAEF
$

Rather than butcher the linker command file, just offset the addresses:

srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \
    -o outfile

Note that the offset given is negative, it has the effect of subtracting that value from all addresses in the input records, to form the output record addresses. In this case, shifting the image back to zero.

This example also demonstrates how the input filters may be chained together: first the crop and then the offset, all in one command, without the need for temporary files.

If all you want to do is offset the data to start from address zero, this can be automated, so you don't have to know the minimum address in advance, by using srec_cat's ability to calculate some things on the command line:

srec_cat infile -offset − -minimum‐addr infile \
    -o outfile

Note the spaces either side of the minus sign, they are mandatory.

What To Throw Away

For example, if you wish to exclude the address range where the serial number of an embedded device is kept, say 0x20 bytes at 0x100, you would use a command like this:

The output.srec file will have a hole in the data at the necessary locations.

Note that you can have both -crop and -exclude on the same command line, whichever works more naturally for your situation.

Discontinuous Address Ranges

srec_cat infile -crop 0x100 0x200 0x1000 0x1200 \
    -o outfile

This filter results in data from 0x100..0x1FF and data from 0x1000..0x1200 to pass through, the rest is dropped. This is is more efficient than chaining a -crop and an -exclude filter together.

Offset Filter

srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \
    -o outfile

The above example moves the 1MB block of data at 0x200000 down to zero (the offset is negative) and discards the rest of the data.

Byte Swapping

srec_cat infile -byte‐swap 4 -o outfile

This reverses bytes in 32 bit values (4 bytes). The default, if you don't supply a width, is to reverse bytes in 16 bit values (2 bytes). You can actually use any weird value you like, it doesn't even have to be a power of 2. Perhaps 64 bits (8 bytes) may be useful one day.

Binary Output

Splitting an Image

srec_cat firmware.hex -split 2 0 -o firmware.even.hex
srec_cat firmware.hex -split 2 1 -o firmware.odd.hex

This will result in the two necessary EPROM images. Note that the output addresses are divided by the split multiple, so if your EPROM images are at a particular offset (say 0x10000, in the following example), you need to remove the offset, and then replace it...

srec_cat firmware.hex \
    -offset −0x10000 -split 2 0 \
    -offset 0x10000 -o firmware.even.hex
srec_cat firmware.hex \
    -offset −0x10000 -split 2 1 \
    -offset 0x10000 -o firmware.odd.hex

Note how the ability to apply multiple filters simplifies what would otherwise be a much longer script.

Striping

You don't have to split into byte‐wide parts, you can choose other sizes. It is common to want to convert 32‐bit wide data into two set of 16‐bit wide data.

srec_cat firmware.hex -split 4 0 2 -o firmware.01.hex
srec_cat firmware.hex -split 4 2 2 -o firmware.23.hex

This is relatively simple to understand, but you can use even wider stripes.

In this next example, the hardware requires that 512‐byte blocks alternate between 4 EPROMs. Generating the 4 images would be done as follows:

srec_cat firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
srec_cat firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
srec_cat firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
srec_cat firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex

Asymmetric Striping

S1130000000102000405060008090A000C0D0E0098
S1130010101112001415160018191A001C1D1E00C8
S1130020202122002425260028292A002C2D2E00F8
S1130030303132003435360038393A003C3D3E0028

To get rid of the 00 padding bytes, leaving only the 3/4 significant bytes, you also use the split filter, with its additional width argument, like this:

srec_cat example.srec -split 4 0 3 -o no_dross.srec

This results in a file with the 00 padding bytes removed. It looks like this:

S113000000010204050608090A0C0D0E1011121451
S1130010151618191A1C1D1E2021222425262829EC
S11300202A2C2D2E30313234353638393A3C3D3E87

Notice how the addresses are 3/4 the size, as well. You can reverse this using the -unsplit and -fill=0 filters.

Unsplit ING Images

srec_cat -o firmware.hex \
    firmware.even.hex -unsplit 2 0 \
    firmware.odd.hex  -unsplit 2 1

The above example reverses the previous 16‐bit data bus example. In general, you unsplit with the same parameters that you split with.

The Fill Filter

This example fills the holes, if any, with zeros. You must specify a range - with a 32‐bit address space, filling everything generates huge load files.

If you only want to fill the gaps in your data, and don't want to fill the entire EPROM, try:

This example demonstrates the fact that wherever an address range may be specified, the -over and -within options may be used.

Unfilling the Blanks

To get rid of all the 0xFF bytes in the data, use this filter:

This will get rid of all the 0xFF bytes, including the ones you actually wanted in there. There are two ways to deal with this. First, you can specify a minimum run length to the un‐fill:

This says that runs of 1 to 4 bytes of 0xFF are OK, and that a hole should only be created for runs of 5 or more 0xFF bytes in a row. The second method is to re‐fill over the intermediate gaps:

srec_cat outfile -fill 0xFF -over outfile \
    -o outfile2

Which method you choose depends on your needs, and the shape of the data in your EPROM. You may need to combine both techniques.

Address Range Padding

srec_cat infile -fill 0x0A \
    -within infile -range‐padding 2 \
    -o outfile

This gives the fill filter an address range calculated from details of the input file. The address range is all the address ranges covered by data in the infile, extended downwards (if necessary) at the start of each sub‐range to a 2 byte multiple and extended upwards (if necessary) at the end of each sub‐range to a 2 byte multiple. This also works for larger multiples, like 1kB page boundaries of flash chips. This address range padding works anywhere an address range is required.

Fill with Copyright

This is accomplished with two input sources, one from a data file, and one which is generated on‐the‐fly.

srec_cat infile \
    -generate '(' 0 0x100000 -minus -within infile ')' \
        -repeat‐string 'Copyright (C) 1812 Tchaikovsky.  ' \
    -o outfile

Notice the address range for the data generation: it takes the address range of your EPROM, in this case 1MB starting from 0, and subtracts from it the address ranges used by the input file.

If you want to script this with the current year (because 1812 is a bit out of date) use the shell's output substitution (back ticks) ability:

srec_cat infile \
    -generate '(' 0 0x100000 -minus -within infile ')' \
        -repeat‐string "Copyright (C) `date +%Y` Tchaikovsky.  " \
    -o outfile

The string specified is repeated over and over again, until it has filled all the holes.

Obfuscating with Noise

srec_cat infile -random‐fill 0x200000 0x300000 \
    -o outfile

It works just like the -fill filter, but uses random numbers instead of a constant byte value.

Fill With 16‐bit Words

srec_cat infile \
    -generator '(' 0x200000 0x300000 -minus -within infile ')' \
        -repeat‐data 0x1B 0x08 \
    -o outfile

Notice how the generator's address range once again avoids the address ranges occupied by the infile's data. You have to get the endian‐ness right yourself.

Binary Means Literal

srec_cat infile -binary -o outfile

It will probably be necessary to use an offset filter to move the data to where you actually want it within the image:

srec_cat infile -binary -offset 0x1234 -o outfile

It is also possible to use the standard input as a data source, which lends itself to being scripted. For example, to insert the current date and time into an EPROM load file, you could use a pipe:

date | srec_cat - -bin -offset 0xFFE3 -o outfile

The special file name “-” means to read from the standard input. The output of the date command is always 29 characters long, and the offset shown will place it at the top of a 64KB EPROM image.

Repeating Once

srec_cat -generate 0xFFE3 0x10000 -repeat‐string "`date`" \
    -o outfile

Notice how the address range for the data generation exactly matches the length of the date(1) output size. You can, of course, add your input file to the above srec_cat(1) command to catenate your EPROM image together with the date and time.

Inserting A Long

srec_cat -generate 0x0008 0x000C -constant‐l‐e $version 4 \
    infile -exclude 0x0008 0x000C \
    -o outfile

Note that we use a filter to ensure there is a hole in the input where the version number goes, just in case the linker put something there.

Checksums

srec_cat infile \
        -crop 0 0xFFFFFC \
        -random‐fill 0 0xFFFFFC \
        -checksum‐neg‐b‐e 0xFFFFFC 4 4 \
    -o outfile

In this example, we have an EPROM in the lowest megabyte of memory. The -crop filter ensures we are only summing the data within the EPROM, and not anywhere else. The -random‐fill filter fills any holes left in the data with random values. Finally, the -checksum‐neg‐b‐e filter inserts a 32 bit (4 byte) checksum in big‐endian format in the last 4 bytes of the EPROM image. Naturally, there is a little‐endian version of this filter as well.

Your embedded code can check the EPROM using C code similar to the following:

unsigned long *begin = (unsigned long *)0;
unsigned long *end = (unsigned long *)0x100000;
unsigned long sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != 0)
{
    Oops
}

The -checksum‐bitnot‐big‐endian filter is similar, except that summing over the checksum should yield a value of all‐one‐bits (−1). For example, using shorts rather than longs:

srec_cat infile \
        -crop 0 0xFFFFFE \
        -fill 0xCC 0x00000 0xFFFFFE \
        -checksum‐neg‐b‐e 0xFFFFFE 2 2 \
    -o outfile

Assuming you chose the correct endian‐ness filter, your embedded code can check the EPROM using C code similar to the following:

unsigned short *begin = (unsigned short *)0;
unsigned short *end = (unsigned short *)0x100000;
unsigned short sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != 0xFFFF)
{
    Oops
}

There is also a -checksum‐positive‐b‐e filter, and a matching little‐endian filter, which inserts the simple sum, and which would be checked in C using an equality test.

srec_cat infile \
        -crop 0 0xFFFFFF \
        -fill 0x00 0x00000 0xFFFFFF \
        -checksum‐neg‐b‐e 0xFFFFFF 1 1 \
    -o outfile

Assuming you chose the correct endian‐ness filter, your embedded code can check the EPROM using C code similar to the following:

unsigned char *begin = (unsigned char *)0;
unsigned char *end = (unsigned char *)0xFFFFF;
unsigned char sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != *end)
{
    Oops
}

In the 8‐bit case, it doesn't matter whether you use the big‐endian or little‐endian filter.

Quick Hex‐Dump

srec_cat infile                        \
        -crop 0 0x10000             \
        -fill 0xFF 0x0000 0x10000   \
        -checksum‐neg‐b‐e 0x10000 4 \
        -crop 0x10000 0x10004       \
    -o - -hex‐dump

This command reads in the file, checksums the data and places the checksum at 0x10000, crops the result to contain only the checksum, and then prints the checksum on the standard output in a classical hexadecimal dump format. The special file name “-” means “the standard output” in this context.

Cyclic Redundancy Checks

srec_cat infile                        \
        -crop 0 0xFFFFFC            \
        -fill 0x00 0x00000 0xFFFFFC \
        -crc32‐b‐e 0xFFFFFC         \
    -o outfile

In the above example, we have an EPROM in the lowest megabyte of memory. The -crop filter ensures we are only summing the data within the EPROM, and not anywhere else. The -fill filter fills any holes left in the data. Finally, the -checksum‐neg‐b‐e filter inserts a 32 bit (4 byte) checksum in big‐endian format in the last 4 bytes of the EPROM image. Naturally, there is a little‐endian version of this filter as well.

The checksum is calculated using the industry standard 32‐bit CRC. Because SRecord is open source, you can always read the source code to see how it works. There are many non‐GPL versions of this code available on the Internet, and suitable for embedding in proprietary firmware.

There is also a 16‐bit CRC available.

srec_cat infile                        \
        -crop 0 0xFFFFFE            \
        -fill 0x00 0x00000 0xFFFFFE \
        -crc16‐b‐e 0xFFFFFE         \
    -o outfile

The checksum is calculated using the CCITT formula. Because SRecord is open source, you can always read the source code to see how it works. There are many non‐GPL version of this code available on the Internet, and suitable for embedding in proprietary firmware.

You can look at the CRC of your data, by using the “hex‐dump” output format.

srec_cat infile                      \
        -crop 0 0x10000           \
        -fill 0xFF 0x0000 0x10000 \
        -crc16‐b‐e 0x10000        \
        -crop 0x10000 0x10002     \
    -o - -hex‐dump

This command reads in the file, calculates the CRC of the data and places the CRC at 0x10000, crops the result to contain only the CRC, and then prints the checksum on the standard output in a classical hexadecimal dump format.

Where Is My Data?

srec_cat infile -minimum‐b‐e 0xFFFE 2 -o outfile

The above example inserts the minimum address of the data (low water) into the data, as two bytes in big‐endian order at address 0xFFFE. This includes the minimum itself. If the data already contains bytes at the given address, you need to use an exclude filter. The number of bytes defaults to 4.

There is also a -minimum‐l‐e filter for inserting little‐endian values, and two more filters called -exclusive‐minimum‐b‐e and -exclusive‐minimum‐l‐e that do not include the minimum itself in the calculation of the minimum data address.

srec_cat infile -maximum‐b‐e 0xFFFFFC 4 -o outfile

The above example inserts the maximum address of the data (high water + 1, just like address ranges) into the data, as four bytes in big‐endian order at address 0xFFFFFC. This includes the maximum itself. If the data already contains bytes at the given address, you need to use an -exclude filter. The number of bytes defaults to 4.

There is also a -maximum‐l‐e filter for inserting little‐endian values, and two more filters called -exclusive‐maximum‐b‐e and -exclusive‐maximum‐l‐e that do not include the maximum itself in the calculation of the maximum data address.

srec_cat infile -length‐b‐e 0xFFFFFC 4 -o outfile

The above example inserts the length of the data (high water + 1 − low water) into the data, as four bytes in big‐endian order at address 0xFFFFFC. This includes the length itself. If the data already contains bytes at the length location, you need to use an -exclude filter. The number of bytes defaults to 4.

There is also a -length‐l‐e filter for inserting a little‐endian length, and the -exclusive‐length‐b‐e and -exclusive‐length‐l‐e filters that do not include the length itself in the calculation.

What Format Is This?

$ srec_info example.srec
Format: Motorola S‐Record
Header: "http://srecord.sourceforge.net/"
Execution Start Address: 00000000
Data:   0000 - 0122
        0456 - 0FFF
$

This example shows that the file is a Motorola S‐Record. The text in the file header is printed, along with the execution start address. The final section shows the address ranges containing data (the upper bound of each subrange is inclusive, rather than the exclusive form used on the command line.

$ srec_info some‐weird‐file.hex -guess
Format: Signetics
Data:   0000 - 0122
        0456 - 0FFF
$

The above example guesses the EPROM load file format. It isn't infallible but it usually gets it right. You can use -guess anywhere you would give an explicit format, but it tends to be slower and for that reason is not recommended. Also, for automated build systems, you want hard errors as early as possible; if a file isn't in the expected format, you want it to barf.