Provided by: srecord_1.58-1_amd64 bug

NAME

       srec_cat - manipulate EPROM load files

SYNOPSIS

       srec_cat [ option...  ] filename...
       srec_cat -Help
       srec_cat -VERSion

DESCRIPTION

       The  srec_cat program is used to assemble the given input files into a single output file.
       The use of filters (see below) allows significant manipulations to be  performed  by  this
       command.

   Data Order
       The  data  from the input files is not immediately written to the output, but is stored in
       memory until the complete EPROM image has been assembled.  Data is  then  written  to  the
       output  file  in  ascending  address  order.   The original ordering of the data (in those
       formats capable of random record ordering) is not preserved.

   Data Comparison
       Because input record order is not preserved, textual comparison of input and output  (such
       as  the  diff(1)  or  tkdiff(1) commands) can be misleading.  Not only can lines appear in
       different address orders, but line lengths and line termination can differ as  well.   Use
       the  srec_cmp(1)  program  to  compare  two  EPROM  load  files.   If a text comparison is
       essential, run both files through the srec_cat(1) program  to  ensure  both  files  to  be
       compared have identical record ordering and line lengths.

   Data Conflicts
       The storing of data in memory enables the detection of data conflicts, typically caused by
       linker sections unintentionally overlapping.

       • A warning will be issued for each address which is redundantly set to the same value.

       • A fatal error will be issued if any address is set with contradictory values.  To  avoid
         this  error use an -exclude -within filter (see srec_input(1)) or, to make it a warning,
         use the -multiple option (see below).

       • A warning will be issued for input files where the data  records  are  not  in  strictly
         ascending  address  order.   To suppress this warning, use the -disable‐sequence‐warning
         option (see below).

       These features are designed to detect problems which are difficult to debug,  and  detects
       them before the data is written to an EPROM and run in your embedded system.

INPUT FILE SPECIFICATIONS

       Input  may  be  qualified  in  two  ways: you may specify a data file or a data generator.
       format and you may specify filters to apply to them.  An input  file  specification  looks
       like this:
              data‐file [ filter ... ]
              data‐generator [ filter ... ]

   Data Files
       Input  from  data  files  is  specified  by  file  name  and  format  name.  An input file
       specification looks like this:
              filename [ format ][ -ignore‐checksums ]
       The default format is Motorola S‐Record format, but many others are also understood.

   Data Generators
       It is also possible to generate data, rather than read it from a  file.   You  may  use  a
       generator  anywhere  you  could  use  a file.  An input generator specification looks like
       this:
              -GENerate address‐range -data‐source
       Generators include random data and various forms of constant data.

   Common Manual Page
       See srec_input(1) for complete details of input specifiers.   This  description  is  in  a
       separate manual page because it is common to more than one SRecord command.

