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 The Commands Lines Are Too Long
18 If you are marooned on an operating system with absurdly short command
19 line length limits, some of the commands which follow may be too long.
20 You can get around this handicap by placing your command line in a
21 file, say fred.txt, and then tell srec_cat(1) to read this file for the
22 rest of its command line, like this
23 srec_cat @fred.txt
24 This also has the advantage of allowing comments, allowing you to write
25 your command line options over several lines, and even indenting to
26 make the command more clear. Comments start at a “#” and extend to the
27 end of the line. Blank lines are ignored.
28 Of course, you could always upgrade to Linux, which has been sucking
30 less for over 27 years now.
31 Your Examples Wanted
33 If you have a clever way of using SRecord, or have solved a difficult
34 problem with SRecord, you could contribute to this manual page, making
35 it more useful for everyone. Send your example in an email to the
36 email address at the end of this manual page.
37
39 The simplest of the things srec_cat(1) can do is convert from one EPROM
40 file format to another. Please keep in mind, as you read this section,
41 that you can do many of these things simultaneously in one command.
42 They are only broken out separately to make them easier to understand.
43 Intel to Motorola
45 One of the simplest examples is converting files from Intel hex format
46 to Motorola S‐Record format:
47 srec_cat intel‐file -intel -o srec‐file
48 Pick any two formats that SRecord understands, it can convert between
49 all of them. (Except the assembler, BASIC, C and FPGA outputs which
50 are write only.)
51 Motorola to Intel
53 Converting the other way is just as simple:
54 srec_cat srec‐file -o intel‐file -intel
55 The default format is Motorola S‐Record format, so it does not need to
56 be specified.
57 Different Shapes of the Same Format
59 It is regrettably common that some addle‐pated EPROM programmers only
60 implement a portion of the specification used to represent their hex
61 files. For example, some compilers produce “s19” Motorola data (that
62 is, S1 data records with S9 start records, 16 bit address fields) which
63 would be OK except that some blockhead EPROM programmers insist on
64 “s37” Motorola data (that is, S3 data records with S7 start records, 32
65 bit address fields).
66 It is possible to convert from one Motorola shape to another using the
68 -Address‐Length option:
69 srec_cat short.srec -o long.srec -address‐length=4
70 This command says to use four byte (32‐bit) addresses on output.
71 This section also applies to Intel hex files, as they, too, have the
73 ability to select from a variety of address widths.
74 Line Lengths
76 From time to time you will come across a feeble‐minded EPROM programmer
77 that can't cope with long SRecord lines, they assume that there will
78 only ever be 16 bytes of data per line, and barf when they see the
79 default 32 byte payloads that srec_cat(1) writes.
80 The Motorola S‐record format definition permits up to 255 bytes of pay‐
82 load. All EPROM programmers should have sufficiently large buffers to
83 cope with records this big. Few do.
84 The -line‐length option may be used to specify the maximum line length
86 (not including the newline) to be used on output. For example, 16 byte
87 payloads for Motorola hex
88 srec_cat long.srec -o short.s19 -line‐length=46
89 The line length option interacts with the address length option, so
90 some tinkering to optimize for your particular situation many be neces‐
91 sary.
92 Just the Data, Please
94 There are some bonehead EPROM programmers which can only cope with data
95 records, and are unable to cope with header records or execution start
96 address records. If you have this problem, the -data‐only option can
97 be used to suppress just about everything except the data. The actual
98 effect depends on the format, of course, because some don't have these
99 features anyway.
100 The -data‐only option is short hand. There are four properties which
102 may be -disabled or -enabled separately. See the srec_cat(1) man page
103 for a description of the -disabled and -enabled options.
104 For example, your neanderthal EPROM programmer requires Motorola hex
106 with header records (S0), but without data count (S5) records. Not
107 using the -data‐only option has it barf on the data count record, but
108 using the -data‐only option has it barf on the missing header record.
109 Using the -disable=data‐count option would leave the header record
110 intact while supressing the data count record.
111 Data Headers
113 The srec_cat(1) command always tries to pass through header records
114 unchanged, whenever they are present. It even tries preserve them
115 across file format changes, to the limit the file formats are capable
116 of.
117 If there is no file header record and you would like to add one, or you
119 wish to override an existing file header record, use the -header=string
120 option. You will need to quote the string (to insulate it from the
121 shell) if it contains spaces or shell meta‐characters.
122 Execution Start Addresses
124 The srec_cat(1) command always tries to pass through execution start
125 addresses (typically occurring at the end of the file), whenever they
126 are present. They are adjusted along with the data records by the
127 -offset filter. It even tries preserve them across file format
128 changes, to the limit the file formats are capable of.
129 If there is no execution start address record and you would like to add
131 one, or you wish to override an existing execution start address
132 record, use the -execution‐start‐address=number option.
133 Please note: the execution start address is a different concept than
135 the first address in memory of your data. Think of it as a “goto”
136 address to be jumped to by the monitor when the hex load is complete.
137 If you want to change where your data starts in memory, use the -offset
138 filter.
139 Fixing Checksums
141 Some embedded firmware developers are saddled with featherbrained tools
142 which produce incorrect checksums, which the more vigilant models of
143 EPROM programmer will not accept.
144 To fix the checksums on a file, use the -ignore‐checksums option. For
146 example:
147 srec_cat broken.srec -ignore‐checksums -o fixed.srec
148 The checksums in broken.srec are parsed (it is still and error if they
149 are absent) but are not checked. The resulting fixed.srec file has
150 correct checksums. The -ignore‐checksums option only applies to input.
151 This option may be used on any file format which has checksums, includ‐
153 ing Intel hex.
154 Discovering Mystery Formats
156 See the What Format Is This? section, below, for how to discover and
157 convert mystery EPROM load file formats.
158
160 It is possible to convert to and from binary files. You can even mix
161 binary files and other formats together in the same srec_cat(1) com‐
162 mand.
163 Writing Binary Files
165 The simplest way of reading a hex file and converting it to a binary
166 file looks like this:
167 srec_cat fred.hex -o fred.bin -binary
168 This reads the Mororola hex file fred.srec and writes it out to the
169 fred.bin as raw binary.
170 Note that the data is placed into the binary file at the byte offset
172 specified by the addresses in the hex file. If there are holes in the
173 data they are filled with zero. This is, of course, common with linker
174 output where the code is placed starting at a particular place in mem‐
175 ory. For example, when you have an image that starts at 0x100000, the
176 first 1MB of the output binary file will be zero.
177 You can automatically cancel this offset using a command like
179 srec_cat fred.hex -offset − -minimum‐addr fred.hex -o fred.bin
180 The above command works by offseting the fred.hex file lower in memory
181 by the least address in the fred.hex file's data.
182 See also the srec_binary(5) man page for additional detail.
184 Reading Binary Files
186 The simplest way of reading a binary file and converting it looks like
187 this
188 srec_cat fred.bin -binary -o fred.srec
189 This reads the binary file fred.bin and writes all of its data back out
190 again as a Motorola S‐Record file.
191 Often, this binary isn't exactly where you want it in the address
193 space, because it is assumed to reside at address zero. If you need to
194 move it around use the -offset filter.
195 srec_cat fred.bin -binary -offset 0x10000 -o fred.srec
196 You also need to avoid file “holes” which are filled with zero. You
197 can use the -crop filter, of you could use the -unfill filter if you
198 done't know exactly where the data is.
199 srec_cat fred.bin -binary -unfill 0x00 512 -o fred.srec
200 The above command removes runs of zero bytes that are 512 bytes long or
201 longer. If your file contains 1GB of leading zero bytes, this is going
202 to be slow, it may be better to use the dd(1) command to slice and dice
203 first.
204
206 The srec_cat command takes its name from the UNIX cat(1) command, which
207 is short for “catenate” or “to join”. The srec_cat command joins EPROM
208 load files together.
209 All In One
211 Joining EPROM load files together into a single file is simple, just
212 name as many files on the command line as you need:
213 srec_cat infile1 infile2 -o outfile
214 This example is all Motorola S‐Record files, because that's the default
215 format. You can have multiple formats in the one command, and
216 srec_cat(1) will still work. You don't even have to output the same
217 format:
218 srec_cat infile1 -spectrum infile2 -needham \
219 -o outfile -signetics
220 These are all ancient formats, however it isn't uncommon to have to mix
221 and match Intel and Motorola formats in the one project.
222 Filtering After Joining
224 There are times when you want to join two sets of data together, and
225 then apply a filter to the joined result. To do this you use parenthe‐
226 ses.
227 srec_cat \
228 '(' \
229 infile -exclude 0xFFF0 0x10000 \
230 -generate 0xFFF0 0xFFF8 -repeat‐string 'Bananas ' \
231 ')' \
232 -b‐e‐length 0xFFF8 4 \
233 -b‐e‐checksum‐neg 0xFFFC 4 4 \
234 -o outfile
235 The above example command catenates an input file (with the generated
236 data area excluded) with a constant string. This catenated input is
237 then filtered to add a 4‐byte length, and a 4‐byte checksum.
238 Joining End‐to‐End
240 All too often the address ranges in the EPROM load files will overlap.
241 You will get an error if they do. If both files start from address
242 zero, because each goes into a separate EPROM, you may need to use the
243 offset filter:
244 srec_cat infile1 \
245 infile2 -offset 0x80000 \
246 -o outfile
247 Sometimes you want the two files to follow each other exactly, but you
248 don't know the offset in advance:
249 srec_cat infile1 \
250 infile2 -offset -maximum‐addr infile1 \
251 -o outfile
252 Notice that where the was a number (0x80000) before, there is now a
253 calculation (-maximum‐addr infile1). This is possible most places a
254 number may be used (also -minimum‐addr and -range).
255
257 It is possible to copy an EPROM load file, selecting addresses to keep
258 and addresses to discard.
259 What To Keep
261 A common activity is to crop your data to match your EPROM location.
262 Your linker may add other junk that you are not interested in, e.g. at
263 the RAM location. In this example, there is a 1MB EPROM at the 2MB
264 boundary:
265 srec_cat infile -crop 0x200000 0x300000 \
266 -o outfile
267 The lower bound for all address ranges is inclusive, the upper bound is
268 exclusive. If you subtract them, you get the number of bytes.
269 Address Offset
271 Just possibly, you have a moronic EPROM programmer, and it barfs if the
272 EPROM image doesn't start at zero. To find out just where is does
273 start in memory, use the srec_info(1) command:
274 $ srec_info example.srec
275 Format: Motorola S‐Record
276 Header: extra‐whizz tool chain linker
277 Execution Start Address: 0x00200000
278 Data: 0x200000 - 0x32AAEF
279 $
280 Rather than butcher the linker command file, just offset the addresses:
281 srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \
282 -o outfile
283 Note that the offset given is negative, it has the effect of subtract‐
284 ing that value from all addresses in the input records, to form the
285 output record addresses. In this case, shifting the image back to
286 zero.
287 This example also demonstrates how the input filters may be chained
289 together: first the crop and then the offset, all in one command, with‐
290 out the need for temporary files.
291 If all you want to do is offest the data to start from address zero,
293 this can be automated, so you don't have to know the minimum address in
294 advance, by using srec_cat's ability to calculate some things on the
295 command line:
296 srec_cat infile -offset − -minimum‐addr infile \
297 -o outfile
298 Note the spaces either side of the minus sign, they are mandatory.
299 What To Throw Away
301 There are times when you need to exclude an small address range from an
302 EPROM load file, rather than wanting to keep a small address range.
303 The -exclude filter may be used for this purpose.
304 For example, if you wish to exclude the address range where the serial
306 number of an embedded device is kept, say 0x20 bytes at 0x100, you
307 would use a command like this:
308 srec_cat input.srec -exclude 0x100 0x120 -o output.srec
309 The output.srec file will have a hole in the data at the necessary
310 locations.
311 Note that you can have both -crop and -exclude on the same command
313 line, whichever works more naturally for your situation.
314 Discontinuous Address Ranges
316 Address ranges don't have to be a single range, you can build up an
317 address range using more than a single pair.
318 srec_cat infile -crop 0x100 0x200 0x1000 0x1200 \
319 -o outfile
320 This filter results in data from 0x100..0x1FF and data from
321 0x1000..0x1200 to pass through, the rest is dropped. This is is more
322 efficient than chaining a -crop and an -exclude filter together.
323
325 It is also possible to change the address of data records, both for‐
326 wards and backwards. It is also possible rearrange where data records
327 are placed in memory.
328 Offset Filter
330 The -offset=number filter operates on the addresses of records. If the
331 number is positive the addresses move that many bytes higher in memory,
332 negative values move lower.
333 srec_cat infile -crop 0x200000 0x300000 -offset −0x200000 \
334 -o outfile
335 The above example moves the 1MB block of data at 0x200000 down to zero
336 (the offset is negative) and discards the rest of the data.
337 Byte Swapping
339 There are times when the bytes in the data need to be swapped, convert‐
340 ing between big‐endian and little‐endian data usually.
341 srec_cat infile -byte‐swap 4 -o outfile
342 This reverses bytes in 32 bit values (4 bytes). The default, if you
343 don't supply a width, is to reverse bytes in 16 bit values (2 bytes).
344 You can actually use any weird value you like, although 64 bits (8
345 bytes) may be useful one day.
346 Binary Output
348 You need to watch out for binary files on output, because the holes are
349 filled with zeros. Your 100kB program at the top of 32‐bit addressed
350 memory will make a 4GB file. See srec_binary(5) for how understand and
351 avoid this problem, usually with the -offset filter.
352 Splitting an Image
354 If you have a 16‐bit data bus, but you are using two 8‐bit EPROMs to
355 hold your firmware, you can generate the even and odd images by using
356 the -SPlit filter. Assuming your firmware is in the firmware.hex file,
357 use the following:
358 srec_cat firmware.hex -split 2 0 -o firmware.even.hex
359 srec_cat firmware.hex -split 2 1 -o firmware.odd.hex
360 This will result in the two necessary EPROM images. Note that the out‐
361 put addresses are divided by the split multiple, so if your EPROM
362 images are at a particular offset (say 0x10000, in the following exam‐
363 ple), you need to remove the offset, and then replace it...
364 srec_cat firmware.hex \
365 -offset −0x10000 -split 2 0 \
366 -offset 0x10000 -o firmware.even.hex
367 srec_cat firmware.hex \
368 -offset −0x10000 -split 2 1 \
369 -offset 0x10000 -o firmware.odd.hex
370 Note how the ability to apply multiple filters simplifies what would
371 otherwise be a much longer script.
372 Striping
374 A second use for the -SPlit filter is memory striping.
375 You don't have to split into byte‐wide parts, you can choose other
377 sizes. It is common to want to convert 32‐bit wide data into two set
378 of 16‐bit wide data.
379 srec_cat firmware.hex -split 4 0 2 -o firmware.01.hex
380 srec_cat firmware.hex -split 4 2 2 -o firmware.23.hex
381 This is relatively simple to understand, but you can use even wider
382 stripes.
383 In this next example, the hardware requires that 512‐byte blocks alter‐
385 nate between 4 EPROMs. Generating the 4 images would be done as fol‐
386 lows:
387 srec_cat firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
388 srec_cat firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
389 srec_cat firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
390 srec_cat firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex
391 Asymmetric Striping
393 A more peculiar example of striping is the Microchip dsPIC33F microcon‐
394 troller, that has a weird memory storage pattern and they are able to
395 store 3 bytes in an address that should only contain 2 bytes. The
396 result is a hex file that has zero‐filled the top byte (little endian),
397 and all addresses are doubled from what they are in the chip. Here is
398 an example:
399 S1130000000102000405060008090A000C0D0E0098
400 S1130010101112001415160018191A001C1D1E00C8
401 S1130020202122002425260028292A002C2D2E00F8
402 S1130030303132003435360038393A003C3D3E0028
403 To get rid of the 00 padding bytes, leaving only the 3/4 significant
404 bytes, you also use the split filter, with its additional width argu‐
405 ment, like this:
406 srec_cat example.srec -split 4 0 3 -o no_dross.srec
407 This results in a file with the 00 padding bytes removed. It looks
408 like this:
409 S113000000010204050608090A0C0D0E1011121451
410 S1130010151618191A1C1D1E2021222425262829EC
411 S11300202A2C2D2E30313234353638393A3C3D3E87
412 Notice how the addresses are 3/4 the size, as well. You can reverse
413 this using the -unsplit and -fill 0 filters.
414 Unspliting Images
416 The unsplit filter may be used to reverse the effects of the split fil‐
417 ter. Note that the address range is expanded leaving holes between the
418 stripes. By using all the stripes, the complete input is reassembled,
419 without any holes.
420 srec_cat -o firmware.hex \
421 firmware.even.hex -unsplit 2 0 \
422 firmware.odd.hex -unsplit 2 1
423 The above example reverses the previous 16‐bit data bus example. In
424 general, you unsplit with the same parameters that you split with.
425
427 Often EPROM load files will have “holes” in them, places where the com‐
428 piler and linker did not put anything. For some purposes this is OK,
429 and for other purposes something has to be done about the holes.
430 The Fill Filter
432 It is possible to fill the blanks where your data does not lie. The
433 simplest example of this fills the entire EPROM:
434 srec_cat infile -fill 0x00 0x200000 0x300000 -o outfile
435 This example fills the holes, if any, with zeros. You must specify a
436 range - with a 32‐bit address space, filling everything generates huge
437 load files.
438 If you only want to fill the gaps in your data, and don't want to fill
440 the entire EPROM, try:
441 srec_cat infile -fill 0x00 -over infile -o outfile
442 This example demonstrates the fact that wherever an address range may
443 be specified, the -over and -within options may be used.
444 Unfilling the Blanks
446 It is common to need to “unfill” an EPROM image after you read it out
447 of a chip. Usually, it will have had all the holes filled with 0xFF
448 (areas of the EPROM you don't program show as 0xFF when you read them
449 back).
450 To get rid of all the 0xFF bytes in the data, use this filter:
452 srec_cat infile -unfill 0xFF -o outfile
453 This will get rid of all the 0xFF bytes, including the ones you actu‐
454 ally wanted in there. There are two ways to deal with this. First,
455 you can specify a minimum run length to the un‐fill:
456 srec_cat infile -unfill 0xFF 5 -o outfile
457 This says that runs of 1 to 4 bytes of 0xFF are OK, and that a hole
458 should only be created for runs of 5 or more 0xFF bytes in a row. The
459 second method is to re‐fill over the intermediate gaps:
460 srec_cat outfile -fill 0xFF -over outfile \
461 -o outfile2
462 Which method you choose depends on your needs, and the shape of the
463 data in your EPROM. You may need to combine both techniques.
464 Address Range Padding
466 Some data formats are 16 bits wide, and automatically fill with 0xFF
467 bytes if it is necessary to fill out the other half of a word which is
468 not in the data. If you need to fill with a different value, you can
469 use a command like this:
470 srec_cat infile -fill 0x0A \
471 -within infile -range‐padding 2 \
472 -o outfile
473 This gives the fill filter an address range calculated from details of
474 the input file. The address range is all the address ranges covered by
475 data in the infile, extended downwards (if necessary) at the start of
476 each sub‐range to a 2 byte multiple and extended upwards (if necessary)
477 at the end of each sub‐range to a 2 byte multiple. This also works for
478 larger multiples, like 1kB page boundaries of flash chips. This
479 address range padding works anywhere an address range is required.
480 Fill with Copyright
482 It is possible to fill unused portions of your EPROM with a repeating
483 copyright message. Anyone trying to reverse engineer your EPROMs is
484 going to see the copyright notice in their hex editor.
485 This is accomplished with two input sources, one from a data file, and
487 one which is generated on‐the‐fly.
488 srec_cat infile \
489 -generate '(' 0 0x100000 -minus -within infile ')' \
490 -repeat‐string 'Copyright (C) 1812 Tchaikovsky. ' \
491 -o outfile
492 Notice how the address range for the data generation: it takes the
493 address range of your EPROM, in this case 1MB starting from 0, and sub‐
494 tracts from it the address ranges used by the input file.
495 If you want to script this with the current year (because 1812 is a bit
497 out of date) use the shell's output substitution (back ticks) ability:
498 srec_cat infile \
499 -generate '(' 0 0x100000 -minus -within infile ')' \
500 -repeat‐string "Copyright (C) `date +%Y` Tchaikovsky. " \
501 -o outfile
502 The string specified is repeated over and over again, until it has
504 filled all the holes.
505 Obfuscating with Noise
507 Sometimes you want to fill your EPROM images with noise, to conceal
508 where the real data stops and starts. You can do this with the -ran‐
509 dom‐fill filter.
510 srec_cat infile -random‐fill 0x200000 0x300000 \
511 -o outfile
512 It works just like the -fill filter, but uses random numbers instead of
513 a constant byte value.
514 Fill With 16‐bit Words
516 When filling the image with a constant byte value doesn't work, and you
517 need a constant 16‐bit word value instead, use the -repeat‐data genera‐
518 tor, which takes an arbitrarily long sequence of bytes to use as the
519 fill pattern:
520 srec_cat infile \
521 -generator '(' 0x200000 0x300000 -minus -within infile ')' \
522 -repeat‐data 0x1B 0x08 \
523 -o outfile
524 Notice how the generator's address range once again avoids the address
525 ranges occupied by the infile's data. You have to get the endian‐ness
526 right yourself.
527
529 From time to time you will want to insert constant data, or data not
530 produced by your compiler or assembler, into your EPROM load images.
531 Binary Means Literal
533 One simple way is to have the desired information in a file. To insert
534 the file's contents literally, with no format interpretation, use the
535 binary input format:
536 srec_cat infile -binary -o outfile
537 It will probably be necessary to use an offset filter to move the data
538 to where you actually want it within the image:
539 srec_cat infile -binary -offset 0x1234 -o outfile
540 It is also possible to use the standard input as a data source, which
541 lends itself to being scripted. For example, to insert the current
542 data and time into an EPROM load file, you could use a pipe:
543 date | srec_cat - -bin -offset 0xFFE3 -o outfile
544 The special file name “-” means to read from the standard input. The
545 output of the date command is always 29 characters long, and the offset
546 shown will place it at the top of a 64KB EPROM image.
547 Repeating Once
549 The Fill with Copyright section, above, shows how to repeat a string
550 over and over. We can use a single repeat to insert a string just
551 once.
552 srec_cat -generate 0xFFE3 0x10000 -repeat‐string "`date`" \
553 -o outfile
554 Notice how the address range for the data generation exactly matches
555 the length of the date(1) output size. You can, of course, add your
556 input file to the above srec_cat(1) command to catenate your EPROM
557 image together with the date and time.
558 Inserting A Long
560 Another possibility is to add the Subversion commit number to your
561 EPROM image. In this example, we are inserting it a a 4‐byte little‐
562 endian value at address 0x0008. The Subversion commit number is in the
563 $version shell variable in this exmaple:
564 srec_cat -generate 0x0008 0x000C -l‐e‐constant $version 4 \
565 infile -exclude 0x0008 0x000C \
566 -o outfile
567 Note that we use a filter to ensure there is a hole in the input where
568 the version number goes, just in case the linker put something there.
569
571 It is possible to add a variety of data about the data to the output.
572 Checksums
574 The -big‐endian‐checksum‐negative filter may be used to sum the data,
575 and then insert the negative of the sum into the data. This has the
576 effect of summing to zero when the checksum itself is summed across,
577 provided the sum width matches the inserted value width.
578 srec_cat infile \
579 -crop 0 0xFFFFFC \
580 -random‐fill 0 0xFFFFFC \
581 -b‐e‐checksum‐neg 0xFFFFFC 4 4 \
582 -o outfile
583 In this example, we have an EPROM in the lowest megabyte of memory.
584 The -crop filter ensures we are only summing the data within the EPROM,
585 and not anywhere else. The -random‐fill filter fills any holes left in
586 the data with random values. Finally, the -b‐e‐checksum‐neg filter
587 inserts a 32 bit (4 byte) checksum in big‐endian format in the last 4
588 bytes of the EPROM image. Naturally, there is a little endian version
589 of this filter as well.
590 Your embedded code can check the EPROM using C code similar to the fol‐
592 lowing:
593 unsigned long *begin = (unsigned long *)0;
594 unsigned long *end = (unsigned long *)0x100000;
595 unsigned long sum = 0;
596 while (begin < end)
597 sum += *begin++;
598 if (sum != 0)
599 {
600 Oops
601 }
602 The -big‐endian‐checksum‐bitnot filter is similar, except that summing
604 over the checksum should yield a value of all‐one‐bits (−1). For exam‐
605 ple, using shorts rather than longs:
606 srec_cat infile \
607 -crop 0 0xFFFFFE \
608 -fill 0xCC 0x00000 0xFFFFFE \
609 -b‐e‐checksum‐neg 0xFFFFFE 2 2 \
610 -o outfile
611 Assuming you chose the correct endian‐ness filter, your embedded code
612 can check the EPROM using C code similar to the following:
613 unsigned short *begin = (unsigned long *)0;
614 unsigned short *end = (unsigned long *)0x100000;
615 unsigned short sum = 0;
616 while (begin < end)
617 sum += *begin++;
618 if (sum != 0xFFFF)
619 {
620 Oops
621 }
622 There is also a -b‐e‐checksum‐positive filter, and a matching little‐
624 endian filter, which inserts the simple sum, and which would be checked
625 in C using an equality test.
626 srec_cat infile \
627 -crop 0 0xFFFFFF \
628 -fill 0x00 0x00000 0xFFFFFF \
629 -b‐e‐checksum‐neg 0xFFFFFF 1 1 \
630 -o outfile
631 Assuming you chose the correct endian‐ness filter, your embedded code
632 can check the EPROM using C code similar to the following:
633 unsigned char *begin = (unsigned long *)0;
634 unsigned char *end = (unsigned long *)0xFFFFF;
635 unsigned char sum = 0;
636 while (begin < end)
637 sum += *begin++;
638 if (sum != *end)
639 {
640 Oops
641 }
642 In the 8‐bit case, it doesn't matter whether you use the big‐endian or
643 little‐endian filter.
644 Quick Hex‐Dump
646 You can look at the checksum of your data, by using the “hex‐dump” out‐
647 put format. This is useful for looking at calculated values, or for
648 debugging an srec_cat(1) command before immortalising it in a script.
649 srec_cat infile \
650 -crop 0 0x10000 \
651 -fill 0xFF 0x0000 0x10000 \
652 -b‐e‐checksum‐neg 0x10000 4 \
653 -crop 0x10000 0x10004 \
654 -o - -hex‐dump
655 This command reads in the file, checksums the data and places the
656 checksum at 0x10000, crops the result to contain only the checksum, and
657 then prints the checksum on the standard output in a classical hexadec‐
658 imal dump format.
659 Cyclic Redundancy Checks
661 The simple additive checksums have a number of theoretical limitations,
662 to do with errors they can and can't detect. The CRC methods have
663 fewer problems.
664 srec_cat infile \
665 -crop 0 0xFFFFFC \
666 -fill 0x00 0x00000 0xFFFFFC \
667 -b‐e‐crc32 0xFFFFFC \
668 -o outfile
669 In the above example, we have an EPROM in the lowest megabyte of mem‐
670 ory. The -crop filter ensures we are only summing the data within the
671 EPROM, and not anywhere else. The -fill filter fills any holes left in
672 the data. Finally, the -b‐e‐checksum‐neg filter inserts a 32 bit (4
673 byte) checksum in big‐endian format in the last 4 bytes of the EPROM
674 image. Naturally, there is a little endian version of this filter as
675 well.
676 The checksum is calculated using the industry standard 32‐bit CRC.
678 Because SRecord is open source, you can always read the source code to
679 see how it works. There are many non‐GPL version of this code avail‐
680 able on the Internet, and suitable for embedding in proprietary
681 firmware.
682 There is also a 16‐bit CRC available.
684 srec_cat infile \
685 -crop 0 0xFFFFFE \
686 -fill 0x00 0x00000 0xFFFFFE \
687 -b‐e‐crc16 0xFFFFFE \
688 -o outfile
689 The checksum is calculated using the CCITT formula. Because SRecord is
691 open source, you can always read the source code to see how it works.
692 There are many non‐GPL version of this code available on the Internet,
693 and suitable for embedding in proprietary firmware.
694 You can look at the CRC of your data, by using the “hex‐dump” output
696 format.
697 srec_cat infile \
698 -crop 0 0x10000 \
699 -fill 0xFF 0x0000 0x10000 \
700 -b‐e‐crc16 0x10000 \
701 -crop 0x10000 0x10002 \
702 -o - -hex‐dump
703 This command reads in the file, calculates the CRC of the data and
704 places the CRC at 0x10000, crops the result to contain only the CRC,
705 and then prints the checksum on the standard output in a classical
706 hexadecimal dump format.
707 Where Is My Data?
709 There are several properties of you EPROM image that you may wish to
710 insert into the data.
711 srec_cat infile -b‐e‐minimum 0xFFFE 2 -o outfile
712 The above example inserts the minimum address of the data (low water)
713 into the data, as two bytes in big‐endian order at address 0xFFFE.
714 This includes the minimum itself. If the data already contains bytes
715 at the given address, you need to use an exclude filter. The number of
716 bytes defaults to 4.
717 There is also a -l‐e‐minimum filter for inserting little‐endian values,
719 and two more filters called -b‐e‐exclusive‐minimum and -l‐e‐exclusive‐
720 minimum that do not include the minimum itself in the calculation of
721 the minimum data address.
722 srec_cat infile -b‐e‐maximum 0xFFFFFC 4 -o outfile
723 The above example inserts the maximum address of the data (high water +
724 1, just like address ranges) into the data, as four bytes in big‐endian
725 order at address 0xFFFFFC. This includes the maximum itself. If the
726 data already contains bytes at the given address, you need to use an
727 exclude filter. The number of bytes defaults to 4.
728 There is also a -l‐e‐maximum filter for inserting little‐endian values,
730 and two more filters called -b‐e‐exclusive‐maximum and -l‐e‐exclusive‐
731 maximum that do not include the maximum itself in the calculation of
732 the maximum data address.
733 srec_cat infile -b‐e‐length 0xFFFFFC 4 -o outfile
734 The above example inserts the length of the data (high water + 1 − low
735 water) into the data, as four bytes in big‐endian order at address
736 0xFFFFFC. This includes the length itself. If the data already con‐
737 tains bytes at the length location, you need to use an exclude filter.
738 The number of bytes defaults to 4.
739 There is also a -l‐e‐length filter for inserting a little‐endian
741 length, and the -b‐e‐exclusive‐length and -l‐e‐exclusive‐length filters
742 that do not include the length itself in the calaculation.
743 What Format Is This?
745 You can obtain a variety of information about an EPROM load file by
746 using the srec_info(1) command. For example:
747 $ srec_info example.srec
748 Format: Motorola S‐Record
749 Header: "http://srecord.sourceforge.net/"
750 Execution Start Address: 00000000
751 Data: 0000 - 0122
752 0456 - 0FFF
753 $
754 This example show that the file is a Motorola S‐Record. The text in
755 the file header is printed, along with the execution start address.
756 The final section shows the address ranges containing data (the upper
757 bound of each subrange is inclusive, rather than the exclusive form
758 used on the command line.
759 $ srec_info some‐weird‐file.hex -guess
760 Format: Signetics
761 Data: 0000 - 0122
762 0456 - 0FFF
763 $
764 The above example guesses the EPROM load file format. It isn't infal‐
765 lible but it usually gets it right. You can use -guess anywhere you
766 would give an explicit format, but it tends to be slower and for that
767 reason is not recommended.
768
770 It is possible to change the values of the data bytes in several ways.
771 srec_cat infile -and 0xF0 -o outfile
772 The above example performs a bit‐wise AND of the data bytes with the
773 0xF0 mask. The addresses of records are unchanged. I can't actually
774 think of a use for this filter.
775 srec_cat infile -or 0x0F -o outfile
776 The above example performs a bit‐wise OR of the data bytes with the
777 0x0F bits. The addresses of records are unchanged. I can't actually
778 think of a use for this filter.
779 srec_cat infile -xor 0xA5 -o outfile
780 The above example performs a bit‐wise exclusive OR of the data bytes
781 with the 0xA5 bits. The addresses of records are unchanged. You could
782 use this to obfuscate the contents of your EPROM.
783 srec_cat infile -not -o outfile
784 The above example performs a bit‐wise NOT of the data bytes. The
785 addresses of records are unchanged. Security by obscurity?
786
788 srec_cat version 1.55
789 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
790 2007, 2008, 2009, 2010 Peter Miller
791 The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use
793 the 'srec_cat -VERSion License' command. This is free software and you
794 are welcome to redistribute it under certain conditions; for details
795 use the 'srec_cat -VERSion License' command.
796
798 Peter Miller E‐Mail: pmiller@opensource.org.au
799 /\/\* WWW: http://miller.emu.id.au/pmiller/
800Reference Manual SRecord srec_examples(1)