1srec_input(1) General Commands Manual srec_input(1)
2
3
4
6 srec_input - input file specifications
7
9 srec_* filename [ format ]
10
12 This manual page describes the input file specifications for the
13 srec_cat(1), srec_cmp(1) and srec_info(1) commands.
14
15 Input files may be qualified in a number of ways: you may specify their
16 format and you may specify filters to apply to them. An input file
17 specification looks like this:
18 filename [ format ][ -ignore-checksums ][ filter ... ]
19
20 The filename The filename may be specified as a file name, or the spe‐
21 cial name “-” which is understood to mean the standard input.
22
23 File Formats
24 The format is specified by the argument after the file name. The for‐
25 mat defaults to Motorola S-Record if not specified. The format speci‐
26 fied are:
27
28 -Absolute_Object_Module_Format
29 This option says to use the Intel Absolute Object Module Format
30 (AOMF) to read the file. (See srec_aomf(5) for a description
31 of this file format.)
32
33 -Ascii-Hex
34 This option says to use the Ascii-Hex format to read the file.
35 See srec_ascii_hex(5) for a description of this file format.
36
37 -Atmel_Generic
38 This option says to use the Atmel Generic format to read the
39 file. See srec_atmel_genetic(5) for a description of this file
40 format.
41
42 -Binary This option says the file is a raw binary file, and should be
43 read literally. (This option may also be written -Raw.) See
44 srec_binary(5) for more information.
45
46 -B-Record
47 This option says to use the Freescale MC68EZ328 Dragonball
48 bootstrap b-record format to read the file. See
49 srec_brecord(5) for a description of this file format.
50
51 -COsmac This option says to use the RCA Cosmac Elf format to read the
52 file. See srec_cosmac(5) for a description of this file for‐
53 mat.
54
55 -Dec_Binary
56 This option says to use the DEC Binary (XXDP) format to read
57 the file. See srec_dec_binary(5) for a description of this
58 file format.
59
60 -Elektor_Monitor52
61 This option says to use the EMON52 format to read the file.
62 See srec_emon52(5) for a description of this file format.
63
64 -FAIrchild
65 This option says to use the Fairchild Fairbug format to read
66 the file. See srec_fairchild(5) for a description of this file
67 format.
68
69 -Fast_Load
70 This option says to use the LSI Logic Fast Load format to read
71 the file. See srec_fastload(5) for a description of this file
72 format.
73
74 -Formatted_Binary
75 This option says to use the Formatted Binary format to read the
76 file. See srec_formatted_binary(5) for a description of this
77 file format.
78
79 -Four_Packed_Code
80 This option says to use the FPC format to read the file. See
81 srec_fpc(5) for a description of this file format.
82
83 -Guess This option may be uased to ask srec_input to guess the input
84 format. This is slower than specifying an explicit format, as
85 it may open and close the file a number of times.
86
87 -Intel This option says to use the Intel hex format to read the file.
88 See srec_intel(5) for a description of this file format.
89
90 -INtel_HeX_16
91 This option says to use the Intel hex 16 (INHX16) format to
92 read the file. See srec_intel16(5) for a description of this
93 file format.
94
95 -MOS_Technologies
96 This option says to use the Mos Technologies format to read the
97 file. See srec_mos_tech(5) for a description of this file for‐
98 mat.
99
100 -Motorola [ width ]
101 This option says to use the Motorola S-Record format to read
102 the file. (May also be written -S-Record.) See
103 srec_motorola(5) for a description of this file format.
104
105 The optional width argument describes the number of bytes which
106 form each address multiple. For normal uses the default of one
107 (1) byte is appropriate. Some systems with 16-bit or 32-bit
108 targets mutilate the addresses in the file; this option will
109 correct for that. Unlike most other parameters, this one can‐
110 not be guessed.
111
112 -Needham_Hexadecimal
113 This option says to use the Needham Electronics ASCII file for‐
114 mat to read the file. See srec_needham(5) for a description of
115 this file format.
116
117 -Ohio_Scientific
118 This option says to use the Ohio Scientific format. See
119 srec_os65v(5) for a description of this file format.
120
121 -SIGnetics
122 This option says to use the Signetics format. See
123 srec_spasm(5) for a description of this file format.
124
125 -SPAsm This option says to use the SPASM assembler output format (com‐
126 monly used by PIC programmers). See srec_spasm(5) for a
127 description of this file format.
128
129 -SPAsm_LittleEndian
130 This option says to use the SPASM assembler output format (com‐
131 monly used by PIC programmers). But with the data the other
132 way around.
133
134 -STewie This option says to use the Stewie binary format to read the
135 file. See srec_stewie(5) for a description of this file for‐
136 mat.
137
138 -Tektronix
139 This option says to use the Tektronix hex format to read the
140 file. See srec_tektronix(5) for a description of this file
141 format.
142
143 -Tektronix_Extended
144 This option says to use the Tektronix extended hex format to
145 read the file. See srec_tektronix_extended(5) for a descrip‐
146 tion of this file format.
147
148 -Texas_Instruments_Tagged
149 This option says to use the Texas Instruments Tagged format to
150 read the file. See srec_ti_tagged(5) for a description of this
151 file format.
152
153 -Texas_Instruments_Tagged_16
154 This option says to use the Texas Instruments SDSMAC 320 format
155 to read the file. See srec_ti_tagged_16(5) for a description
156 of this file format.
157
158 -Texas_Instruments_TaXT
159 This option says to use the Texas Instruments TXT (MSP430) for‐
160 mat to read the file. See srec_ti_txt(5) for a description of
161 this file format.
162
163 -VMem This option says to use the Verilog VMEM format to read the
164 file. See srec_vmem(5) for a description of this file format.
165
166 -WILson This option says to use the wilson format to read the file.
167 See srec_wilson(5) for a description of this file format.
168
169 Ignore Checksums
170 The -ignore-checksums option may be used to disable checksum validation
171 of input files, for those formats which have checksums at all. Note
172 that the checksum values are still read in and parsed (so it is still
173 an error if they are missing) but their values are not checked. Used
174 after an input file name, the option affects that file alone; used any‐
175 where else on the command line, it applies to all following files.
176
177 Generators
178 It is also possible to generate data, rather than read it from a file.
179 You may use a generator anywhere you could use a file. An input gener‐
180 ator specification looks like this:
181
182 -GENerate address-range -data-source
183
184 The -data-source may be one of the following:
185
186 -CONSTant number
187 This generator manufactures data with the given byte value of
188 the the given address range. For example, to fill memory
189 addresses 100..199 with newlines (0x0A), you could use a com‐
190 mand like
191
192 srec_cat -generate 100 200 -constant 10 -o newlines.srec
193
194 This can, of course, be combined with data from files.
195
196 -REPeat_Data number...
197 This generator manufactures data with the given byte values
198 repeating over the the given address range. For example, to
199 create a data region with 0xDE in the even bytes and 0xAD in
200 the odd bytes, use a generator like this:
201
202 srec_cat -generate 0x1000 0x2000 -repeat-data 0xDE 0xAD
203
204 The repeat boundaries are aligned with the base of the address
205 range, modulo the number of bytes.
206
207 -REPeat_String text
208 This generator is almost identical to -repeat-data except that
209 the data to be repeated is the text of the given string. For
210 example, to fill the holes in an eprom image eprom.srec with
211 the text “Copyright (C) 1812 Tchaikovsky”, combine a generator
212 and an -exclude filter, such as the command
213
214 srec_cat eprom.srec \
215 -generate 0 0x100000 \
216 -repeat-string 'Copyright (C) 1812 Tchaikovsky. ' \
217 -exclude -within eprom.srec \
218 -o eprom.filled.srec
219
220 The thing to note is that we have two data sources: the
221 eprom.srec file, and generated data over an address range which
222 covers first megabyte of memory but excluding areas covered by
223 the eprom.srec data.
224
225 Anything else will result in an error.
226
227 Input Filters
228 You may specify zero or more filters to be applied. Filters are
229 applied in the order the user specifies.
230
231 -Big_Endian_Checksum_BitNot address [ nbytes [ width ]]
232 This filter may be used to insert the one's complement checksum
233 of the data into the data, most significant byte first. The
234 data is literaly summed; if there are duplicate bytes, this
235 will produce an incorrect result, if there are holes, it will
236 be as if they were filled with zeros. If the data already con‐
237 tains bytes at the checksum location, you need to use an
238 exclude filter, or this will generate errors. You need to
239 apply and crop or fill filters before this filter. The value
240 will be written with the most significant byte first. The num‐
241 ber of bytes of resulting checksum defaults to 4. The width
242 (the width in bytes of the values being summed) defaults to 1.
243
244 -Big_Endian_Checksum_Negative address [ nbytes [ width ]]
245 This filter may be used to insert the two's complement (nega‐
246 tive) checksum of the data into the data. Otherwise similar to
247 the above.
248
249 -Big_Endian_Checksum_Positive address [ nbytes [ width ]]
250 This filter may be used to insert the simple checksum of the
251 data into the data. Otherwise similar to the above.
252
253 -Little_Endian_Checksum_BitNot address [ nbytes [ width ]]
254 This filter may be used to insert the one's complement (bitnot)
255 checksum of the data into the data, least significant byte
256 first. Otherwise similar to the above.
257
258 -Little_Endian_Checksum_Negative address [ nbytes [ width ]]
259 This filter may be used to insert the two's complement (nega‐
260 tive) checksum of the data into the data. Otherwise similar to
261 the above.
262
263 -Little_Endian_Checksum_Negative address [ nbytes [ width ]]
264 This filter may be used to insert the simple checksum of the
265 data into the data. Otherwise similar to the above.
266
267 -Byte_Swap [ width ]
268 This filter may be used to swap pairs of odd and even bytes.
269 By specifying a width (in bytes) it is possible to reverse the
270 order of 4 and 8 bytes, the default is 2 bytes. (Widths in
271 excess of 8 are assumed to be number of bits.) It is not pos‐
272 suble to swap non-power-of-two addresses. To change the align‐
273 ment, use the offset filter before and after.
274
275 -Big_Endian_CRC16 address [ -Cyclic_Redundancy_Check_16_XMODEM ]
276 This filter may be used to insert an industry standard 16-bit
277 CRC checksum of the data into the data. Two bytes, big-endian
278 order, are inserted at the address given. Holes in the input
279 data are ignored. Bytes are processed in ascending address
280 order (not in the order they appear in the input).
281
282 By default a CCITT calculation is performed. If the optional
283 -Cyclic_Redundancy_Check_16_XMODEM argument is present, the
284 alternate XMODEM calculation is performed.
285
286 Note: If you have holes in your data, you will get a different
287 CRC than if there were no holes. This is important because the
288 in-memory EEPROM image will not have holes. You almost always
289 want to use the -fill filter before any of the CRC filters.
290 You will receive a warning if the data presented for CRC has
291 holes.
292
293 You should also be aware that the lower and upper bounds of
294 your data may not be the same as the lower and upper bounds of
295 your EEPROM. This is another reason to use the -fill filter,
296 because it will establish the data across the full EEPROM
297 address range.
298
299 -Little_Endian_CRC16 address
300 As above, except little-endian order.
301
302 -Big_Endian_CRC32 address
303 This filter may be used to insert an industry standard 32-bit
304 CRC checksum of the data into the data. Four bytes, big-endian
305 order, are inserted at the address given. Holes in the input
306 data are ignored. Bytes are processed in ascending address
307 order (not in the order they appear in the input). See also
308 the note about holes, above.
309
310 -Little_Endian_CRC32 address
311 As above, except little-endian order.
312
313 -Crop address-range
314 This filter may be used to isolate a section of data, and dis‐
315 card the rest.
316
317 -Exclude address-range
318 This filter may be used to exclude a section of data, and keep
319 the rest. The is the logical complement of the -Crop filter.
320
321 -Fill value address-range
322 This filter may be used to fill any gaps in the data with bytes
323 equal to value. The fill will only occur in the address range
324 given.
325
326 -UnFill value [ min-run-length ]
327 This filter may be used to create gaps in the data with bytes
328 equal to value. You can think of it as reversing the effects
329 of the -Fill filter. The gaps will only be created if the are
330 at least min-run-length bytes in a row (defaults to 1).
331
332 -Random_Fill address-range
333 This filter may be used to fill any gaps in the data with ran‐
334 dom bytes. The fill will only occur in the address range
335 given.
336
337 -AND value
338 This filter may be used to bit-wise AND a value to every data
339 byte. This is useful if you need to clear bits. Only existing
340 data is altered, no holes are filled.
341
342 -eXclusive-OR value
343 This filter may be used to bit-wise XOR a value to every data
344 byte. This is useful if you need to invert bits. Only exist‐
345 ing data is altered, no holes are filled.
346
347 -OR value
348 This filter may be used to bit-wise OR a value to every data
349 byte. This is useful if you need to set bits. Only existing
350 data is altered, no holes are filled.
351
352 -NOT This filter may be used to bit-wise NOT the value of every data
353 byte. This is useful if you need to invert the data. Only
354 existing data is altered, no holes are filled.
355
356 -Big_Endian_Length address [ nbytes ]
357 This filter may be used to insert the length of the data (high
358 water minus low water) into the data. This includes the length
359 itself. If the data already contains bytes at the length loca‐
360 tion, you need to use an exclude filter, or this will generate
361 errors. The value will be written with the most significant
362 byte first. The number of bytes defaults to 4.
363
364 -Little_Endian_Length address [ nbytes ]
365 As above, however the value will be written with the least sig‐
366 nificant byte first.
367
368 -Big_Endian_MAXimum address [ nbytes ]
369 This filter may be used to insert the maximum address of the
370 data (high water
371 + 1) into the data. This includes the maximum itself. If the
372 data already contains bytes at the given address, you need to
373 use an exclude filter, or this will generate errors. The value
374 will be written with the most significant byte first. The num‐
375 ber of bytes defaults to 4.
376
377 -Little_Endian_MAXimum address [ nbytes ]
378 As above, however the value will be written with the least sig‐
379 nificant byte first.
380
381 -Big_Endian_MINimum address [ nbytes ]
382 This filter may be used to insert the minimum address of the
383 data (low water) into the data. This includes the minimum
384 itself. If the data already contains bytes at the given
385 address, you need to use an exclude filter, or this will gener‐
386 ate errors. The value will be written with the most signifi‐
387 cant byte first. The number of bytes defaults to 4.
388
389 -Little_Endian_MINimum address [ nbytes ]
390 As above, however the value will be written with the least sig‐
391 nificant byte first.
392
393 -OFfset nbytes
394 This filter may be used to offset the addresses by the given
395 number of bytes. No data is lost, the addresses will wrap
396 around in 32 bits, if necessary. You may use negative numbers
397 for the offset, if you wish to move data lower in memory.
398
399 -SPlit multiple [ offset [ width ] ]
400 This filter may be used to split the input into a subset of the
401 data, and compress the address range so as to leave no gaps.
402 This useful for wide data buses and memory striping. The mul‐
403 tiple is the bytes multiple to split over, the offset is the
404 byte offset into this range (defaults to 0), the width is the
405 number of bytes to extract (defaults to 1) within the multiple.
406 In order to leave no gaps, the output addresses are (width /
407 multiple) times the input addresses.
408
409 -Un_SPlit multiple [ offset [ width ] ]
410 This filter may be used to reverse the effects of the split
411 filter. The arguments are identical. Note that the address
412 range is expanded (multiple / width) times, leaving holes
413 between the stripes.
414
415 Address Ranges
416 There are three ways to specify an address range:
417
418 minimum maximum
419 If you specify two number on the command line (decimal, octal
420 and hexadecimal are understood, using the C conventions) this
421 is an explicit address range. The minimum is inclusive, the
422 maximum is exclusive (one more than the last address). If the
423 maximum is given as zero then the range extends to the end of
424 the address space.
425
426 -Within input-specification
427 This says to use the specified input file as a mask. The range
428 includes all the places the specified input has data, and holes
429 where it has holes. The input specification need not be just a
430 file name, it may be anything any other input specification can
431 be. (You may need to enclose input-specification in parenthe‐
432 ses to make sure it can't misinterpret which arguments go with
433 input specification.)
434
435 -OVER input-specification
436 This says to use the specified input file as a mask. The range
437 extends from the minimum to the maximum address used by the
438 input, and ignores any holes. The input specification need not
439 be just a file name, it may be anything any other input speci‐
440 fication can be. (You may need to enclose input-specification
441 in parentheses to make sure it can't misinterpret which argu‐
442 ments go with input specification.)
443
444 address-range -RAnge-PADding number
445 It is also possible to pad ranges to be whole aligned multiples
446 of the given number. For example
447 input-file -fill 0xFF -within input-file -range-pad 512
448 will fill the input-file so that it consists of whole 512-byte
449 blocks, aligned on 512 byte boundaries. Any large holes in the
450 data will also be multiples of 512 bytes, though they may have
451 been shrunk as blocks before and after are padded.
452
453 This operator has the same precedence as the explicit union
454 operator.
455
456 address-range -INTERsect address-range
457 You can intersect two address ranges to produce a smaller
458 address range. The insersection operator has higher precedence
459 than the implicit union operator (evaluated left to right).
460
461 address-range -UNIon address-range
462 You can union two address ranges to produce a larger address
463 range. The union operator has lower precedence than the inter‐
464 section operator (evaluated left to right).
465
466 address-range -DIFference address-range
467 You can difference two address ranges to produce a smaller
468 address range. The result is the left hand range with all of
469 the right hand range removed. The difference operator has the
470 same precedence as the implicit union operator (evaluated left
471 to right).
472
473 address-range address-range
474 In addition, all of these methods may be used, and used more
475 than once, and the results will be combined (implicit union
476 operator, same precedence as explicit union operator).
477
478 Calculated Values
479 Most of the places above where a number is expected, you may supply one
480 of the following:
481
482 -MINimum input-specification
483 This inserts the minimum address of the specified input file.
484 The input specification need not be just a file name, it may be
485 anything any other input specification can be. (You may need
486 to enclose input-specification in parentheses to make sure it
487 can't misinterpret which arguments go with input specifica‐
488 tion.)
489
490 -MAXimum input-specification
491 This inserts the maximum address of the specified input file,
492 plus one. The input specification need not be just a file
493 name, it may be anything any other input specification can be.
494 (You may need to enclose input-specification in parentheses to
495 make sure it can't misinterpret which arguments go with input
496 specification.)
497
498 -Length input-specification
499 This inserts the length of the address range in the specified
500 input file, ignoring any holes. The input specification need
501 not be just a file name, it may be anything any other input
502 specification can be. (You may need to enclose input-specifi‐
503 cation in parentheses to make sure it can't misinterpret which
504 arguments go with input specification.)
505
506 For example, the -OVER file option can be thought of a short-hand for
507 '(' -min file -max file ')', except that it is much easier to type, and
508 also more efficient.
509
510 In addition, calculated values may optionally be rounded in one of
511 three ways:
512
513 value -Round_Down number
514 The value is rounded down to the the largest integer smaller
515 than or equal to a whole multiple of the number.
516
517 value -Round_Nearest number
518 The value is rounded to the the nearest whole multiple of the
519 number.
520
521 value -Round_Up number
522 The value is rounded up to the the smallest integer larger than
523 or equal to a whole multiple of the number.
524
525 When using parentheses, they must each be a separate command line argu‐
526 ment, they can't be within the text of the preceeding or following
527 option, and you will need to quote them to get them past the shell, as
528 '(' and ')'.
529
531 srec_input version 1.35
532 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
533 2007 Peter Miller
534
535 The srec_input program comes with ABSOLUTELY NO WARRANTY; for details
536 use the 'srec_input -VERSion License' command. This is free software
537 and you are welcome to redistribute it under certain conditions; for
538 details use the 'srec_input -VERSion License' command.
539
541 Peter Miller E-Mail: millerp@canb.auug.org.au
542 /\/\* WWW: http://www.canb.auug.org.au/~millerp/
543
544
545
546Reference Manual SRecord srec_input(1)