1p2bin(1) General Commands Manual p2bin(1)
2
6 p2bin - convert code files into hex files
7
10 p2bin [ option(s) ] <name(s)> [ further options/names ]
11
14 P2BIN is a tool to convert the contents of one or several code files
15 generated by AS into binary files. A binary file is a 1:1 memory image
16 of the processor's memory and is especially suited for EPROM program‐
17 mers and emulators.
18 Arguments to P2BIN may be either command line parameters or file name
20 specifications. Any argument that starts with the charactes +, - or /
21 is regarded as a comand line parameter (which may take an additional
22 command line argument); any other argument is regarded as a file name.
23 Generally, P2BIN needs at least two file names: An input code file and
24 the name of the binary output file. If multiple file names are given,
25 P2BIN will always take the last name as the output file's name. If an
26 input file name does not have an extension, the extension '.p' is added
27 automatically. Similarly, the extension '.bin' is added automatically
28 to the target file's name. A special case occurs when only one file
29 name is given: P2BIN will then take its name as the source (possibly
30 extended with '.p'), and the same name as target (with '.bin' as addi‐
31 tional or replaced extension).
32
35 If a command-line parameter starts with a slash(/) or minus sign(-), it
36 turns an option on; if a command-line parameter starts with a plus
37 sign(+), it turns a specific option off. Numeric arguments to parame‐
38 ters can be either written in decimal or hexadecimal notation. For
39 hexadecimal notation, prefix the number with a dollar($) sign. In the
40 following list, all options will be shown in the form that is needed to
41 change the default behaviour, which might be a plus or minus sign,
42 depening on wether the option is on or off by default.
43 p2bin accepts the following command-line parameters:
45 -f <number>[,<further numbers>]
47 Add <number> to the list of record header IDs that allow a
49 record from a source file to be written to the target file. A
50 certain header ID marks code for a certain target processor fam‐
51 ily; thus, this filter allows to distill code for a certain pro‐
52 cessor out of a source file that contains code for different
53 processor families. Negation of this parameter removes certain
54 header IDs from P2BIN's list. See the user manual of AS for a
55 list of all possible header ID values. If P2BIN's list of
56 header IDs is empty, no filtering will take place, i.e. all
57 records from a source file will make it into the target file.
58 -l <number>
60 Set the value that should be used to fill memory areas in the
62 binary image that are unused by the input code file(s). The
63 default for this is to fill unused areas with the value 255
64 (0xff), which is the best choice for EPROMs as erased EPROM
65 cells carry this value and an intelligent EPROM burner can skip
66 these cells, speeding up the programming process and reducing
67 stress for the EPROM. However, there are specialized EPROMs
68 that have zeros in their cells after erasure, and you might want
69 to fill unused areas with a code that executes as a NOP or BREAK
70 statement.
71 -m <all|even|odd|byte<0|1|2|3>|word<0|1>>
73 Set the mask of bytes to be filtered out. If your target pro‐
75 cessor has a 16- or 32-bit data path, but your EPROMs are only
76 8- or 16-bits wide, the code has to be spread over the EPROMs in
77 an alternating fashion. This option allows you to do the nece‐
78 sary splitting, however you have to run P2BIN two or four times
79 with different masks. The possible arguments have the following
80 meanings:
81 all does not do any filtering, i.e. all bytes of your code will
83 show up in the resulting image. This is the default.
84 even or odd will take only those bytes whose addresses are in
86 the form 2*n or 2*n+1. They are useful if you have a 16-bit
87 data path and two 8-bit EPROMs.
88 byte0, byte1, byte2 or byte3 will take only those bytes whose
90 addresses are in the form 4*n ... 4*n+3. They are useful if you
91 have a 32-bit data path and four 8-bit EPROMs.
92 word0 or word1 will take only those bytes whose addresses are in
94 the form 4*n+0 / 4*n+1 or 4*n+2 / 4*n+3. They are useful if you
95 have a 32-bit data path and two 16-bit EPROMs.
96 When using one of these filters, the resulting images will auto‐
98 matically become smaller by a factor of 2 or 4. Beware that
99 this does not influence address specifications given with the -r
100 command-line parameter! See also the examples section below for
101 correct usage.
102 -r < <start>-<stop> >
104 Set a certain address range to be filtered out of the input
106 file(s). Code that lies outside this range does not appear in
107 the output file. The default for the address filter is the
108 0-$7fff, which might create confusion in some cases. As a spe‐
109 cial option, <start> and <stop> may consist of just a single
110 dollar sign (escape this in UNIX shells!) to signify the lowest
111 resp. highest address that occurs in the input file(s). Using
112 this option will implicitly enable a second pass over all input
113 files to find the minimum and maximum values before conversion
114 starts, reducing the speed of P2BIN slightly.
115 -e <address>
117 Set an entry address or modify an existing one. P2BIN can
119 optionally prepend the start address to the binary image to tell
120 a program loader where to jump after the image has been loaded
121 (see the '-S' option). Normally, this address is generated by
122 AS if the program's END statement has a label as argument, but
123 this options allows to change the entry point or add one if it
124 was forgotten in the program itself.
125 -S [L|B]<n>
127 Instruct P2BIN to prepend the program entry address to the
129 image. 'n' is the length in bytes the address should have and
130 has an allowed range from 1 to 4. The number may be prefixed by
131 a 'L' or 'B' letter that sets the endianess of the address. If
132 no letter is used, little endian is assumed.
133 -s
135 Tell P2BIN to include a checksum into the image. A checksum is
137 a byte value entered into the image's last byte that is the
138 two's complement of the sum of all previous bytes. Therefore,
139 the sum of all bytes modulus 256 will become zero. This option
140 is useful if you want to check the ROM contents in your program
141 as part of a power-on self-test, but keep in mind that you must
142 not use the last byte for your own purposes any more!
143 -k
145 Instruct P2BIN to erase the program source files after conver‐
147 sion.
148
151 Parameters need not neccessarily be given in the command line itself.
152 Before processing of command line parameters starts, P2BIN will look if
153 the P2BINCMD environment variable is defined. If it exists, its con‐
154 tents will be treated as additional command line paramters whose syntax
155 is absolutely equal to normal command line parameters. As exception is
156 made if the variable's contents start with a '@' sign; in such a case,
157 the string after the '@' sign is treated as the name of a file that
158 contains the options. Such a file (also called a 'key file') has the
159 advantage that it allows the options to be written in different lines,
160 and it does not have a size limit. Some operating systems (like MS-
161 DOS) do have a length limit on command lines and environment variable
162 contents, so the key file may be your only option if you have a lot of
163 lengthy parameters for P2BIN.
164
167 p2bin may return with the following codes:
168 0 no errors.
170 1 incorrect command line parameters.
172 2 I/O-error.
174 3 An input file had an incorrect format.
176
179 To convert a file file1.p fully into its binary representation, use
180 p2bin -r \$-\$ file1
182 If you have a processor with a 64 KByte address space and a 16-bit data
184 path and you want to assure that the memory image always starts at
185 address 0, regardless of address layout in the code file, use
186 p2bin -r 0-\$ffff -m even file1 evenfile
188 p2bin -r 0-\$ffff -m odd file1 oddfile
190 to get images for two 27256 EPROMs.
192
195 p2bin supports national languages in the same way as AS. See the man‐
196 ual page for asl(1) for more information about this.
197
200 Calling P2BIN without any arguments will print a short help listing all
201 command line parameters.
202
205 asl(1), plist(1), pbind(1), p2hex(1)
206
209 P2BIN originally appeared as an AS tool in 1992, written in Borland-
210 Pascal, and was ported to C and UNIX in 1996.
211
214 Command line interpreters of some operating systems reserve some char‐
215 acters for their own use, so it might be necessary to give command line
216 parameters with certain tricks (e.g., with the help of escape charac‐
217 ters).
218 P2BIN does not have so far an opportunity to filter records by target
220 segment. Instead, records that contain data for any other segment than
221 CODE are completely ignored.
222
225 Alfred Arnold (alfred@ccac.rwth-aachen.de)
226 p2bin(1)