Rechercher une page de manuel
srec_examples
Langue: en
Version: SRecord (debian - 07/07/09)
Section: 1 (Commandes utilisateur)
Sommaire
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.
Your Examples Wanted
If you have a clever way of using SRecord, or have solves a difficult problem with SRecord, you could contribute to this manual page, making it more useful for everyone. Send 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
Motorola to Intel
Converting the other way is just as simple:- srec_cat srec-file -o intel-file -intel
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 section also applies to Intel hex files, as they, too, have the ability to select from a variety of address widths.
Line Lengths
From time to time you will come across a feeble-minded EPROM programmer that can't cope with long SRecord lines, they assume that there will only ever be 16 bytes of data per line, and barf when they see the default 32 byte payloads that srec_cat(1) writes.The Motorola S-record format definition permits up to 255 bytes of payload. All EPROM programmers should have sufficiently large 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
- srec_cat long.srec -o short.s19 --line-length=46
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 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.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 which 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.
Start Addresses
The srec_cat(1) command always tries to pass through 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 start address record and you would like to add one, or you which to override an existing start address record, use the -start-address=number option.
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
This option may be used on any file format which has checksums, including Intel hex.
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
-
srec_cat infile1 -spectrum infile2 -needham \ -o outfile -signetics
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 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_inf(1) command:-
$ srec_info example.srec Format: Motorola S-Record Header: extra-whizz tool chain linker Start: 0x00200000 Data: 0x200000 - 0x32AAEF $
-
srec_cat infile -crop 0x200000 0x300000 -offset -0x200000 \ -o outfile
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 offest 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 - -minmum 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
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. You 100kB program at the top of 32-bit addressed memory will make a 4GB file. See srec_binary(1) 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. In this 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
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
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
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
- srec_cat infile -unfill 0xFF 5 -o outfile
-
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
The string specified is repeated over and over again, until it has filled all the holes.
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
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
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 -big-endian-checksum-bitnot 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 \ --b-e-checksum-neg 0xFFFFFE 2 2 \ -o outfile
-
unsigned short *begin = (unsigned long *)0; unsigned short *end = (unsigned long *)0x100000; unsigned short sum = 0; while (begin < end) sum += *begin++; if (sum != 0xFFFF) { Oops }
There is also a -b-e-checksum-positive 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 \ --b-e-checksum-neg 0xFFFFFF 1 1 \ -o outfile
-
unsigned char *begin = (unsigned long *)0; unsigned char *end = (unsigned long *)0xFFFFF; unsigned char sum = 0; while (begin < end) sum += *begin++; if (sum != *end) { Oops }
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
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 version 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 \ --b-e-crc16 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.
Where Am I?
There are several properties of you EPROM image that you may wish to insert into the data.-
srec_cat infile --b-e-minimum 0xFFFFFE 2 -o outfile
-
srec_cat infile --b-e-maximum 0xFFFFFE 2 -o outfile
-
srec_cat infile --b-e-maximum 0xFFFFFE 2 -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/" Start: 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.39Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Peter Miller
The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.
AUTHOR
Peter Miller | E-Mail: | millerp@canb.auug.org.au |
/\/\* | WWW: | http://www.canb.auug.org.au/~millerp/ |
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre