INTRODUCTION The HEX utility is a task that runs on the PDP-11 under the RSX11M operating system.Its purpose is to manipulate INTEL hex formatted files as output by the linkers.The hex file is,in essence,the "task image"of the software to run in a microprocessor-based system.For a detailed description of the format of an INTEL hex file see Appendix A. The principle component of the HEX utility is a 32K byte virtual memory area.This allows the user to manipulate code in memory as if it were resident in the target machine.Note that the 32K byte virtual memory can be extended to cover the entire 64K address range via the OFFSET command(see notes on the use of the offset in Section IV). All numbers in the manual(unless stated otherwise)and all input/ output of the HEX utility are hexidecimal. Additional qualifiers for help are: INVOKE for help on how to invoke hex COMMANDS for general help on command syntax COMMANDNAME for an individual command syntax CLP for help on command line processing FILESPEC for help on filespecs OFFSETINFO for help on setting an offset EXAMPLE for an example FORMAT for info on INTEL HEX format MESSAGES for description of all messages 2 INVOKE II. HOW TO INVOKE HEX HEX can be invoked in two ways: 1) Interactive mode >HEX Type "HEX" in response to the MCR prompt. HEX>command Command lines may be entered. HEX>command HEX>^Z Control-Z terminates HEX. 2) Indirect command mode >HEX@filespec where filespec is the file specification of an indirect command file containing a list of HEX commands. Note that the invocation of HEX may itself be contained in an indirect command file,but filespec as shown above may contain only HEX commands. Upon entering HEX,the virtual memory is FF-filled and the offset and transfer address values are set to 0000. Typically, a HEX session would proceed as follows: 1) if the prom that the user is preparing for is FF-filled when blank, it is not necessary to fill the virtual memory.Otherwise,it will be necessary to FILL the virtual memory with the normally blank value(see the FILL command in Section III). 2) if the address range of the hex files that you intend to manipulate lies within the range 0000-7FFF,it is not necessary to set an offset value.Otherwise,an OFFSET should be specified(see the OFFSET command in section III and notes on using the offset in section IV). 3) READ the INTEL hex file(s) into the virtual memory (see the READ command in Section III). 4) Optionally,you may manipulate or examine the contents of virtual memory. 5) Finally,WRITE selected sections of virtual memory out to create new hex files. 2 COMMANDS III. COMMAND DESCRIPTIONS Descriptions of valid HEX commands follow.The following notes apply: 1) aaaa or similar represents a 4-digit hex number. 2) vv or similar represents a 2-digit hex byte value. 3) Uppercase words are required keywords. 4) Structures in brackets show an optional parameter.The brackets are NOT part of the syntax. Commands are: INIT FILL OFFSET READ COMPARE COPY CRC DISPLAY EDIT SUM TRANSFER WRITE For help on a command,Type "HELP HEX commandname" 2 INIT HEX>INIT This command resets the hex utility to its initial conditions.Virtual memory is FF-filled and offset and transfer address values are set to 0000. 2 FILL HEX>FILL FROM aaaa THRU bbbb WITH vv Locations aaaa thru bbbb are filled with byte value vv. 2 OFFSET HEX>OFFSET [ aaaa] The offset command with no argument displays the current offset value. If a value is specified,that value becomes the new offset. See notes on the use of the offset in Section IV. 2 READ HEX>READ [ FROM aaaa THRU bbbb] FILE filespec where filespec is a file specification(see Section IV)of an INTEL hex format file.For a description of the INTEL hex format,see Appendix A. The code defined by the file will be placed in its proper location in virtual memory.Unspecified locations are not affected. Optionally,limits may be placed on the portion of the input file to be used to define virtual memory.If so specified,only code defining addresses from aaaa thru bbbb will be placed in virtual memory. The transfer address from the trailer record updates the current transfer address value. 2 COMPARE HEX>COMPARE [ FROM aaaa THRU bbbb] FILE filespec where filespec is a file specification(see Section IV)of an INTEL hex format file.For a description of the INTEL hex format,see Appendix A. The code defined by the file will be compared to the value at that location in virtual memory.Uspecified locations are not compared. Differences are reported to the terminal.The contents of virtual memory is not affected. Optionally,limits may be placed on the portion of the input file to be used to compare to virtual memory.If so specified,only code defining addresses from aaaa thru bbbb will be compared to virtual memory. The transfer address from the trailer record is also compared to the current transfer address value. 2 COPY HEX>COPY FROM aaaa THRU bbbb TO cccc This command will copy the values contained in locations aaaa thru bbbb to the locations starting at cccc.The copy does not affect the source area unless it is overlapped by the target area.The Copy proceeds byte-wise from aaaa thru bbbb. 2 CRC HEX>CRC FROM aaaa THRU bbbb [ TO cccc] Calculates the standard bisync CRC byte-wise from aaaa thru bbbb,using a preset of 0000.If a TO address is specified,the result is stored there in high-low order.Whether or not a TO address is specified,the CRC value is displayed on the terminal. 2 DISPLAY HEX>DISPLAY FROM aaaa THRU bbbb [FILE filespec] where filespec is a file specification(see Section IV). The contents of aaaa thru bbbb are displayed on the screen(or, if specified,to a file which is then spooled to the printer). The address aaaa is rounded down to aaa0,and bbbb is rounded up to bbbF. 2 EDIT HEX>EDITaaaa initiates an interactive session which allows you to examine and optionally replace the contents of virtual memory starting at location aaaa.The following will be displayed: aaaa vv- where aaaa is the current address being edited,and vv is the contents of that location.At this point,the user has four options: 1. Type a two-digit hex value and terminate with the ENTER (or RETURN) key.This will replace the contents of the location being edited and bring up the next location for editing. 2. Hit ENTER (or RETURN).This will leave the location as is and will bring up the next sequential location for editing. 3. Type a two-digit hex value and terminate with the ESC key.This will replace the contents of the location being edited and then return to Hex command mode. 4. Hit ESC.This will leave the location as is and return to HEX command mode. 2 MOVE HEX> MOVE BYTE FROM X TO Y OR HEX> MOVE WORD FROM X TO Y where x and y represent either a four-digit hex number valid under the current offset or a pseudo-register specification (see section IV). The MOVE command is a variation of the COPY command. MOVE is limited to a one byte or one word transfer, but can access the pseudo-register set. Like COPY, MOVE has no affect on the source area. A word moves copies the entire word at one time, rather than bytewise as in copy. 2 SEARCH HEX> SEARCH FROM aaaa TO bbbb FOR xx OR HEX> SEARCH FROM aaaa TO bbbb FOR xxxx searches the specified range of virtual memory for the byte or word value given. The addresses containing the value are displayed. In the case of a word value, the search is for that value in lo-hi order. 2 SUM HEX>SUM FROM aaaa THRU bbbb Calculates and displays on the terminal a 16-bit byte-wise summation of locations aaaa thru bbbb. 2 TRANSFER HEX>TRANSFER [ aaaa] The transfer command with no argument displays the current transfer address value. If a value is specified,that value becomes the new transfer address. 2 WRITE HEX>WRITE FROM aaaa THRU bbbb FILE filespec creates an INTEL hex file defining locations aaaa thru bbbb.For a definition of filespec,see Section IV. The maximum number of bytes,defined per line will be 20(hex).For a detailed description of INTEL hex format,see Appendix A. The current transfer address will be placed in the trailer record. 2 CLP COMMAND LINE PROCESSING A command line consists of up to 80 ASCII characters terminated by an ENTER or ESC.The command line may originte from the terminal or an indirect command file.A command line which begins with a semi- colon is treated as a comment. All spaces and tabs are removed from the command line.This may result in seemingly incorrect error messages.Consider the following command line: WRITE FROM 0000 THRU 0FF FILE TEST.HEX Internally,this command is processed as if it were: WRITE FROM 0000 THRU 0FFF ILE TEST.HEX Therefore,the error message would pertain to the missing keyword "FILE". 2 FILESPEC FILE SPECIFICATION A file specification consists of the following: DV00:[ggg,mmm]name.ext;v where DV00: is a device name ggg,mmm is a uic name is the name of the file ext is the file type ;v is the version number The following defaults are available: SY0: for device current UIC for the UIC .HEX for the extension ;0 for the version number TI: is a file specification representing the terminal at which HEX is running. 2 OFFSETINFO OFFSET Internally,HEX uses a 32K byte buffer as virtual memory,However,the utility can handle the entire 64K addressing range by using an offset facility.The user is responsible for setting the appropriate offset with the OFFSET command.This offset is automatically subtracted from all addresses input to HEX(either from the hex input file or command entry)and correspondingly added to output(either hex output file or display). The offset should be chosen so that the addresses to be handled will be offset internally to within 0000 to 7FFF. For example,if the user wishes to manipulate a hex file defining addresses 9000 to BFFF,an offset of 8000 would be appropriate. After the offset is given,the offsetting of addresses internally is totally transparent to the user,i.e. the user specifies(and sees) actual addresses. Consider the following analogy:You have a machine with RAM sockets and addressing provisions for 64K of RAM.But,alas,you only have 32K worth of RAM chips.Assuming the chips must be placed contiguously,at what address would you begin placing the RAM chips in order to handle the addresses defined by your hex file?This address would be the appropriate offset value for the HEX utility.Note again,that once you have "placed the RAM chips" (by specifying an offset),you are dealing with the actual addresses. 2 EXAMPLE The following example of a HEX session is provided to show some of the uses of the HEX features.The example here is intentionally complicated to demonstrate the usefulness of the indirect command file input approach.Once the commands are determined,they can be entered in an indirect command file and used again and again. Consider the following problem:You have a link which produces a hex file called COM.HEX that defines addresses between 0000-0FFF and from B800-BFFF.You also have a link which produces a hex file called MTI.HEX that defines addresses between 0000-0FFF and from B800-BFFF. You desire the following: 1. Hex files called C0000.HEX and C0800.HEX which define 0000-7FFF and 0800-0FFF,RESPECTIVELY,USING THE CODE FROM COM.HEX. 2. Hex files M0000.HEX and M0800.HEX which define 0000-07FF and 0800- 0FFF,respectively,using the code from MTI.HEX. 3. A file CPROM.HEX made up as follows: B800-B8FF as defined by MTI.HEX, B900-B9FF as defined by COM.HEX, BA00-BFF5 as defined by MTI.HEX, BFF6-BFFD containing the CRC's in high-low for C0000.HEX, C0800.HEX,M0000.HEX,and M0800.HEX(in that order),and BFFE- BFFF containing a value such that the CRC of the entire CPROM.HEX will be 0000. 4. Finally, a nicely formatted display of CPROM's contents to be spooled to the printer. The following commands will do the job: READ FROM 0000 THRU 1FFF FILE COM.HEX WRITE FROM 0000 THRU 07FF FILE C0000.HEX WRITE FROM 0800 THRU 0FFF FILE C0800.HEX CRC FROM 0000 THRU 07FF TO 7FF6 CRC FROM 0800 THRU 0FFF TO 7FF8 FILL FROM 0000 THRU 1FFF WITH FF READ FROM 0000 THRU 1FFF FILE MTI.HEX WRITE FROM 0000 THRU 07FF FILE M0000.HEX WRITE FROM 0800 THRU 0FFF FILE M0800.HEX CRC FROM 0000 THRU 07FF TO 7FFA CRC FROM 0800 THRU 0FFF TO 7FFC OFFSET 8000 FILL FROM B800 THRU BFFF WITH FF READ FROM B800 THRU BFFF FILE MTI.HEX READ FROM B900 THRU B9FF FILE COM.HEX COPY FROM FFF6 THRU FFFD TO BFF6 CRC FROM B800 THRU BFFD TO BFFE WRITE FROM B800 THRU BFFF FILE CPROM.HEX DISPLAY FROM B800 THRU BFFF FILE CPROM.LST The commands are self-documenting except for the following trick:The computed CRC values were temporarily stored in "high memory".The OFFSET command "renames" this temporary location.Note also that we used the FILL command rather than INIT,since INIT would have wiped out our temporary store location for the CRC values.After the rest of CPROM is read in,we move the CRC values into place,then do a CRC on all but the last two bytes of CPROM, and place the CRC into those last two bytes. Again,this example is certainly not typical,but was chosen to show that a complicated hex file ritual can be completely using HEX. 2 FORMAT INTEL HEX FORMAT HEX uses the following definition of INTEL hex format: The file contains zero or more definition records in the format :ccabcdrrn(1)n(1)...n(c)n(c)ss where : signals the start of the record,cc is a non-zero data count, abcd is the first address that this record defines,rr is the recrod type(00 for a definition record),n(1)n(1)...n(c)n(c)is the data to be loaded beginning at address abcd,ss is a hex number such that cc+ab+cd+n(1)n(1)+...+n(c)n(c)+ss = 00(mod 100H). The file must contain one trailer record of the form :00abcdrrss where abcd is the program transfer address,rr is the record type (usually 01,but not officially defined),and ss is a hex number such that ab+cd+rr+ss=00(mod 100H) Any record not containing a colon is treated as a comment.Characters or spaces preceding a colon in a record are treated as a comment. any record following the trailer record is ignored. The records in the file need not be sorted(in ascending order by address),or of any particular count.The file need not define every address in its range. 2 MESSAGES MESSAGES Address: xxxx Memory: yy File: zz This is an informative message displayed by the COMPARE operation when a mismatch is detected between the file and the current contents of virtual memory.COMPARE continues until completion. Address out of range The specified address in a command line or an input hex file cannot be handled under the current offset,or,the FROM address specified is greater than the TO address. Checksum error A checksum error was detected during a hex file READ operation.The offending record is displayed,and the READ terminated. Command input error HEX was unable to get a command line due to a system problem, control characters typed accidentally,or because the specified indirect command file was not found/accessible. Command input timeout The Hex utility has exitted because of a two minute timeout on command input. CRC:xxxx This is an informative message in response to a CRC command.It appears even when the CRC value is destined using the TO option. EOF reached before trailer record During a hex file READ operation,physical end of file occurred before a trailer record was found(see Appendix A). Extra ignored: This message is followed by the characters remaining on the command line after a command syntax error was discovered,or superfluous to an otherwise legitimate command.In the second case,the command up to that point was accepted and processed.Spaces and tabs do not appear in the command characters displayed. Filename syntax error The file specification was improper.A missing right bracket in the UIC specification,for example.Note,however,that most filename syntax errors will result in a FILE OPEN ERROR rather than FILE NAME SYNTAX ERROR. File open error A problem was encountered during an attempt to open a file for input or output.For a read operation,the file may not exist.For a read or write operation,you may not have sufficient privlege to open such a file under the specified UIC,specified device may be offline,or some other system problem occurred which prevented you from opening the file. Hex conversion error An illegal(perhaps missing)character was encountered in trying to obtain a hex digit from a command line or hex input file.If encountered in a hex file READ operation,the offending record is displayed,and the READ terminated. Illegal command The first word of the command line was not found in the command dictionary. I/O error An unrecoverable I/O error occurred during a read or write operation You may lack sufficient privilege to access the specified file,the device is offline,or a system problem occurred.Consult system manager. Low:xxxx High:xxxx Count:xxxx Sum:xxxx Transfer:xxxx This informative message shows statistics gathered during a hex file READ or WRITE operation.All numbers are hexidecimal.The lowest address and highest address actually loaded are displayed,as is the count of bytes loaded and the transfer address obtained from the trailer record. The sum is a 16-bit byte-wise sum over the range of the READ or WRITE. Missing keyword A required keyword(FROM,THRU,TO,FILE,etc.)is missing or misspelled in the command line.Consult user's guide for exact syntax of the command. Offset:xxxx This is an informative message in response to an OFFSET command with no argument.The value displayed is the current offset value. Sum:xxxx This is an informative message in response to a SUM command.The value is the 16-bit byte-wise sum over the specified range. Transfer:xxxx This is an informative message in response to a TRANSFER command with no argument.The value shown is the current transfer address. Transfer:xxxx File:zzzz This is an informative message in given by the COMPARE operation when a mismatch is detected between the current value of the transfer address and the value specified by the file. any message which looks like: TASK"...HEX"TERMINATED ODD ADDRESS TRAP OR OTHER TRAP FOUR PC 00000 PS 00000 R0 00000 R1 00000 R2 00000 R3 00000 R4 00000 R5 00000 SP 00000 This indicates a severe system problem,or,the execution of a particular sequence of instructions in the HEX task image which resulted in register contents and/or a trap not envisioned by the author(i.e.,you stumbled upon a bug).Consult system manager.