1srec_cat(1) General Commands Manual srec_cat(1)
2
6 srec_cat - manipulate EPROM load files
7
9 srec_cat [ option... ] filename...
10 srec_cat -Help
11 srec_cat -VERSion
12
14 The srec_cat program is used to assemble the given input files into a
15 single output file. The use of filters (see below) allows significant
16 manipulations to be performed by this command.
17 Data Order
19 The data from the input files is not immediately written to the output,
20 but is stored in memory until the complete EPROM image has been assem‐
21 bled. Data is then written to the output file in ascending address
22 order. The original ordering of the data (in those formats capable of
23 random record ordering) is not preserved.
24 Data Comparison
26 Because input record order is not preserved, textual comparison of
27 input and output (such as the diff(1) or tkdiff(1) commands) can be
28 misleading. Not only can lines appear in different address orders, but
29 line lengths and line termination can differ as well. Use the
30 srec_cmp(1) program to compare two EPROM load files. If a text compar‐
31 ison is essential, run both files through the srec_cat(1) program to
32 ensure both files to be compared have identical record ordering and
33 line lengths.
34 Data Conflicts
36 The storing of data in memory enables the detection of data conflicts,
37 typically caused by linker sections unintentionally overlapping.
38 · A warning will be issued for each address which is redundantly set to
40 the same value.
41 · A fatal error will be issued if any address is set with contradictory
43 values. To avoid this error use an -exclude -within filter (see
44 srec_input(1)) or, to make it a warning, use the -contradictory‐bytes
45 option (see below).
46 · A warning will be issued for input files where the data records are
48 not in strictly ascending address order. To suppress this warning,
49 use the -disable‐sequence‐warning option (see below).
50 These features are designed to detect problems which are difficult to
52 debug, and detects them before the data is written to an EPROM and run
53 in your embedded system.
54
56 Input may be qualified in two ways: you may specify a data file or a
57 data generator. format and you may specify filters to apply to them.
58 An input file specification looks like this:
59 data‐file [ filter ... ]
60 data‐generator [ filter ... ]
61 Data Files
63 Input from data files is specified by file name and format name. An
64 input file specification looks like this:
65 filename [ format ][ -ignore‐checksums ]
66 The default format is Motorola S‐Record format, but many others are
67 also understood.
68 Data Generators
70 It is also possible to generate data, rather than read it from a file.
71 You may use a generator anywhere you could use a file. An input gener‐
72 ator specification looks like this:
73 -GENerate address‐range -data‐source
74 Generators include random data and various forms of constant data.
75 Common Manual Page
77 See srec_input(1) for complete details of input specifiers. This
78 description is in a separate manual page because it is common to more
79 than one SRecord command.
80
82 The following options are understood:
83 @filename
85 The named text file is read for additional command line argu‐
86 ments. Arguments are separated by white space (space, tab,
87 newline, etc). There is no wildcard mechanism. There is no
88 quoting mechanism. Comments, which start with '#' and extend
89 to the end of the line, are ignored. Blank lines are ignored.
90 -Output filename [ format ]
92 This option may be used to specify the output file to be used.
93 The special file name “-[rq] is understood to mean the standard
94 output. Output defaults to the standard output if this option
95 is not used.
96 The format may be specified as:
98 -Absolute_Object_Module_Format
100 An Intel Absolute Object Module Format file will be
101 written. (See srec_aomf(5) for a description of this
102 file format.)
103 -Ascii_Hex
105 An Ascii‐Hex file will be written. (See
106 srec_ascii_hex(5) for a description of this file for‐
107 mat.)
108 -ASM [ prefix ][ -option... ]
110 A series of assembler DB statements will be written.
111 The optional prefix may be specified to change the
113 names of the symbols generated. The defaults to
114 "eprom" if not set.
115 Several options are available to modify the style of
117 output:
118 -Dot_STyle
120 Use "dot" style pseudo‐ops instead of words.
121 For example .byte instead of the DB default.
122 -HEXadecimal_STyle
124 Use hexadecimal numbers in the output, rather
125 than the default decimal numbers.
126 -Section_STyle
128 By default the generated assemble of placed at
129 the correct address using ORG pseudo‐ops. Sec‐
130 tion style output emits tables of section
131 addresses and lengths, so the data may be
132 related at runtime.
133 -A430 Generate output which is compliant to the
135 a430.exe compiler as it is used, e.g. in IAR
136 Embedded Workbench. This is short‐hand for
137 -section‐style -hex‐style
138 -CL430 Generate output which is Code Composer Essen‐
140 tials compliant, i.e. the compiler of it. This
141 is short‐hand for -section‐style -hex‐style
142 -dot‐style
143 -Output_Word
145 Generate output which is in two‐byte words
146 rather than bytes. This assumes little‐endian
147 words; you will need to use the -Byte‐Swap fil‐
148 ter if your target is big‐endian. No attempt
149 is made to align the words onto even address
150 boundaries; use and input filter such as
151 input‐file -fill 0xFF -within input‐file
152 -range‐pad 2
153 to pad the data to whole words first.
154 -Atmel_Generic
156 An Atmel Generic file will be written. (See
157 srec_atmel_generic(5) for a description of this file
158 format.)
159 -BASic A series of BASIC DATA statements will be written.
161 -B‐Record
163 A Freescale MC68EZ328 Dragonball bootstrap b‐record
164 format file will be written. (See srec_brecord(5) for
165 a description of this file format.)
166 -Binary A raw binary file will be written. If you get unex‐
168 pected results please see the srec_binary(5) manual for
169 more information.
170 -C‐Array [ identifier ][ -option... ]
172 A C array defintion will be written.
173 The optional identifier is the name of the variable to
175 be defined, or bugus if not specified.
176 -INClude
178 This option asks for an include file to be gen‐
179 erated as well.
180 -No‐CONST
182 This options asks for the variables to not use
183 the const keyword (they are declared constant
184 be default, so that they are placed into the
185 read‐only segment in embedded systems).
186 -C_COMpressed
188 These options ask for an compressed c‐array
189 whose memory gaps will not be filled.
190 -Output_Word
192 This option asks for an output which is in
193 words not in bytes. This is little endian, so
194 you may need to
195 -PREfix string
197 This option allows a string to be prepended to
198 the array definition. This is commonly used for
199 non‐standard options common to cross compilers.
200 -POSTfix string
202 This option allows a string to be appended to
203 the array definition. This is commonly used for
204 non‐standard options common to cross compilers.
205 -COE This option says to use the Xilinx Coefficient File
207 Format (.coe) for output. (See srec_coe(5) for a
208 description of this file format.)
209 -COsmac An RCA Cosmac Elf format file will be written. (See
211 srec_cosmac(5) for a description of this file format.)
212 -Dec_Binary
214 A DEC Binary (XXDP) format file will be written. (See
215 srec_dec_binary(5) for a description of this file for‐
216 mat.)
217 -Elektor_Monitor52
219 This option says to use the EMON52 format file when
220 writing the file. (See srec_emon52(5) for a descrip‐
221 tion of this file format.)
222 -FAIrchild
224 This option says to use the Fairchild Fairbug format
225 file when writing the file. (See srec_fairchild(5) for
226 a description of this file format.)
227 -Fast_Load
229 This option says to use the LSI Logic Fast Load format
230 file when writing the file. (See srec_fastload(5) for
231 a description of this file format.)
232 -Formatted_Binary
234 A Formatted Binary format file will be written. (See
235 srec_formatted_binary(5) for a description of this file
236 format.)
237 -FORTH [ -option ]
239 A FORTH input file will be written. Each line of out‐
240 put includes a byte value, an address, and a command.
241 -RAM The store command is C! This is the default.
243 -EEPROM The store command is EEC!
245 -Four_Packed_Code
247 This option says to use the PFC format file when writ‐
248 ing the file. (See srec_fpd(5) for a description of
249 this file format.)
250 -HEX_Dump
252 A human readable hexadecimal dump (including ASCII)
253 will be printed.
254 -IDT An IDT System Integration Manager (IDT/sim) binary file
256 will be written. (See srec_idt(5) for a description of
257 this file format.)
258 -Intel An Intel hex format file will be written. (See
260 srec_intel(5) for a description of this file format.)
261 The default is to emit “i32hex” 32‐bit linear address‐
262 ing; if you want “i16hex” 20‐bit extended segment
263 addressing use the -address‐length=3 option, if you
264 want “i8hex” 16‐bit addressing use the -address‐
265 length=2 option.
266 -Intel_HeX_16
268 An Intel‐16 hex format (INHX16) file will be written.
269 (See srec_intel16(5) for a description of this file
270 format.)
271 -Lattice_Memory_Initialization_Format [ width ]
273 The Memory Initialization Format (.mem) by Lattice
274 Semiconductor is understood for writing only. (A.k.a.
275 -MEM) (See srec_mem(5) for a description of this file
276 format.)
277 -LOGisim
279 LOginsim logic simuator uses the format See
280 -srec_logisim(5) form more information.
281 -Memory_Initialization_File [ width ]
283 Memory Initialization File (MIF) by Altera format will
284 be written. The width defaults to 8 bits. (See
285 srec_mif(5) for a description of this file format.)
286 -Mips_Flash_Big_Endian
288 -Mips_Flash_Little_Endian
290 MIPS Flash file format will be written. (See
291 srec_mips_flash(5) for a description of this file for‐
292 mat.)
293 -MOS_Technologies
295 An Mos Technologies format file will be written. (See
296 srec_mos_tech(5) for a description of this file for‐
297 mat.)
298 -Motorola [ width ]
300 A Motorola S‐Record file will be written. (See
301 srec_motorola(5) for a description of this file for‐
302 mat.) This is the default output format. By default,
303 the smallest possible address length is emitted, this
304 will be S19 for data in the first 64KB; if you wish to
305 force S28 use the -address‐length=3 option; if you wish
306 to force S37 use the -address‐length=4 option
307 The optional width argument describes the number of
309 bytes which form each address multiple. For normal
310 uses the default of one (1) byte is appropriate. Some
311 systems with 16‐bit or 32‐bit targets mutilate the
312 addresses in the file; this option will imitate that
313 behavior. Unlike most other parameters, this one can‐
314 not be guessed.
315 -MsBin This option says to use the Windows CE Binary Image
317 Data Format to write the file. See srec_msbin(5) for a
318 description of this file format.
319 -Needham_Hexadecimal
321 This option says to use the Needham Electronics ASCII
322 file format to write the file. See srec_needham(5) for
323 a description of this file format.
324 -Ohio_Scientific
326 This option says to use the Ohio Scientific hexadecimal
327 format. See srec_os65v(5) for a description of this
328 format.
329 -PPB This option says to use the Stag Prom Programmer binary
331 format. See srec_ppb(5) for a description of this for‐
332 mat.
333 -PPX This option says to use the Stag Prom Programmer hexa‐
335 decimal format. See srec_ppx(5) for a description of
336 this format.
337 -SIGnetics
339 This option says to use the Signetics hex format. See
340 srec_signetics(5) for a description of this format.
341 -SPAsm This option says to use the SPASM assembler output for‐
343 mat (commonly used by PIC programmers). See
344 srec_spasm(5) for a description of this format.
345 -SPAsm_Little_Endian
347 This option says to use the SPASM assembler output for‐
348 mat (commonly used by PIC programmers). But with the
349 data the other way around.
350 -STewie A Stewie binary format file will be written. (See
352 srec_stewie(5) for a description of this file format.)
353 -Tektronix
355 A Tektronix hex format file will be written. (See
356 srec_tektronix(5) for a description of this file for‐
357 mat.)
358 -Tektronix_Extended
360 A Tektronix extended hex format file will be written.
361 (See srec_tektronix_extended(5) for a description of
362 this file format.)
363 -Texas_Instruments_Tagged
365 A TI‐Tagged format file will be written. (See
366 srec_ti_tagged(5) for a description of this file for‐
367 mat.)
368 -Texas_Instruments_Tagged_16
370 A Texas Instruments SDSMAC 320 format file will be
371 written. (See srec_ti_tagged_16(5) for a description
372 of this file format.)
373 -Texas_Instruments_TeXT
375 This option says to use the Texas Instruments TXT
376 (MSP430) format to write the file. See srec_ti_txt(5)
377 for a description of this file format.
378 -TRS80 This option says to use the Radio Shack TRS‐80 object
380 file format to write the file. See srec_trs80(5) for a
381 description of this file format.
382 -VHdl [ bytes‐per‐word [ name ]]
384 A VHDL format file will be written. The bytes‐per‐word
385 defaults to one, the name defaults to eprom. The
386 etc/x_defs_pack.vhd file in the source distribution
387 contains an example ROM definitions pack for the type‐
388 independent output. You may need to use the -byte‐swap
389 filter to get the byte order you want.
390 -VMem [ memory‐width ]
392 A Verilog VMEM format file will be written. The mem‐
393 ory‐width may be 8, 16, 32, 64 or 128 bits; defaults to
394 32 if unspecified. (See srec_vmem(5) for a description
395 of this file format.) You may need to use the -byte‐
396 swap filter to get the byte order you want.
397 -WILson A wilson format file will be written. (See srec_wil‐
399 son(5) for a description of this file format.)
400 -Address_Length number
402 This option many be used to specify the minimum number of bytes
403 to be used in the output to represent an address (padding with
404 leading zeros if necessary). This helps when talking to imbe‐
405 cilic EPROM programmer devices which do not fully implement the
406 format specification.
407 -CRLF This option is short‐hand for the -line‐termination=crlf
409 option. For use with hare‐brained EPROM programmer devices
410 which assume all the world uses Evil Bill's operating system's
411 line termination.
412 -Data_Only
414 This option implies the -disable=header, -disable=data‐count,
415 -disable=exec‐start‐address and -disable=footer options.
416 -DISable feature‐name
418 This option is used to disable the output of a named feature.
419 See the -enable option for a description of the available fea‐
420 tures.
421 -ENable feature‐name
423 This option is used to enable the output of a named feature.
424 Header This feature controls the presence of header records,
426 records which appear before the data itself. Headers
427 often, but not always, include descriptive text.
428 Execution_Start_Address
430 This feature controls the presence of execution start
431 address records, which is where the monitor will jump
432 to and start executing code once the hex file has fin‐
433 ished loading.
434 Data_Count
436 This feature controls the presence of data record count
437 records, which appear aftre the data, and state how
438 many data records preceeded them. Usually a data
439 integrity mechanism.
440 Footer This feature controls the presence of a file termina‐
442 tion record, one that does not double as an execution
443 start address record.
444 Optional_Address
446 In formats that have the address and the data separated
447 or partially separated (as opposed to having a complete
448 address in every record) it is possible to disable
449 emitting the first address where that address would be
450 zero, as these format often default the address to zero
451 if no address is seen beofre the first data record.
452 This is disabled by default, the zero address is always
453 emitted.
454 Not all formats have all of the above features. Not all for‐
456 mats are able to optionally omit any or all the above features.
457 Feature names may be abbreviated like command line option
458 names.
459 -Execution_Start_Address number
461 This option may be used to set the execution start address, in
462 those formats which support it. The execution start address is
463 where the monitor will jump to and start executing code once
464 the hex file has finished loading, think of it as a “goto”
465 address. Usually ignored by EPROM programmer devices. This
466 option implies the -enable=exec‐start‐addr option.
467 Please note: the execution start address is a different concept
469 than the first address in memory of your data. If you want to
470 change where your data starts in memory, use the -offset fil‐
471 ter.
472 -HEAder string
474 This option may be used to set the header comment, in those
475 formats which support it. This option implies the
476 -enable=header option.
477 If you need to inject binary data into the header, use the URL
479 encoding that uses % followed by two hexadeimal characters.
480 For example a backspace would be encoded as “%08”.
481 -IGnore_Checksums
483 The -IGnore‐Checksums option may be used to disable checksum
484 validation of input files, for those formats which have check‐
485 sums at all. Note that the checksum values are still read in
486 and parsed (so it is still an error if they are missing) but
487 their values are not checked. Used after an input file name,
488 the option affects that file alone; used anywhere else on the
489 command line, it applies to all following files.
490 -Line_Termination style‐name
492 This option may be used to specify line termination style for
493 text output. The default is to use the host operating system's
494 default line termination style (but Cygwin behaves as if it's
495 Unix). Use this option with caution, because it will also
496 introduce extra (i.e. wrong) CR bytes into binary formats.
497 Carriage_Return_Line_Feed
499 Use the CRLF line termination style, typical of DOS and M$
500 Windows.
501 NewLine
503 Use the NL line termination style, typical of Unix and
504 Linux.
505 Carriage_Return
507 Use the CR line termination style, typical of Apple Macin‐
508 tosh.
509 All other line termination style names will produce a fatal
511 error. Style names may be abbreviated like command line option
512 names.
513 -Line_Length number
515 This option may be used to limit the length of the output lines
516 to at most number characters. (Not meaningful for binary file
517 format.) Defaults to something less than 80 characters,
518 depending on the format. If you need to control the maximum
519 number of bytes in each output record, use the
520 --Ouput_Block_Size option.
521 -Output_Block_Size number
523 This option may be used to specify the exact number of data
524 bytes to appear in each output record. There are format‐spe‐
525 cific limitations on this value, you will get an error if the
526 value isn't valid. If you need to control the maximum number
527 of characters on a line of text output, use the --Line_Length
528 option.
529 -Output_Block_Packing
531 From time to time, with large files, you may notice that your
532 data records are spit unexpectedly on output. This usually
533 happens where record lengths are not a power of 2. If this
534 bothers you (or your comparison tools) this option may be used
535 to repack the output so that SRecord's internal block bound‐
536 aries are not visable in the output.
537 -Output_Block_Alignment
539 This option is similar to the -Output_Block_Packing option,
540 except that short records are used after holes to cause subse‐
541 quent records to be placed on a block size boundary.
542 -Enable_Sequence_Warnings
544 This option may be used to enable warnings about input files
545 where the data records are not in strictly ascending address
546 order. Only one warning is issued per input file. This is the
547 default.
548 Note: the output of srec_cat(1) is always in this order.
550 Note: This option must be used before the input file. This is
552 because if there are several files on the command line, each
553 may need different settings. The setting remains in force
554 until the next -Disable_Sequence_Warnings option.
555 -Disable_Sequence_Warnings
557 This option may be used to disable warnings about input files
558 where the data records are not in strictly ascending address
559 order.
560 Note: This option must be used before the offending input file.
562 This is because if there are several files on the command line,
563 each may need different settings. The setting remains in force
564 until the next -Ensable_Sequence_Warnings option.
565 All other options will produce a diagnostic error.
567 All options may be abbreviated; the abbreviation is documented as the
569 upper case letters, all lower case letters and underscores (_) are
570 optional. You must use consecutive sequences of optional letters.
571 All options are case insensitive, you may type them in upper case or
573 lower case or a combination of both, case is not important.
574 For example: the arguments “-help”, “-HEL” and “-h” are all interpreted
576 to mean the -Help option. The argument “-hlp” will not be understood,
577 because consecutive optional characters were not supplied.
578 Options and other command line arguments may be mixed arbitrarily on
580 the command line.
581 The GNU long option names are understood. Since all option names for
583 srec_cat are long, this means ignoring the extra leading “-”. The
584 “--option=value” convention is also understood.
585
587 The srec_cat command will exit with a status of 1 on any error. The
588 srec_cat command will only exit with a status of 0 if there are no
589 errors.
590
592 srec_cat version 1.64
593 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
594 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller
595 The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use
597 the 'srec_cat -VERSion License' command. This is free software and you
598 are welcome to redistribute it under certain conditions; for details
599 use the 'srec_cat -VERSion License' command.
600
602 Scott Finneran E‐Mail: scottfinneran@yahoo.com.au
603 Peter Miller E‐Mail: pmiller@opensource.org.au
604Reference Manual SRecord srec_cat(1)