1p2bin(1)                    General Commands Manual                   p2bin(1)
2
3
4

NAME

6       p2bin - convert code files into hex files
7
8

SYNTAX

10       p2bin [ option(s) ] <name(s)> [ further options/names ]
11
12

DESCRIPTION

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
19       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
33

COMMAND-LINE PARAMETERS

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
44       p2bin accepts the following command-line parameters:
45
46       -f <number>[,<further numbers>]
47
48              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
59       -l <number>
60
61              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
72       -m <all|even|odd|byte<0|1|2|3>|word<0|1>>
73
74              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
82              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
85              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
89              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
93              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
97              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
103       -r < <start>-<stop> >
104
105              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
116       -e <address>
117
118              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
126       -S [L|B]<n>
127
128              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
134       -s
135
136              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
144       -k
145
146              Instruct  P2BIN  to erase the program source files after conver‐
147              sion.
148
149

PRESETTING PARAMETERS

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
165

RETURN CODES

167       p2bin may return with the following codes:
168
169       0      no errors.
170
171       1      incorrect command line parameters.
172
173       2      I/O-error.
174
175       3      An input file had an incorrect format.
176
177

EXAMPLES

179       To convert a file file1.p fully into its binary representation, use
180
181       p2bin -r \$-\$ file1
182
183       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
187       p2bin -r 0-\$ffff -m even file1 evenfile
188
189       p2bin -r 0-\$ffff -m odd file1 oddfile
190
191       to get images for two 27256 EPROMs.
192
193

NATIONAL LANGUAGE SUPPORT

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
198

TIPS

200       Calling P2BIN without any arguments will print a short help listing all
201       command line parameters.
202
203

SEE ALSO

205       asl(1), plist(1), pbind(1), p2hex(1)
206
207

HISTORY

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
212

BUGS

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
219       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
223

AUTHOR(S)

225       Alfred Arnold (alfred@ccac.rwth-aachen.de)
226
227
228
229
230                                                                      p2bin(1)
Impressum