diff options
Diffstat (limited to 'p2hex.1')
| -rw-r--r-- | p2hex.1 | 288 |
1 files changed, 288 insertions, 0 deletions
@@ -0,0 +1,288 @@ +.TH p2hex 1 + +.SH NAME +.B p2hex \- convert code files into hex files + +.SH SYNTAX +.B p2hex +[ option(s) ] <name(s)> [ further options/names ] + +.SH DESCRIPTION + +P2HEX is a tool to convert the contents of one or several code files +generated by AS into HEX files. A HEX file is a common method of +representing binary data in a way that is human-readable and +transferrable over non-transparent data lines. Generally spoken, +each byte of code or data is represented by two characters that show +the byte in its hexadecimal notation. A HEX file also contains +additional information like addresses and checksums that ease +processing of the data. Unfortunately, there is no generally +accepted standard format for HEX files. Instead, every processor +manufacturer developed his own format and some of them have become +"industry standards". P2HEX supports all formats that seem to have +gained acceptance, with some variations that are commonplace. + +Arguments to P2HEX 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, P2HEX needs at least two file names: An +input code file and the name of the HEX output file. If multiple +file names are given, P2HEX 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 '.hex' is added automatically to the target file's name. +A special case occurs when only one file name is given: P2HEX will +then take its name as the source (possibly extended with '.p'), and +the same name as target (with '.hex' as additional or replaced +extension). + +By default, P2HEX will choose a HEX format that is the most common +for the processor family a source file contains code for; this +however means that if the source file(s) contain(s) code for different +processor families, the HEX file might become an undesirable mixture +of formats; use the +.B -F +command-line parameter to force a certain format then. + +.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 p2hex +accepts the following command-line parameters: +.TP +.B -a + +Tell P2HEX to use relative addressing in the output HEX file. By +default, addresses the HEX file will be exactly the same absolute +addresses as they were in the code file. This may create problems +with some EPROM-burners if your code does not start at address 0. In +relative mode, the address filter's start address (see the +.B -r +command line switch) is subtracted from all addresses specifications +in the HEX file (with the exception of the entry address). +Therefore, addresses in the HEX file again start at 0. +.TP +.B -d < <start address>-<stop address> > +Tell P2HEX that items in the address range given by the argument +should be regarded as data rather than code. This option only has a +meaning for the TI-DSK format that can differenciate between code and +data. It will probably disappear on the day when P2HEX can process +all address spaces, making a manual distinction unnecessary. +.TP +.B -e <address> + +Set an entry address or modify an existing one. Some HEX file +formats can carry a special record for an entry address that tells a +program loader where to jump after a program has been loaded. +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 -F <Default|Moto|Intel|Intel16|Intel32|MOS|Tek|DSK> + +Force a certain format for the output HEX file. By default, P2HEX +will choose one depending on the target processor. Using +.B Default +as argument will also set this behaviour, which might be useful to +revert to P2HEX's default behaviour if the default has been changed +(see the discussion of the +.B P2HEXCMD +variable below for presetting parameters). + +.B Moto +stands for the Motorola S-Record format, which allows addresses from +16 to 32 bits in length and entry addresses. It bears its name due +to the fact that every record starts with the letter S. + +.B Intel +is the "standard" Intellec-MCS8-Format for a variety of Intel +8-Bit-CPUs that almost became a standard, but was originally limited +to 16-bit addresses. In later editions, the addressing capability +was extended to 20 ( +.B Intel16 +) and 32 bits ( +.B Intel32 +). + +.B MOS +is a simple format introduced by the manufacturer MOS for their line +of 65xx CPUs. It is limited to 16-bit addresses, just like the +.B Tek +format that was defined by Tektronix. + +.B DSK +is the format Texas Instruments uses for their line of 16-bit +fixed-point signal processors. In contrast to all other formats, it +is word-oriented and can distinguish between data and code segments. +.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 P2HEX's +list. See the user manual of AS for a list of all possible header ID +values. If P2HEX'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 -i <0|1|2> + +Change the terminating line for an Intel-HEX file. Normally, an +Intel-HEX file is terminated with the line +.B :00000001FF , +but there are sources that also mention +.B :00000001 +or +.B :0000000000 +as the last line. The numeric argument of this parameter selects one +of these opportunities, with the first one being the default. This +parameter only has an effect if the target file's format is one of +the Intel-HEX variants. +.TP +.B -l <length> + +Set the maximum number of bytes per record, and therefore the maximum +length of a line in the target file. Possible values are between 2 +and 254 bytes, with 16 being the default. +.TP +.B -m <0..3> + +Set one of the four Intel-Hex variants defined by Microchip for the +PIC family of microcontrollers. The Default is the INHX8(0) format, +which contains all words in a Lobyte-Hibyte-ordering. INHX16M(1) does just +the opposite, whereas INHX8L(2) and INHX8H(3) only store the lower +resp. higher bytes of each word. This parameter only has an effect +if the target file's format is one of the Intel-HEX variants. +.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 P2HEX +slightly. +.TP +.B -s + +In Motorola S-Record format, force P2HEX to write a termination record +after each group of data records, which may be necessary in some cases +(but creates problems most of the time...) +.TP +.B +5 + +Disable output of Motorola S5-records, which contain the number of +data records that were sent and therefore allow an additional level +of checking. However, they are not understood by all programs and +therefore might be a source of trouble. +.TP +.B -M <1|2|3> + +Force P2HEX to use a minimum length for the address fields of Motorola +S-records. For example, a value of 2 will effectively disable S1 records, +and a value of 3 will force usage of S3 records. The default is 1, which +enables full automatic setting of the S record length. +.TP +.B -k + +Instruct P2HEX 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, P2HEX will look if the +.B P2HEXCMD +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 P2HEX. + +.SH RETURN CODES + +.B p2hex +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 HEX representation on a Unix platform, use +.PP +.B p2hex -r \e$-\e$ file1 +.PP +If you additionally want to force usage of the Motorola S-Record format, use +.PP +.B p2hex -r \e$-\e$ -F Moto file1 +.PP + +.SH NATIONAL LANGUAGE SUPPORT + +p2hex supports national languages in the same way as AS. See the manual +page for asl(1) for maore information about this. + +.SH TIPS + +Calling P2HEX without any arguments will print a short help +listing all command line parameters. + +.SH SEE ALSO + +asl(1), plist(1), pbind(1), p2bin(1) + +.SH HISTORY + +P2HEX 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). + +P2HEX 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) + |