aboutsummaryrefslogtreecommitdiffstats
path: root/p2bin.1
diff options
context:
space:
mode:
Diffstat (limited to 'p2bin.1')
-rw-r--r--p2bin.1241
1 files changed, 241 insertions, 0 deletions
diff --git a/p2bin.1 b/p2bin.1
new file mode 100644
index 0000000..66248d4
--- /dev/null
+++ b/p2bin.1
@@ -0,0 +1,241 @@
+.TH p2bin 1
+
+.SH NAME
+.B p2bin \- convert code files into hex files
+
+.SH SYNTAX
+.B p2bin
+[ option(s) ] <name(s)> [ further options/names ]
+
+.SH DESCRIPTION
+
+P2BIN is a tool to convert the contents of one or several code files
+generated by AS into binary files. A binary file is a 1:1 memory image
+of the processor's memory and is especially suited for EPROM programmers
+and emulators.
+
+Arguments to P2BIN 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, P2BIN needs at least two file names: An
+input code file and the name of the binary output file. If multiple
+file names are given, P2BIN 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 '.bin' is added automatically to the target file's name.
+A special case occurs when only one file name is given: P2BIN will
+then take its name as the source (possibly extended with '.p'), and
+the same name as target (with '.bin' as additional or replaced
+extension).
+
+.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 p2bin
+accepts the following command-line parameters:
+.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 P2BIN's
+list. See the user manual of AS for a list of all possible header ID
+values. If P2BIN'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 -l <number>
+
+Set the value that should be used to fill memory areas in the binary
+image that are unused by the input code file(s). The default for this
+is to fill unused areas with the value 255 (0xff), which is the best choice
+for EPROMs as erased EPROM cells carry this value and an intelligent
+EPROM burner can skip these cells, speeding up the programming process and
+reducing stress for the EPROM. However, there are specialized EPROMs that
+have zeros in their cells after erasure, and you might want to fill unused
+areas with a code that executes as a NOP or BREAK statement.
+.TP
+.B -m <all|even|odd|byte<0|1|2|3>|word<0|1>>
+
+Set the mask of bytes to be filtered out. If your target processor has
+a 16- or 32-bit data path, but your EPROMs are only 8- or 16-bits wide,
+the code has to be spread over the EPROMs in an alternating fashion.
+This option allows you to do the necesary splitting, however you have
+to run P2BIN two or four times with different masks. The possible arguments
+have the following meanings:
+
+.B all
+does not do any filtering, i.e. all bytes of your code will show up in the
+resulting image. This is the default.
+
+.B even
+or
+.B odd
+will take only those bytes whose addresses are in the form 2*n or 2*n+1. They
+are useful if you have a 16-bit data path and two 8-bit EPROMs.
+
+.B byte0, byte1, byte2
+or
+.B byte3
+will take only those bytes whose addresses are in the form 4*n ... 4*n+3.
+They are useful if you have a 32-bit data path and four 8-bit EPROMs.
+
+.B word0
+or
+.B word1
+will take only those bytes whose addresses are in the form 4*n+0 / 4*n+1
+or 4*n+2 / 4*n+3. They are useful if you have a 32-bit data path and two
+16-bit EPROMs.
+
+When using one of these filters, the resulting images will automatically
+become smaller by a factor of 2 or 4. Beware that this does not influence
+address specifications given with the
+.B -r
+command-line parameter! See also the examples section below for correct
+usage.
+.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 P2BIN
+slightly.
+.TP
+.B -e <address>
+
+Set an entry address or modify an existing one. P2BIN can optionally
+prepend the start address to the binary image to tell a program loader
+where to jump after the image has been loaded (see the '-S' option).
+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 -S [L|B]<n>
+
+Instruct P2BIN to prepend the program entry address to the image. 'n' is
+the length in bytes the address should have and has an allowed range from 1
+to 4. The number may be prefixed by a 'L' or 'B' letter that sets the
+endianess of the address. If no letter is used, little endian is assumed.
+.TP
+.B -s
+
+Tell P2BIN to include a checksum into the image. A checksum is a byte
+value entered into the image's last byte that is the two's complement of
+the sum of all previous bytes. Therefore, the sum of all bytes modulus
+256 will become zero. This option is useful if you want to check the
+ROM contents in your program as part of a power-on self-test, but keep
+in mind that you must not use the last byte for your own purposes any
+more!
+.TP
+.B -k
+
+Instruct P2BIN 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, P2BIN will look if the
+.B P2BINCMD
+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 P2BIN.
+
+.SH RETURN CODES
+
+.B p2bin
+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 binary representation, use
+.PP
+.B p2bin -r \e$-\e$ file1
+.PP
+If you have a processor with a 64 KByte address space and a 16-bit
+data path and you want to assure that the memory image always starts
+at address 0, regardless of address layout in the code file, use
+.PP
+.B p2bin -r 0-\e$ffff -m even file1
+.B evenfile
+
+.B p2bin -r 0-\e$ffff -m odd file1
+.B oddfile
+.PP
+to get images for two 27256 EPROMs.
+
+.SH NATIONAL LANGUAGE SUPPORT
+
+p2bin supports national languages in the same way as AS. See the manual
+page for asl(1) for maore information about this.
+
+.SH TIPS
+
+Calling P2BIN without any arguments will print a short help
+listing all command line parameters.
+
+.SH SEE ALSO
+
+asl(1), plist(1), pbind(1), p2hex(1)
+
+.SH HISTORY
+
+P2BIN 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).
+
+P2BIN 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)
+