OPTIONS

       The following options are understood:

       @filename
               The  named text file is read for additional command line arguments.  Arguments are
               separated by white space  (space,  tab,  newline,  etc).   There  is  no  wildcard
               mechanism.   There  is  no  quoting mechanism.  Comments, which start with '#' and
               extend to the end of the line, are ignored.  Blank lines are ignored.

       -Output filename [ format ]
               This option may be used to specify the output file to be used.  The  special  file
               name  “-[rq]  is  understood  to mean the standard output.  Output defaults to the
               standard output if this option is not used.

               The format may be specified as:

               -Absolute_Object_Module_Format
                       An Intel Absolute  Object  Module  Format  file  will  be  written.   (See
                       srec_aomf(5) for a description of this file format.)

               -Ascii_Hex
                       An   Ascii‐Hex  file  will  be  written.   (See  srec_ascii_hex(5)  for  a
                       description of this file format.)

               -ASM [ prefix ][ -option... ]
                       A series of assembler DB statements will be written.

                       The optional prefix may be specified to change the names  of  the  symbols
                       generated.  The defaults to "eprom" if not set.

                       Several options are available to modify the style of output:

                       -Dot_STyle
                               Use  "dot"  style  pseudo‐ops instead of words.  For example .byte
                               instead of the DB default.

                       -HEXadecimal_STyle
                               Use hexadecimal numbers in the output,  rather  than  the  default
                               decimal numbers.

                       -Section_STyle
                               By default the generated assemble of placed at the correct address
                               using ORG  pseudo‐ops.   Section  style  output  emits  tables  of
                               section  addresses  and  lengths,  so  the  data may be related at
                               runtime.

                       -A430   Generate output which is compliant to the a430.exe compiler as  it
                               is  used,  e.g. in IAR Embedded Workbench.  This is short‐hand for
                               -section‐style -hex‐style

                       -CL430  Generate  output which is Code Composer Essentials compliant, i.e.
                               the  compiler  of it.  This is short‐hand for -section‐style -hex‐
                               style -dot‐style

                       -Output_Word
                               Generate output which is in  two‐byte  words  rather  than  bytes.
                               This  assumes little‐endian words; you will need to use the -Byte‐
                               Swap filter if your target is big‐endian.  No attempt is  made  to
                               align the words onto even address boundaries; use and input filter
                               such as
                                       input‐file -fill 0xFF -within input‐file
                                       -range‐pad 2
                               to pad the data to whole words first.

               -Atmel_Generic
                       An Atmel Generic file will be written.  (See srec_atmel_generic(5)  for  a
                       description of this file format.)

               -BASic  A series of BASIC DATA statements will be written.

               -B‐Record
                       A  Freescale  MC68EZ328  Dragonball bootstrap b‐record format file will be
                       written.  (See srec_brecord(5) for a description of this file format.)

               -Binary A raw binary file will be written.  If you get unexpected  results  please
                       see the srec_binary(5) manual for more information.

               -C‐Array [ identifier ][ -option... ]
                       A C array defintion will be written.

                       The  optional  identifier  is  the  name of the variable to be defined, or
                       bugus if not specified.

                       -INClude
                               This option asks for an include file to be generated as well.

                       -No‐CONST
                               This options asks for the variables to not use the  const  keyword
                               (they  are  declared  constant be default, so that they are placed
                               into the read‐only segment in embedded systems).

                       -C_COMpressed
                               These options ask for an compressed c‐array whose memory gaps will
                               not be filled.

                       -Output_Word
                               This  option  asks  for  an output which is in words not in bytes.
                               This is little endian, so you may need to

               -COsmac An RCA Cosmac Elf format file will be written.  (See srec_cosmac(5) for  a
                       description of this file format.)

               -Dec_Binary
                       A  DEC Binary (XXDP) format file will be written.  (See srec_dec_binary(5)
                       for a description of this file format.)

               -Elektor_Monitor52
                       This option says to use the EMON52 format  file  when  writing  the  file.
                       (See srec_emon52(5) for a description of this file format.)

               -FAIrchild
                       This option says to use the Fairchild Fairbug format file when writing the
                       file.  (See srec_fairchild(5) for a description of this file format.)

               -Fast_Load
                       This option says to use the LSI Logic Fast Load format file  when  writing
                       the file.  (See srec_fastload(5) for a description of this file format.)

               -Formatted_Binary
                       A    Formatted    Binary    format    file    will   be   written.    (See
                       srec_formatted_binary(5) for a description of this file format.)

               -FORTH [ -option ]
                       A FORTH input file will be written.  Each line of output includes  a  byte
                       value, an address, and a command.

                       -RAM    The store command is C!  This is the default.

                       -EEPROM The store command is EEC!

               -Four_Packed_Code
                       This  option  says to use the PFC format file when writing the file.  (See
                       srec_fpd(5) for a description of this file format.)

               -HEX_Dump
                       A human readable hexadecimal dump (including ASCII) will be printed.

               -IDT    An IDT System Integration Manager (IDT/sim) binary file will  be  written.
                       (See srec_idt(5) for a description of this file format.)

               -Intel  An  Intel  hex  format  file  will  be  written.  (See srec_intel(5) for a
                       description of this file format.)  The default is to emit “i32hex”  32‐bit
                       linear addressing; if you want “i16hex” 20‐bit extended segment addressing
                       use the -address‐length=3 option, if you want  “i8hex”  16‐bit  addressing
                       use the -address‐length=2 option.

               -Intel_HeX_16
                       An   Intel‐16   hex   format   (INHX16)   file   will  be  written.   (See
                       srec_intel16(5) for a description of this file format.)

               -Memory_Initialization_File [ width ]
                       (Altera) Memory Initialization File (MIF) format  will  be  written.   The
                       width defaults to 8 bits.  (See srec_mif(5) for a description of this file
                       format.)

               -Mips_Flash_BigEndian

               -Mips_Flash_LittleEndian
                       MIPS Flash file format will be written.   (See  srec_mips_flash(5)  for  a
                       description of this file format.)

               -MOS_Technologies
                       An  Mos  Technologies  format file will be written.  (See srec_mos_tech(5)
                       for a description of this file format.)

               -Motorola [ width ]
                       A Motorola S‐Record file will be written.   (See  srec_motorola(5)  for  a
                       description  of this file format.)  This is the default output format.  By
                       default, the smallest possible address length is emitted, this will be S19
                       for  data  in  the  first 64KB; if you wish to force S28 use the -address‐
                       length=3 option; if you wish to force S37 use the -address‐length=4 option

                       The optional width argument describes the number of bytes which form  each
                       address  multiple.   For  normal  uses  the  default  of  one  (1) byte is
                       appropriate.  Some systems with 16‐bit  or  32‐bit  targets  mutilate  the
                       addresses  in  the  file;  this option will imitate that behavior.  Unlike
                       most other parameters, this one cannot be guessed.

               -MsBin  This option says to use the Windows CE Binary Image Data Format  to  write
                       the file.  See srec_msbin(5) for a description of this file format.

               -Needham_Hexadecimal
                       This option says to use the Needham Electronics ASCII file format to write
                       the file.  See srec_needham(5) for a description of this file format.

               -Ohio_Scientific
                       This option says to use  the  Ohio  Scientific  hexadecimal  format.   See
                       srec_os65v(5) for a description of this format.

               -PPB    This  option  says  to  use  the  Stag Prom Programmer binary format.  See
                       srec_ppb(5) for a description of this format.

               -PPX    This option says to use the Stag Prom Programmer hexadecimal format.   See
                       srec_ppx(5) for a description of this format.

               -SIGnetics
                       This  option  says to use the Signetics hex format.  See srec_signetics(5)
                       for a description of this format.

               -SPAsm  This option says to use the SPASM assembler output format  (commonly  used
                       by PIC programmers).  See srec_spasm(5) for a description of this format.

               -SPAsm_LittleEndian
                       This  option  says to use the SPASM assembler output format (commonly used
                       by PIC programmers).  But with the data the other way around.

               -STewie A Stewie binary format file will be written.  (See  srec_stewie(5)  for  a
                       description of this file format.)

               -Tektronix
                       A Tektronix hex format file will be written.  (See srec_tektronix(5) for a
                       description of this file format.)

               -Tektronix_Extended
                       A  Tektronix  extended  hex   format   file   will   be   written.    (See
                       srec_tektronix_extended(5) for a description of this file format.)

               -Texas_Instruments_Tagged
                       A  TI‐Tagged  format  file  will be written.  (See srec_ti_tagged(5) for a
                       description of this file format.)

               -Texas_Instruments_Tagged_16
                       A Texas  Instruments  SDSMAC  320  format  file  will  be  written.   (See
                       srec_ti_tagged_16(5) for a description of this file format.)

               -Texas_Instruments_TeXT
                       This option says to use the Texas Instruments TXT (MSP430) format to write
                       the file.  See srec_ti_txt(5) for a description of this file format.

               -VHdl [ bytes‐per‐word [ name ]]
                       A VHDL format file will be written.  The bytes‐per‐word defaults  to  one,
                       the  name  defaults  to eprom.  The etc/x_defs_pack.vhd file in the source
                       distribution contains an  example  ROM  definitions  pack  for  the  type‐
                       independent  output.  You may need to use the -byte‐swap filter to get the
                       byte order you want.

               -VMem [ memory‐width ]
                       A Verilog VMEM format file will be written.  The memory‐width  may  be  8,
                       16,  32, 64 or 128 bits; defaults to 32 if unspecified.  (See srec_vmem(5)
                       for a description of this file format.)  You may need to  use  the  -byte‐
                       swap filter to get the byte order you want.

               -WILson A  wilson  format  file  will  be  written.   (See  srec_wilson(5)  for  a
                       description of this file format.)

       -Address_Length number
               This option many be used to specify the minimum number of bytes to be used in  the
               output  to  represent  an address (padding with leading zeros if necessary).  This
               helps when talking to imbecilic  EPROM  programmer  devices  which  do  not  fully
               implement the format specification.

       -Data_Only
               This option implies the -disable=header, -disable=data‐count, -disable=exec‐start‐
               address and -disable=footer options.

       -ENable feature‐name
               This option is used to enable the output of a named feature.

               Header  This feature controls the presence of header records, records which appear
                       before   the   data  itself.   Headers  often,  but  not  always,  include
                       descriptive text.

               Data_Count
                       This feature controls the presence of data  record  count  records,  which
                       appear  aftre  the  data,  and state how many data records preceeded them.
                       Usually a data integrity mechanism.

               Execution_Start_Address
                       This feature controls the presence of  execution  start  address  records,
                       which  is where the monitor will jump to and start executing code once the
                       hex file has finished loading.

               Footer  This feature controls the presence of a file termination record, one  that
                       does not double as an execution start address record.

               Optional_Address
                       In  formats  that  have  the  address  and the data separated or partially
                       separated (as opposed to having a complete address in every record) it  is
                       possible to disable emitting the first address where that address would be
                       zero, as these format often default the address to zero if no  address  is
                       seen  beofre the first data record.  This is disabled by default, the zero
                       address is always emitted.

               Not all formats have all of the above features.   Not  all  formats  are  able  to
               optionally  omit  any or all the above features.  Feature names may be abbreviated
               like command line option names.

       -DISable feature‐name
               This option is used to disable the output of a named  feature.   See  the  -enable
               option for a description of the available features.

       -IGnore_Checksums
               The  -IGnore‐Checksums  option may be used to disable checksum validation of input
               files, for those formats which have checksums at  all.   Note  that  the  checksum
               values  are still read in and parsed (so it is still an error if they are missing)
               but their values are not checked.  Used after  an  input  file  name,  the  option
               affects that file alone; used anywhere else on the command line, it applies to all
               following files.

       -Enable_Sequence_Warnings
               This option may be used to enable  warnings  about  input  files  where  the  data
               records  are  not in strictly ascending address order.  Only one warning is issued
               per input file.  This is the default.

               Note: the output of srec_cat(1) is always in this order.

               Note: This option must be used before the input file.  This is  because  if  there
               are  several  files  on  the  command line, each may need different settings.  The
               setting remains in force until the next -Disable_Sequence_Warnings option.

       -Disable_Sequence_Warnings
               This option may be used to disable warnings  about  input  files  where  the  data
               records are not in strictly ascending address order.

               Note:  This  option must be used before the offending input file.  This is because
               if there are several files on the command line, each may need different  settings.
               The setting remains in force until the next -Ensable_Sequence_Warnings option.

       -CRLF   This  option  is  short‐hand  for the -line‐termination=crlf option.  For use with
               harebrained EPROM programmer devices which assume all the world uses  Evil  Bill's
               operating system's line termination.

       -Line_Termination style‐name
               This  option  may  be used to specify line termination style for text output.  The
               default is to use the host operating system's default line termination style  (but
               Cygwin  behaves  as  if it's Unix).  Use this option with caution, because it will
               also introduce extra (i.e. wrong) CR bytes into binary formats.

               Carriage_Return_Line_Feed
                   Use the CRLF line termination style, typical of DOS and M$ Windows.

               NewLine
                   Use the NL line termination style, typical of Unix and Linux.

               Carriage_Return
                   Use the CR line termination style, typical of Apple Macintosh.

               All other line termination style names will produce a fatal  error.   Style  names
               may be abbreviated like command line option names.

       -Line_Length number
               This  option may be used to limit the length of the output lines to at most number
               characters.  (Not meaningful for binary file format.)  Defaults to something  less
               than  80  characters, depending on the format.  If you need to control the maximum
               number of bytes in each output record, use the --Ouput_Block_Size option.

       -HEAder string
               This option may be used to set the header comment, in those formats which  support
               it.  This option implies the -enable=header option.

       -Execution_Start_Address number
               This option may be used to set the execution start address, in those formats which
               support it.  The execution start address is where the monitor  will  jump  to  and
               start  executing  code  once  the  hex file has finished loading, think of it as a
               “goto” address.  Usually ignored by EPROM programmer devices.  This option implies
               the -enable=exec‐start‐addr option.

               Please  note:  the  execution  start address is a different concept than the first
               address in memory of your data.  If you want to change where your data  starts  in
               memory, use the -offset filter.

       -Output_Block_Size number
               This  option  may  be  used to specify the exact number of data bytes to appear in
               each output record.  There are format‐specific limitations on this value, you will
               get  an error if the value isn't valid.  If you need to control the maximum number
               of characters on a line of text output, use the --Line_Length option.

       -Output_Block_Packing
               From time to time, with large files, you may notice that  your  data  records  are
               spit  unexpectedly on output.  This usually happens where record lengths are not a
               power of 2.  If this bothers you (or your comparison tools)  this  option  may  be
               used  to  repack  the  output  so that SRecord's internal block boundaries are not
               visable in the output.

       -Output_Block_Alignment
               This option is similar to the  -Output_Block_Packing  option,  except  that  short
               records  are  used after holes to cause subsequent records to be placed on a block
               size boundary.

       -MULTiple
               Use this option to permit a file to contain multiple  (contradictory)  values  for
               some  memory  locations.   A  warning will be printed.  The last value in the file
               will be used.  The default is for this condition to be a fatal error.

       All other options will produce a diagnostic error.

       All options may be abbreviated; the abbreviation is documented as the upper case  letters,
       all  lower  case  letters  and  underscores  (_)  are  optional.  You must use consecutive
       sequences of optional letters.

       All options are case insensitive, you may type them in upper  case  or  lower  case  or  a
       combination of both, case is not important.

       For  example: the arguments “-help”, “-HEL” and “-h” are all interpreted to mean the -Help
       option.  The  argument  “-hlp”  will  not  be  understood,  because  consecutive  optional
       characters were not supplied.

       Options and other command line arguments may be mixed arbitrarily on the command line.

       The  GNU  long option names are understood.  Since all option names for srec_cat are long,
       this means ignoring the extra  leading  “-”.   The  “--option=value”  convention  is  also
       understood.

EXIT STATUS

       The srec_cat command will exit with a status of 1 on any error.  The srec_cat command will
       only exit with a status of 0 if there are no errors.

COPYRIGHT

       srec_cat version 1.58
       Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004,  2005,  2006,  2007,  2008,  2009,
       2010, 2011 Peter Miller

       The  srec_cat  program  comes  with  ABSOLUTELY NO WARRANTY; for details use the 'srec_cat
       -VERSion License' command.  This is free software and you are welcome to  redistribute  it
       under certain conditions; for details use the 'srec_cat -VERSion License' command.

AUTHOR

       Peter Miller   E‐Mail:   pmiller@opensource.org.au
       /\/\*             WWW:   http://miller.emu.id.au/pmiller/