.\"
.\"     srecord - manipulate eprom load files
.\"     Copyright (C) 2001, 2002, 2004, 2006, 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/>.
.\"
.TH "New Format" "SRecord" "SRecord" "Reference Manual"
.SH NAME
How to add a new file format
.XX "" "How to add a new file format"
.SH DESCRIPTION
This section describes how to add a new file format.  It's mostly a
set of reminders for the maintainer.  If you want a format added
to the distribution, use this method and e-mail the maintainer a patch
(generated with \f[CW]diff -u -r\fP, usually) and it can be added to the sources
if appropriate.
.SS New Files
The following files need to be create for a new format.
.TP 8n
lib/srec/output/file/\fIname\fP.cc
This file is how to write the new format.
Take a look at the other files in the same directory
for examples.  Also check out \fIlib/srec/output/file.h\fP and
\fIlib/srec/output.h\fP for various helper methods.
.TP 8n
lib/srec/output/file/\fIname\fP.h
This is the class declaration for the above file.
.TP 8n
lib/srec/input/file/\fIname\fP.cc
This file is how to read the new format.
Take a look at the other files in the same directory
for examples.  Also check out \fIlib/srec/input/file.h\fP and
\fIlib/srec/input.h\fP for various helper methods.
.TP 8n
lib/srec/input/file/\fIname\fP.h
This is the class declaration for the above file.
.TP 8n
man/man5/srec_\fIname\fP.5
This file describes the format.  Take a look at the other files in the
same directory for examples.
.SS Modified Files
The following files need to be updated to mention the new format.
.TP 8n
etc/README.man
Mention the new format in the section of this file which describes
the supported file formats.
.TP 8n
etc/index.html
Mention the new format in the section of this file which describes
the supported file formats.
.TP 8n
lib/srec/arglex.h
Add the new format to the command line argument type enum.
.TP 8n
lib/srec/arglex.cc
Add the new format to the array of command line arguments types.
.TP 8n
lib/srec/arglex/input.cc
Add the new format to the code which parses input formats.
.TP 8n
lib/srec/arglex/output.cc
Add the new format to the code which parses output formats.
.TP 8n
lib/srec/input/file/guess.cc
Add the new format to the list of formats which are tested.
.TP 8n
man/man1/o_input.so
Mention the new format in the section of this file which describes
the supported input file formats.
.TP 8n
man/man1/srec_cat.1
Mention the new format in the section of this file which describes
the supported output file formats.
.TP 8n
Makefile
Actually, the system the maintainer uses automatically generates this
file, but if you aren't using Aegis you will need to edit this file for
your own use.
.SS Tests
You may have noticed that SRecord comes with a lot of tests.  You are
more likely to get the patch for your new format accepted rapidly if it
comes with at least one test for its output class, and at least one test
for its input class.
.SH IMPLEMENTATION ISSUES
In implementing a new file format, there are a couple of philosophical
issues which affect technical decissions:
.TP 8n
Be liberal in what you accept
Where ever possible, consume the widest possible interpretation of
valid data.  This includes treating mandatory input fields as optional
(\f[I]e.g.\fP file headers and start addresses), and coping with input
definitions to their logical extremes (\f[I]e.g.\fP 255 byte data
records in Motorola format).
Checksums should always be checked on input, only ignore them if the
\-ignore-checksums command line option has been given.
Absurd line lengths must be tolerated.
.TP 8n
Be conservative in what you produce
Even when the input is questionable, the output produced by
\f[I]srec_cat\fP must always be strictly conforming with the format
definition (except as mandated by command line options, see below).
Checksums, if the format has them, must always be correct on output.
Line lengths should default to something reasonable (about 80 characters
or less).
.TP 8n
Eat Your Own Dog Food
You input class must always be able to consume what your output class
produces, no matter what combination of command line options (see below)
has been selected.
.TP 8n
Round Trip
.RS
.TP 3n
In general, what went in is what comes out.
.TP 3n
\(bu
The data may be re-arranged in order, the line lengths may change, but
the same data should go out as came in.
(The data should be unchanged even if the format changed,
assuming equally capable formats.)
.TP 3n
\(bu
If the input has no header record, the output should not have one either
(if at all possible).  This means not automagically inserting a header
record if the output file code sees data as the first method call.
(The \-data-only flag affects this, too.)
.TP 3n
\(bu
If the input has no start address record, the output should not have one
either (if at all possible).  This means not automagically inserting a
start address record if the output file code does not see one by the
time the destructor is called.
(The \-data-only flag affects this, too.)
.RE
.TP 8n
Holes
Do not to fill in holes in the data.  That said, sometimes you
\f[I]have\fP to fill holes in the data.  This happens, for example, when
a 16-bit format is faced with an 8-bit byte of data for one or other
half of a 16-bit word.  If there is no other way around it, fill the
hole with 0xFF.  This is because most erased EPROMs have 0xFF data, and
so the 0xFF won't change anything.
.PP
There are also some command line arguments you will need to take into account:
.TP 8n
\fB\-address-length\fP
This options is used to specify the minimum address length, if your new
format has a choice about how many bytes of address it produces.
.TP 8n
\fB\-data-only\fP
If this flag is set, only data records should be produced.  No headers,
no start addresses, nothing, even if the format specifications
considers these mandatory.  Do what the user said.  This is available
as the \f[CW]data_only_flag\fP instance variable in the methods of your
derived class.
.TP 8n
\fB\-ignore-checksums\fP
If this flag is set, your file input methods must parse \f[I]but not
check\fP checksums, if the format has checksums.  This is available in
the \f[CW]use_checksums()\fP method within the methods of your derived
class.  This only applies to input; output must always produce correct
checksums.
.TP 8n
\fB\-line-length\fP
Where your ouput format is text, and there exists the possibility of
putting more or less text on each line (\f[I]e.g.\fP the Motorola format
allows a variable number of data bytes per record) then this should be
controlable.  This manifests in the \f[CW]address_length_set\fP and
\f[CW]preferred_block_size_get\fP methods you must implement in your
derived class.
.SH AUTHOR
.TS
tab(;);
l l l.
Peter Miller;E-Mail:;millerp@canb.auug.org.au
\f(CW/\e/\e*\fP;WWW:;http://www.canb.auug.org.au/~millerp/
.TE