289 lines
11 KiB
Groff
289 lines
11 KiB
Groff
.TH p2hex 1
|
|
|
|
.SH NAME
|
|
.B p2hex \- convert code files into hex files
|
|
|
|
.SH SYNTAX
|
|
.B p2hex
|
|
[ option(s) ] <name(s)> [ further options/names ]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
P2HEX is a tool to convert the contents of one or several code files
|
|
generated by AS into HEX files. A HEX file is a common method of
|
|
representing binary data in a way that is human-readable and
|
|
transferrable over non-transparent data lines. Generally spoken,
|
|
each byte of code or data is represented by two characters that show
|
|
the byte in its hexadecimal notation. A HEX file also contains
|
|
additional information like addresses and checksums that ease
|
|
processing of the data. Unfortunately, there is no generally
|
|
accepted standard format for HEX files. Instead, every processor
|
|
manufacturer developed his own format and some of them have become
|
|
"industry standards". P2HEX supports all formats that seem to have
|
|
gained acceptance, with some variations that are commonplace.
|
|
|
|
Arguments to P2HEX may be either command line parameters or file name
|
|
specifications. Any argument that starts with the charactes +, - or
|
|
/ is regarded as a comand line parameter (which may take an
|
|
additional command line argument); any other argument is regarded as
|
|
a file name. Generally, P2HEX needs at least two file names: An
|
|
input code file and the name of the HEX output file. If multiple
|
|
file names are given, P2HEX will always take the last name as the
|
|
output file's name. If an input file name does not have an
|
|
extension, the extension '.p' is added automatically. Similarly, the
|
|
extension '.hex' is added automatically to the target file's name.
|
|
A special case occurs when only one file name is given: P2HEX will
|
|
then take its name as the source (possibly extended with '.p'), and
|
|
the same name as target (with '.hex' as additional or replaced
|
|
extension).
|
|
|
|
By default, P2HEX will choose a HEX format that is the most common
|
|
for the processor family a source file contains code for; this
|
|
however means that if the source file(s) contain(s) code for different
|
|
processor families, the HEX file might become an undesirable mixture
|
|
of formats; use the
|
|
.B -F
|
|
command-line parameter to force a certain format then.
|
|
|
|
.SH COMMAND-LINE PARAMETERS
|
|
|
|
If a command-line parameter starts with a slash(/) or minus sign(-),
|
|
it turns an option on; if a command-line parameter starts with a plus
|
|
sign(+), it turns a specific option off. Numeric arguments to
|
|
parameters can be either written in decimal or hexadecimal notation.
|
|
For hexadecimal notation, prefix the number with a dollar($) sign.
|
|
In the following list, all options will be shown in the form that is
|
|
needed to change the default behaviour, which might be a plus or
|
|
minus sign, depening on wether the option is on or off by default.
|
|
|
|
.B p2hex
|
|
accepts the following command-line parameters:
|
|
.TP
|
|
.B -a
|
|
|
|
Tell P2HEX to use relative addressing in the output HEX file. By
|
|
default, addresses the HEX file will be exactly the same absolute
|
|
addresses as they were in the code file. This may create problems
|
|
with some EPROM-burners if your code does not start at address 0. In
|
|
relative mode, the address filter's start address (see the
|
|
.B -r
|
|
command line switch) is subtracted from all addresses specifications
|
|
in the HEX file (with the exception of the entry address).
|
|
Therefore, addresses in the HEX file again start at 0.
|
|
.TP
|
|
.B -d < <start address>-<stop address> >
|
|
Tell P2HEX that items in the address range given by the argument
|
|
should be regarded as data rather than code. This option only has a
|
|
meaning for the TI-DSK format that can differenciate between code and
|
|
data. It will probably disappear on the day when P2HEX can process
|
|
all address spaces, making a manual distinction unnecessary.
|
|
.TP
|
|
.B -e <address>
|
|
|
|
Set an entry address or modify an existing one. Some HEX file
|
|
formats can carry a special record for an entry address that tells a
|
|
program loader where to jump after a program has been loaded.
|
|
Normally, this address is generated by AS if the program's END
|
|
statement has a label as argument, but this options allows to change
|
|
the entry point or add one if it was forgotten in the program itself.
|
|
.TP
|
|
.B -F <Default|Moto|Intel|Intel16|Intel32|MOS|Tek|DSK>
|
|
|
|
Force a certain format for the output HEX file. By default, P2HEX
|
|
will choose one depending on the target processor. Using
|
|
.B Default
|
|
as argument will also set this behaviour, which might be useful to
|
|
revert to P2HEX's default behaviour if the default has been changed
|
|
(see the discussion of the
|
|
.B P2HEXCMD
|
|
variable below for presetting parameters).
|
|
|
|
.B Moto
|
|
stands for the Motorola S-Record format, which allows addresses from
|
|
16 to 32 bits in length and entry addresses. It bears its name due
|
|
to the fact that every record starts with the letter S.
|
|
|
|
.B Intel
|
|
is the "standard" Intellec-MCS8-Format for a variety of Intel
|
|
8-Bit-CPUs that almost became a standard, but was originally limited
|
|
to 16-bit addresses. In later editions, the addressing capability
|
|
was extended to 20 (
|
|
.B Intel16
|
|
) and 32 bits (
|
|
.B Intel32
|
|
).
|
|
|
|
.B MOS
|
|
is a simple format introduced by the manufacturer MOS for their line
|
|
of 65xx CPUs. It is limited to 16-bit addresses, just like the
|
|
.B Tek
|
|
format that was defined by Tektronix.
|
|
|
|
.B DSK
|
|
is the format Texas Instruments uses for their line of 16-bit
|
|
fixed-point signal processors. In contrast to all other formats, it
|
|
is word-oriented and can distinguish between data and code segments.
|
|
.TP
|
|
.B -f <number>[,<further numbers>]
|
|
|
|
Add <number> to the list of record header IDs that allow a record
|
|
from a source file to be written to the target file. A certain
|
|
header ID marks code for a certain target processor family; thus,
|
|
this filter allows to distill code for a certain processor out of a
|
|
source file that contains code for different processor families.
|
|
Negation of this parameter removes certain header IDs from P2HEX's
|
|
list. See the user manual of AS for a list of all possible header ID
|
|
values. If P2HEX's list of header IDs is empty, no filtering will
|
|
take place, i.e. all records from a source file will make it into the
|
|
target file.
|
|
.TP
|
|
.B -i <0|1|2>
|
|
|
|
Change the terminating line for an Intel-HEX file. Normally, an
|
|
Intel-HEX file is terminated with the line
|
|
.B :00000001FF ,
|
|
but there are sources that also mention
|
|
.B :00000001
|
|
or
|
|
.B :0000000000
|
|
as the last line. The numeric argument of this parameter selects one
|
|
of these opportunities, with the first one being the default. This
|
|
parameter only has an effect if the target file's format is one of
|
|
the Intel-HEX variants.
|
|
.TP
|
|
.B -l <length>
|
|
|
|
Set the maximum number of bytes per record, and therefore the maximum
|
|
length of a line in the target file. Possible values are between 2
|
|
and 254 bytes, with 16 being the default.
|
|
.TP
|
|
.B -m <0..3>
|
|
|
|
Set one of the four Intel-Hex variants defined by Microchip for the
|
|
PIC family of microcontrollers. The Default is the INHX8(0) format,
|
|
which contains all words in a Lobyte-Hibyte-ordering. INHX16M(1) does just
|
|
the opposite, whereas INHX8L(2) and INHX8H(3) only store the lower
|
|
resp. higher bytes of each word. This parameter only has an effect
|
|
if the target file's format is one of the Intel-HEX variants.
|
|
.TP
|
|
.B -r < <start>-<stop> >
|
|
|
|
Set a certain address range to be filtered out of the input file(s).
|
|
Code that lies outside this range does not appear in the output file.
|
|
The default for the address filter is the 0-$7fff, which might create
|
|
confusion in some cases. As a special option,
|
|
.B <start>
|
|
and
|
|
.B <stop>
|
|
may consist of just a single dollar sign (escape this
|
|
in UNIX shells!) to signify the lowest resp. highest address that
|
|
occurs in the input file(s). Using this option will implicitly
|
|
enable a second pass over all input files to find the minimum and
|
|
maximum values before conversion starts, reducing the speed of P2HEX
|
|
slightly.
|
|
.TP
|
|
.B -s
|
|
|
|
In Motorola S-Record format, force P2HEX to write a termination record
|
|
after each group of data records, which may be necessary in some cases
|
|
(but creates problems most of the time...)
|
|
.TP
|
|
.B +5
|
|
|
|
Disable output of Motorola S5-records, which contain the number of
|
|
data records that were sent and therefore allow an additional level
|
|
of checking. However, they are not understood by all programs and
|
|
therefore might be a source of trouble.
|
|
.TP
|
|
.B -M <1|2|3>
|
|
|
|
Force P2HEX to use a minimum length for the address fields of Motorola
|
|
S-records. For example, a value of 2 will effectively disable S1 records,
|
|
and a value of 3 will force usage of S3 records. The default is 1, which
|
|
enables full automatic setting of the S record length.
|
|
.TP
|
|
.B -k
|
|
|
|
Instruct P2HEX to erase the program source files after conversion.
|
|
|
|
.SH PRESETTING PARAMETERS
|
|
|
|
Parameters need not neccessarily be given in the command line itself. Before
|
|
processing of command line parameters starts, P2HEX will look if the
|
|
.B P2HEXCMD
|
|
environment variable is defined. If it exists, its contents will be
|
|
treated as additional command line paramters whose syntax is absolutely
|
|
equal to normal command line parameters. As exception is made if the
|
|
variable's contents start with a '@' sign; in such a case, the string after
|
|
the '@' sign is treated as the name of a file that contains the options.
|
|
Such a file (also called a 'key file') has the advantage that it allows
|
|
the options to be written in different lines, and it does not have a size
|
|
limit. Some operating systems (like MS-DOS) do have a length limit on
|
|
command lines and environment variable contents, so the key file may be
|
|
your only option if you have a lot of lengthy parameters for P2HEX.
|
|
|
|
.SH RETURN CODES
|
|
|
|
.B p2hex
|
|
may return with the following codes:
|
|
.TP
|
|
.B 0
|
|
no errors.
|
|
.TP
|
|
.B 1
|
|
incorrect command line parameters.
|
|
.TP
|
|
.B 2
|
|
I/O-error.
|
|
.TP
|
|
.B 3
|
|
An input file had an incorrect format.
|
|
|
|
.SH EXAMPLES
|
|
|
|
To convert a file
|
|
.B file1.p
|
|
fully into its HEX representation on a Unix platform, use
|
|
.PP
|
|
.B p2hex -r \e$-\e$ file1
|
|
.PP
|
|
If you additionally want to force usage of the Motorola S-Record format, use
|
|
.PP
|
|
.B p2hex -r \e$-\e$ -F Moto file1
|
|
.PP
|
|
|
|
.SH NATIONAL LANGUAGE SUPPORT
|
|
|
|
p2hex supports national languages in the same way as AS. See the manual
|
|
page for asl(1) for maore information about this.
|
|
|
|
.SH TIPS
|
|
|
|
Calling P2HEX without any arguments will print a short help
|
|
listing all command line parameters.
|
|
|
|
.SH SEE ALSO
|
|
|
|
asl(1), plist(1), pbind(1), p2bin(1)
|
|
|
|
.SH HISTORY
|
|
|
|
P2HEX originally appeared as an AS tool in 1992, written in
|
|
Borland-Pascal, and was ported to C and UNIX in 1996.
|
|
|
|
.SH BUGS
|
|
|
|
Command line interpreters of some operating systems reserve some
|
|
characters for their own use, so it might be necessary to give
|
|
command line parameters with certain tricks (e.g., with the help
|
|
of escape characters).
|
|
|
|
P2HEX does not have so far an opportunity to filter records by
|
|
target segment. Instead, records that contain data for any other
|
|
segment than CODE are completely ignored.
|
|
|
|
.SH AUTHOR(S)
|
|
|
|
Alfred Arnold (a.arnold@kfa-juelich.de)
|
|
|