'\" t
.\"     srecord - The "srecord" program.
.\"     Copyright (C) 2007 Peter Miller
.\"
.\"     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 3 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, see
.\"     <http://www.gnu.org/licenses/>.
.\"
.ds n) srec_cat
.TH srec_examples 1 SRecord "Reference Manual"
.SH NAME
srec_examples \- examples of how to use SRecord
.XX "srec_examples(1)" "examples of how to use SRecord"
.SH DESCRIPTION
The \f[I]srec_cat\fP command is very powerful, due to the ability to combine
the the input filters in almost unlimited ways.
This manual page describes a few of them.
.PP
This manual page describes how to use the various input files, input
filters and input generators.  But these are only examples, for more
complete details, see the \f[I]srec_input\fP(1) manual page.
.SS Your Examples Wanted
If you have a clever way of using SRecord, or have solves a difficult
problem with SRecord, you could contribute to this manual page, making
it more useful for everyone.  Send an email to the email address at the
end of this manual page.
.SH CONVERTING FILE FORMATS
The simplest of the things \f[I]srec_cat\fP(1) can do is convert from
one EPROM file format to another.  Please keep in mind, as you read this
section, that you can do many of these things simultaneously in one
command.  They are only broken out separately to make them easier to
understand.
.SS Intel to Motorola
One of the simplest examples is converting files from Intel hex format
to Motorola S-Record format:
.RS
.ft CW
srec_cat \f[I]intel-file\fP -intel -o \f[I]srec-file\fP
.ft R
.RE
Pick any two formats that SRecord understands,
it can convert between all of them.
(Except the assembler, BASIC, C and FPGA outputs which are write only.)
.SS Motorola to Intel
Converting the other way is just as simple:
.RS
.ft CW
srec_cat \f[I]srec-file\fP -o \f[I]intel-file\fP -intel
.ft R
.RE
The default format is Motorola S-Record format,
so it does not need to be specified.
.SS Different Shapes of the Same Format
It is regrettably common that some addle-pated EPROM programmers only
implement a portion of the specification used to represent their hex
files.  For example, some compilers produce \(lqs19\(rq Motorola
data (that is, S1 data records with S9 start records, 16 bit address
fields) which would be OK except that some blockhead EPROM programmers insist
on \(lqs37\(rq Motorola data (that is, S3 data records with S7 start
records, 32 bit address fields).
.PP
It is possible to convert from one Motorola shape to another using the
\fB\-Address-Length\fP option:
.RS
.ft CW
srec_cat short.srec -o long.srec --address-length=4
.ft R
.RE
This command says to use four byte (32-bit) addresses on output.
.PP
This section also applies to Intel hex files, as they, too, have the
ability to select from a variety of address widths.
.SS Line Lengths
From time to time you will come across a feeble-minded EPROM programmer
that can't cope with long SRecord lines, they assume that there will
only ever be 16 bytes of data per line, and barf when they see the
default 32 byte payloads that \f[I]srec_cat\fP(1) writes.
.PP
The Motorola S-record format definition permits up to 255 bytes of
payload.  All EPROM programmers \f[I]should\fP have sufficiently large
buffers to cope with records this big.  Few do.
.PP
The \-line-length option may be used to specify the maximum line length
(not including the newline) to be used on output.
For example, 16 byte payloads for Motorola hex
.RS
.ft CW
srec_cat long.srec -o short.s19 --line-length=46
.ft R
.RE
The line length option interacts with the address length option, so some
tinkering to optimize for your particular situation many be necessary.
.SS Just the Data, Please
There are some bonehead EPROM programmers which can only cope with data
records, and are unable to cope with header records or start address
records.  If you have this problem, the \fB\-data-only\fP option can be
used to suppress just about everything except the data.  The actual
effect depends on the format, of course, because some don't have these
features anyway.
.SS Data Headers
The \f[I]srec_cat\fP(1) command always tries to pass through header
records unchanged, whenever they are present.
It even tries preserve them across file format changes,
to the limit the file formats are capable of.
.PP
If there is no file header record and you would like to add one,
or you which to override an existing file header record, use the
\fB\-header\fP=\f[I]string\fP option.  You will need to quote the
string (to insulate it from the shell) if it contains spaces or shell
meta-characters.
.SS Start Addresses
The \f[I]srec_cat\fP(1) command always tries to pass through start
addresses (typically occurring at the end of the file), whenever they
are present.  They are adjusted along with the data records by the
\fB\-offset\fP filter.  It even tries preserve them across file format
changes, to the limit the file formats are capable of.
.PP
If there is no start address record and you would like to add one,
or you which to override an existing start address record, use the
\fB\-start-address\fP=\f[I]number\fP option.
.SS Fixing Checksums
Some embedded firmware developers are saddled with featherbrained tools
which produce incorrect checksums, which the more vigilant models of
EPROM programmer will not accept.
.PP
To fix the checksums on a file, use the \fB\-ignore-checksums\fP option.
For example:
.RS
.ft CW
srec_cat broken.srec --ignore-checksums -o fixed.srec
.ft R
.RE
The checksums in \f[I]broken.srec\fP are parsed (it is still
and error if they are absent) but are not checked.  The
resulting \f[I]fixed.srec\fP file has correct checksums.  The
\fB\-ignore-checksums\fP option only applies to input.
.PP
This option may be used on any file format which has checksums,
including Intel hex.
.\" ------------------------------------------------------------------------
.SH JOINING FILES TOGETHER
The \f[I]srec_cat\fP command takes its name from the UNIX \f[I]cat\fP(1)
command, which is short for 'catenate' or 'to join'.
The \f[I]srec_cat\fP command joins EPROM load files together.
.SS All In One
Joining EPROM load files together into a single file is simple, just
name as many files on the command line as you need:
.RS
.ft CW
srec_cat \f[I]infile1\fP \f[I]infile2\fP -o \f[I]outfile\fP
.ft R
.RE
This example is all Motorola S-Record files, because that's the
default format.  You can have multiple formats in the one command, and
\f[I]srec_cat\fP(1) will still work.  You don't even have to output the
same format:
.RS
.nf
.ft CW
srec_cat \f[I]infile1\fP -spectrum \f[I]infile2\fP -needham \e
    -o \f[I]outfile\fP -signetics
.ft R
.fi
.RE
These are all ancient formats, however it isn't uncommon to have to mix
and match Intel and Motorola formats in the one project.
.SS Joining End-to-End
All too often the address ranges in the EPROM load files will overlap.
You will get an error if they do.
If both files start from address zero, because each goes into a separate
EPROM, you may need to use the offset filter:
.RS
.ft CW
.nf
srec_cat \f[I]infile1\fP \e
    \f[I]infile2\fP -offset 0x80000 \e
    -o \f[I]outfile\fP
.fi
.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
.nf
srec_cat \f[I]infile1\fP \e
    \f[I]infile2\fP -offset -maximum \f[I]infile1\fP \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Notice that where the was a number (0x80000) before, there is now a
calculation (\-maximum \f[I]infile1\fP).  This is possible most places
a number may be used (also \-minimum and \-range).
.\" ------------------------------------------------------------------------
.SH CROPPING THE DATA
It is possible to copy an EPROM load file,
selecting addresses to keep and addresses to discard.
.SS What To Keep
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, \f[I]e.g.\fP
at the RAM location.  In this example, there is a 1MB EPROM at the 2MB
boundary:
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP -crop 0x200000 0x300000 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
The lower bound for all address ranges is inclusive, the upper bound is
exclusive.  If you subtract them, you get the number of bytes.
.SS Address Offset
Just possibly, you have a moronic EPROM programmer, and it barfs if the
EPROM image doesn't start at zero.
To find out just where is \f[I]does\fP start in memory,
use the \f[I]srec_inf\fP(1) command:
.RS
.ft CW
.nf
$ \f[CB]srec_info example.srec\fP
Format: Motorola S-Record
Header: extra-whizz tool chain linker
Start:  0x00200000
Data:   0x200000 - 0x32AAEF
$
.fi
.ft R
.RE
Rather than butcher the linker command file,
just offset the addresses:
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP -crop 0x200000 0x300000 -offset -0x200000 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Note that the offset given is \f[I]negative\fP, it has the effect of
subtracting that value from all addresses in the input records, to form
the output record addresses.  In this case, shifting the image back to zero.
.PP
This example also demonstrates how the input filters may be chained
together: first the crop and then the offset, all in one command,
without the need for temporary files.
.PP
If all you want to do is offest the data to start from address zero,
this can be automated, so you don't have to know the minimum address in
advance, by using \f[I]srec_cat\fP's ability to calculate some things on
the command line:
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP -offset - -minmum \f[I]infile\fP \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Note the spaces either side of the minus sign, they are mandatory.
.SS What To Throw Away
There are times when you need to exclude an small address range from an
EPROM load file, rather than wanting to keep a small address range.
The \fB\-exclude\fP filter may be used for this purpose.
.PP
For example, if you wish to exclude the address range where the serial
number of an embedded device is kept, say 0x20 bytes at 0x100, you would use
a command like this:
.RS
.ft CW
srec_cat input.srec -exclude 0x100 0x120 -o output.srec
.ft R
.RE
The \f[I]output.srec\fP file will have a hole in the data at the
necessary locations.
.PP
Note that you can have both \fB\-crop\fP and \fB\-exclude\fP on the same
command line,
whichever works more naturally for your situation.
.SS Discontinuous Address Ranges
Address ranges don't have to be a single range, you can build up an
address range using more than a single pair.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP -crop 0x100 0x200 0x1000 0x1200 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
This filter results in data from 0x100..0x1FF and data from
0x1000..0x1200 to pass through, the rest is dropped.  This is is more
efficient than chaining a \-crop and an \-exclude filter together.
.\" ------------------------------------------------------------------------
.SH MOVING THINGS AROUND
It is also possible to change the address of data records, both forwards
and backwards.  It is also possible rearrange where data records are
placed in memory.
.SS Offset Filter
The \fB\-offset=\fP\f[I]number\fP filter operates on the addresses of
records.  If the number is positive the addresses move that many bytes
higher in memory, negative values move lower.
.RS
.nf
.ft CW
srec_cat \f[I]infile\fP -crop 0x200000 0x300000 -offset -0x200000 \e
    -o \f[I]outfile\fP
.ft R
.fi
.RE
The above example moves the 1MB block of data at 0x200000 down to zero
(the offset is \f[I]negative\fP) and discards the rest of the data.
.SS Byte Swapping
There are times when the bytes in the data need to be swapped,
converting between big-endian and little-endian data usually.
.RS
.nf
.ft CW
srec_cat \f[I]infile\fP --byte-swap 4 -o \f[I]outfile\fP
.ft R
.fi
.RE
This reverses bytes in 32 bit values (4 bytes).  The default, if you
don't supply a width, is to reverse bytes in 16 bit values (2 bytes).
You can actually use any weird value you like, although 64 bits (8
bytes) may be useful one day.
.SS Binary Output
You need to watch out for binary files on output, because the holes are
filled with zeros.  You 100kB program at the top of 32-bit addressed
memory will make a 4GB file.  See \f[I]srec_binary\fP(1) for how
understand and avoid this problem, usually with the \-offset filter.
.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 \f[I]firmware.hex\fP
file, use the following:
.RS
.nf
.ft CW
srec_cat firmware.hex -split 2 0 -o firmware.even.hex
srec_cat 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
srec_cat firmware.hex \e
    -offset -0x10000 -split 2 0 \e
    -offset 0x10000 -o firmware.even.hex
srec_cat 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.
.SS Striping
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
srec_cat firmware.hex -split 0x800 0x000 0x200 -o firmware.0.hex
srec_cat firmware.hex -split 0x800 0x200 0x200 -o firmware.1.hex
srec_cat firmware.hex -split 0x800 0x400 0x200 -o firmware.2.hex
srec_cat firmware.hex -split 0x800 0x600 0x200 -o firmware.3.hex
.ft R
.fi
.RE
.SS Unspliting Images
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.
.RS
.nf
.ft CW
srec_cat -o firmware.hex \e
    firmware.even.hex -unsplit 2 0 \e
    firmware.odd.hex  -unsplit 2 1
.ft R
.fi
.RE
The above example reverses the previous 16-bit data bus example,.
.\" ------------------------------------------------------------------------
.SH FILLING THE BLANKS
Often EPROM load files will have \(lqholes\(rq in them, places where the
compiler and linker did not put anything.  For some purposes this is OK,
and for other purposes something has to be done about the holes.
.SS The Fill Filter
It is possible to fill the blanks where your data does not lie.
The simplest example of this fills the entire EPROM:
.RS
.ft CW
srec_cat \f[I]infile\fP -fill 0x00 0x200000 0x300000 -o \f[I]outfile\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 \f[I]huge\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
srec_cat \f[I]infile\fP -fill 0x00 -over \f[I]infile\fP -o \f[I]outfile\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 \(lqunfill\(rq 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
srec_cat \f[I]infile\fP -unfill 0xFF -o \f[I]outfile\fP
.ft R
.RE
This will get rid of \f[I]all\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
srec_cat \f[I]infile\fP -unfill 0xFF 5 -o \f[I]outfile\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
.nf
srec_cat \f[I]outfile\fP -fill 0xFF -over \f[I]outfile\fP \e
    -o \f[I]outfile2\fP
.fi
.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 Address Range Padding
Some data formats are 16 bits wide, and automatically fill with 0xFF bytes if
it is necessary to fill out the other half of a word which is not in the data.
If you need to fill with a different value, you can use a command like this:
.RS
.nf
.ft CW
srec_cat \f[I]infile\fP -fill 0x0A \e
    -within \f[I]infile\fP -range-padding 2 \e
    -o \f[I]outfile\fP
.ft R
.fi
.RE
This gives the fill filter an address range calculated from details of
the input file.  The address range is all the address ranges covered by
data in the \f[I]infile\fP, extended downwards (if necessary) at the
start of each sub-range to a 2 byte multiple and extended upwards (if
necessary) at the end of each sub-range to a 2 byte multiple.  This also
works for larger multiples, like 1kB page boundaries of flash chips.
This address range padding works anywhere an address range is required.
.SS Fill with Copyright
It is possible to fill unused portions of your EPROM with a repeating
copyright message.  Anyone trying to reverse engineer your EPROMs is
going to see the copyright notice in their hex editor.
.PP
This is accomplished with two input sources, one from a data file,
and one which is generated on-the-fly.
.RS
.nf
.ft CW
srec_cat \f[I]infile\fP \e
    -generate '(' 0 0x100000 -minus -within \f[I]infile\fP ')' \e
        -repeat-string 'Copyright (C) 1812 Tchaikovsky.  ' \e
    -o \f[I]outfile\fP
.ft R
.fi
.RE
Notice how the address range for the data generation: it takes the
address range of your EPROM, in this case 1MB starting from 0, and
subtracts from it the address ranges used by the input file.
.PP
The string specified is repeated over and over again, until it has
filled all the holes.
.SS Obfuscating with Noise
Sometimes you want to fill your EPROM images with noise, to conceal
where the real data stops and starts.
You can do this with the \fB\-random-fill\fP filter.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP -random-fill 0x200000 0x300000 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
It works just like the \fB\-fill\fP filter,
but uses random numbers instead of a constant byte value.
.SS Fill With 16-bit Words
When filling the image with a constant byte value doesn't work, and you
need a constant 16-bit word value instead, use the \fB\-repeat-data\fP
generator, which takes an arbitrarily long sequence of bytes to use as
the fill pattern:
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
    -generator '(' 0x200000 0x300000 -minus -within \f[I]infile\fP ')' \e
        -repeat-data 0x1B 0x08 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Notice how the generator's address range once again avoids the address
ranges occupied by the \f[I]infile\fP's data.
You have to get the endian-ness right yourself.
.SH DATA ABOUT THE DATA
It is possible to add a variety of data about the data to the output.
.SS Checksums
The \fB\-big-endian-checksum-negative\fP filter may be used to sum the
data, and then insert the negative of the sum into the data.  This has
the effect of summing to zero when the checksum itself is summed across,
provided the sum width matches the inserted value width.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
        --crop 0 0xFFFFFC \e
        --random-fill 0 0xFFFFFC \e
        --b-e-checksum-neg 0xFFFFFC 4 4 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
In this example, we have an EPROM in the lowest megabyte of memory.
The \-crop filter ensures we are only summing the data within the EPROM,
and not anywhere else.
The \-random-fill filter fills any holes left in the data with random values.
Finally, the \-b-e-checksum-neg filter inserts a 32 bit (4 byte) checksum
in big-endian format in the last 4 bytes of the EPROM image.
Naturally, there is a little endian version of this filter as well.
.PP
Your embedded code can check the EPROM using C code similar to the following:
.RS
.nf
.ft CW
unsigned long *begin = (unsigned long *)0;
unsigned long *end = (unsigned long *)0x100000;
unsigned long sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != 0)
{
    \f[I]Oops\fP
}
.ft R
.fi
.RE
.PP
The \-big-endian-checksum-bitnot filter is similar, except that summing
over the checksum should yield a value of all-one-bits (-1).
For example, using shorts rather than longs:
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
        --crop 0 0xFFFFFE \e
        --fill 0xCC 0x00000 0xFFFFFE \e
        --b-e-checksum-neg 0xFFFFFE 2 2 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Assuming you chose the correct endian-ness filter,
your embedded code can check the EPROM using C code similar to the following:
.RS
.nf
.ft CW
unsigned short *begin = (unsigned long *)0;
unsigned short *end = (unsigned long *)0x100000;
unsigned short sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != 0xFFFF)
{
    \f[I]Oops\fP
}
.ft R
.fi
.RE
.PP
There is also a \-b-e-checksum-positive filter, and a matching
little-endian filter, which inserts the simple sum, and which would be
checked in C using an equality test.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
        --crop 0 0xFFFFFF \e
        --fill 0x00 0x00000 0xFFFFFF \e
        --b-e-checksum-neg 0xFFFFFF 1 1 \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
Assuming you chose the correct endian-ness filter,
your embedded code can check the EPROM using C code similar to the following:
.RS
.nf
.ft CW
unsigned char *begin = (unsigned long *)0;
unsigned char *end = (unsigned long *)0xFFFFF;
unsigned char sum = 0;
while (begin < end)
    sum += *begin++;
if (sum != *end)
{
    \f[I]Oops\fP
}
.ft R
.fi
.RE
In the 8-bit case, it doesn't matter whether you use the big-endian or
little-endian filter.
.SS Cyclic Redundancy Checks
The simple additive checksums have a number of theoretical limitations,
to do with errors they can and can't detect.  The CRC methods have fewer
problems.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
        --crop 0 0xFFFFFC \e
        --fill 0x00 0x00000 0xFFFFFC \e
        --b-e-crc32 0xFFFFFC \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
In the above example, we have an EPROM in the lowest megabyte of memory.
The \-crop filter ensures we are only summing the data within the EPROM,
and not anywhere else.
The \-fill filter fills any holes left in the data.
Finally, the \-b-e-checksum-neg filter inserts a 32 bit (4 byte) checksum
in big-endian format in the last 4 bytes of the EPROM image.
Naturally, there is a little endian version of this filter as well.
.PP
The checksum is calculated using the industry standard 32-bit CRC.
Because SRecord is open source, you can always read the source code
to see how it works.  There are many non-GPL version of this code
available on the Internet, and suitable for embedding in proprietary
firmware.
.PP
There is also a 16-bit CRC available.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP \e
        --crop 0 0xFFFFFE \e
        --fill 0x00 0x00000 0xFFFFFE \e
        --b-e-crc16 0xFFFFFE \e
    -o \f[I]outfile\fP
.fi
.ft R
.RE
.PP
The checksum is calculated using the CCITT formula.
Because SRecord is open source, you can always read the source code
to see how it works.  There are many non-GPL version of this code
available on the Internet, and suitable for embedding in proprietary
firmware.
.SS Where Am I?
There are several properties of you EPROM image that you may wish to
insert into the data.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --b-e-minimum 0xFFFFFE 2 -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example inserts the minimum address of the data
(\f[I]low water\fP)
into the data.  This includes the minimum itself.
If the data already contains bytes at the given address,
you need to use an exclude filter.
The value will be written with the most significant byte first.
The number of bytes defaults to 4.
There is also a little-endian variant.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --b-e-maximum 0xFFFFFE 2 -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example inserts the maximum address of the data
(\f[I]high water + 1\fP, just like address ranges)
into the data.  This includes the maximum itself.
If the data already contains bytes at the given address,
you need to use an exclude filter.
The value will be written with the most significant byte first.
The number of bytes defaults to 4.
There is also a little-endian variant.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --b-e-maximum 0xFFFFFE 2 -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example inserts the length of the data
(\f[I]high water\fP + 1 - \f[I]low water\fP) into the data.
This includes the length itself.
If the data already contains bytes at the length location,
you need to use an exclude filter.
The value will be written with the most significant byte first.
The number of bytes defaults to 4.
There is also a little-endian variant.
.SS What Format Is This?
You can obtain a variety of information about an EPROM load file
by using the \f[I]srec_info\fP(1) command.
For example:
.RS
.ft CW
.nf
$ \f[CB]srec_info example.srec\fP
Format: Motorola S-Record
Header: "http://srecord.sourceforge.net/"
Start:  00000000
Data:   0000 - 0122
        0456 - 0FFF
$
.fi
.ft R
.RE
This example show that the file is a Motorola S-Record.  The text in the
file header is printed, along with the start address.  The final section
shows the address ranges containing data (the upper bound of each
subrange is \f[I]in\f[P]clusive, rather than the \f[I]ex\f[P]clusive form
used on the command line.
.RS
.ft CW
.nf
$ \f[CB]srec_info some-weird-file.hex --guess\fP
Format: Signetics
Data:   0000 - 0122
        0456 - 0FFF
$
.fi
.ft R
.RE
The above example guesses the EPROM load file format.
It isn't infallible but it usually gets it right.
You can use \fB\-guess\fP anywhere you would give an explicit format,
but it tends to be slower and not recommended.
.SH MANGLING THE DATA
It is possible to change the values of the data bytes in several ways.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --and 0xF0 -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example performs a bit-wise AND of the data bytes with the 0xF0 mask.
The addresses of records are unchanged.
I can't actually think of a use for this filter.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --or 0x0F -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example performs a bit-wise OR of the data bytes with the 0x0F bits.
The addresses of records are unchanged.
I can't actually think of a use for this filter.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --xor 0xA5 -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example performs a bit-wise exclusive OR of the data bytes
with the 0xA5 bits.
The addresses of records are unchanged.
You could use this to obfuscate the contents of your EPROM.
.RS
.ft CW
.nf
srec_cat \f[I]infile\fP --not -o \f[I]outfile\fP
.fi
.ft R
.RE
The above example performs a bit-wise NOT of the data bytes.
The addresses of records are unchanged.
Security by obscurity?
.so z_copyright.so
.\" vim:ts=8:sw=4:et