1srec_cat(1)                 General Commands Manual                srec_cat(1)
2
3
4

NAME

6       srec_cat - manipulate EPROM load files
7

SYNOPSIS

9       srec_cat [ option...  ] filename...
10       srec_cat -Help
11       srec_cat -VERSion
12

DESCRIPTION

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
18   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
25   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
35   Data Conflicts
36       The storing of data in memory enables the detection of data  conflicts,
37       typically caused by linker sections unintentionally overlapping.
38
39       · A warning will be issued for each address which is redundantly set to
40         the same value.
41
42       · 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
47       · 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
51       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

INPUT FILE SPECIFICATIONS

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
62   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
69   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
76   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

OPTIONS

82       The following options are understood:
83
84       @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
91       -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
97               The format may be specified as:
98
99               -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
104               -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
109               -ASM [ prefix ][ -option... ]
110                       A series of assembler DB statements will be written.
111
112                       The optional prefix may  be  specified  to  change  the
113                       names  of  the  symbols  generated.   The  defaults  to
114                       "eprom" if not set.
115
116                       Several options are available to modify  the  style  of
117                       output:
118
119                       -Dot_STyle
120                               Use  "dot"  style  pseudo‐ops instead of words.
121                               For example .byte instead of the DB default.
122
123                       -HEXadecimal_STyle
124                               Use hexadecimal numbers in the  output,  rather
125                               than the default decimal numbers.
126
127                       -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
134                       -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
139                       -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
144                       -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
155               -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
160               -BASic  A series of BASIC DATA statements will be written.
161
162               -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
167               -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
171               -C‐Array [ identifier ][ -option... ]
172                       A C array defintion will be written.
173
174                       The optional identifier is the name of the variable  to
175                       be defined, or bugus if not specified.
176
177                       -INClude
178                               This option asks for an include file to be gen‐
179                               erated as well.
180
181                       -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
187                       -C_COMpressed
188                               These  options  ask  for  an compressed c‐array
189                               whose memory gaps will not be filled.
190
191                       -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
196                       -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
201                       -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
206               -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
210               -COsmac An RCA Cosmac Elf format file will  be  written.   (See
211                       srec_cosmac(5) for a description of this file format.)
212
213               -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
218               -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
223               -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
228               -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
233               -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
238               -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
242                       -RAM    The store command is C!  This is the default.
243
244                       -EEPROM The store command is EEC!
245
246               -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
251               -HEX_Dump
252                       A human readable  hexadecimal  dump  (including  ASCII)
253                       will be printed.
254
255               -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
259               -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
267               -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
272               -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
278               -LOGisim
279                       LOginsim   logic   simuator   uses   the   format   See
280                       -srec_logisim(5) form more information.
281
282               -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
287               -Mips_Flash_Big_Endian
288
289               -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
294               -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
299               -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
308                       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
316               -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
320               -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
325               -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
330               -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
334               -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
338               -SIGnetics
339                       This  option says to use the Signetics hex format.  See
340                       srec_signetics(5) for a description of this format.
341
342               -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
346               -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
351               -STewie A Stewie binary format  file  will  be  written.   (See
352                       srec_stewie(5) for a description of this file format.)
353
354               -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
359               -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
364               -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
369               -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
374               -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
379               -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
383               -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
391               -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
398               -WILson A wilson format file will be written.   (See  srec_wil‐
399                       son(5) for a description of this file format.)
400
401       -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
408       -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
413       -Data_Only
414               This option implies the  -disable=header,  -disable=data‐count,
415               -disable=exec‐start‐address and -disable=footer options.
416
417       -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
422       -ENable feature‐name
423               This option is used to enable the output of a named feature.
424
425               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
429               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
435               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
441               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
445               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
455               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
460       -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
468               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
473       -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
478               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
482       -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
491       -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
498               Carriage_Return_Line_Feed
499                   Use  the CRLF line termination style, typical of DOS and M$
500                   Windows.
501
502               NewLine
503                   Use the NL line termination  style,  typical  of  Unix  and
504                   Linux.
505
506               Carriage_Return
507                   Use  the CR line termination style, typical of Apple Macin‐
508                   tosh.
509
510               All other line termination style names  will  produce  a  fatal
511               error.  Style names may be abbreviated like command line option
512               names.
513
514       -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
522       -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
530       -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
538       -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
543       -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
549               Note: the output of srec_cat(1) is always in this order.
550
551               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
556       -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
561               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
566       All other options will produce a diagnostic error.
567
568       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
572       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
575       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
579       Options  and  other  command line arguments may be mixed arbitrarily on
580       the command line.
581
582       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

EXIT STATUS

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
596       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

MAINTAINER

602       Scott Finneran   E‐Mail:   scottfinneran@yahoo.com.au
603       Peter Miller     E‐Mail:   pmiller@opensource.org.au
604
605
606
607Reference Manual                    SRecord                        srec_cat(1)
Impressum