 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 SEARCH SUM TRANSFER WRITE
	COMPLEMENT NEGATE

	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.

	The offset value must be even (word boundary).

	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.

	READ has two optional parameters which may appear immediately preceding
	the keyword "FILE".  If both parameters are given, they must be given 
	in the order shown here:

	PLUS cccc	specifies that the 4-digit hex number ccc should be
	   or		added to/subtracted from the address in the hex file
	MINUS cccc	being read.

	PARTIAL		indicates that the file being read does not contain
			a trailer record.


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.

	COMPARE has two optional parameters which may appear immediately 
	preceding the keyword "FILE".  If both parameters are given, they must be given 
	be given in the order shown here:

	PLUS cccc	specifies that the 4-digit hex number ccc should be
	   or		added to/subtracted from the address in the hex file
	MINUS cccc	being compared.

	PARTIAL		indicates that the file being read does not contain
			a trailer record.


2 NEGATE

	HEX>NEGATE FROM aaaa THRU bbbb

	Each byte of virtual memory from aaaa thru bbbb is arithmetically
	complemented (2's complement).
 
2 COPY

		 [ EVEN ]
	HEX>COPY [  ODD ] 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.

	COPY has optional parameters EVEN or ODD (mutually exclusive) which
	allow the user to copy only those bytes from the FROM-THRU range that
	are even/odd. This is particularly useful in setting up files to
	program 8-bit proms for a 16-bit data bus. For example:

	COPY EVEN FROM 4000 THRU 5FFF TO 0000

	will copy:	4000 --> 0000
			4002 --> 0001
			.
			.
			5FFE --> 0FFF
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.
 
	If %XX is specified as a pseudo-register, the high byte of the CRC
	will be put into %XX, and the low byte will be put into %XX+1.
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 COMPLEMENT

	HEX>COMPLEMENT FROM aaaa THRU bbbb

	Each byte of virtual memory from aaaa thru bbbb is logically
	complemented (1's complement).
 
2 SEARCH

	HEX> SEARCH FROM aaaa THRU bbbb FOR xx
		OR
	HEX> SEARCH FROM aaaa THRU 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 [TO cccc]

	Calculates and displays on the terminal a 16-bit byte-wise summation
	of locations aaaa thru bbbb.
 
	If a TO address is specified,the result is stored 
	there in low-high order.Whether or not a TO address is specified,the
	sum value is displayed on the terminal.
 
	If %XX is specified as a pseudo-register, the low byte of the SUM
	will be put into %XX, and the high byte will be put into %XX+1.
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 aaa thru bbb.
	For a detailed description of INTEL hex format, see Appendix a.

	The current transfer address will be placed in the trailer record.

	WRITE has three optional parameters which may appear between
	the thru address value and the FILE keyword.  If more
	than one of these optional parameters are used, they MUST appear
	in the order described here:

	PLUS cccc	specifies that, although the data comes from
   	or		virtual memory locations aaaa-bbbb, the address
	MINUS cccc	in the file should be aaaa-bbbb or minus cccc.

	WIDTH dd	allows the user to specify the width(in hexidecimal)
			of the INTEL hex file.  The allowable
			range is 01-20.  Default is 20.

	PARTIAL		specifies that no trailer record should be

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 originate from the terminal
	or an indirect command file. A command line which begins with a semi-
	colon is treated as a comment. If executing from a command file, the
	comment is not echoed to the screen. A command line beginning with an
	asterisk "*" is still treated as a comment, but is echoed to the screen
	if executing from a command file.
	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.

	The offset value must be even.

	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 %00
	CRC FROM 0800 THRU 0FFF TO %02
	INIT
	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 %04
	CRC FROM 0800 THRU 0FFF TO %06
	INIT
	OFFSET 8000
	READ FROM B800 THRU BFFF FILE MTI.HEX
	READ FROM B900 THRU B9FF FILE COM.HEX
	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.HEX
	DISPLAY FROM B800 THRU BFFF FILE CPROM.LST

	The commands are self-documenting.

	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.

	Invalid width parameter

	The width parameter must be a two-digit hexidecimal number 
	from 01 thru 20.


	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.  In some cases, the range over which the sum is to 
	be computed includes addresses not valid under the current offset.
	An "address out of range error will be issued, and the sum will be
	shown as "????".


	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 must be even

	The value given for offset must be even (word-aligned).


	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.

	Trailer record ignored

	During a READ or COMPARE of a file described as PARTIAL, a trailer
	record was encountered and ignored.  the READ/COMPARE operation 
	terminates at this point.

	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.
