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 -multiple option
45 (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 in a separate manual page because it is common to more than
79 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 -COsmac An RCA Cosmac Elf format file will be written. (See
197 srec_cosmac(5) for a description of this file format.)
198 -Dec_Binary
200 A DEC Binary (XXDP) format file will be written. (See
201 srec_dec_binary(5) for a description of this file for‐
202 mat.)
203 -Elektor_Monitor52
205 This option says to use the EMON52 format file when
206 writing the file. (See srec_emon52(5) for a descrip‐
207 tion of this file format.)
208 -FAIrchild
210 This option says to use the Fairchild Fairbug format
211 file when writing the file. (See srec_fairchild(5) for
212 a description of this file format.)
213 -Fast_Load
215 This option says to use the LSI Logic Fast Load format
216 file when writing the file. (See srec_fastload(5) for
217 a description of this file format.)
218 -Formatted_Binary
220 A Formatted Binary format file will be written. (See
221 srec_formatted_binary(5) for a description of this file
222 format.)
223 -FORTH [ -option ]
225 A FORTH input file will be written. Each line of out‐
226 put includes a byte value, an address, and a command.
227 -RAM The store command is C! This is the default.
229 -EEPROM The store command is EEC!
231 -Four_Packed_Code
233 This option says to use the PFC format file when writ‐
234 ing the file. (See srec_fpd(5) for a description of
235 this file format.)
236 -HEX_Dump
238 A human readable hexadecimal dump (including ASCII)
239 will be printed.
240 -Intel An Intel hex format file will be written. (See
242 srec_intel(5) for a description of this file format.)
243 The default is to emit 32‐bit linear addressing; if you
244 want 16‐bit extended segment addressing use the
245 -address‐length=2 option.
246 -Intel_16
248 An Intel‐16 hex format file will be written. (See
249 srec_intel16(5) for a description of this file format.)
250 -Memory_Initialization_File [ width ]
252 (Altera) Memory Initialization File (MIF) format will
253 be written. The width defaults to 8 bits. (See
254 srec_mif(5) for a description of this file format.)
255 -MOS_Technologies
257 An Mos Technologies format file will be written. (See
258 srec_mos_tech(5) for a description of this file for‐
259 mat.)
260 -Motorola [ width ]
262 A Motorola S‐Record file will be written. (See
263 srec_motorola(5) for a description of this file for‐
264 mat.) This is the default output format. By default,
265 the smallest possible address length is emitted, this
266 will be S19 for data in the first 64KB; if you wish to
267 force S28 use the -address‐length=3 option; if you wish
268 to force S37 use the -address‐length=4 option
269 The optional width argument describes the number of
271 bytes which form each address multiple. For normal
272 uses the default of one (1) byte is appropriate. Some
273 systems with 16‐bit or 32‐bit targets mutilate the
274 addresses in the file; this option will imitate that
275 behavior. Unlike most other parameters, this one can‐
276 not be guessed.
277 -MsBin This option says to use the Windows CE Binary Image
279 Data Format to write the file. See srec_msbin(5) for a
280 description of this file format.
281 -Needham_Hexadecimal
283 This option says to use the Needham Electronics ASCII
284 file format to write the file. See srec_needham(5) for
285 a description of this file format.
286 -Ohio_Scientific
288 This option says to use the Ohio Scientific hexadecimal
289 format. See srec_os65v(5) for a description of this
290 format.
291 -SIGnetics
293 This option says to use the Signetics hex format. See
294 srec_signetics(5) for a description of this format.
295 -SPAsm This option says to use the SPASM assembler output for‐
297 mat (commonly used by PIC programmers). See
298 srec_spasm(5) for a description of this format.
299 -SPAsm_LittleEndian
301 This option says to use the SPASM assembler output for‐
302 mat (commonly used by PIC programmers). But with the
303 data the other way around.
304 -STewie A Stewie binary format file will be written. (See
306 srec_stewie(5) for a description of this file format.)
307 -Tektronix
309 A Tektronix hex format file will be written. (See
310 srec_tektronix(5) for a description of this file for‐
311 mat.)
312 -Tektronix_Extended
314 A Tektronix extended hex format file will be written.
315 (See srec_tektronix_extended(5) for a description of
316 this file format.)
317 -Texas_Instruments_Tagged
319 A TI‐Tagged format file will be written. (See
320 srec_ti_tagged(5) for a description of this file for‐
321 mat.)
322 -Texas_Instruments_Tagged_16
324 A Texas Instruments SDSMAC 320 format file will be
325 written. (See srec_ti_tagged_16(5) for a description
326 of this file format.)
327 -Texas_Instruments_TeXT
329 This option says to use the Texas Instruments TXT
330 (MSP430) format to write the file. See srec_ti_txt(5)
331 for a description of this file format.
332 -VHdl [ bytes‐per‐word [ name ]]
334 A VHDL format file will be written. The bytes‐per‐word
335 defaults to one, the name defaults to eprom. The
336 etc/x_defs_pack.vhd file in the source distribution
337 contains an example ROM definitions pack for the type‐
338 independent output. You may need to use the -byte‐swap
339 filter to get the byte order you want.
340 -VMem [ memory‐width ]
342 A Verilog VMEM format file will be written. The mem‐
343 ory‐width may be 8, 16, 32, 64 or 128 bits; defaults to
344 32 if unspecified. (See srec_vmem(5) for a description
345 of this file format.) You may need to use the -byte‐
346 swap filter to get the byte order you want.
347 -WILson A wilson format file will be written. (See srec_wil‐
349 son(5) for a description of this file format.)
350 -Address_Length number
352 This option many be used to specify the minimum number of bytes
353 to be used in the output to represent an address (padding with
354 leading zeros if necessary). This helps when talking to imbe‐
355 cilic EPROM programmer devices which do not fully implement the
356 format specification.
357 -Data_Only
359 This option implies the -disable=header, -disable=data‐count,
360 -disable=exec‐start‐address and -disable=footer options.
361 -ENable feature‐name
363 This option is used to enable the output of a named feature.
364 Header This feature controls the presence of header records,
366 records which appear before the data itself. Headers
367 often, but not always, include descriptive text.
368 Data_Count
370 This feature controls the presence of data record count
371 records, which appear aftre the data, and state how
372 many data records preceeded them. Usually a data
373 intergrity mechanism.
374 Execution_Start_Address
376 The feature controls the presence of execution start
377 address records, which is where the monitor will jump
378 to and start executing code once the hex file has fin‐
379 ished loading.
380 Footer This feature controls the presence of a file termina‐
382 tion record, one that does not double as an execution
383 start address record.
384 Not all formats have all of the above features. Not all for‐
386 mats are able to optionally omit any or all the above features.
387 Feature names may be abbreviated like command line option
388 names.
389 -DISable feature‐name
391 This option is used to disable the output of a named feature.
392 See the -enable option for a description of the available fea‐
393 tures.
394 -IGnore_Checksums
396 The -ignore‐checksums option may be used to disable checksum
397 validation of input files, for those formats which have check‐
398 sums at all. Note that the checksum values are still read in
399 and parsed (so it is still an error if they are missing) but
400 their values are not checked. Used after an input file name,
401 the option affects that file alone; used anywhere else on the
402 command line, it applies to all following files.
403 -Enable_Sequence_Warnings
405 This option may be used to enable warnings about input files
406 where the data records are not in strictly ascending address
407 order. Only one warning is issued per input. This is the
408 default. Note: the output of srec_cat(1) is always in this
409 order.
410 -Disable_Sequence_Warnings
412 This option may be used to disable warnings about input files
413 where the data records are not in stricyly ascending address
414 order.
415 -CRLF This option is short‐hand for the -line‐termination=crlf
417 option. For use with harebrained EPROM programmer devices
418 which assume all the world uses Evil Bill's operating system's
419 line termination.
420 -Line_Termination style‐name
422 This option may be used to specify line termination style for
423 text output. The default is to use the host operating system's
424 default line termination style (but Cygwin behaves as if it's
425 Unix). Use this option with caution, because it will also
426 introduce extra (i.e. wrong) CR bytes into binary formats.
427 Carriage_Return_Line_Feed
429 Use the CRLF line termination style, typical of DOS and M$
430 Windows.
431 NewLine
433 Use the NL line termination style, typical of Unix and
434 Linux.
435 Carriage_Return
437 Use the CR line termination style, typical of Apple Macin‐
438 tosh.
439 All other line termination style names will produce a fatal
441 error. Style names may be abbreviated like command line option
442 names.
443 -Line_Length number
445 This option may be used to limit the length of the output lines
446 to at most number characters. (Not meaningful for binary file
447 format.) Defaults to something less than 80 characters,
448 depending on the format.
449 -HEAder string
451 This option may be used to set the header comment, in those
452 formats which support it. This option implies the
453 -enable=header option.
454 -Execution_Start_Address number
456 This option may be used to set the execution start address, in
457 those formats which support it. The execution start address is
458 where the monitor will jump to and start executing code once
459 the hex file has finished loading, think of it as a “goto”
460 address. Usually ignored by EPROM programmer devices. This
461 option implies the -enable=exec‐start‐addr option.
462 Please note: the execution start address is a different concept
464 than the first address in memory of your data. If you want to
465 change where your data starts in memory, use the -offset fil‐
466 ter.
467 -MULTiple
469 Use this option to permit a file to contain multiple (contra‐
470 dictory) values for some memory locations. A warning will be
471 printed. The last value in the file will be used. The default
472 is for this condition to be a fatal error.
473 All other options will produce a diagnostic error.
475 All options may be abbreviated; the abbreviation is documented as the
477 upper case letters, all lower case letters and underscores (_) are
478 optional. You must use consecutive sequences of optional letters.
479 All options are case insensitive, you may type them in upper case or
481 lower case or a combination of both, case is not important.
482 For example: the arguments “-help”, “-HEL” and “-h” are all interpreted
484 to mean the -Help option. The argument “-hlp” will not be understood,
485 because consecutive optional characters were not supplied.
486 Options and other command line arguments may be mixed arbitrarily on
488 the command line.
489 The GNU long option names are understood. Since all option names for
491 srec_cat are long, this means ignoring the extra leading “-”. The
492 “--option=value” convention is also understood.
493
495 The srec_cat command will exit with a status of 1 on any error. The
496 srec_cat command will only exit with a status of 0 if there are no
497 errors.
498
500 srec_cat version 1.55
501 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
502 2007, 2008, 2009, 2010 Peter Miller
503 The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use
505 the 'srec_cat -VERSion License' command. This is free software and you
506 are welcome to redistribute it under certain conditions; for details
507 use the 'srec_cat -VERSion License' command.
508
510 Peter Miller E‐Mail: pmiller@opensource.org.au
511 /\/\* WWW: http://miller.emu.id.au/pmiller/
512Reference Manual SRecord srec_cat(1)