srec_examples(1) | General Commands Manual | srec_examples(1) |
NAME¶
srec_examples - examples of how to use SRecordDESCRIPTION¶
The srec_cat command is very powerful, due to the ability to combine the the input filters in almost unlimited ways. This manual page describes a few of them. This manual page describes how to use the various input files, input filters and input generators. But these are only examples, for more complete details, see the srec_input(1) manual page.The Commands Lines Are Too Long¶
If you are marooned on an operating system with absurdly short command line length limits, some of the commands which follow may be too long. You can get around this handicap by placing your command line in a file, say fred.txt, and then tell srec_cat(1) to read this file for the rest of its command line, like thissrec_cat @fred.txt
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¶
If you have a clever way of using SRecord, or have solved a difficult problem with SRecord, you could contribute to this manual page, making it more useful for everyone. Send your example in an email to the email address at the end of this manual page.CONVERTING FILE FORMATS¶
The simplest of the things srec_cat(1) can do is convert from one EPROM file format to another. Please keep in mind, as you read this section, that you can do many of these things simultaneously in one command. They are only broken out separately to make them easier to understand.Intel to Motorola¶
One of the simplest examples is converting files from Intel hex format to Motorola S‐Record format:srec_cat intel‐file -intel -o
srec‐file
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¶
Converting the other way is just as simple:srec_cat srec‐file -o
intel‐file -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 regrettably common that some addle‐pated EPROM programmers only implement a portion of the specification used to represent their hex files. For example, some compilers produce “s19” Motorola data (that is, S1 data records with S9 start records, 16 bit address fields) which would be OK except that some blockhead EPROM programmers insist on “s37” Motorola data (that is, S3 data records with S7 start records, 32 bit address fields). It is possible to convert from one Motorola shape to another using the -Address‐Length option:srec_cat short.srec -o long.srec
-address‐length=4
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:
srec_cat i32.hex -o i16.hex
-address‐length=3
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¶
From time to time you will come across a feeble‐minded EPROM programmer that can't cope with long text lines, they assume that there will only ever be 46 characters per line and barf when they see the default line lengths that srec_cat(1) writes (or worse, get a stack scribble and crash). 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 hexsrec_cat long.srec -o short.s19
-line‐length=46
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¶
Every once in a while you will come across an ancient daft EPROM programmer that can't cope with long data records, they assume that there will only ever be at most 16 bytes of data per record, and barf when they see the default 32 byte payloads that srec_cat(1) writes (or worse, the buffer over‐run causes a tall grass walk that scribbles on your EPROM). 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:srec_cat long.srec -o short.hex -intel -obs=16
Be careful not to put the -obs option between the output file name and
the format specifier.
Just the Data, Please¶
There are some bonehead EPROM programmers which can only cope with data records, and are unable to cope with header records or execution start address records. If you have this problem, the -data‐only option can be used to suppress just about everything except the data. The actual effect depends on the format, of course, because some don't have these features anyway. 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¶
The srec_cat(1) command always tries to pass through header records unchanged, whenever they are present. It even tries preserve them across file format changes, to the limit the file formats are capable of. 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¶
The srec_cat(1) command always tries to pass through execution start addresses (typically occurring at the end of the file), whenever they are present. They are adjusted along with the data records by the -offset filter. It even tries preserve them across file format changes, to the limit the file formats are capable of. 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¶
Some embedded firmware developers are saddled with featherbrained tools which produce incorrect checksums, which the more vigilant models of EPROM programmer will not accept. To fix the checksums on a file, use the -ignore‐checksums option. For example:srec_cat broken.srec -ignore‐checksums -o
fixed.srec
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¶
See the What Format Is This? section, below, for how to discover and convert mystery EPROM load file formats.BINARY FILES¶
It is possible to convert to and from binary files. You can even mix binary files and other formats together in the same srec_cat(1) command.Writing Binary Files¶
The simplest way of reading a hex file and converting it to a binary file looks like this:srec_cat fred.hex -o fred.bin -binary
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
srec_cat fred.hex -offset − -minimum‐addr
fred.hex -o fred.bin
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¶
The simplest way of reading a binary file and converting it looks like thissrec_cat fred.bin -binary -o fred.srec
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.
srec_cat fred.bin -binary -offset 0x10000 -o
fred.srec
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.
srec_cat fred.bin -binary -unfill 0x00 512 -o
fred.srec
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.
JOINING FILES TOGETHER¶
The srec_cat command takes its name from the UNIX cat(1) command, which is short for “catenate” or “to join”. The srec_cat command joins EPROM load files together.All In One¶
Joining EPROM load files together into a single file is simple, just name as many files on the command line as you need:srec_cat infile1 infile2 -o
outfile
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
Filtering After Joining¶
There are times when you want to join two sets of data together, and then apply a filter to the joined result. To do this you use parentheses.srec_cat \ '(' \ infile -exclude 0xFFF0 0x10000 \ -generate 0xFFF0 0xFFF8 -repeat‐string 'Bananas ' \ ')' \ -b‐e‐length 0xFFF8 4 \ -b‐e‐checksum‐neg 0xFFFC 4 4 \ -o outfile
Joining End‐to‐End¶
All too often the address ranges in the EPROM load files will overlap. You will get an error if they do. If both files start from address zero, because each goes into a separate EPROM, you may need to use the offset filter:srec_cat infile1 \ infile2 -offset 0x80000 \ -o outfile
srec_cat infile1 \ infile2 -offset -maximum‐addr infile1 \ -o outfile
CROPPING THE DATA¶
It is possible to copy an EPROM load file, selecting addresses to keep and addresses to discard.What To Keep¶
A common activity is to crop your data to match your EPROM location. Your linker may add other junk that you are not interested in, e.g. at the RAM location. In this example, there is a 1MB EPROM at the 2MB boundary:srec_cat infile -crop 0x200000 0x300000 \ -o outfile
Address Offset¶
Just possibly, you have a moronic EPROM programmer, and it barfs if the EPROM image doesn't start at zero. To find out just where is does start in memory, use the srec_info(1) command:$ srec_info example.srec Format: Motorola S‐Record Header: extra‐whizz tool chain linker Execution Start Address: 0x00200000 Data: 0x200000 - 0x32AAEF $
srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \ -o outfile
srec_cat infile -offset − -minimum‐addr infile \ -o outfile
What To Throw Away¶
There are times when you need to exclude an small address range from an EPROM load file, rather than wanting to keep a small address range. The -exclude filter may be used for this purpose. 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:srec_cat input.srec -exclude 0x100 0x120 -o
output.srec
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¶
Address ranges don't have to be a single range, you can build up an address range using more than a single pair.srec_cat infile -crop 0x100 0x200 0x1000 0x1200 \ -o outfile
MOVING THINGS AROUND¶
It is also possible to change the address of data records, both forwards and backwards. It is also possible rearrange where data records are placed in memory.Offset Filter¶
The -offset=number filter operates on the addresses of records. If the number is positive the addresses move that many bytes higher in memory, negative values move lower.srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \ -o outfile
Byte Swapping¶
There are times when the bytes in the data need to be swapped, converting between big‐endian and little‐endian data usually.srec_cat infile -byte‐swap 4 -o outfile
Binary Output¶
You need to watch out for binary files on output, because the holes are filled with zeros. Your 100kB program at the top of 32‐bit addressed memory will make a 4GB file. See srec_binary(5) for how understand and avoid this problem, usually with the -offset filter.Splitting an Image¶
If you have a 16‐bit data bus, but you are using two 8‐bit EPROMs to hold your firmware, you can generate the even and odd images by using the -SPlit filter. Assuming your firmware is in the firmware.hex file, use the following:srec_cat firmware.hex -split 2 0 -o firmware.even.hex srec_cat firmware.hex -split 2 1 -o firmware.odd.hex
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
Striping¶
A second use for the -SPlit filter is memory 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
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¶
A more peculiar example of striping is the Microchip dsPIC33F microcontroller, that has a weird memory storage pattern and they are able to store 3 bytes in an address that should only contain 2 bytes. The result is a hex file that has zero‐filled the top byte (little endian), and all addresses are doubled from what they are in the chip. Here is an example:S1130000000102000405060008090A000C0D0E0098 S1130010101112001415160018191A001C1D1E00C8 S1130020202122002425260028292A002C2D2E00F8 S1130030303132003435360038393A003C3D3E0028
srec_cat example.srec -split 4 0 3 -o no_dross.srec
S113000000010204050608090A0C0D0E1011121451 S1130010151618191A1C1D1E2021222425262829EC S11300202A2C2D2E30313234353638393A3C3D3E87
Unspliting Images¶
The unsplit filter may be used to reverse the effects of the split filter. Note that the address range is expanded leaving holes between the stripes. By using all the stripes, the complete input is reassembled, without any holes.srec_cat -o firmware.hex \ firmware.even.hex -unsplit 2 0 \ firmware.odd.hex -unsplit 2 1
FILLING THE BLANKS¶
Often EPROM load files will have “holes” in them, places where the compiler and linker did not put anything. For some purposes this is OK, and for other purposes something has to be done about the holes.The Fill Filter¶
It is possible to fill the blanks where your data does not lie. The simplest example of this fills the entire EPROM:srec_cat infile -fill 0x00 0x200000 0x300000 -o
outfile
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:
srec_cat infile -fill 0x00 -over infile -o
outfile
This example demonstrates the fact that wherever an address range may be
specified, the -over and -within options may be used.
Unfilling the Blanks¶
It is common to need to “unfill” an EPROM image after you read it out of a chip. Usually, it will have had all the holes filled with 0xFF (areas of the EPROM you don't program show as 0xFF when you read them back). To get rid of all the 0xFF bytes in the data, use this filter:srec_cat infile -unfill 0xFF -o
outfile
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:
srec_cat infile -unfill 0xFF 5 -o
outfile
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
Address Range Padding¶
Some data formats are 16 bits wide, and automatically fill with 0xFF bytes if it is necessary to fill out the other half of a word which is not in the data. If you need to fill with a different value, you can use a command like this:srec_cat infile -fill 0x0A \ -within infile -range‐padding 2 \ -o outfile
Fill with Copyright¶
It is possible to fill unused portions of your EPROM with a repeating copyright message. Anyone trying to reverse engineer your EPROMs is going to see the copyright notice in their hex editor. 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
srec_cat infile \ -generate '(' 0 0x100000 -minus -within infile ')' \ -repeat‐string "Copyright (C) `date +%Y` Tchaikovsky. " \ -o outfile
Obfuscating with Noise¶
Sometimes you want to fill your EPROM images with noise, to conceal where the real data stops and starts. You can do this with the -random‐fill filter.srec_cat infile -random‐fill 0x200000 0x300000 \ -o outfile
Fill With 16‐bit Words¶
When filling the image with a constant byte value doesn't work, and you need a constant 16‐bit word value instead, use the -repeat‐data generator, which takes an arbitrarily long sequence of bytes to use as the fill pattern:srec_cat infile \ -generator '(' 0x200000 0x300000 -minus -within infile ')' \ -repeat‐data 0x1B 0x08 \ -o outfile
INSERTING CONSTANT DATA¶
From time to time you will want to insert constant data, or data not produced by your compiler or assembler, into your EPROM load images.Binary Means Literal¶
One simple way is to have the desired information in a file. To insert the file's contents literally, with no format interpretation, use the binary input format:srec_cat infile -binary -o outfile
srec_cat infile -binary -offset 0x1234 -o outfile
date | srec_cat - -bin -offset 0xFFE3 -o outfile
Repeating Once¶
The Fill with Copyright section, above, shows how to repeat a string over and over. We can use a single repeat to insert a string just once.srec_cat -generate 0xFFE3 0x10000 -repeat‐string "`date`" \ -o outfile
Inserting A Long¶
Another possibility is to add the Subversion commit number to your EPROM image. In this example, we are inserting it a a 4‐byte little‐endian value at address 0x0008. The Subversion commit number is in the $version shell variable in this example:srec_cat -generate 0x0008 0x000C -l‐e‐constant $version 4 \ infile -exclude 0x0008 0x000C \ -o outfile
DATA ABOUT THE DATA¶
It is possible to add a variety of data about the data to the output.Checksums¶
The -big‐endian‐checksum‐negative filter may be used to sum the data, and then insert the negative of the sum into the data. This has the effect of summing to zero when the checksum itself is summed across, provided the sum width matches the inserted value width.srec_cat infile \ -crop 0 0xFFFFFC \ -random‐fill 0 0xFFFFFC \ -b‐e‐checksum‐neg 0xFFFFFC 4 4 \ -o outfile
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 }
srec_cat infile \ -crop 0 0xFFFFFE \ -fill 0xCC 0x00000 0xFFFFFE \ -b‐e‐checksum‐neg 0xFFFFFE 2 2 \ -o outfile
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 }
srec_cat infile \ -crop 0 0xFFFFFF \ -fill 0x00 0x00000 0xFFFFFF \ -b‐e‐checksum‐neg 0xFFFFFF 1 1 \ -o outfile
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 }
Quick Hex‐Dump¶
You can look at the checksum of your data, by using the “hex‐dump” output format. This is useful for looking at calculated values, or for debugging an srec_cat(1) command before immortalizing it in a script.srec_cat infile \ -crop 0 0x10000 \ -fill 0xFF 0x0000 0x10000 \ -b‐e‐checksum‐neg 0x10000 4 \ -crop 0x10000 0x10004 \ -o - -hex‐dump
Cyclic Redundancy Checks¶
The simple additive checksums have a number of theoretical limitations, to do with errors they can and can't detect. The CRC methods have fewer problems.srec_cat infile \ -crop 0 0xFFFFFC \ -fill 0x00 0x00000 0xFFFFFC \ -b‐e‐crc32 0xFFFFFC \ -o outfile
srec_cat infile \ -crop 0 0xFFFFFE \ -fill 0x00 0x00000 0xFFFFFE \ -b‐e‐crc16 0xFFFFFE \ -o outfile
srec_cat infile \ -crop 0 0x10000 \ -fill 0xFF 0x0000 0x10000 \ -b‐e‐crc16 0x10000 \ -crop 0x10000 0x10002 \ -o - -hex‐dump
Where Is My Data?¶
There are several properties of your EPROM image that you may wish to insert into the data.srec_cat infile -b‐e‐minimum 0xFFFE 2 -o outfile
srec_cat infile -b‐e‐maximum 0xFFFFFC 4 -o outfile
srec_cat infile -b‐e‐length 0xFFFFFC 4 -o outfile
What Format Is This?¶
You can obtain a variety of information about an EPROM load file by using the srec_info(1) command. For example:$ srec_info example.srec Format: Motorola S‐Record Header: "http://srecord.sourceforge.net/" Execution Start Address: 00000000 Data: 0000 - 0122 0456 - 0FFF $
$ srec_info some‐weird‐file.hex -guess Format: Signetics Data: 0000 - 0122 0456 - 0FFF $
MANGLING THE DATA¶
It is possible to change the values of the data bytes in several ways.srec_cat infile -and 0xF0 -o outfile
srec_cat infile -or 0x0F -o outfile
srec_cat infile -xor 0xA5 -o outfile
srec_cat infile -not -o outfile
COPYRIGHT¶
srec_cat version 1.58AUTHOR¶
Peter Miller | E‐Mail: | pmiller@opensource.org.au |
/\/\* | WWW: | http://miller.emu.id.au/pmiller/ |
SRecord | Reference Manual |