'\" t
.\"	srecord - manipulate eprom load files
.\"	Copyright (C) 1998, 2000-2005 Peter Miller;
.\"	All rights reserved.
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 2 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program; if not, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: manual entry for the srec_cat command
.\"
.ds n) srec_cat
.TH \*(n) 1 "" SRecord "Reference Manual"
.SH NAME
srec_cat \- manipulate eprom load files
.XX "srec_cat(1)" "manipulate eprom load files"
.SH SYNOPSIS
.B \*(n)
[
.IR option \&...
]
.IR filename \&...
.br
.B \*(n)
.B -Help
.br
.B \*(n)
.B -VERSion
.SH DESCRIPTION
The
.I \*(n)
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.
.PP
A warning will be emitted for each address wich is redundantly se to the
same value.  A fatal error will be issued if any address is set with
contradictory values.
To supress this behaviour, use an \fB\-exclude \-within\fP filter.
.so o_input.so
.br
.ne 1i
.SH OPTIONS
The following options are understood:
.TP 8n
\fB\-Output\fP \fIfilename\fP [ \fIformat\fP ]
.RS
This option may be used to specify the output file to be used.
The special file name ``-'' is understood to mean the standard output.
Output defaults to the standard output if this option is not used.
.PP
The \fIformat\fP may be specified as:
.TP 8n
\fB\-Absolute_Object_Module_Format\fP
An Intel Absolute Object Module Format file will be written.
(See
.IR srec_aomf (5)
for a description of this file format.)
.TP 8n
\fB\-Ascii_Hex\fP
An Ascii-Hex file will be written.
(See
.IR srec_ascii_hex (5)
for a description of this file format.)
.TP 8n
\fB\-ASM\fP
A series of assembler DB statements will be written.
.TP 8n
\fB\-Atmel_Generic\fP
An Atmel Generic file will be written.
(See
.IR srec_atmel_generic (5)
for a description of this file format.)
.TP 8n
\fB\-BASic\fP
A series of BASIC DATA statements will be written.
.TP 8n
\fB\-Binary\fP
A raw binary file will be written.
.TP 8n
\fB\-C-Array\fP \fIidentifier\fP
A C array declaration will be written.
The \fIidentifier\fP is the name of the variable to be defined.
.TP 8n
\fB\-COsmac\fP
An RCA Cosmac Elf format file will be written.
(See \fIsrec_cosmac\fP(5) for a description of this file format.)
.TP 8n
\fB\-Dec_Binary\fP
A DEC Binary (XXDP) format file will be written.
(See
.IR srec_dec_binary (5)
for a description of this file format.)
.TP 8n
\fB\-Elektor_Monitor52\fP
This option says to use the EMON52 format file when writing the file.
(See
.IR srec_emon52 (5)
for a description of this file format.)
.TP 8n
\fB\-FAIrchild\fP
This option says to use the Fairchild Fairbug format file when writing the file.
(See \fIsrec_fairchild\fP(5) for a description of this file format.)
.TP 8n
\fB\-Fast_Load\fP
This option says to use the LSI Logic Fast Load format file when writing
the file.
(See \fIsrec_fastload\fP(5) for a description of this file format.)
.TP 8n
\fB\-Formatted_Binary\fP
A Formatted Binary format file will be written.
(See \fIsrec_formatted_binary\fP(5) for a description of this file format.)
.TP 8n
\fB\-Four_Packed_Code\fP
This option says to use the PFC format file when writing the file.
(See
.IR srec_fpd (5)
for a description of this file format.)
.TP 8n
\fB\-Intel\fP
An Intel hex format file will be written.
(See
.IR srec_intel (5)
for a description of this file format.)
The default is to emit 32-bit linear addressing;
if you want 16-bit extended segment addressing
use the \fB--address-length=2\fP option.
.TP 8n
\fB\-MOS_Technologies\fP
An Mos Technologies format file will be written.
(See
.IR srec_mos_tech (5)
for a description of this file format.)
.TP 8n
\fB\-Motorola\fP
A Motorola S-Record file will be written.
(See
.IR 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 \fB--address-length=3\fP option;
if you wish to force S37 use the \fB--address-length=4\fP option
.TP 8n
\fB\-Needham_Hexadecimal\fP
This option says to use the Needham Electronics ASCII file format to
write the file.  See \fIsrec_needham\fP(5) for a description of this
file format.
.TP 8n
\fB\-Ohio_Scientific\fP
This option says to use the Ohio Scientific hexadecimal format.
See \fIsrec_os65v\fP(5) for a description of this format.
.TP 8n
\fB\-SIGnetics\fP
This option says to use the Signetics hex format.
See \fIsrec_signetics\fP(5) for a description of this format.
.TP 8n
\fB\-SPAsm\fP
This option says to use the SPASM assembler output format (commonly used
by PIC programmers).
See \fIsrec_spasm\fP(5) for a description of this format.
.TP 8n
\fB\-SPAsm_LittleEndian\fP
This option says to use the SPASM assembler output format (commonly used
by PIC programmers).  But with the data the other way around.
.TP 8n
\fB\-STewie\fP
A Stewie binary format file will be written.
(See
.IR srec_stewie (5)
for a description of this file format.)
.TP 8n
\fB\-Tektronix\fP
A Tektronix hex format file will be written.
(See
.IR srec_tektronix (5)
for a description of this file format.)
.TP 8n
\fB\-Tektronix_Extended\fP
A Tektronix extended hex format file will be written.
(See
.IR srec_tektronix_extended (5)
for a description of this file format.)
.TP 8n
\fB\-Texas_Instruments_Tagged\fP
A TI-Tagged format file will be written.
(See
.IR srec_ti_tagged (5)
for a description of this file format.)
.TP 8n
\fB\-VHdl\fP [ \fIbytes-per-word\fP [ \fIname\fP ]]
A VHDL format file will be written.
The \fIbytes-per-word\fP defaaults to one,
the \fIname\fP defaults to \f[CW]eprom\fP.
The \fIetc/x_defs_pack.vhd\fP file in the source distribution contains an
example ROM definitions pack for the type-independent output.
.TP 8n
\fB\-VMem\fP [ \fImemory-width\fP ]
A Verilog VMEM format file will be written.
The \fImemory-width\fP may be 8, 16, 32, 64 or 128 bits;
.\"
.\" The default number of bits is 32.
.\" If you change this, you must also change the following files:
.\"     lib/srec/arglex_output.cc
.\"     lib/srec/output/file/vmem.cc
.\"
defaults to 32 if unspecified.
(See \fIsrec_vmem\fP(5) for a description of this file format.)
.TP 8n
\fB\-WILson\fP
A wilson format file will be written.
(See
.IR srec_wilson (5)
for a description of this file format.)
.RE
.TP 8n
\fB\-Address_Length\fP \fInumber\fP
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 brain-dead EPROM programmers which do not
fully implement the format specification.
.TP 8n
.B \-Data_Only
This option may be used to suppress all output except data fields.
This helps when talking to brain-dead EPROM programmers which do not
fully implement the format specification.
.TP 8n
.B \-CRLF
This option may be used to specify CRLF line termination for text
output.  For use with brain-dead EPROM programmers which assume all the
world uses Evil Bill's operating system's line termination.  The default
is to use the current operating system's default line termination.
Use this option with caution, because it will also introduce extra (i.e.
wrong) CR bytes into binary formats.
.TP 8n
\fB-Line_Length\fP \fInumber\fP
This option may be used to limit the length of the output lines to at
most \fInumber\fP characters.  (Not meaningful for binary file format.)
Defaults to something less than 80 characters, depending on the format.
.TP 8n
\fB\-HEAder\fP \fIstring\fP
This option may be used to set the header comment,
in those formats which support it.
.TP 8n
\fB\-Start_Address\fP \fInumber\fP
This option may be used to set the start address,
in those formats which support it.
.so o_multiple.so
.PP
All other options will produce a diagnostic error.
.so z_options.so
.so z_exit.so
.SH EXAMPLES
The \fI\*(n)\fP command is very powerful, due to the ability to combine
the the input filters in almost unlimited ways.
.SS Converting File Formats
The simplest case is converting files from Intel hex format to Motorola
S-Record format:
.RS
.ft CW
\*(n) \fIintel-file\fP -intel -o \fIsrec-file\fP
.ft R
.RE
Converting the other was is just as simple:
.RS
.ft CW
\*(n) \fIsrec-file\fP -o \fIintel-file\fP -intel
.ft R
.RE
In each case, the default format is Motorola S-Record format,
so it does not need to be specified.
.SS Cropping the Data
A common activity is to crop your data to match your EPROM location.
Your linker may add other junk that you are not interested in, \fIe.g.\fP
at the RAM location.  In this example, there is a 1MB EPROM at the 2MB
boundary:
.RS
.ft CW
\*(n) \fIinfile\fP -crop 0x200000 0x300000 -o \fIoutfile\fP
.ft R
.RE
The lower bound is inclusive, the upper bound is exclusive.
.SS Address Offset
Just possibly, you have a moronic EPROM programmer, and it barfs if the
eprom doesn't start at zero.  Rather than butcher the linker command file,
just offset the addresses:
.RS
.ft CW
\*(n) \fIinfile\fP -crop 0x200000 0x300000 -offset -0x200000 -o \fIoutfile\fP
.ft R
.RE
This example also demonstrates how the input filters may be chained together.
.SS Joining Files Together
The \fI\*(n)\fP command takes its name from the UNIX \fIcat\fP(1) command,
which is short for `catenate' or `to join'.  Joining files together into
a single file is simple, just name as many files on the command line as
you need:
.RS
.ft CW
\*(n) \fIinfile1\fP \fIinfile2\fP -o \fIoutfile\fP
.ft R
.RE
However, this assumes that the files don't overlap in any way (you will
get an error if they do).  If both files start from address zero, you
may need to use the offset filter:
.RS
.ft CW
\*(n) \fIinfile1\fP \fIinfile2\fP -offset 0x80000 -o \fIoutfile\fP
.ft R
.RE
Sometimes you want the two files to follow each other exactly,
but you don't know the offset in advance:
.RS
.ft CW
\*(n) \fIinfile1\fP \fIinfile2\fP -offset -maximum \fIinfile1\fP
-o \fIoutfile\fP
.ft R
.RE
Notice that where the was a number (0x80000) before, there is now a
calculation (\-maximum \fIinfile1\fP).  This is possible most places
a number may be used (also \-minimum and \-range).
.SS Filling the Blanks
It is possible to fill the blanks where our data does not lie.
The simplest example of this fills the entire EPROM:
.RS
.ft CW
\*(n) \fIinfile\fP -fill 0x00 0x200000 0x300000 -o \fIoutfile\fP
.ft R
.RE
This example fills the holes, if any, with zeros.
You must specify a range - with a 32-bit address space,
filling everything generates \fIhuge\fP load files.
.PP
If you only want to fill the gaps in your data,
and don't want to fill the entire EPROM, try:
.RS
.ft CW
\*(n) \fIinfile\fP -fill 0x00 -over \fIinfile\fP -o \fIoutfile\fP
.ft R
.RE
This example demonstrates the fact that wherever an address range may be
specified, the \fB\-over\fP and \fB\-within\fP options may be used.
.SS Unfilling the Blanks
It is common to need to ``unfill'' an eprom image after you read it out of
a chip.  Usually, it will have had all the holes filled with 0xFF (areas
of the EPROM you don't program show as 0xFF when you read them back).
.PP
To get rid of all the 0xFF bytes in the data, use this filter:
.RS
.ft CW
\*(n) \fIinfile\fP -unfill 0xFF -o \fIoutfile\fP
.ft R
.RE
This will get rid of \fIall\fP the 0xFF bytes, including the ones you
actually wanted in there.  There are two ways to deal with this.  First,
you can specify a minimum run length to the un-fill:
.RS
.ft CW
\*(n) \fIinfile\fP -unfill 0xFF 5 -o \fIoutfile\fP
.ft R
.RE
This says that runs of 1 to 4 bytes of 0xFF are OK, and that a hole
should only be created for runs of 5 or more 0xFF bytes in a row.
The second method is to re-fill over the intermediate gaps:
.RS
.ft CW
\*(n) \fIoutile\fP -fill 0xFF -over \fIoutfile\fP -o \fIoutfile2\fP
.ft R
.RE
Which method you choose depends on your needs, and the shape of the data
in your EPROM.  You may need to combine both techniques.
.SS Splitting an Image
If you have a 16-bit data bus, but you are using two 8-bit EPROMs to
hold your firmware, you can generate the even and odd images by using
the \-SPlit filter.  Assuming your firmware is in the \fIfirmware.hex\fP
file, use the following:
.RS
.nf
.ft CW
\*(n) firmware.hex -split 2 0 -o firmware.even.hex
\*(n) firmware.hex -split 2 1 -o firmware.odd.hex
.ft R
.fi
.RE
This will result in the two necessary EPROM images.  Note that the output
addresses are divided by the split multiple, so if your EPROM images
are at a particular offset (say 0x10000, in the following example),
you need to remove the offset, and then replace it...
.RS
.nf
.ft CW
.ta 0.5i 1i 1.5i
\*(n) firmware.hex \e
	-offset -0x10000 -split 2 0 \e
	-offset 0x10000 -o firmware.even.hex
\*(n) firmware.hex \e
	-offset -0x10000 -split 2 1 \e
	-offset 0x10000 -o firmware.odd.hex
.ft R
.fi
.RE
Note how the ability to apply multiple filters simplifies what would
otherwise be a much longer script.
.PP
A second use for the \-SPlit filter is memory striping.
In this example, the hardware requires that 512-byte blocks alternate
between 4 EPROMs.  Generating the 4 images would be done as follows:
.RS
.nf
.ft CW
\*(n) firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
\*(n) firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
\*(n) firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
\*(n) firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex
.ft R
.fi
.RE
.PP
The unsplit filter may be used to reverse the effects of the split filter.
Note that the address range is expanded leaving holes between the stripes.
By using all the stripes, the complete input is reassembled, without
any holes.  For example, to reverse our previous 16-bit data bus example,
use the following command:
.RS
.nf
.ft CW
.ta 0.5i 1i 1.5i
\*(n) -o firmware.hex \e
	firmware.even.hex -unsplit 2 0 \e
	firmware.odd.hex  -unsplit 2 1
.ft R
.fi
.RE
.so z_copyright.so