From 333b605b2afd472b823aeda0adf0e8b1ea9843c0 Mon Sep 17 00:00:00 2001 From: fishsoupisgood Date: Mon, 27 May 2019 02:41:51 +0100 Subject: initial commit from asl-1.41r8.tar.gz --- p2bin.1 | 241 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 p2bin.1 (limited to 'p2bin.1') 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) ] [ 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 [,] + +Add 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 + +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 |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 < - > + +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 +and +.B +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
+ +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] + +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) + -- cgit v1.2.3