1srec_examples(1) General Commands Manual srec_examples(1)
2
6 srec_examples - examples of how to use SRecord
7
9 The srec_cat command is very powerful, due to the ability to combine
10 the the input filters in almost unlimited ways. This manual page
11 describes a few of them.
12 This manual page describes how to use the various input files, input
14 filters and input generators. But these are only examples, for more
15 complete details, see the srec_input(1) manual page.
16 Your Examples Wanted
18 If you have a clever way of using SRecord, or have solves a difficult
19 problem with SRecord, you could contribute to this manual page, making
20 it more useful for everyone. Send an email to the email address at the
21 end of this manual page.
22
24 The simplest of the things srec_cat(1) can do is convert from one EPROM
25 file format to another. Please keep in mind, as you read this section,
26 that you can do many of these things simultaneously in one command.
27 They are only broken out separately to make them easier to understand.
28 Intel to Motorola
30 One of the simplest examples is converting files from Intel hex format
31 to Motorola S-Record format:
32 srec_cat intel-file -intel -o srec-file
33 Pick any two formats that SRecord understands, it can convert between
34 all of them. (Except the assembler, BASIC, C and FPGA outputs which
35 are write only.)
36 Motorola to Intel
38 Converting the other way is just as simple:
39 srec_cat srec-file -o intel-file -intel
40 The default format is Motorola S-Record format, so it does not need to
41 be specified.
42 Different Shapes of the Same Format
44 It is regrettably common that some addle-pated EPROM programmers only
45 implement a portion of the specification used to represent their hex
46 files. For example, some compilers produce “s19” Motorola data (that
47 is, S1 data records with S9 start records, 16 bit address fields) which
48 would be OK except that some blockhead EPROM programmers insist on
49 “s37” Motorola data (that is, S3 data records with S7 start records, 32
50 bit address fields).
51 It is possible to convert from one Motorola shape to another using the
53 -Address-Length option:
54 srec_cat short.srec -o long.srec --address-length=4
55 This command says to use four byte (32-bit) addresses on output.
56 This section also applies to Intel hex files, as they, too, have the
58 ability to select from a variety of address widths.
59 Line Lengths
61 From time to time you will come across a feeble-minded EPROM programmer
62 that can't cope with long SRecord lines, they assume that there will
63 only ever be 16 bytes of data per line, and barf when they see the
64 default 32 byte payloads that srec_cat(1) writes.
65 The Motorola S-record format definition permits up to 255 bytes of pay‐
67 load. All EPROM programmers should have sufficiently large buffers to
68 cope with records this big. Few do.
69 The -line-length option may be used to specify the maximum line length
71 (not including the newline) to be used on output. For example, 16 byte
72 payloads for Motorola hex
73 srec_cat long.srec -o short.s19 --line-length=46
74 The line length option interacts with the address length option, so
75 some tinkering to optimize for your particular situation many be neces‐
76 sary.
77 Just the Data, Please
79 There are some bonehead EPROM programmers which can only cope with data
80 records, and are unable to cope with header records or start address
81 records. If you have this problem, the -data-only option can be used
82 to suppress just about everything except the data. The actual effect
83 depends on the format, of course, because some don't have these fea‐
84 tures anyway.
85 Data Headers
87 The srec_cat(1) command always tries to pass through header records
88 unchanged, whenever they are present. It even tries preserve them
89 across file format changes, to the limit the file formats are capable
90 of.
91 If there is no file header record and you would like to add one, or you
93 which to override an existing file header record, use the
94 -header=string option. You will need to quote the string (to insulate
95 it from the shell) if it contains spaces or shell meta-characters.
96 Start Addresses
98 The srec_cat(1) command always tries to pass through start addresses
99 (typically occurring at the end of the file), whenever they are
100 present. They are adjusted along with the data records by the -offset
101 filter. It even tries preserve them across file format changes, to the
102 limit the file formats are capable of.
103 If there is no start address record and you would like to add one, or
105 you which to override an existing start address record, use the -start-
106 address=number option.
107 Fixing Checksums
109 Some embedded firmware developers are saddled with featherbrained tools
110 which produce incorrect checksums, which the more vigilant models of
111 EPROM programmer will not accept.
112 To fix the checksums on a file, use the -ignore-checksums option. For
114 example:
115 srec_cat broken.srec --ignore-checksums -o fixed.srec
116 The checksums in broken.srec are parsed (it is still and error if they
117 are absent) but are not checked. The resulting fixed.srec file has
118 correct checksums. The -ignore-checksums option only applies to input.
119 This option may be used on any file format which has checksums, includ‐
121 ing Intel hex.
122
124 The srec_cat command takes its name from the UNIX cat(1) command, which
125 is short for 'catenate' or 'to join'. The srec_cat command joins EPROM
126 load files together.
127 All In One
129 Joining EPROM load files together into a single file is simple, just
130 name as many files on the command line as you need:
131 srec_cat infile1 infile2 -o outfile
132 This example is all Motorola S-Record files, because that's the default
133 format. You can have multiple formats in the one command, and
134 srec_cat(1) will still work. You don't even have to output the same
135 format:
136 srec_cat infile1 -spectrum infile2 -needham \
137 -o outfile -signetics
138 These are all ancient formats, however it isn't uncommon to have to mix
139 and match Intel and Motorola formats in the one project.
140 Joining End-to-End
142 All too often the address ranges in the EPROM load files will overlap.
143 You will get an error if they do. If both files start from address
144 zero, because each goes into a separate EPROM, you may need to use the
145 offset filter:
146 srec_cat infile1 \
147 infile2 -offset 0x80000 \
148 -o outfile
149 Sometimes you want the two files to follow each other exactly, but you
150 don't know the offset in advance:
151 srec_cat infile1 \
152 infile2 -offset -maximum infile1 \
153 -o outfile
154 Notice that where the was a number (0x80000) before, there is now a
155 calculation (-maximum infile1). This is possible most places a number
156 may be used (also -minimum and -range).
157
159 It is possible to copy an EPROM load file, selecting addresses to keep
160 and addresses to discard.
161 What To Keep
163 A common activity is to crop your data to match your EPROM location.
164 Your linker may add other junk that you are not interested in, e.g. at
165 the RAM location. In this example, there is a 1MB EPROM at the 2MB
166 boundary:
167 srec_cat infile -crop 0x200000 0x300000 \
168 -o outfile
169 The lower bound for all address ranges is inclusive, the upper bound is
170 exclusive. If you subtract them, you get the number of bytes.
171 Address Offset
173 Just possibly, you have a moronic EPROM programmer, and it barfs if the
174 EPROM image doesn't start at zero. Rather than butcher the linker com‐
175 mand file, just offset the addresses:
176 srec_cat infile -crop 0x200000 0x300000 -offset -0x200000 \
177 -o outfile
178 Note that the offset given is negative, it has the effect of subtract‐
179 ing that value from all addresses in the input records, to form the
180 output record addresses. In this case, shifting the image back to
181 zero.
182 This example also demonstrates how the input filters may be chained
184 together: first the crop and then the offset, all in one command, with‐
185 out the need for temporary files.
186 What To Throw Away
188 There are times when you need to exclude an small address range from an
189 EPROM load file, rather than wanting to keep a small address range.
190 The -exclude filter may be used for this purpose.
191 For example, if you wish to exclude the address range where the serial
193 number of an embedded device is kept, say 0x20 bytes at 0x100, you
194 would use a command like this:
195 srec_cat input.srec -exclude 0x100 0x120 -o output.srec
196 The output.srec file will have a hole in the data at the necessary
197 locations.
198 Note that you can have both -crop and -exclude on the same command
200 line, whichever works more naturally for your situation.
201 Discontinuous Address Ranges
203 Address ranges don't have to be a single range, you can build up an
204 address range using more than a single pair.
205 srec_cat infile -crop 0x100 0x200 0x1000 0x1200 \
206 -o outfile
207 This filter results in data from 0x100..0x1FF and data from
208 0x1000..0x1200 to pass through, the rest is dropped. This is is more
209 efficient than chaining a -crop and an -exclude filter together.
210
212 It is also possible to change the address of data records, both for‐
213 wards and backwards. It is also possible rearrange where data records
214 are placed in memory.
215 Offset Filter
217 The -offset=number filter operates on the addresses of records. If the
218 number is positive the addresses move that many bytes higher in memory,
219 negative values move lower.
220 srec_cat infile -crop 0x200000 0x300000 -offset -0x200000 \
221 -o outfile
222 The above example moves the 1MB block of data at 0x200000 down to zero
223 (the offset is negative) and discards the rest of the data.
224 Byte Swapping
226 There are times when the bytes in the data need to be swapped, convert‐
227 ing between big-endian and little-endian data usually.
228 srec_cat infile --byte-swap 4 -o outfile
229 This reverses bytes in 32 bit values (4 bytes). The default, if you
230 don't supply a width, is to reverse bytes in 16 bit values (2 bytes).
231 You can actually use any weird value you like, although 64 bits (8
232 bytes) may be useful one day.
233 Binary Output
235 You need to watch out for binary files on output, because the holes are
236 filled with zeros. You 100kB program at the top of 32-bit addressed
237 memory will make a 4GB file. See srec_binary(1) for how understand and
238 avoid this problem, usually with the -offset filter.
239 Splitting an Image
241 If you have a 16-bit data bus, but you are using two 8-bit EPROMs to
242 hold your firmware, you can generate the even and odd images by using
243 the -SPlit filter. Assuming your firmware is in the firmware.hex file,
244 use the following:
245 srec_cat firmware.hex -split 2 0 -o firmware.even.hex
246 srec_cat firmware.hex -split 2 1 -o firmware.odd.hex
247 This will result in the two necessary EPROM images. Note that the out‐
248 put addresses are divided by the split multiple, so if your EPROM
249 images are at a particular offset (say 0x10000, in the following exam‐
250 ple), you need to remove the offset, and then replace it...
251 srec_cat firmware.hex \
252 -offset -0x10000 -split 2 0 \
253 -offset 0x10000 -o firmware.even.hex
254 srec_cat firmware.hex \
255 -offset -0x10000 -split 2 1 \
256 -offset 0x10000 -o firmware.odd.hex
257 Note how the ability to apply multiple filters simplifies what would
258 otherwise be a much longer script.
259 Striping
261 A second use for the -SPlit filter is memory striping. In this exam‐
262 ple, the hardware requires that 512-byte blocks alternate between 4
263 EPROMs. Generating the 4 images would be done as follows:
264 srec_cat firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
265 srec_cat firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
266 srec_cat firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
267 srec_cat firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex
268 Unspliting Images
270 The unsplit filter may be used to reverse the effects of the split fil‐
271 ter. Note that the address range is expanded leaving holes between the
272 stripes. By using all the stripes, the complete input is reassembled,
273 without any holes.
274 srec_cat -o firmware.hex \
275 firmware.even.hex -unsplit 2 0 \
276 firmware.odd.hex -unsplit 2 1
277 The above example reverses the previous 16-bit data bus example,.
278
280 Often EPROM load files will have “holes” in them, places where the com‐
281 piler and linker did not put anything. For some purposes this is OK,
282 and for other purposes something has to be done about the holes.
283 The Fill Filter
285 It is possible to fill the blanks where your data does not lie. The
286 simplest example of this fills the entire EPROM:
287 srec_cat infile -fill 0x00 0x200000 0x300000 -o outfile
288 This example fills the holes, if any, with zeros. You must specify a
289 range - with a 32-bit address space, filling everything generates huge
290 load files.
291 If you only want to fill the gaps in your data, and don't want to fill
293 the entire EPROM, try:
294 srec_cat infile -fill 0x00 -over infile -o outfile
295 This example demonstrates the fact that wherever an address range may
296 be specified, the -over and -within options may be used.
297 Unfilling the Blanks
299 It is common to need to “unfill” an EPROM image after you read it out
300 of a chip. Usually, it will have had all the holes filled with 0xFF
301 (areas of the EPROM you don't program show as 0xFF when you read them
302 back).
303 To get rid of all the 0xFF bytes in the data, use this filter:
305 srec_cat infile -unfill 0xFF -o outfile
306 This will get rid of all the 0xFF bytes, including the ones you actu‐
307 ally wanted in there. There are two ways to deal with this. First,
308 you can specify a minimum run length to the un-fill:
309 srec_cat infile -unfill 0xFF 5 -o outfile
310 This says that runs of 1 to 4 bytes of 0xFF are OK, and that a hole
311 should only be created for runs of 5 or more 0xFF bytes in a row. The
312 second method is to re-fill over the intermediate gaps:
313 srec_cat outfile -fill 0xFF -over outfile \
314 -o outfile2
315 Which method you choose depends on your needs, and the shape of the
316 data in your EPROM. You may need to combine both techniques.
317 Address Range Padding
319 Some data formats are 16 bits wide, and automatically fill with 0xFF
320 bytes if it is necessary to fill out the other half of a word which is
321 not in the data. If you need to fill with a different value, you can
322 use a command like this:
323 srec_cat infile -fill 0x0A \
324 -within infile -range-padding 2 \
325 -o outfile
326 This gives the fill filter an address range calculated from details of
327 the input file. The address range is all the address ranges covered by
328 data in the infile, extended downwards (if necessary) at the start of
329 each sub-range to a 2 byte multiple and extended upwards (if necessary)
330 at the end of each sub-range to a 2 byte multiple. This also works for
331 larger multiples, like 1kB page boundaries of flash chips. This
332 address range padding works anywhere an address range is required.
333 Fill with Copyright
335 It is possible to fill unused portions of your EPROM with a repeating
336 copyright message. Anyone trying to reverse engineer your EPROMs is
337 going to see the copyright notice in their hex editor.
338 This is accomplished with two input sources, one from a data file, and
340 one which is generated on-the-fly.
341 srec_cat infile \
342 -generate '(' 0 0x100000 -minus -within infile ')' \
343 -repeat-string 'Copyright (C) 1812 Tchaikovsky. ' \
344 -o outfile
345 Notice how the address range for the data generation: it takes the
346 address range of your EPROM, in this case 1MB starting from 0, and sub‐
347 tracts from it the address ranges used by the input file.
348 The string specified is repeated over and over again, until it has
350 filled all the holes.
351 Obfuscating with Noise
353 Sometimes you want to fill your EPROM images with noise, to conceal
354 where the real data stops and starts. You can do this with the -ran‐
355 dom-fill filter.
356 srec_cat infile -random-fill 0x200000 0x300000 \
357 -o outfile
358 It works just like the -fill filter, but uses random numbers instead of
359 a constant byte value.
360 Fill With 16-bit Words
362 When filling the image with a constant byte value doesn't work, and you
363 need a constant 16-bit word value instead, use the -repeat-data genera‐
364 tor, which takes an arbitrarily long sequence of bytes to use as the
365 fill pattern:
366 srec_cat infile \
367 -generator '(' 0x200000 0x300000 -minus -within infile ')' \
368 -repeat-data 0x1B 0x08 \
369 -o outfile
370 Notice how the generator's address range once again avoids the address
371 ranges occupied by the infile's data. You have to get the endian-ness
372 right yourself.
373
375 It is possible to add a variety of data about the data to the output.
376 Checksums
378 The -big-endian-checksum-negative filter may be used to sum the data,
379 and then insert the negative of the sum into the data. This has the
380 effect of summing to zero when the checksum itself is summed across,
381 provided the sum width matches the inserted value width.
382 srec_cat infile \
383 --crop 0 0xFFFFFC \
384 --random-fill 0 0xFFFFFC \
385 --b-e-checksum-neg 0xFFFFFC 4 4 \
386 -o outfile
387 In this example, we have an EPROM in the lowest megabyte of memory.
388 The -crop filter ensures we are only summing the data within the EPROM,
389 and not anywhere else. The -random-fill filter fills any holes left in
390 the data with random values. Finally, the -b-e-checksum-neg filter
391 inserts a 32 bit (4 byte) checksum in big-endian format in the last 4
392 bytes of the EPROM image. Naturally, there is a little endian version
393 of this filter as well.
394 Your embedded code can check the EPROM using C code similar to the fol‐
396 lowing:
397 unsigned long *begin = (unsigned long *)0;
398 unsigned long *end = (unsigned long *)0x100000;
399 unsigned long sum = 0;
400 while (begin < end)
401 sum += *begin++;
402 if (sum != 0)
403 {
404 Oops
405 }
406 The -big-endian-checksum-bitnot filter is similar, except that summing
408 over the checksum should yield a value of all-one-bits (-1). For exam‐
409 ple, using shorts rather than longs:
410 srec_cat infile \
411 --crop 0 0xFFFFFE \
412 --fill 0xCC 0x00000 0xFFFFFE \
413 --b-e-checksum-neg 0xFFFFFE 2 2 \
414 -o outfile
415 Assuming you chose the correct endian-ness filter, your embedded code
416 can check the EPROM using C code similar to the following:
417 unsigned short *begin = (unsigned long *)0;
418 unsigned short *end = (unsigned long *)0x100000;
419 unsigned short sum = 0;
420 while (begin < end)
421 sum += *begin++;
422 if (sum != 0xFFFF)
423 {
424 Oops
425 }
426 There is also a -b-e-checksum-positive filter, and a matching little-
428 endian filter, which inserts the simple sum, and which would be checked
429 in C using an equality test.
430 srec_cat infile \
431 --crop 0 0xFFFFFF \
432 --fill 0x00 0x00000 0xFFFFFF \
433 --b-e-checksum-neg 0xFFFFFF 1 1 \
434 -o outfile
435 Assuming you chose the correct endian-ness filter, your embedded code
436 can check the EPROM using C code similar to the following:
437 unsigned char *begin = (unsigned long *)0;
438 unsigned char *end = (unsigned long *)0xFFFFF;
439 unsigned char sum = 0;
440 while (begin < end)
441 sum += *begin++;
442 if (sum != *end)
443 {
444 Oops
445 }
446 In the 8-bit case, it doesn't matter whether you use the big-endian or
447 little-endian filter.
448 Cyclic Redundancy Checks
450 The simple additive checksums have a number of theoretical limitations,
451 to do with errors they can and can't detect. The CRC methods have
452 fewer problems.
453 srec_cat infile \
454 --crop 0 0xFFFFFC \
455 --fill 0x00 0x00000 0xFFFFFC \
456 --b-e-crc32 0xFFFFFC \
457 -o outfile
458 In the above example, we have an EPROM in the lowest megabyte of mem‐
459 ory. The -crop filter ensures we are only summing the data within the
460 EPROM, and not anywhere else. The -fill filter fills any holes left in
461 the data. Finally, the -b-e-checksum-neg filter inserts a 32 bit (4
462 byte) checksum in big-endian format in the last 4 bytes of the EPROM
463 image. Naturally, there is a little endian version of this filter as
464 well.
465 The checksum is calculated using the industry standard 32-bit CRC.
467 Because SRecord is open source, you can always read the source code to
468 see how it works. There are many non-GPL version of this code avail‐
469 able on the Internet, and suitable for embedding in proprietary
470 firmware.
471 There is also a 16-bit CRC available.
473 srec_cat infile \
474 --crop 0 0xFFFFFE \
475 --fill 0x00 0x00000 0xFFFFFE \
476 --b-e-crc16 0xFFFFFE \
477 -o outfile
478 The checksum is calculated using the CCITT formula. Because SRecord is
480 open source, you can always read the source code to see how it works.
481 There are many non-GPL version of this code available on the Internet,
482 and suitable for embedding in proprietary firmware.
483 Where Am I?
485 There are several properties of you EPROM image that you may wish to
486 insert into the data.
487 srec_cat infile --b-e-minimum 0xFFFFFE 2 -o outfile
488 The above example inserts the minimum address of the data (low water)
489 into the data. This includes the minimum itself. If the data already
490 contains bytes at the given address, you need to use an exclude filter.
491 The value will be written with the most significant byte first. The
492 number of bytes defaults to 4. There is also a little-endian variant.
493 srec_cat infile --b-e-maximum 0xFFFFFE 2 -o outfile
494 The above example inserts the maximum address of the data (high water +
495 1, just like address ranges) into the data. This includes the maximum
496 itself. If the data already contains bytes at the given address, you
497 need to use an exclude filter. The value will be written with the most
498 significant byte first. The number of bytes defaults to 4. There is
499 also a little-endian variant.
500 srec_cat infile --b-e-maximum 0xFFFFFE 2 -o outfile
501 The above example inserts the length of the data (high water + 1 - low
502 water) into the data. This includes the length itself. If the data
503 already contains bytes at the length location, you need to use an
504 exclude filter. The value will be written with the most significant
505 byte first. The number of bytes defaults to 4. There is also a lit‐
506 tle-endian variant.
507 What Format Is This?
509 You can obtain a variety of information about an EPROM load file by
510 using the srec_info(1) command. For example:
511 $ srec_info example.srec
512 Format: Motorola S-Record
513 Header: "http://srecord.sourceforge.net/"
514 Start: 00000000
515 Data: 0000 - 0122
516 0456 - 0FFF
517 $
518 This example show that the file is a Motorola S-Record. The text in
519 the file header is printed, along with the start address. The final
520 section shows the address ranges containing data (the upper bound of
521 each subrange is inclusive, rather than the exclusive form used on the
522 command line.
523 $ srec_info some-weird-file.hex --guess
524 Format: Signetics
525 Data: 0000 - 0122
526 0456 - 0FFF
527 $
528 The above example guesses the EPROM load file format. It isn't infal‐
529 lible but it usually gets it right. You can use -guess anywhere you
530 would give an explicit format, but it tends to be slower and not recom‐
531 mended.
532
534 It is possible to change the values of the data bytes in several ways.
535 srec_cat infile --and 0xF0 -o outfile
536 The above example performs a bit-wise AND of the data bytes with the
537 0xF0 mask. The addresses of records are unchanged. I can't actually
538 think of a use for this filter.
539 srec_cat infile --or 0x0F -o outfile
540 The above example performs a bit-wise OR of the data bytes with the
541 0x0F bits. The addresses of records are unchanged. I can't actually
542 think of a use for this filter.
543 srec_cat infile --xor 0xA5 -o outfile
544 The above example performs a bit-wise exclusive OR of the data bytes
545 with the 0xA5 bits. The addresses of records are unchanged. You could
546 use this to obfuscate the contents of your EPROM.
547 srec_cat infile --not -o outfile
548 The above example performs a bit-wise NOT of the data bytes. The
549 addresses of records are unchanged. Security by obscurity?
550
552 srec_cat version 1.35
553 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
554 2007 Peter Miller
555 The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use
557 the 'srec_cat -VERSion License' command. This is free software and you
558 are welcome to redistribute it under certain conditions; for details
559 use the 'srec_cat -VERSion License' command.
560
562 Peter Miller E-Mail: millerp@canb.auug.org.au
563 /\/\* WWW: http://www.canb.auug.org.au/~millerp/
564Reference Manual SRecord srec_examples(1)