1p2hex(1) General Commands Manual p2hex(1)
2
6 p2hex - convert code files into hex files
7
10 p2hex [ option(s) ] <name(s)> [ further options/names ]
11
14 P2HEX is a tool to convert the contents of one or several code files
15 generated by AS into HEX files. A HEX file is a common method of rep‐
16 resenting binary data in a way that is human-readable and transferrable
17 over non-transparent data lines. Generally spoken, each byte of code
18 or data is represented by two characters that show the byte in its
19 hexadecimal notation. A HEX file also contains additional information
20 like addresses and checksums that ease processing of the data. Unfor‐
21 tunately, there is no generally accepted standard format for HEX files.
22 Instead, every processor manufacturer developed his own format and some
23 of them have become "industry standards". P2HEX supports all formats
24 that seem to have gained acceptance, with some variations that are com‐
25 monplace.
26 Arguments to P2HEX may be either command line parameters or file name
28 specifications. Any argument that starts with the charactes +, - or /
29 is regarded as a comand line parameter (which may take an additional
30 command line argument); any other argument is regarded as a file name.
31 Generally, P2HEX needs at least two file names: An input code file and
32 the name of the HEX output file. If multiple file names are given,
33 P2HEX will always take the last name as the output file's name. If an
34 input file name does not have an extension, the extension '.p' is added
35 automatically. Similarly, the extension '.hex' is added automatically
36 to the target file's name. A special case occurs when only one file
37 name is given: P2HEX will then take its name as the source (possibly
38 extended with '.p'), and the same name as target (with '.hex' as addi‐
39 tional or replaced extension).
40 By default, P2HEX will choose a HEX format that is the most common for
42 the processor family a source file contains code for; this however
43 means that if the source file(s) contain(s) code for different proces‐
44 sor families, the HEX file might become an undesirable mixture of for‐
45 mats; use the -F command-line parameter to force a certain format then.
46
49 If a command-line parameter starts with a slash(/) or minus sign(-), it
50 turns an option on; if a command-line parameter starts with a plus
51 sign(+), it turns a specific option off. Numeric arguments to parame‐
52 ters can be either written in decimal or hexadecimal notation. For
53 hexadecimal notation, prefix the number with a dollar($) sign. In the
54 following list, all options will be shown in the form that is needed to
55 change the default behaviour, which might be a plus or minus sign,
56 depening on wether the option is on or off by default.
57 p2hex accepts the following command-line parameters:
59 -a
61 Tell P2HEX to use relative addressing in the output HEX file.
63 By default, addresses the HEX file will be exactly the same
64 absolute addresses as they were in the code file. This may cre‐
65 ate problems with some EPROM-burners if your code does not start
66 at address 0. In relative mode, the address filter's start
67 address (see the -r command line switch) is subtracted from all
68 addresses specifications in the HEX file (with the exception of
69 the entry address). Therefore, addresses in the HEX file again
70 start at 0.
71 -d < <start address>-<stop address> >
73 Tell P2HEX that items in the address range given by the argument
74 should be regarded as data rather than code. This option only
75 has a meaning for the TI-DSK format that can differenciate
76 between code and data. This option is principally obsolete
77 since P2HEX can now directly process data from the DATA segment.
78 It should not be used in new projects, since it may be removed
79 in the near future.
80 -e <address>
82 Set an entry address or modify an existing one. Some HEX file
84 formats can carry a special record for an entry address that
85 tells a program loader where to jump after a program has been
86 loaded. Normally, this address is generated by AS if the pro‐
87 gram's END statement has a label as argument, but this options
88 allows to change the entry point or add one if it was forgotten
89 in the program itself.
90 -F <Default|Moto|Intel|Intel16|Intel32|MOS|Tek|DSK>
92 Force a certain format for the output HEX file. By default,
94 P2HEX will choose one depending on the target processor. Using
95 Default as argument will also set this behaviour, which might be
96 useful to revert to P2HEX's default behaviour if the default has
97 been changed (see the discussion of the P2HEXCMD variable below
98 for presetting parameters).
99 Moto stands for the Motorola S-Record format, which allows
101 addresses from 16 to 32 bits in length and entry addresses. It
102 bears its name due to the fact that every record starts with the
103 letter S.
104 Intel is the "standard" Intellec-MCS8-Format for a variety of
106 Intel 8-Bit-CPUs that almost became a standard, but was origi‐
107 nally limited to 16-bit addresses. In later editions, the
108 addressing capability was extended to 20 ( Intel16 ) and 32 bits
109 ( Intel32 ).
110 MOS is a simple format introduced by the manufacturer MOS for
112 their line of 65xx CPUs. It is limited to 16-bit addresses,
113 just like the Tek format that was defined by Tektronix.
114 DSK is the format Texas Instruments uses for their line of
116 16-bit fixed-point signal processors. In contrast to all other
117 formats, it is word-oriented and can distinguish between data
118 and code segments. Atmel is the simple Hex format defined by
119 Atmel for the AVR RISC family.
120 -f <number>[,<further numbers>]
122 Add <number> to the list of record header IDs that allow a
124 record from a source file to be written to the target file. A
125 certain header ID marks code for a certain target processor fam‐
126 ily; thus, this filter allows to distill code for a certain pro‐
127 cessor out of a source file that contains code for different
128 processor families. Negation of this parameter removes certain
129 header IDs from P2HEX's list. See the user manual of AS for a
130 list of all possible header ID values. If P2HEX's list of
131 header IDs is empty, no filtering will take place, i.e. all
132 records from a source file will make it into the target file.
133 -i <0|1|2>
135 Change the terminating line for an Intel-HEX file. Normally, an
137 Intel-HEX file is terminated with the line :00000001FF , but
138 there are sources that also mention :00000001 or :0000000000 as
139 the last line. The numeric argument of this parameter selects
140 one of these opportunities, with the first one being the
141 default. This parameter only has an effect if the target file's
142 format is one of the Intel-HEX variants.
143 -l <length>
145 Set the maximum number of bytes per record, and therefore the
147 maximum length of a line in the target file. Possible values
148 are between 2 and 254 bytes, with 16 being the default.
149 -m <0..3>
151 Set one of the four Intel-Hex variants defined by Microchip for
153 the PIC family of microcontrollers. The Default is the INHX8(0)
154 format, which contains all words in a Lobyte-Hibyte-ordering.
155 INHX16M(1) does just the opposite, whereas INHX8L(2) and
156 INHX8H(3) only store the lower resp. higher bytes of each word.
157 This parameter only has an effect if the target file's format is
158 one of the Intel-HEX variants.
159 -r < <start>-<stop> >
161 Set a certain address range to be filtered out of the input
163 file(s). Code that lies outside this range does not appear in
164 the output file. The default for the address filter is the
165 0-$7fff, which might create confusion in some cases. As a spe‐
166 cial option, <start> and <stop> may consist of just a single
167 dollar sign (escape this in UNIX shells!) or 0x to signify the
168 lowest resp. highest address that occurs in the input file(s).
169 Using this option will implicitly enable a second pass over all
170 input files to find the minimum and maximum values before con‐
171 version starts, reducing the speed of P2HEX slightly.
172 -s
174 In Motorola S-Record format, force P2HEX to write a termination
176 record after each group of data records, which may be necessary
177 in some cases (but creates problems most of the time...)
178 +5
180 Disable output of Motorola S5-records, which contain the number
182 of data records that were sent and therefore allow an additional
183 level of checking. However, they are not understood by all pro‐
184 grams and therefore might be a source of trouble.
185 -M <1|2|3>
187 Force P2HEX to use a minimum length for the address fields of
189 Motorola S-records. For example, a value of 2 will effectively
190 disable S1 records, and a value of 3 will force usage of S3
191 records. The default is 1, which enables full automatic setting
192 of the S record length.
193 -avrlen <2|3>
195 Set the address field length of Atmel AVR Hex files to either
197 two or three bytes (the latter is the default).
198 -k
200 Instruct P2HEX to erase the program source files after conver‐
202 sion.
203 -avrlen <2|3>
205 Set the width of the address field used for the Atmel hex file
207 format. By default, 3-byte addresses will be used.
208
211 Parameters need not neccessarily be given in the command line itself.
212 Before processing of command line parameters starts, P2HEX will look if
213 the P2HEXCMD environment variable is defined. If it exists, its con‐
214 tents will be treated as additional command line paramters whose syntax
215 is absolutely equal to normal command line parameters. As exception is
216 made if the variable's contents start with a '@' sign; in such a case,
217 the string after the '@' sign is treated as the name of a file that
218 contains the options. Such a file (also called a 'key file') has the
219 advantage that it allows the options to be written in different lines,
220 and it does not have a size limit. Some operating systems (like MS-
221 DOS) do have a length limit on command lines and environment variable
222 contents, so the key file may be your only option if you have a lot of
223 lengthy parameters for P2HEX.
224
227 p2hex may return with the following codes:
228 0 no errors.
230 1 incorrect command line parameters.
232 2 I/O-error.
234 3 An input file had an incorrect format.
236
239 To convert a file file1.p fully into its HEX representation on a Unix
240 platform, use
241 p2hex -r \$-\$ file1
243 If you additionally want to force usage of the Motorola S-Record for‐
245 mat, use
246 p2hex -r \$-\$ -F Moto file1
248
250 p2hex supports national languages in the same way as AS. See the man‐
251 ual page for asl(1) for more information about this.
252
255 Calling P2HEX without any arguments will print a short help listing all
256 command line parameters.
257
260 asl(1), plist(1), pbind(1), p2bin(1)
261
264 P2HEX originally appeared as an AS tool in 1992, written in Borland-
265 Pascal, and was ported to C and UNIX in 1996.
266
269 Command line interpreters of some operating systems reserve some char‐
270 acters for their own use, so it might be necessary to give command line
271 parameters with certain tricks (e.g., with the help of escape charac‐
272 ters).
273 P2HEX does not have so far an opportunity to filter records by target
275 segment. Instead, records that contain data for any other segment than
276 CODE are completely ignored.
277
280 Alfred Arnold (alfred@ccac.rwth-aachen.de)
281 p2hex(1)