.SKIP 10 .FLAGS BOLD .CENTER ^*HEX FILE EDITOR (HEX)\* .SKIP 2 .CENTER DECUS Library Program 11-480 .SKIP 10 .INDENT 10 Author: .LEFT MARGIN +20 Kevin Angley Telex Computer Products, Inc. Communication Products Division 3301 Terminal Drive, Raleigh, North Carolina 27604, USA (919) 834-5251 .SKIP 2 .LEFT MARGIN -10 Modified by: .SKIP 1 .LEFT MARGIN +10 Chris Doran Sira Ltd. South Hill, Chilslhurst, Kent, BR7 5EH England .LEFT MARGIN -10 and .LEFT MARGIN +10 Scott Smith Telex Computer Products, Inc. Raleigh, North Carolina 27604, USA .LEFT MARGIN -10 and .LEFT MARGIN +10 Dave Moore Telex Computer Products, Inc. Raleigh, North Carolina 27604, USA .PAGE .REQUIRE "manual.rnt" .NO FLAGS ALL .LAYOUT 2,2 .PARAGRAPH 0,1 .AUTOPARAGRAPH .NO AUTOSUBTITLE .CHAPTER INTRODUCTION The HEX utility is a task that runs under VAX/VMS. Its purpose is to manipulate object files output by various linkers or assemblers. Such object files (often coded as hexadecimal numbers, and hence called "hex" files) are, in essence, "task images" of software to run in microprocessor-based systems. Detailed description of acceptable formats are given in Appendix A. The HEX command contains the following data structures which are manipulated by user commands: .LITERAL Virtual memory This is the principal component of the HEX utility. It is a 64K byte area which allows the user to manip- ulate code in memory as if it were resident in the target machine. Addressing Mode HEX will handle 16, 24, or 32-bit addressing modes. The mode is 16-bit by default, but can be changed by the ADDRESSING MODE or OFFSET command. Pseudo-registers A bank of 256 (decimal) bytes is available as user- definable workspace. (See Section 2.8). File format This defines the assembler or emulator format for various microprocessors. (See Section 2.5.14 and Appendix A). Transfer Address The transfer (start) address of the user program can be read, modified, and written out. (See Section 2.5.33). Program name A 0-8 character program name can be read, modified, and written by those formats which support it. (See Section 2.5.21). LOW register This contains the lowest address used in the last READ or COMPARE operation. (See Section 2.4). HIGH register This contains the highest address from READ or COMPARE. .END LITERAL .CHAPTER OPERATING INSTRUCTIONS .TITLE HEX FILE EDITOR .SUBTITLE Operating Instructions .HEADER LEVEL 1 HOW TO INVOKE HEX HEX can be invoked in two ways: .LIST .LEFT MARGIN 0 .LIST ELEMENT Interactive Mode .LITERAL $ HEX Type HEX in response to the DCL prompt. HEX> command Command lines may be entered. HEX> command HEX> ^Z Control/Z terminates HEX. .END LITERAL .LIST ELEMENT Indirect command mode .LITERAL $ HEX @filespec Where filespec is the file specification of an indirect command file containing a list of HEX commands. (The file type for indirect command file defaults to .CMD.) .END LITERAL Note that the invocation of HEX may itself be contained within a DCL command file. In addition, HEX indirect command files may be nested arbitrarily deep. .END LIST Upon entering HEX, virtual memory is FF-filled, the offset and transfer address values are set to 0000, the program name is blank (8 spaces), the object file format is set to INTEL, 16-bit address mode is selected, and LOW and HIGH addresses are set to all ones and all zeros respectively. The "HEX>" prompt is displayed on the terminal, indicating that the task is ready to receive a command. Typically, a HEX session would proceed as follows: .LIST .LIST ELEMENT If the PROM which the use is preparing 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 description of the FILL command in Section 2.5.13.) .LIST ELEMENT If the address range of the object files that you intend to manipulate lies withing the range 0000-FFFF, it is not necessary to set an offset value. Otherwise, an OFFSET should be specified. (See the description of the OFFSET command in Section 2.5.24 and notes on using it in Section 2.9.) .LIST ELEMENT READ the object file(s) into virtual memory. (See the description of the READ command in Section 2.5.26.) .LIST ELEMENT Optionally, you may manipulate or examine the contents of virtual memory. .LIST ELEMENT Finally, WRITE selected sections of virtual memory out to create new object files. (See the description of the WRITE command in Section 2.5.35 and the APPEND command in Section 2.5.3.) .END LIST HEX is exited by typing EXIT or Control/Z at the terminal. .HEADER LEVEL 1 COMMAND DESCRIPTIONS Descriptions of valid HEX commands follow. The following general notes apply: .LIST .LIST ELEMENT aaaa, bbbb, and sequential use of early letters of the alphabet indicate a 1-8 digit hexidecimal number. Leading zeros may be omitted without effect in all commands except OFFSET. (See Section 2.5.24 for a description of the effect of leading zeros in the OFFSET command.) .LIST ELEMENT vvvv, wwww, xxxx, or similar indicate a hexadecimal number of exactly the same number of digits as there are characters. (E.g., vv is a 2 digit byte, xxxxxx is a 6 digit 24-bit address.) .LIST ELEMENT pp indicates a byte value which may be entered either as a 2-digit hexadecimal number, or a character specification in one of the following forms (where c indicates a printing character and ^, ', ~,and - are literal characters): .LITERAL ^c control codes, 00-1F, shown as ^@, ^A, ^B, ... ^_ 'c printing characters, codes 20-7E, with parity bit set -- 'space to '~. (Some control codes are also also accepted. ^# the parity-clear delete character, code 7F ~c control codes with parity bit set -- 80-9F, ~@ ... ~_ -c printing characters with parity bit set, codes A0-FE -- -space , -!, ... -~ ~# the parity-set delete character, code FF .END LITERAL .LIST ELEMENT qqqq indicates a 16-bit value which may be entered either as a 4-digit hex number, or a double-quote followed by two ASCII characters. Thus "ab and 4142 have the same effect, since the hex codes for the characters a and b are 41 and 42 respectively. Only parity-clear, printing characters may be entered in this format. .LIST ELEMENT nnnnnnnn or mmmmmmmm indicates a 1-8 character program name. .LIST ELEMENT **** represents an entity which may either be an address or a pseudo-register, written as %xx. .LIST ELEMENT Uppercase words are required keywords. They may be abbreviated to as few characters as is needed to make them unambiguous. .LIST ELEMENT Structures in braces ({...}) show an optional parameter. The braces are not part of the syntax. .LIST ELEMENT All numbers in this manual (unless stated otherwise) and all input/output of the HEX utility are hexadecimal. .END LIST For example: .SKIP 1 .LEFT MARGIN +5 FILL FROM aaaa THRU bbbb WITH pp .SKIP 1 .LEFT MARGIN -5 FILL is the command, FROM, THRU, and WITH are required keywords, aaaa and bbbb are 4, 6, or 8-digit hexadecimal numbers depending on the current addressing mode, and pp is a 2-digit hexadecimal number or character specification. Thus the following are valid FILL commands: .SKIP 1 .LEFT MARGIN +5 .LITERAL FILL FROM 0000 THRU 07FF WITH 55 (16-bit mode) FILL FROM 0A0010 THRU 0A0110 WITH ^A (24-bit mode) FILL FROM FFEE0A00 THRU FFEE0FFF WITH 'x (32-bit mode) .END LITERAL .LEFT MARGIN -5 .HEADER LEVEL 1 COMMAND SUMMARY The following commands are available: .LEFT MARGIN +5 .LITERAL ADDRESSING sets addressing mode to 16, 24, or 32-bit. AND logical AND constant with bytes in address range. APPEND write memory at end of an existing object file. COMPARE compare memory with an object file. COMPLEMENT take one's complement of bytes in address range. COPY copy values from one area to another. CRC compute standard bisync cyclic redundancy check on range. CSUM store a SAL-type CSUM block containing sum of data bytes. DECREMENT subtract constant from bytes in address range. DIVIDE divide bytes in address range by constant. DISPLAY display portions of memory at terminal or printer. ECHO turns on command line display (cancels NOECHO). EDIT examine and optionally replace values in the file. EXIT exits HEX and returns control to DCL. FILL fill address range with a value. FORMAT specify or display current object file format. HELP request on-line help. IDENT display HEX's version number (latest revision date). INCREMENT add constant to bytes in address range. INIT reset to initial conditions. MOVE move values from one area to another. MULTIPLY multiply bytes in address range by constant. NAME set or display current program name. NEGATE take two's complemet (negative) of bytes in address range. NOECHO turns off command line display (cancels ECHO). OFFSET display or define address offset. OR logical inclusive OR constant with bytes in address range. READ read in an object file. REMAINDER set bytes in address range to remainder on division. REVERSE reverses byte order in place in a given range. ROTATE rotate bits of bytes in address range. SEARCH scan the file for a particular byte or word value. SHIFT arithmetic or logically shift bits of bytes in range. SUM compute Data I/O programmer 16-bit byte-wise sum-check. TRANSFER manipulate the transfer address. USE specify which 8-bit section of an addressable unit to use. WRITE write memory to a new object file. XOR logical exclusive OR constant with bytes in address range. * displayable comment (used in indirect command files). ; non-displayable comment (used in indirect command files). . issue DCL command. ? request on-line help (equivalent to HELP command). ctrl/Z exit. .END LITERAL .LEFT MARGIN -5 .HEADER LEVEL 1 RANGE SPECIFICATION Many of these commands take a memory range specification of the basic form: .LITERAL { ODD/EVEN } FROM aaaa THRU bbbb { STEP vv } .END LITERAL where aaaa and bbbb are the (inclusive) addresses for the operation. By default, every byte in that range is included, but if a STEP ss option is given, only every vv'th address, starting at aaaa and <= bbbb, is used. ODD and EVEN may be used to select only odd or even addresses respectively, and thus imply a STEP of 02. If given, they will force aaaa to be rounded up, if necessary, to the next appropriate byte boundary. The main purpose of the ODD and EVEN options is to enable the production of PROM files for 16-bit processors (e.g. LSI-11 or TI99xx series), which need separate hi- and low-byte 8-bit PROMs. STEP supports the more general case, e.g. 32-bit processors would need four PROMs each written with a STEP of 04. The main function of these options is thus for use with the WRITE command. For completeness, however, they are supported in all commands which take a range specification, although they may not be of much value in many cases. Note that if used with a WRITE command, then the resulting object file can only be sensibly processed by another READ or COMPARE with the same STEP. The keywords LOW and HIGH may be given as alternatives to aaaa and bbbb. They have as their values the lowest and highest addresses referenced in the last READ or COMPARE operation. Initially, and after INIT, LOW is set to all ones, and HIGH is set to all zeros. Their values are not affected by any other command. The following examples illustrate the use of LOW and HIGH: .LEFT MARGIN +5 .LITERAL READ FILE TEST DISPLAY FROM LOW THRU HIGH FILE TEST1 SUM FROM 0000 THRU HIGH CRC FROM LOW THRU 7FFF .END LITERAL .LEFT MARGIN -5 LOW and HIGH are not updated when the offset is changed and thus may go out of range after an OFFSET command, particularly one that changes the addressing mode (number of bits). A READ or COMPARE that terminates prematurely (e.g. on a checksum error) leaves LOW and HIGH set to their correct values at the point just prior to the error. The current values of LOW and HIGH can be displayed with the DISPLAY LOW or DISPLAY HIGH commands. COMPARE, READ, WRITE, and APPEND have three optional parameters which may follow the range specification: .LEFT MARGIN +5 .LITERAL PLUS dddd specifies a hex value dddd which should be added to each address (except the transfer address) read from or written to the file. MINUS dddd specifies a hex value to be subtracted from each address in the file. PARTIAL indicates that the file does not or should not contain a trailer record. .END LITERAL .LEFT MARGIN -5 Thus the full formal syntax of a range specification is: .LITERAL {ODD/EVEN} FROM aaaa/LOW THRU bbbb/HIGH {STEP cc} {PLUS/MINUS dddd} {PARTIAL} .END LITERAL In the following descriptions, this will be shown simply as .LITERAL FROM aaaa THRU bbbb .END LITERAL with an indication if PLUS, MINUS, and PARTIAL keywords are allowed. .HEADER LEVEL 1 DETAILED DESCRIPTIONS OF COMMANDS .HEADER LEVEL 2 ADDRESSING .INDENT 5 ADDRESSING MODE {type} .SKIP 1 where type is either 16, 24, or 32. This command sets the addressing mode to 16-, 24-, or 32-bit. The addressing mode may also be set with the OFFSET command. (See Section 2.5.24 for details of how OFFSET affects addressing mode.) If no type is specified, ADDRESSING MODE displays the current addressing mode. .HEADER LEVEL 2 AND .INDENT 5 AND FROM aaaa THRU bbbb WITH pp .SKIP 1 Stores in each byte in the given range the logical AND of its original value with the constant pp. For example: .LITERAL AND FROM LOW THRU HIGH WITH 07 INCREMENT FROM LOW THRU HIGH BY '0 .END LITERAL selects only the low three bits of each byte in the area just read in and then adds the ASCII code for 0 to each byte, converting the area to octal digits. .HEADER LEVEL 2 APPEND .INDENT 5 APPEND FROM aaaa THRU bbbb {WIDTH vvvv} FILE filespec .SKIP 1 This is basically the same as WRITE (which see for further details), but instead of creating a new file, the memory area is written in the current format to the end of an existing object file. It is the user's responsibility to ensure that the old file is in the right format. In particular, it should have been written without a trailer record (PARTIAL option). Otherwise, the appended data will be ignored by READ. APPEND does not write a file header record, but will write a trailer unless the PARTIAL option is given. One use of the APPEND command is to write a file from a program which is in several areas with intervening rubbish. E.g., if a program takes low memory from 0000 to 01FF, and high memory from 4000 to 4FFF, then it could be output by .LITERAL WRITE FROM 0000 THRU 01FF PARTIAL FILE TEMP APPEND FROM 4000 THRU 4FFF FILE TEMP .END LITERAL PLUS, MINUS, and PARTIAL options are allowed in APPEND range specifications. .HEADER LEVEL 2 COMPARE .INDENT 5 COMPARE {FROM aaaa THRU bbbb} FILE filespec .SKIP 1 where filespec is a file specification (see Section 2.7) of an object file in the currently selected format. The code contained in the file will be compared with values at the same locations in virtual memory. Unspecified locations are not checked. Differences are reported to the terminal. The contents of virtual memory are 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 to bbbb will be compared to virtual memory. MOSTEK format files must contain a header record. PLUS and MINUS options are also allowed in the COMPARE range specification. For formats which have one, an error will be generated if there is no trailer record unless the PARTIAL option is included, or if there is a trailer record but PARTIAL was included. The transfer address and program name from the appropriate records (if defined for the particular format type) are also compared with the current values, and differences reported. An alternative form of the COMPARE command enables two areas of memory to be compared: .SKIP 1 .INDENT 5 COMPARE {FROM aaaa THRU bbbb} WITH cccc .SKIP 1 In this form, the command compares the contents of the area of memory from address aaaa to address bbbb with the contents of that beginning at address cccc. PLUS, MINUS, and STEP options in the range specification applies to accesses to the first area only -- the second area is always read as sequential bytes beginning at cccc. If no range specification is given in this form of compare, that of the last command line that did have one is used instead. .HEADER LEVEL 2 CRC .INDENT 5 CRC FROM aaaa THRU bbbb {TO ****} {EXPECTING vvvv} .SKIP 1 Calculates the standard bisync CRC of every byte in the range, using a preset of 0000. If a TO address is specified, the result is stored there in high-low order. **** is either an address or a pseudo-register (see Section 2.8). If the latter, the high byte of the CRC will be put into %xx, and the low byte into %xx+1. Whether or not a TO address is specified, the CRC value is displayed on the terminal screen. If an optional EXPECTING parameter is entered with the command, HEX compares the expected value with the calculated value. If the two are different, an error message is displayed. .HEADER LEVEL 2 CSUM .INDENT 5 CSUM FROM aaaa THRU bbbb .SKIP 1 Calculates and displays on the terminal a 16-bit byte-wise summation of locations in the given range (i.e. as SUM), and then writes a 4-byte SAL assembler-type CSUM block at bbbb+1, in form: .LITERAL bbbb+1 = aaaa low bbbb+2 = aaaa high bbbb+3 = sum low bbbb+4 = sum high .END LITERAL The CSUM block enables instruments to check for PROM integrity, e.g. on startup. This command is useful for creating PROM checksum blocks in files produced by assemblers without this facility, or to write an updated CSUM block into edited or copied data. .HEADER LEVEL 2 DECREMENT .INDENT 5 DECREMENT FROM aaaa THRU bbbb {BY pp} .SKIP 1 This command subtracts pp (default 01) from each byte in the given range. .HEADER LEVEL 2 DISPLAY .INDENT 5 DISPLAY {ASCII} FROM aaaa THRU bbbb {FILE filespec} .SKIP 1 where filespec is a file specification (see Section ***). The contents of aaaa to bbbb are displayed to the terminal (or, if given, to a file.) If the STEP size is (default) 01, the address aaaa if rounded down to aaa0 and bbbb is rounded up to bbbF. By default, data bytes are shown as two hex digits. However, the ASCII option causes them to be shown as ASCII characters. Non-printing characters are shown as the printing equivalent, using the character specification format shown in Section 2.2, except that the apostrophe before parity-clear printing characters is omitted. The DISPLAY command has three other forms: .SKIP 1 .INDENT 5 DISPLAY PSEUDO .SKIP 1 displays the current contents of all 256 pseudo-registers to the terminal screen. .SKIP 1 .INDENT 5 DISPLAY HIGH or DISPLAY LOW .SKIP 1 will display the current values of both HIGH and LOW. .HEADER LEVEL 2 DIVIDE .INDENT 5 DIVIDE {SIGNED} FROM aaaa THRU bbbb BY pp .SKIP 1 This command divides each byte in the given range by the constant pp. Source and constant bytes are treated as signed (2's complement) if the SIGNED option is given. The default is unsigned. Division by zero sets all bytes in the range to zero. .HEADER LEVEL 2 ECHO .INDENT 5 ECHO .SKIP 1 Turns on display of lines read from an indirect command file after it has been disabled by NOECHO (see Section 2.5.23). The default is to echo all commands read. .HEADER LEVEL 2 EDIT .INDENT 5 EDIT aaaa {STEP ww} .SKIP 1 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: .SKIP 1 .INDENT 5 aaaa vv=cc- .SKIP 1 where aaaa is the current address being edited, vv is its contents in hexadecimal, and cc shows the ASCII or control character in the same way as DISPLAY. HEX then waits for a reply in one of the following forms. ( and denote pressing the RETURN or Control Z keys respectively.) .LEFT MARGIN +5 .LITERAL pp to replace the contents of the location being edited and open the next ww'th location for editing. to leave the location as it is and open the next ww'th location. pp^ to replace the contents of the location being edited and open the previous ww'th location for editing. ^ to leave the location as it is and open the previous ww'th location for editing. pp to replace the contents of the open location and then return to HEX command mode. to leave the location as is and return to HEX command mode. .END LITERAL .LEFT MARGIN -5 pp may take the form of a two-digit hexadecimal byte value, or a character specifier as shown in Section 2.2. As the EDIT command requires interactive input from the user, it is not allowed within indirect command files. .HEADER LEVEL 2 EXIT .INDENT 5 EXIT .SKIP 1 Exits from HEX, returning to the operating system (DCL) or calling program. This command has the same effect as typing control/Z at the terminal, but may be included in a command file, enabling HEX to be run without user intervention. .HEADER LEVEL 2 FILL .INDENT 5 FILL FROM aaaa THRU bbbb WITH pp .SKIP 1 Every location from aaaa to bbb is set to byte value pp. .HEADER LEVEL 2 FORMAT .INDENT 5 FORMAT {type} .SKIP 1 IF type is omitted, the current format is shown. Otherwise, type specifies the object file format and default filetypes for READ, COMPARE, WRITE, and APPEND commands (and default WIDTH for WRITE and APPEND), as: .LITERAL type WIDTH filetype notes ----------------- ----------- -------- ----- INTEL 32/250 .HEX MOTOROLA 32/252 .HEX ROCKWELL 32/252 .HEX RCA 32/168 .HEX COSMAC UT4 utility TEKHEX 32/250 .HEX Tektronix emulators EXTENDED {TEKHEX} 32/250 .HEX ditto, "Extended TekHex" TEXAS 32/200 .OBJ TI 7000, 9900, and 99000 family MOSTEK 32/250 .HEX TCI 32/253 .HEX FAIRCHILD 32/254 .HEX "Fairbug" format .END LITERAL WIDTH values are in decimal but must be specified in hexadecimal. The first value shown is the default and the second is the maximum that will fit into HEX's I/O buffer. Appendix A gives full details of the various file format. EXTENDED TEKHEX may be abbreviated to EXTENDED. .HEADER LEVEL 2 HELP .LITERAL HELP {command} or ? {command} .END LITERAL Displays instructions for using the named HEX command (if given). If no command is named, a summary table showing synataxes of all commands if given. .HEADER LEVEL 2 IDENT .INDENT 5 IDENT .SKIP 1 displays the program identification for this version of HEX, as: .SKIP 1 .INDENT 5 : HEX version dd-mmm-yy .HEADER LEVEL 2 INCREMENT .INDENT 5 INCREMENT FROM aaaa THRU bbbb {BY pp} .SKIP 1 This command adds pp (default 1) to each byte in the given range. .HEADER LEVEL 2 INIT .INDENT 5 INIT {WITH pp} .SKIP 1 This command resets the HEX utility to its initial conditions. Virtual memory is filled with value pp (default FF), offset and transfer address values are set to 0000, the program name is set to null (8 spaces), and the LOW and HIGH range values to all ones and all zeros repsectively. Addressing mode, format, and pseudo-registers are unaffected by INIT. .HEADER LEVEL 2 MOVE .LITERAL MOVE BYTE FROM **** TO **** or MOVE WORD FROM **** TO **** .END LITERAL where ****'s represent either a four-digit hexadecimal number valid under the current offset, or a pseudo-register specification (see Section 2.8). The MOVE command is a variation of the COPY command. It 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 MOVE copies the entire word at one one time, rather than byte wise as in COPY. .HEADER LEVEL 2 MULTIPLY .INDENT 5 MULTIPLY FROM aaaa THRU bbbb BY pp .SKIP 1 This command multiplies each byte in the given range by constants pp. Any high order part of the result is lost, so there is no difference between signed and unsigned multiplication, and hence no need for a SIGNED option. .HEADER LEVEL 2 NAME .INDENT 5 NAME {nnnnnnnn} .SKIP 1 If nnnnnnnn is omitted, the current program name (if any) is displayed. If nnnnnnnn is given, this becomes the new 1-8 character program name. Any ASCII characters except space and tab, may be used in the name. Trailing blanks are appended if less that eight characters are given, and and excess characters are ignored. Not all object file formats allow a program name, and among those that do, some may not accept all ASCII characters or may not allow all eight characters. HEX does not check the validity of the name entered under the current format. .HEADER LEVEL 2 NEGATE .INDENT 5 NEGATE FROM aaaa THRU bbbb .SKIP 1 This command sets each byte in the given range to its arithmetic (two's) complement, i.e., reverses its sign. .HEADER LEVEL 2 NOECHO .INDENT 5 NOECHO .SKIP 1 Turns off display of lines being read from an indirect command file, including displayable comments, and also statistics reports from READ and WRITE commands. Other messages, such as errors, terminal DISPLAY listings, SEARCH and COMPARE matches or mismatches, still appear. The NOECHO command does not affect commands typed directly at the terminal; these are alway echoed. Echoing is re-enabled by the ECHO command (see Section 2.5.10). Placing this command at the beginning of a command file enables HEX command files to be executed without filling the screen with unwanted information. Thus a standard Motorola to Intel conversion could be carried out without concerning the user with HEX internals by invoking it with an indirect command file containing: .NO FILL .LEFT MARGIN +5 .SKIP 1 NOECHO FORMAT MOTOROLA READ FILE TEST_1 FORMAT INTEL WRITE FROM LOW THRU HIGH FILE TEST_2 EXIT .SKIP 1 .LEFT MARGIN -5 .FILL .HEADER LEVEL 2 OFFSET .INDENT 5 OFFSET {aaaa} .SKIP 1 The OFFSET command with no argument displays the current offset value. If a value is specified, that value becomes the new offset. OFFSET also sets the addressing mode depending on the number of hexadecimal digits given in the value according to the following scheme: .NOFILL .LEFT MARGIN +15 .SKIP 1 1-4 digits 16-bit addressing 5-6 digits 24-bit addressing 7-8 digits 32-bit addressing .FILL .SKIP 1 .LEFT MARGIN -15 Thus using leading zeros in the OFFSET command can affect addressing mode. For instance, the command OFFSET 00000000 would set addressing mode to 32-bit while it would leave the actual offset at zero. The addressing mode may also be set directly via the ADDRESSING command (see Section 2.5.1). Neither the OFFSET nor the ADDRESSING command checks to see that the specified addressing mode is valid for the current format. See notes on the use of offset in Section 2.9. .HEADER LEVEL 2 OR .INDENT 5 OR FROM aaaa THRU bbbb with pp .SKIP 1 This command sets each byte in the given range to its logical inclusive OR with the given constant. .HEADER LEVEL 2 READ .INDENT 5 READ {FROM aaaa THRU bbbb} {PLUS/MINUS cccc} {PARTIAL} FILE filespec .SKIP 1 where filespec is a file specification (see Section 2.7) of an object file in the current format. 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 to bbbb will be placed in virtual memory. A STEP vv option may be used to cause data to be placed at every vv'th location, when the file was written in this way (presumably with a compatible WRITE). Intermediate locations are not affected. The transfer address and program name from the appropriate records (if supported by the current file format) replace the current values, and values for LOW and HIGH keywords are updated. (They are set to all ones and all zeros respectively if no data is read in.) For formats which have one, an error will be generated if there is no trailer record unless the PARTIAL option is included, or if there is a trailer record but PARTIAL was included. .HEADER LEVEL 2 REVERSE .INDENT 5 REVERSE {ODD/EVEN} FROM aaaa THRU bbbb {STEP ss} .SKIP 1 reverses in place the values contained in every ss'th location from aaaa thru bbbb i.e. aaaa is exchanged with bbbb, aaaa+ss with bbbb+ss etc. bbbb is rounded down, if necessary, so that bbbb-aaaa is an exact multiple of ss. If ss is not 1, intervening locations in the range are unaffected. This command is useful when setting up data for memory which is addressed through inverting buffers. If, for example, we have to blow a 2K PROM for such a system, then the byte at 0000 will have to be placed at 07FF, that at 0001 at 07FE, etc. Note that for a program taking several PROMs, the contents of each must be reversed separately, e.g.: .SKIP 1 .NO FILL .LEFT MARGIN +5 REVERSE FROM 0000 THRU 07FF REVERSE FROM 0800 THRU 0FFF WRITE FROM 0000 THRU 0FFF WIDTH 800 FILE PROMS .FILL .LEFT MARGIN -5 .HEADER LEVEL 2 REMAINDER .INDENT 5 REMAINDER {SIGNED} FROM aaaa THRU bbbb BY pp .SKIP 1 This command sets each byte in the given range to the remainder on dividing by constants pp (sometimes called the "modulus"). Source and constant bytes are treated as signed (2's complement) if the SIGNED option is given, otherwise the default is unsigned. If pp is zero, all bytes in the range are left unchanged. .HEADER LEVEL 2 ROTATE .INDENT 5 ROTATE LEFT/RIGHT FROM aaaa THRU bbbb {BY pp} .SKIP 1 This command internally rotates each byte in the given range by pp bits (default 01). One of the keywords LEFT or RIGHT must be given to indicate the direction of rotation. For right rotates, bit 0 is copied to bit 7 at each step, and for left rotates, bit 7 goes to bit 0. pp is taken as a full 8-bit unsigned number, although values above 7 are redundant. .HEADER LEVEL 2 SEARCH .LITERAL SEARCH FROM aaaa THRU bbbb FOR {NOT} pp or SEARCH FROM aaaa THRU bbbb FOR {NOT} qqqq .END LITERAL .SKIP 1 searches the specified range of virtual memory for the byte or word value given. If the NOT option is set, SEARCH searches for all values not equal to the specified byte or word. The addresses containing the value and its contents are displayed, together with the total number of matches found. In the case of a word value, the search is for a pair of adjacent bytes (even if the STEP is not 01) containing that value in lo-hi order. pp is a 2-digit hexadecimal byte or character specification (see Section 2.2). qqqq may be a 4-digit hexadecimal number, or a double-quote followed by two ASCII characters. (Only parity-cleared printing characters are allowed.) .HEADER LEVEL 2 SHIFT .INDENT 5 SHIFT LEFT/RIGHT {SIGNED} FROM aaaa THRU bbbb {BY pp} .SKIP 1 This command shifts each byte in the given range by pp bits (default 01). One of the keywords LEFT or RIGHT must be given to indicate the direction of shift. For left shifts, bit 0 is shifted into bit 1, bit 0 is set to 0, and bit 7 is lost at each step. For right shifts, bit 7 is cleared unless the SIGNED option is selected, when it is replicated. pp is taken as a full 8-bit unsigned number, although values above 7 simply cause bytes to be set to a constant 00 or FF. .HEADER LEVEL 2 SUM .INDENT 5 SUM FROM aaaa THRU bbbb {TO ****} EXPECTING vvvv .SKIP 1 Calculates and displays on the terminal a 16-bit byte-wise summation of every byte in the range. If a TO address is specified, the result is stored there in low-high order. Whether or not a TO address is given, the sum value is displayed on the terminal. If %xx is specified as a pseudo-register, the low byte of SUM will be put into %xx, and the high byte will be put into %xx+1. If an optional EXPECTING parameter is entered with the command, HEX compares the expected value with the calculated value. If the two are different, an error message is displayed. .HEADER LEVEL 2 TRANSFER .INDENT 5 TRANSFER {aaaa} .SKIP 1 The transfer command with no argument displays the current transfer address. If a value is specified, that becomes the new transfer address. .HEADER LEVEL 2 USE USE aa OF bb FOR READ .SKIP 1 This command sets up HEX to handle files in which the basic addressable unit is wider than eight bits. The command instructs READ to input only one 8-bit section of addressable unit at each location. Thus the use command allows these files to be split into partitions suitable for loading into 8-bit proms. bb represents the number of 8-bit groups that make up each addressable unit (the width of the addressable unit must be a multiple of eight bits). aa specifies which of the bb bit groups is to be input as the value of a location. .HEADER LEVEL 2 WRITE .INDENT 5 WRITE FROM aaaa THRU bbbb {WIDTH vv/vvvv} FILE filespec .SKIP 1 creates an object file defining locations aaaa to bbbb in the currently defined format. The STEP range argument may be used to generate high and low byte PROM files. Texas format files write data as byte pairs and thus require WIDTH to be even. If an odd value is given, HEX will use the next even one instead without warning. The current program name will be included in the object file if the format provides for this. The transfer address will be included will be included if the format allows, unless the PARTIAL option is given to suppress it. PLUS or MINUS options may be used to add or subtract a constant value from load addresses (but not transfer address) written into the file. Appendix A gives full descriptions of object file formats. Note that not all formats support 24- or 32-bit addressing. Where this is the case, only the low 16 bits of addresses will be written. To reload such files correctly, a PLUS option must be used iwht the subsequent READ or COMPARE. .HEADER LEVEL 2 XOR .INDENT 5 XOR FROM aaaa THRU bbbb WITH pp .SKIP 1 This command sets each byte in the given range to its logical exclusive OR with pp, i.e. every bit in each source byte which differs from the equivalent bit in pp is set; every bit which is the same as in pp is cleared. .HEADER LEVEL 2 . (CLI Command) .INDENT 5 .LITERAL . {command} .END LITERAL .SKIP 1 If a command argument is given, the rest of the line after the fullstop is sent to DCL. Control returns to HEX after the command is executed. If there is no command argument, HEX releases control of the terminal to DCL. At this point, any number of DCL commands may be issued. Entering the DCL command LOGOUT or EOJ will cause HEX to be restarted with virtual memory and all variables (offset, transfer address, program name, etc.) exactly as they were before control was given to DCL. The . command, in either form, enables a system command (e.g. an assembly) to be issued without losing the contents of HEX's buffer and any edits made. .HEADER LEVEL 1 COMMAND LINE PROCESSING A command line consists of up to 80 (decimal) ASCII characters terminated by a RETURN. The command line may originate from the terminal or an indirect command file. A command line which begins with a semicolon (;) or asterisk (*) is treated as a comment. When commands are read from a file, comments beginning with asterisks are displayed while those beginning with semicolons are not. All lowercase characters (except the single character following a quote ('), minus (-), or tilde (~) or two characters following a double_quote (")) are converted to upper case before the command line is parsed. Keywords may be abbreviated to their shortest unambiguous form. For instance, COMPARE may be abbreviated to no shorter than COMPA (to distinguish it from COMPLEMENT) while HELP may be abbreviated to just H. .HEADER LEVEL 1 FILE SPECIFICATION A file specification takes the standard VMS form: .SKIP 1 .INDENT 5 node::device:[dir]file.ext;v .SKIP 1 where .NO FILL .LEFT MARGIN +5 node is the DECNET node, default current node, device is the device name, default is the current device, dir is the directory spec, default is the current directory, name is the name of the file, no default, ext is the file type, default depends on context, v is the version number, default is the highest version number. .FILL .LEFT MARGIN -5 .HEADER LEVEL 1 PSEUDO-REGISTERS Certain commands support specification of a pseudo-register. There are 256 (decimal) 8-bit registers. These may be used as temporary storage for moving bytes or words around in memory. Any two consecutive registers can be addressed as a 16-bit register in the context of certain commands. They are represented by the symbol '%' followed by a two digit hex number, %00 to %FF. There is no requirement that an even register be specified for use as a word. If used as a word, %xx contains the low byte and %xx+1 (modulus 100H) contains the high byte. Pseudo-registers are not initialized, are not affected by INIT, and have no relation to the OFFSET structure. .HEADER LEVEL 1 OFFSET Internally, HEX uses a 64K byte buffer as virtual memory. However, the utility can handle the entire 2**32 addressing range by using an appropriate offset. 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 FFFF. For example, if the user wishes to manipulate an object file defining addresses 019000 to 01BFFF, an offset of 10000 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. Changing the offset does not affect the contents of virtual memory. Thus if current offset is set to 0000 and virtual memory contains the contents of an object file with data from 0000 to 03FF, a subsequent command of OFFSET 8000 would cause HEX to consider the data as now residing in memory from 8000 to 83FF. The OFFSET command also set the addressing mode to 16, 24, or 32 bits depending on the number of hexadecimal digits given in the value. (See the description of the OFFSET command for further details.) However, the addressing mode set by OFFSET may be overridden with the ADDRESSING MODE command. For instance, the command OFFSET 8000 would set the addressing mode to 16-bit. If you wanted to force 32-bit addressing, the command ADDRESSING MODE 32 would override the addressing mode set by the OFFSET command. OFFSET does not affect the values of LOW, HIGH or the transfer address. .HEADER LEVEL 1 EXAMPLES As a first, simple example, consider the need to split up file BIG.HEX, which contains PROM code in address range 1000 to 3E65, and RAM code from 9000 up, into separate blocks for programming 4k-byte PROMs. First, the source file is READ in, using the THRU option to skip any RAM setup commands which might otherwise give a read error. .SKIP 1 .INDENT 5 READ FROM 1000 THRU 5000 FILE BIG .SKIP 1 Three WRITE commands then output the data into separate files: .SKIP 1 .LEFT MARGIN +5 .NO FILL WRITE FROM 1000 THRU 1FFF FILE LITTLE1 WRITE FROM 2000 THRU 2FFF FILE LITTLE2 WRITE FROM 3000 THRU 3FFF FILE LITTLE3 .SKIP 1 .LEFT MARGIN -5 These can be verified by compare operations as: .SKIP 1 .LEFT MARGIN +5 COMPARE FILE LITTLE1 COMPARE FILE LITTLE2 COMPARE FILE LITTLE3 .SKIP 1 .FILL .LEFT MARGIN -5 The second example si intentionally complicated to demonstrate the usefullness 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 an assembly which produces an object file call COM.LDA that defines addresses between 0000-0FFF and from B800-BFFF. You also have an assembly which produces a file called MTI.LDA that defines addresses between 0000-0FFF and from B000-BFFF. You desire the following: .LIST .LIST ELEMENT Files called C0000.LDA and C0800.LDA which define 0000-07FF and 0800-0FFF, repsectively, using the code from COM.LDA. .LIST ELEMENT Files called M0000.LDA and M0800.LDA which define 0000-07FF and 0800-0FFF, repsectively, using the code from MTI.LDA. .LIST ELEMENT A file CPROM.HEX made up as follows: .LEFT MARGIN +5 .LITERAL B800-B8FF as defined by MTI.LDA, B900-B9FF as defined by COM.LDA, BA00-BFF5 as defined by MTI.LDA, BFF6-BFFD containing the CRC's in high - low order for C0000.LDA, C0800.LDA, M0000.LDA, and M0000.LDA (in that order), and BFFE-BFFF containing a value such that the CRC of the entire CPROM.LDA will be 0000. .END LITERAL .LIST ELEMENT Finally, a nicely formatted display fo CPROM's contents which may be later spooled to the printer. .END LIST The following commands will do the job: .SKIP 1 .LEFT MARGIN +5 .NO FILL READ FROM 0000 THRU 1FFF FILE COM.LDA WRITE FROM 0000 THRU 07FF FILE C0000.LDA WRITE FROM 0800 THRU 0FFF FILE C0800.LDA CRC FROM 0000 THRU 07FF TO %00 CRC FROM 0800 THRU 0FFF TO %02 INIT READ FROM 0000 THRU 1FFF FILE MTI.LDA WRITE FROM 0000 THRU 07FF FILE M0000.LDA WRITE FROM 0800 THRU 0FFF FILE M0800.LDA CRC FROM 0000 THRU 07FF TO %04 CRC FROM 0800 THRU 0FFF TO %06 INIT READ FROM B800 THRU BFFF FILE MTI.LDA READ FROM B900 THRU B9FF FILE COM.LDA MOVE WORD FROM %00 TO BFF6 MOVE WORD FROM %02 TO BFF8 MOVE WORD FROM %04 TO BFFA MOVE WORD FROM %06 TO BFFC CRC FROM B800 THRU BFFD TO BFFE WRITE FROM B800 THRU BFFF FILE CPROM.LDA DISPLAY FROM B800 THRU BFFF FILE CPROM.LST .SKIP 1 .FILL .LEFT MARGIN -5 The commands are self-documenting. Again, this example is certainly not typical, but was chosen to show that a complicated manipulation can be completely performed using HEX. .CHAPTER Error Messages .TITLE HEX FILE EDITOR .SUBTITLE Error Messages Note: References below to READ usually apply also to COMPARE, and those to WRITE may apply to APPEND. .SKIP 2 %HEX-W-ADDRRNGERR - .LEFT MARGIN +5 The specified address is not valid under the current offset. The offending address must lay within the range delineated in the error message. .LEFT MARGIN -5 .SKIP 1 %HEX-W-AMBIG - .LEFT MARGIN +5 The specified key word is ambiguous in this context. Enter more characters. .LEFT MARGIN -5 .SKIP 1 %HEX-W-CMPRNGERR - .LEFT MARGIN +5 COMPARE tried to compare virtual memory with an address which is out of range. .LEFT MARGIN -5 .SKIP 1 %HEX-W-CPYRNGERR - .LEFT MARGIN +5 COPY attempted to write to an out of range address. .LEFT MARGIN -5 .SKIP 1 %HEX-W-CRCRNGERR - .LEFT MARGIN +5 CRC attempted to write to an out of range address. .LEFT MARGIN -5 .SKIP 1 %HEX-W-DIVBYZERO - .LEFT MARGIN +5 DIVIDE by zero. All addresses in the specified range are set to zero. .LEFT MARGIN -5 .SKIP 1 %HEX-W-EDITRNGERR - .LEFT MARGIN +5 EDIT attempted access an out of range address. .LEFT MARGIN -5 .SKIP 1 %HEX-W-EXPECTERR - .LEFT MARGIN +5 The EXPECTING parameter for a CRC or SUM command is greater than FFFF. .LEFT MARGIN -5 .SKIP 1 %HEX-W-EXTCHRSIGNOR - .LEFT MARGIN +5 Extra characters have been entered following a legal command. HEX ignores any such characters. .LEFT MARGIN -5 .SKIP 1 %HEX-W-FNF - .LEFT MARGIN +5 File not found. Re-enter the command with the correct filespec. .LEFT MARGIN -5 .SKIP 1 %HEX-W-FORMATERR - .LEFT MARGIN +5 The file being READ or COMPAREd is not in the currently specified format. .LEFT MARGIN -5 .SKIP 1 %HEX-W-FROMTHRUERR - .LEFT MARGIN +5 The FROM parameter was greater than the THRU parameter. .LEFT MARGIN -5 .SKIP 1 %HEX-W-HIGHRNGERR - .LEFT MARGIN +5 The HIGH address is out of range in the current OFFSET. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGCHAR - .LEFT MARGIN +5 A record in the object file being READ contains an illegal character. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGCONTCODE - .LEFT MARGIN +5 The control character specified as a WITH or BY parameter is not a legal control code. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGFILESPEC - .LEFT MARGIN +5 The file specification is in an improper form. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGHELP - .LEFT MARGIN +5 The string specified in a HELP command contains illegal (non-alphanumeric) characters. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGHEX - .LEFT MARGIN +5 A non-hexadecimal string has been entered where a hexadecimal value is expected. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGNAM - .LEFT MARGIN +5 The current program name is not in a legal format for the current format. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGPRNTCHR - .LEFT MARGIN +5 The character specified as a WITH or BY parameter is not a legal printing character. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGPSEUDO - .LEFT MARGIN +5 An illegal pseudo-register has been specified. Pseudo-register addresses must be between 00 and FF. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGTRANSFER - .LEFT MARGIN +5 The specified transfer address is illegal. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGUSEVAL - .LEFT MARGIN +5 The second parameter in a USE statement was greater than the first. .LEFT MARGIN -5 .SKIP 1 %HEX-W-ILLEGWILDCARD - .LEFT MARGIN +5 A file specification with a wildcard character was entered. .LEFT MARGIN -5 .SKIP 1 %HEX-W-INCOMPLETE - .LEFT MARGIN +5 An incomplete command was entered. Additional keywords or parameters are required. .LEFT MARGIN -5 .SKIP 1 %HEX-W-LOWRNGERR - .LEFT MARGIN +5 The address specified by LOW is out of range for the current offset. .LEFT MARGIN -5 .SKIP 1 %HEX-W-MOSITERERR - .LEFT MARGIN +5 A Mostek format iterated data record in an illegal format was encountered during READ. .LEFT MARGIN -5 .SKIP 1 %HEX-W-MOVEADDRERR - .LEFT MARGIN +5 TO address in MOVE WORD command out of range. .LEFT MARGIN -5 .SKIP 1 %HEX-W-NAMETOOLONG - .LEFT MARGIN +5 The program name specified in a NAME command is more than eight characters long. .LEFT MARGIN -5 .SKIP 1 %HEX-W-NOFILESPEC - .LEFT MARGIN +5 No file was specified after the '@' as an indirect command file. .LEFT MARGIN -5 .SKIP 1 %HEX-W-NONINTEREDIT - .LEFT MARGIN +5 The EDIT command was contained in an indirect command file. EDIT may only be run interactively. .LEFT MARGIN -5 .SKIP 1 %HEX-W-NOPARTINDIC - .LEFT MARGIN +5 A READ PARTIAL command was issued for a Mostek format file whose file header block indicated that the file was a complete file. .LEFT MARGIN -5 .SKIP 1 %HEX-W-NOTRAILER - .LEFT MARGIN +5 A trailer record was expected during a READ or COMPARE (i.e., no PARTIAL qualifier was included in the command) but not found. .LEFT MARGIN -5 .SKIP 1 %HEX-W-OFFTRUNC - .LEFT MARGIN +5 The high order bits of the OFFSET were truncated during WRITE of an Intel extended address record. Intel format allows a maximum of 20 bits to specify the offset. .LEFT MARGIN -5 .SKIP 1 %HEX-W-OPENERR - .LEFT MARGIN +5 Error attempting to open the specified file. .LEFT MARGIN -5 .SKIP 1 %HEX-W-PARTINDIC - .LEFT MARGIN +5 A READ command without a PARTIAL qualifier was issued for a Mostek format file whose file header block indicated that the file was a partial file. .LEFT MARGIN -5 .SKIP 1 %HEX-W-PLUSRNGERR - .LEFT MARGIN +5 The value specified as a PLUS or MINUS parameter is out of range. .LEFT MARGIN -5 .SKIP 1 %HEX-W-READNONHEX - .LEFT MARGIN +5 An illegal non-hexadecimal character was encountered during a READ operation. .LEFT MARGIN -5 .SKIP 1 %HEX-W-READRNGERR - .LEFT MARGIN +5 An attempt was made to READ data into an address which was out of range. This could either be caused by an incorrect OFFSET or an invalid PLUS or MINUS value. .LEFT MARGIN -5 .SKIP 1 %HEX-W-READSUMERR - .LEFT MARGIN +5 An object file record was READ whose checksum is incorrect. .LEFT MARGIN -5 .SKIP 1 %HEX-W-RECFORMATERR - .LEFT MARGIN +5 An object file record was READ which was not in the currently defined format. .LEFT MARGIN -5 .SKIP 1 %HEX-W-REMBYZERO - .LEFT MARGIN +5 A REMAINDER command was issued with zero as the BY parameter. No data values in the specified range were changed. .LEFT MARGIN -5 .SKIP 1 %HEX-W-REVRNGERR - .LEFT MARGIN +5 A REVERSE command was issued which would cause an address to go out of range. No data values were exchanged. .LEFT MARGIN -5 .SKIP 1 %HEX-W-SRCDSTOVERLAP - .LEFT MARGIN +5 A COPY command was issued whose source area is overlapped by its destination area. The COPY will proceed but the data in the overlap area will be overwritten. .LEFT MARGIN -5 .SKIP 1 %HEX-W-STEPCONFLICT - .LEFT MARGIN +5 A STEP qualifier was include in a command which also include an ODD or EVEN qualifier. The two sets of qualifiers are mutually exclusive. .LEFT MARGIN -5 .SKIP 1 %HEX-W-STEPOUTOFRNG - .LEFT MARGIN +5 A STEP parameter was entered which was greater than FF. .LEFT MARGIN -5 .SKIP 1 %HEX-W-STEPZERO - .LEFT MARGIN +5 A STEP parameter of zero was entered. .LEFT MARGIN -5 .SKIP 1 %HEX-W-SUMRNGERR - .LEFT MARGIN +5 The address specified as the TO parameter in a SUM command was out of range. .LEFT MARGIN -5 .SKIP 1 %HEX-W-SYNTAX - .LEFT MARGIN +5 A syntax error was detected in the current command at or shortly after the specified keyword. .LEFT MARGIN -5 .SKIP 1 %HEX-W-UNEXPECTCRC - .LEFT MARGIN +5 The CRC value calculated by HEX does not match that input as the EXPECTING parameter. .LEFT MARGIN -5 .SKIP 1 %HEX-W-UNEXPECTSUM - .LEFT MARGIN +5 The SUM value calculated by HEX does not match that input as the EXPECTING parameter. .LEFT MARGIN -5 .SKIP 1 %HEX-W-UNEXPTRAILER - .LEFT MARGIN +5 A trailer record was encountered during a READ in which the PARTIAL qualifier had been specified. .LEFT MARGIN -5 .SKIP 1 %HEX-W-USERNGERR - .LEFT MARGIN +5 A USE parameter was entered which is out of range. USE values must be between 1 and FF. .LEFT MARGIN -5 .SKIP 1 %HEX-W-VALRNGERR - .LEFT MARGIN +5 The value specified with a BY or WITH qualifier was greater than FF. .LEFT MARGIN -5 .SKIP 1 %HEX-W-WIDTHERR - .LEFT MARGIN +5 An invalid WIDTH value was entered for the currently defined format. .LEFT MARGIN -5 .APPENDIX OBJECT FILE FORMATS .TITLE HEX FILE EDITOR .SUBTITLE Object File Formats There are three basic type of object files: .LIST .LIST ELEMENT Hexadecimal files consist of ASCII records containing hexadecimal numbers for addresses, data bytes, and other load information. They are human-readable, and acceptable as input to text editors. Intel, Motorola, and most other formats fall into this class. Their basic formats are very similar, the differences being in placement of address, data, control, and checksum information. .LIST ELEMENT PROM programmer files. These also contain hexadecimal (or octal) data, but the load address and checksum are in separate file records, instead of at the start of each individual record. .LIST ELEMENT Binary files are not human-readable, and not usually acceptable to editors (even if you could understand what you were editiing). Such files are produced by the DEC MACRO assembler and TKB task-builder, by SAL cross-assemblers with the special Sira binary object file option, and by the Whitesmiths' linker. .END LIST The records in a 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; undefined locations will be left unchanged. Any record following a trailer record is ignored. This appendix summarizes the various formats as they are used by HEX. Consult the appropriate software manuals for full details. Some formats have additional options not described here. The effects of using them is undefined -- they may be simply ignored, cause HEX to reject a file READ, or even crash it. Note that many formats do not provide for 24 or 32-bit addresses. In such cases only as many low bytes as are supported are written by HEX, and a suitable OFFSET and/or PLUS value must be given in order to READ it back. Examples are given of each format, obtained by writin out an area of memory from 1010 to 1032 set to ascending byte values, and with a program name of PROGRAM, and transfer address 1234, so a DISPLAY command would give: .LITERAL Name: PROGRAM Transfer: 1234 Address 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ------- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 1010 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 1020 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 1030 21 22 23 FF FF FF FF FF FF FF FF FF FF FF FF FF .END LITERAL .HEADER LEVEL 1 INTEL FORMAT Standard Intel hexadecimal object format is: .SKIP 1 .INDENT 10 :bbaaaattdddd ... ddcc .SKIP 1 .NO FILL where: .FILL .LEFT MARGIN +5 .LITERAL : marks the start of the record. bb is a two-digit hexadecimal number of data bytes in the record aaaa is a four-digit hexadecimal load addres of the first byte of data if tt is 00, or always 0000 if tt is non-zero. tt is a two digit number defining the record type: 00 indicates a data record, 01 indicates end of file, 02 indicates an extended address record, 03 indicates a transfer address record. dd are two-digit hexadecimal values of data bytes to be stored. cc is a two-digit record checksum -- the two's complement of the sum of all the bytes from the byte count to the last data byte, so that (aa+aa+tt+dd+dd+ ... +dd+cc) is zero. .END LITERAL .LEFT MARGIN -5 A file will consist of a number of records, terminating with one in which tt is 01 or bb is equal to zero (the latter condition is not part of the current Intel standard, but is supported by HEX for historical reasons). Extended address records (type 02) are used in 24- and 32-bit modes to specify a "segment base address" to be added to all subsequent data record addresses (aaaa's). Extended address records always contain two bytes of data giving, in high-low order, bits 4-20 of the base address, as base address/10H (bits 0-3 are always clear). In 24- and 32-bit modes, files written by HEX begin with an 02 record giving the current OFFSET/10H. Only bits 0-3 of OFFSET are then added to the address fields in subsequent data records. In 16-bit mode, no 02 record is written, and OFFSET is added in full to data record addresses. Therefore, one should not APPEND in 16-bit mode to a file previously written wiht a non-zero 24- or 32-bit offset -- use OFFSET 000000 instead. The 03 record specifies a transfer address. It contains two pairs of data bytes. The first pair gives bits 4-20 of a base address, as above, and the second pair bits 0-15 of the relative address to be added to this. HEX always set the first pair to bits 16-19 of the transfer address, with the remaining bits clear, and puts the low 16 bits of the transfer address into the second pair. There is no facility to define the program name, which is therefore unchanged when an INTEL format object record is read. Characters preceding a colon in a record are treated as a comment, and any record not containing a colon is ignored. The following example is output for the standard data in 16-bit mode: .LITERAL :201010000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20B0 :0310300021222357 :0400000300001234B3 :00000001FF .END LITERAL .HEADER LEVEL 1 MOTOROLA FORMAT Motorola format object files consist of a number of blocks in the following format: .SKIP 1 .INDENT 10 Stbbaaaadddd ... ddcc .SKIP 1 where: .LEFT MARGIN +5 .LITERAL St is two ASCII characters defining the block type: S0 denotes a file header, S1 and S2 define data blocks, and S8 and S9 define end of file blocks. bb is two hex digits giving the number of bytes (pairs of hex ASCII characters) specified, including the address, data, and checksum. aaaa if a 4 or 6-digit hex number defining the load address of the first byte, high byte first. S1 and S9 records have 4-digit addresses, S2 and S8 records have 6. There is no provision for 32-bit addresses, which are therefore trun- cated to 24 bits. dd are pairs of hex digits defining the data to be stored. cc is two hex ASCII characters defining the checksum for the block. This is the one's complement of the sum of all the bytes from the byte count to the last data byte (bb+aa+aa+ dd+dd+ ... dd), so that the 8-bit sum of everything except the St is $FF. .END LITERAL .LEFT MARGIN -5 A complete object file commences with an S0 block having a dummy address of 0000, and a data portion of 0-6 bytes, which is the first six characters of the program name, written as ASCII character values in hexadecimal. This is followed by a number of S1 or S2 records which contain the actual object code. The file terminates with an S8 or S9 record containing only the start address of the program. As for Intel, anything on a line up to the S, or after the S8/S9 trailer record, is treated as comment. Example: .LITERAL S00A000050524F4752414DDD S12310100102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20AC S106103021222353 S9031234B6 .END LITERAL .HEADER LEVEL 1 ROCKWELL FORMAT Rockwell format files consist of a number of blocks in the following format, compatible with the KIM/TIM/MDT format, also used by the Commodore 'PET' assembler: .SKIP 1 .INDENT 10 ;bbaaaadd ... ddcccc .SKIP 1 where: .LEFT MARGIN +5 .LITERAL bb is two hex digits giving the number of data bytes, dd...dd, (pairs of hex ASCII characters) in the block. aaaa is a four-digit hexadecimal number giving the load address of the first byte, high byte first. dd are two-digit hexadecimal numbers defining the data to be stored. cccc is a four-digit hexadecimal checksum for the block. This is the sum of all the bytes from the byte count to the last data byte inclusive (bb+aa+aa+dd+ ... +dd). .END LITERAL .LEFT MARGIN -5 The file ends with a block having a byte count of 00, and an "address" which is the number of blocks in the file. There is no way of giving a program name or start address. Example: .LITERAL ;2010100102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F200250 ;03103021222300A9 ;0000020002 .END LITERAL .HEADER LEVEL 1 RCA FORMAT The UT4 utility of the COSMAC evaluation kit monitor recognizes data records of the form: .SKIP 1 .INDENT 10 !Maaaaxddxddx ... ddxt .SKIP 1 and trailer records as: .SKIP 1 .INDENT 10 $P{ssss} .SKIP 1 where: .LEFT MARGIN +5 .LITERAL !M indicates a following load address. Everything before this indicator (or a $P) is ignored. aaaa is a 1-4 digit hexadecimal number giving the load address. Only the last four digits are significant. dd are two-digit hexadecimal values of the data to be stored. x represents any non-hexadecimal number separators, which are ignored. At least one such separator must appear after the aaaa address field, but they are optional between data bytes. HEX always writes single spaces. t is a line terminator, comma, semicolon, or blank, where: comma indicates that the following record contains data only, to be loaded contiguously with that on this record, and no !Maaaa address specifi- cation is required (or allowed). semicolon indicates that data on the following record is to be loaded starting at a new address given by an aaaa field (without a !M prefix) as the first item on that record. blank indicates the end of a data record. The next record must start with a full !Maaaa load ad- dress or a $P transfer address specification. ssss (if given) is the transfer address. It may be omitted, but HEX still expects a $P record as a file trailer. .END LITERAL .LEFT MARGIN -5 The following example illustrates the three types of data record, all of which are acceptable on READ. HEX only WRITES semicolon or blank terminated records, displaying the load address of each line for convenience: .LEFT MARGIN +5 .LITERAL !M1010 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E, 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E, 102E 1F 20 21 22 23 $P1234 .END LITERAL .LEFT MARGIN -5 .HEADER LEVEL 1 TEKHEX FORMAT Standard Tektronix ("TekHex") format, uset by the 8000 series emulators, is: .SKIP 1 .INDENT 10 /aaaabbhhdddddd ... ddcc .SKIP 1 where: .LEFT MARGIN +5 .LITERAL aaaa is a four-digit hexadecimal load address of the first byte of the data. bb is a two-digit hexadecimal number of data bytes in the record. hh is a two-digit checksum of the address and byte count fields. This is the sum of the values of those six hex digits, i.e., a+a+a+a+b+b dd are two-digit hexadecimal values of the data to be stored. cc is a two-digit hexadecimal checksum of the data bytes, being the sum of the values of the preceding 2*bb digits, i.e., d+d+ ... +d. .END LITERAL .LEFT MARGIN -5 A file may consist of a number of records and is terminated by a record containing no data (hence bb = 00), and an address which is the transfer address of the program (or 0000 if none), as: .LITERAL /101020040102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2002 /103003042122230C /1234000A .END LITERAL .HEADER LEVEL 1 EXTENDED TEKHEX FORMAT Extended TekHex format is used by Tektronix 8550 series emulators. The data and trailer record format is: .SKIP 1 .INDENT 10 %bbtccna...adddddd ... dd .SKIP 1 where: .LEFT MARGIN +5 .LITERAL bb is a two-digit hexadecimal number giving the number of characters in the record, excluding the starting percent (%). t is the record type: 3 is a symbol definition record (header), 6 is a data record, and 8 a trailer. cc is a two-digit checksum of all characters except itself and the %, with special character coding as shown below. na...a is an n-digit hexadecimal load address of the first byte of the data. dd are two-digit hexadecimal values of the data to be stored. .END LITERAL .LEFT MARGIN -5 The header record ("symbol record") has a somewhat different format: .SKIP 1 .INDENT 10 %bb3ccns...s0nl...lnc...c .SKIP 1 where bb and cc are as above, t=3, and: .LEFT MARGIN +5 .LITERAL ns...s is the program name. nl...l is an n-digit hexadecimal number giving the lowest address in the module. nc...c is an n-digit number giving the number of bytes in the module. .END LITERAL .LEFT MARGIN -5 HEX writes a full header record as above, but ignores the low address and count value. Tektronix emulators may write other information into "symbol records", but this is also ignored by HEX. A file starts with a header record giving the program name, followed by a number of data records, and terminated by a type 8 trailer record containing the addres defining the transfer address of the program (or 0000 if none), as: .LITERAL %163B57PROGRAM041010223 %4A61C410100102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20 %1061B41030212223 %0A82041234 .END LITERAL Checksums are computed by summing the characters in each record, assigning them non-ASCII codes: - .LITERAL Characters Value (decimal) ---------- --------------- 0-9 0-9 A-Z 10-35 $ 36 . 38 _ 39 a-z 40-65 .END LITERAL All other characters are illegal and will result in a fatal error if encountered in a READ or WRITE operation. Note: 8550 emulators seem to add C0000000 to all addresses, so an OFFSET of this value should always be set before processing extended Tekhex files. .HEADER LEVEL 1 TEXAS FILE FORMAT Texas object files, used by development systems for the TI99xx series of processors, consist of a number of entries, each of which starts with a single "tag" character which identifies the type of entry and hence the meaning of any following characters. The following record types are recognized by HEX: .LEFT MARGIN +5 .LITERAL 00000nnnnnnnn specify program name, nnnnnnnn. 1aaaa specify program transfer address, aaaa. 7ssss ssss is checksum of all ASCII chars, including 7 tag. 9aaaa specify load address, aaaa, for following B records. Bdddd specify data word. F marks end of record. : comment trailer block. .END LITERAL .LEFT MARGIN -5 Other types are defined for relocatable code, but these are not supported by HEX and will give fatal load errors. Entries of different types may be concatenated into longer file records, each ending with an F entry. The load address automatically advances by two for each B entry, unless modified by an intervening 9. Checksums are the negative of the 16-bit sum of all ASCII codes form the previous checksum of start of file up to and including the 7 checksum entry tag. (The end of record markers (F) are not included in calculating checksums.) The transfer address block may appear anywhere in the file. Hex places it at the end, followed by a trailer block, the only required component of which is the ":". HEX adds its name and revision date to the trailer block as a comment. Note that data entries always give a full word. HEX will put a null padding byte at the end of the output if necessary. Formally, all 9 entries should specify even addresses, and some development systems will round down an odd one. HEX does not do this, however, so that the addresses are correct for high-byte PROM files. Example: .LITERAL 00000PROGRAM 7FCA1F 91010B0102B0304B0506B0708B090AB0B0CB0D0EB0F10B1112B1314B1516B1718B191A7F0C9F 9102AB1B1CB1D1EB1F20B2122B23007F93BF 112347FECEF : HEX Version 11-APR-1986 .END LITERAL .HEADER LEVEL 1 MOSTEK FILE FORMAT MOSTEK files have four types of record, with the following general format: .SKIP 1 .INDENT 10 ttrrrrxx...xxcc .SKIP 1 where: .LEFT MARGIN +5 .LITERAL tt is the block type: F0 is a header record, F2 is an "enumerated" data record, F4 is an "iterated" data record, and F6 is a trailer record. rrrr is the number of bytes in the record body plus the checksum. xx...xx is the record body, whose format depends on the record type. cc is the negative of the sum of all bytes in the block from tt up to the last byte of the record body, so that the sum of all bytes in the block is 00. .END LITERAL .LEFT MARGIN -5 Module header blocks take the form: .SKIP 1 .INDENT 10 F0rrrrssnn...nnaappmmllllhhhhcc .SKIP 1 where, in addtion to above: .LEFT MARGIN +5 .LITERAL ss is the length of the program name. This can be up to 100 (decimal) characters, but HEX only reads or writes a maximum of 8. nn...nn is the hexadecimally encoded program name. If there is none, ss is 00, and nn...nn is omitted. aa is the address size, according to the current mode as determined by the last OFFSET or ADDRESSING MODE command. Only 16- and 32-bit addressing is supported; 24-bit is treated as 32. This field must therefore be 10 or 20. Any other value will give an error in READ. pp is a code identifying the processor: 00 = unknown, 01 = 3870, 02 = 8080, 03 = Z80, 05 = 68000. HEX ignores this field on READ, and always sets it to 00 (unknown) on WRITE. mm is the module type: 00 is a non-main module, and 02 is a main module. 01 is added to the code if there is a transfer address. READ sets or clears the PARTIAL flag according to the transfer address bit. WRITE always sets mm to 02 or 03. llll is the low 16-bits of the lowest address in the module. This is ignored by READ and set to FROM by WRITE. hhhh is the low 16-bits of the highest address. This is ignored by READ and set to THRU by WRITE. .END LITERAL .LEFT MARGIN -5 Enumerated data records have format: .SKIP 1 .INDENT 10 F2rrrraaaadd...ddcc .SKIP 1 where .LEFT MARGIN +5 .LITERAL aaaa is a 4 or 8-digit hexadecimal load address for the first byte in the record. dd...dd are the data bytes to be loaded sequentially from this address. .END LITERAL .LEFT MARGIN -5 Iterated data records have format: .SKIP 1 .INDENT 10 F4rrrraaaannnnbbyy...yycc .SKIP 1 where .LEFT MARGIN +5 .LITERAL aaaa is again a 4 or 8-digit load address for the first byte. nnnn is a replication factor giving the number of times the current portion of the block is to be repeated. bb is a block count, zero is this is the final inner block, non-zero if there are further nested ones. yy...yy is an inner nested repeat of another block containing fields nnnnbbyy...yy if bb is non-zero, otherwise it takes the form wwdd...dd, where ww is a byte count of dd...dd bytes to be inserted nnnn times. .END LITERAL .LEFT MARGIN -5 Nesting to 15 levels is allowed, but HEX does not check whether this is exceeded. Clearly, this nested structure can be extremely complicated. READ should be able to process any structure. WRITE only produces the simple case of a single level of identical data bytes when all of the current WIDTH bytes are the same (and WIDTH > 5). Note that the checksum for an iterated record is the sum of the bytes in the record, not all the repeated data stored in memory. The trailer block has the format: .INDENT 10 .SKIP 1 F6rrrraaaacc .SKIP 1 where: .LEFT MARGIN +5 .LITERAL aaaa is the transfer address. This may be omitted if there isn't one, in which case rrrr is 0001. .END LITERAL .LEFT MARGIN -5 The following example is the standard data, extended to address 104F to show an iterated record of all FF's: .LEFT MARGIN +5 .LITERAL F000110850524F4752414D201000031010106F0D F2002310100102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20BB F200231030212223FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF62 F40008105000200001FF84 F600031234C1 .END LITERAL .LEFT MARGIN -5 .HEADER LEVEL 1 TCI FORMAT This format consists of records of the form: .INDENT 10 .SKIP 1 @aaaadddd ... dd .SKIP 1 where: .LEFT MARGIN +5 .LITERAL @ marks the start of the record -- everything before it is ignored. aaaa is a four-digit hexadecimal load address the first byte of the data. dd are pairs of hex digits defining the data bytes. .END LITERAL .LEFT MARGIN -5 There is no byte count field (everything in the file record after aaaa is taken as data), no trailer record, and no way to write program name or start address. Example: .LEFT MARGIN +5 .LITERAL @10100102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20 @1030212223 .END LITERAL .LEFT MARGIN -5 .HEADER LEVEL 1 FAIRCHILD FORMAT This is the format used by the "Fairbug" monitor. Three types of record are used: .SKIP 1 .NO FILL .LEFT MARGIN +10 Saaaa Xdddd ... ddc * .SKIP 1 .LEFT MARGIN -10 .FILL where: .LEFT MARGIN +5 .LITERAL aaaa is a four-digit hexadecimal load address of the first data byte, high byte first. dd are two-digit hexadecimal values of the data to be stored. c is a hexadecimal digit giving the checksum for record. This is the sum of all the data nibbles, d+d+d+ ... d, ignoring overflow above 4 bits. .END LITERAL .LEFT MARGIN -5 The file ends with a record starting with an asterisk. There is no way to give a program name or transfer address. Example: .LEFT MARGIN +5 .LITERAL S1010 X0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F202 X212223C * .END LITERAL .LEFT MARGIN -5