SECTION 8

USER IMPLEMENTED CODE FUNCTIONS

8-1 OVERVIEW

The Programmer is already familiar with the environment of his own target system. He knows there is a 64K byte address space called the Memory Address Space and within this address space are various blocks of ROM, RAM, and, in some systems, I/O control or data registers. In addition, there is a 256-byte I/O address space which, in most systems, contains the addresses of I/O devices.

The EM-180 also has an internal address space with its own ROM, RAM, and I/O. The EM-180 control program and Built-In Code Functions reside in this address space. Any EPROM plugged into the Diagnostic PROM Socket also appears in this internal address space. It is thus possible for User Code Functions to access all Diagnostic Emulator facilities and to function exactly as if they were factory programmed.

However, the Code Function programs executing within the internal address space do not have direct access to the user's system target address space. If it is necessary for a Code Function to read or write to the external target system, it must do so in cooperation with the Diagnostic Emulator hardware circuits. Consequently, a rigidly defined routine must be executed to perform read or write operations to the target system. The Built-In Code Functions, as well as the EXAMINE and STORE routines, use EM-180 control program subroutines, and the user may also use these same subroutines to read and write to the target program address space.

8-2 INTERNAL ENVIRONMENT

Figure 8-2.1. EM-180 Internal Memory Map

0000
. . .	CONTROL ROM 1
07FF	(U103)
0800	2716 or 2732
. . .
0FFF
1000
. . .	CONTROL ROM 2
17FF	(U104)
1800	2732
. . .
1FFF
2000
. . .	FRONT PANEL
27FF	DIAGNOSTIC EPROM
2800	2716 or 2732
. . .
2FFF
3000	SCRATCHPAD RAM
30FF	(See Fig. 8-2.2)

8-2.1 ROM

8-2.2 FRONT PANEL EPROM SOCKET

8-2.3 SCRATCHPAD RAM

The Scratchpad RAM also contains the area where the processor registers are saved each time the emulation processor pauses; also, the saved register values are restored each time the emulation processor begins to run. User implemented programs may obtain these register values or even alter them if desired. The user should carefully avoid altering any of the data contained in the firmware stack area or firmware scratchpad locations to avoid crashing the control program.

NOTE: EM-180's with serial #1801135 or higher have an additional 768 Bytes of Scratchpad RAM residing from 3100₁₆ to 33FF₁₆. This additional RAM is available for user written code function programs.

Figure 8-2.2. Map of Internal Scratchpad RAM

ADDRESS

3000	SCRAM
	. . .	For use by user written code function programs.		(96 Bytes) (See Sec. 8-2.3.)
305F
3060
	. . .	Firmware scratchpad locations used by emulator control program.		(83 Bytes)
30B2
30B3
	. . .	Emulator Firmware stack area.		(45 Bytes)
30DF
30E0	RPC	16	Target Register PC	(2 Bytes)
30E2	R	16	Target Register SP	(2 Bytes)
30E4	RIX	16	Target Index Register X	(2 Bytes)
30E6	RIY	16	Target Index Register Y	(2 Bytes)
30E8	RPHL	16	Target Register HL'	(2 Bytes)
30EA	RPDE	16	Target Register DE'	(2 Bytes)
30EC	RPBC	16	Target Register BC'	(2 Bytes)
30EE	RPAF	16	Target Register AF'	(2 Bytes)
30F0	RHL	16	Target Register HL	(2 Bytes)
30F2	RDE	16	Target Register DE	(2 Bytes)
30F4	RBC	16	Target Register BC	(2 Bytes)
30F6	RAF	16	Target Register AF	(2 Bytes)
30F8	RBEG	16	Begin Pointer	(2 Bytes)
30FA	REND	16	End Pointer	(2 Bytes)
30FC	RADR	16	Current Address of Test	(2 Bytes)
30FE	RDTA	8	Current Data	(1 Byte)
30FF	FLAGS	8	Flag Display Data	(1 Byte)
				------------
			TOTAL:	256 Bytes

8-2.4 I/O DEVICES

KEYBOARD: The state of the Keyboard Keyswitches may be read by the processor at a series of eight addresses from 3480₁₆ through 3487₁₆. Four Keyswitches may be read at each of the input addresses as shown in Figure 8-2.3. A key depression causes the corresponding bit to go low as seen in the input data. For example, if Key 9 is depressed, bit 1 of location 3482₁₆ will be low. Bits 4, 5, 6 and 7 of all eight of the input ports see the same data; bit 4 in all locations will be low if a jumper on the Keyboard called the Option A jumper is installed. Bit 5 in all locations senses the state of pin 61 on the keyboard card connector; this pin is left open in the EM-180. Bit 6 will be low if the most recent system reset was caused by the power-on-reset circuitry; bit 6 will be high if the most recent system reset was caused by the RESET Key or a reset command from the target system. Bit 7 will be high if any of the following keys are depressed: RUN, RUN-BKPT or STEP.

The user who decides to write software to directly read the Keyboard must be aware that there is no key debouncing or other processing of the key closure done by the hardware. Consequently, it is necessary to provide the keystroke debouncing, repeating key features or other special processing in the software that scans the Keyboard. There is a Keyboard scan routine already in the EM-180 which may be accessed by the user that provides the most commonly needed features. See Section 8-6.

SERIAL INPUT/OUTPUT PORT: The EM-180 Diagnostic Emulator contains circuitry that implements a full-duples (two-way) serial Input/Output port that conforms to RS-232C requirements. The baud-rate, parity and character length of the data transmitted and received is set up by hardware switches. (See Sections 9-2 and 9-3). The nature and format of data transmitted is under the control of software. The software is able to send data to the serial output circuits, read data from the serial input circuits and test the setatus of the serial port circuitry via three ports as shown in Figure 8-2.4 Data is transferred to and from the serial port by means of a Universal Asynchronous Receiver-Transmitter (UART).

Data to be output through the serial port is written to the UART data write address. The data enters the UART transmit buffer register, and then enters the transmit shift register where it is shifted out in serial form bit by bit. New data may be written to the transmit buffer register as soon as the previous data has entered the transmit shift register and before it has completed the process of shifting out.

Figure 8-2.3. Keyboard Input Locations

Bit read is '0' if the key is depressed; otherwise '1'.

	7	6	5	4	3	2	1	0
348016					3	2	1	0
348116					7	6	5	4
348216					B	A	9	8
348316					F	E	D	C
348416					INC	DEC	EXAM	STORE
348516					LOAD DATA	TRACE	I/O ADDR	MEM ADDR
348616					REG	BKPT B	BKPT A	CODE
348716					x	x	x	x

'0' if Option A jumper installed.
'0' if pin 61 card edge is low
'0' if Power-On-Reset (cold start)
'1' if Keyswitch Reset (warm start)
'1' if RUN, RUN-BKPT or STEP keys are depressed

Figure 8-2.4 Serial Port Data and Status Locations

UART DATA WRITE	340016
UART DATA READ	340016
UART STATUS READ	347516

Data Available
Transmit Buffer Empty
End of Character
75 Hz square wave
Framing Error
Overrun Error
1200 Hz square wave
¬Clear-to-Send

The UART Status Register (Figure 8-2.4) contains two bits which inform the software of the status of the transmitter registers as follows:

Bit 1, Transmit Buffer Empty, will be read as '1' when the transmit buffer register may be loaded with another character. A '0' means that the transmit data register contains data that has not yet been moved into the transmit shift register.

Bit 2, End of Character, will go to '1' at the time that a character has shifted out of the transmit shift register. If there is another character waiting in the transmit buffer register, then bit 2 will immediately go to '0' as the new character enters the shift register to be transmitted.

Data received by the EM-180 through the serial port is entered into the UART receiver shift register. When an entire character has been received, it is transferred to the receiver holding register and is then available to the software by reading the data at the UART Data Read address. Several status bits in the UART Status Register (Figure 8-2.4) give information bbout the received data as follows:

Bit 0, Data Available, goes to '1' when an entire character has been received and transferred to the receiver holding register. When the software reads the UART Data Read location, this bit is cleared to '0'.

Bit 4, Framing Error, goes to '1' if the received character has no stop bit at the expected location. This usually means that the transmitting device is sending characters of different length or baud rate than the EM-180 is set up to receive. Noise may also cause this error.

Bit 5, Overrun Error, goes to '1' if a previously received character in the receiver holding register is not read by the CPU before another character is received and transferred into the holding register.

The clear-to-send input (Auxiliary Connector, Pin 5) is visible to the software as Bit 7 of the UART status register. This bit is '0' if clear-to-send is true (high); if clear-to-send is low or disconnected, this bit is '1'. (Note, however, that this bit may be forced to the '0' state by setting Option Switch 3 closed. See Section 9-2.)

Two other bits share the UART Status Register, but are not directly involved in the communications functions.

Bit 3, 75 Hz, is a 75Hz square wave that is derived from the bit-rate-generator crystal oscillator. This bit is seen by the software as alternate '1' and '0' with a 13.33 mSEC full cycle.

Bit 6, 1200 Hz, is a 1200 Hz square wave that is derived from the bit-rate-generator crystal oscillator.

One additional output port is associated with the communications interface. This port controls the Request-to-Send (RTS) signal that is output on Pin 4 of the Auxiliary Connector.

7	6	5	4	3	2	1	0
RTS	X	X	X	X	X	X	X	347516

The RTS output port is located at address 3475₁₆. Writing a '1' to Bit 5 of the port will set the RTS signal to its negative (marking, or OFF) state; writing a '0' sets the RTS signal positive (spacing or ON). All of the remaining bits of the port are "don't care" and have no effect.

HEXADECIMAL DISPLAYS AND TRACE MEMORY: The EM-180 Trace Memory is a 252-word by 32-bit memory whose primary function is to record each bus cycle that occurs to the target system. At any given time, a single word of the Trace Memory is selected by an 8-bit register called the 'XADDR' (trace index address) register. If, for example, the XADDR register contains a 43, then the next bus cycle that occurs will be written into location 43 of the Trace Memory. Immediately after the data is written, the XADDR register is incremented (by hardware) so that the current Trace Memory address becomes 44. If the emulation processor were executing a target program, each bus cycle is written into the Trace Memory and XADDR is incremented for the next cycle. When XADDR reaches its maximum value FF₁₆ and is again incremented, it overflows to 00₁₆ so that the first location of the memory effectively follows the last location. Thus the Trace Memory may be viewed as a ring memory in which each additional bus cycle may be entered in the next position around the ring. Once the Trace Memory is full, each additional bus cycle simply overwrites the oldest bus cycle in the memory.

The Address and Data hexadecimal displays and the eight discrete Machine Cycle indicatiors are wired directly to the Trace Memory circuitry so that the current Trace Memory word (the word designated by the XADDR register) is always displayed unless the displays are explicitly blanked.

When the EM-180 is in the PAUSE mode, the internal control program has access to the Trace Memory and the displays by means of a set of five ports. See Figure 8-2.5. The five ports are as follows:

XADDR (360016)	This port gives access to the Trace Index Address register. The control program may read this location to obtain the current value of the XADDR register, and may store new values in the register. Storing a new value in XADDR will change the current trace word that is accessed and displayed on the EM-180 display panel.
TDATA (364016)	This port gives access to the eight-bit wide portion of the current Trace Memory word that records the data bus signals of each machine cycle. The control program may read this locaiton to obtain the data portion of the current trace word, or may store new data to the data portion of the trace word.
TADDL (364116)	This port gives access to the eight-bit portion of the current trace word that records the low order eight bits of the address bus of each machine cycle. The control program may read or write this location.
TADDH (364216)	This port gives access to the eight-bit portion of the current trace word that records the high order eight-bits of the address bus. The control program may read or write this location.
TCNTL (364316)	This port gives access to the eight-bit portion of the current trace word that records the control bits of each machine cycle. The control program may read or write this location. The control bits are arranged in the port as shown below: 7 6 5 4 3 2 1 0 TCNTL 364316 WR RD IACK IORQ EXT BKPT M1* M1

Any time that the control program writes new data into the Trace Memory, the data stored will immediately be seen on the appropriate displays.

Figure 8-2.5. Trace Memory Format

3641₁₆ 3642₁₆ 3640₁₆ LOW HI 3643₁₆ DATA ADDR ADDR CONTROL 00 01 02 CURRENT TRACE WORD XADDR 3600₁₆

BF

TRACE INDEX ADDRESS TRACE MEMORY 252 words by 32 bits

3600₁₆ XADDR

3640₁₆ TDATA

3641₁₆ TADDL TRACE MEMORY ACCESS PORTS

3642₁₆ TADDH

3643₁₆ TCNTL

SPEAKER: The EM-180 incorporates a very small dynamic speaker that is located on the Keyboard printed circuit board. A port is provided to control the current to the speaker to generate tones or other sounds under software control. It is necessary for the software to generate the actual waveform to be output by the speaker; there is no tone generation hardware in the EM-180. The speaker output port is diagrammed below:

7	6	5	4	3	2	1	0
SPKR	X	X	X	X	X	X	X	346B16

Writing a '1' to Bit 7 switches DC current to the speaker ON; writing '0' to Bit 7 switches the current OFF. Bits 0 through 6 of the port are "don't care" bits and have no effect.

HARDWARE CONTROLS: There are a few additional output ports in the EM-180 internal address space that are used for such functions as initiating the Binary Address mode, entering the "introspection" mode and other hardware features. Details of these ports are not contained in this manual.

BREAKPOINT COMPARATORS: A series of output ports is used to set up the Breakpoint Comparator address values and to control the desired operating mode. These ports are detailed below:

BKPTAL	344716	Breakpoint A Low Order Address
BKPTAH	344816	Breakpoint A High Order Address
BKPTBL	345716	Breakpoint B Low Order Address
BKPTBH	345816	Breakpoint B High Order Address
TRIGA	346016	Trigger A
IOA	346116	I/O A
RDA	346216	Read A
WRA	346316	Write A
TRIGB	346416	Trigger B
IOB	346516	I/O B
RDB	346616	Read B
WRB	346716	Write B
RANGE	346816	Range Enable
INLEXL	346916	Inclusive/Exclusive Select
ATHENB	346A16	A-Then-B Enable

The ports BKPTAL and BKPTAH are used to set up the A Breakpoint address. The software should store the appropriate low and high order address bits to these ports. In the case of an I/O address which has only eight bits, the low order breakpoint address should be loaded; the high order breakpoint address port will have no effect.

The ports BKPTBL and BKPTBH are used to set up the B Breakpoint address in a manner analogous to that described above.

Two ports, TRIGA and TRIGB, are used to output to the BKPT A and BKPT B output pins of the auxiliary connector (pins 12 and 13; see Figure 9-1.1). Storing a '1' to the bit 7 position of the ports results in a high level at the corresponding output pin. To generate an output pulse the software must store a '1' followed by a '0' to the bit 7 position of the port. ZBit positions 0-6 of the ports have no effect on the system. Inclusion of these ports in the EM-180 system enables user programmed Code Functions to output trigger signals to external equipment such as oscilloscopes or signature analyzers.

Ports IOA and IOB are used to configure the breakpoint comparators to respond to either memory cycles or I/O cycles. Storing a '1' to the bit 7 position of either port will cause the associated breakpoint comparator to respond to I/O cycles with matching 8-bit low order address values. Storing a '0' to the bit 7 position of either port iwll cause hte associated breakpoint comparator to respond to memory cycles with matching 16-bit address values. Bits 0 through 6 of these ports have no effect.

Ports RDA and RDB are used to enable the breakpoint comparators to respond to read cycles (either memory read cycles or I/O reazd cycles). The comparators will respond to read cycles if a '1' is stored to bit position 7 of the associated port.

Ports WRA and WRB are used to enable the breakpoint comparators to respond to write cycles (either memory write cycles or I/O write cycles) by storing a '1' to bit position 7 of the relevant port.

Notice that if '1' bits are stored to both the RDA and WRA ports, the A breakpoint comparator will respond to both read and write cycles. If a '0' is stored to both ports, the comparator will not respond to any cycles and is thus disabled. The B breakpoint comparator may be controlled in a similar manner.

Three ports, RANGE, INLEXL and ATHENB are used to configure the breakpoint circuitry for several special operating modes (see Section 4-1.4). Any address in the range from A to B may be detected by writing a '1' to bit 7 of the INLEXL port. In order to include both endpoints of the range (address = A and address = B), it is recommended that both the A and B comparators also be enabled for read and write cycles.

With a '1' stored to the INLEXL port, the inclusive range (everything from A to B) is detected. With a '0' stored to the INLEXL port, the exclusive range (every address outside the range of A to B) is detected. Again, it is required that the A and B comparators also be set up to detect read and write cycles to ensure that both end points are included in the range.

The ATHENB port is used to set up sequential operation of the comparators so that a breakpoint stop signal is generated only when the B address is encountered after the A address has been previously been encountered. To set up this mode, store a '1' to the bit 7 position of the ATHENB port. Also, make sure that the RANGE circuitry is disabled ('0' to RANGE port).

8-3 ENTRY TO USER CODE FUNCTIONS

Key Sequence	Transfer Address
CODE 0	200016
CODE 1	200316
CODE 2	200616
CODE 3	200916
CODE 4	200C16
CODE 5	200F16
CODE 6	201216
CODE 7	201516
CODE 8	201816
CODE 9	201B16

Thus, each of the key sequences has associated with it an entry address in the address space assigned to the Diagnostic Prom socket. It is the responsibility of the user to properly code the EPROM so that the desired actions occur for each entry address. It is necessary that the first instruction of every Code Function be a jump instruction (op-code C3₁₆) because the control software exampines the Diagnostic Prom for the presence of this data before transferring control to it. See the examples given in Section 8-8.

8-4 INTROSPECTION MODE

8-4.1 CODE F

CODE F

After entering the CODE F mode, the user may examine or alter the internal memory space, step or run programs in the internal memory space, and review the contents of the trace memory after program execution. Breakpoints may also be used to halt program execution at appropriate internal addresses. The RESET key returns the EM-180 to normal operation.

8-5 GETTING TO AND FROM THE TARGET SYSTEM

1. Read from or write to a location in the target address space.

2. Read from or write to an I/O port address in the target address space.

3. Go to and begin executing a program residing in the target address space.

4. Return from running a program in the target address space to a program (user code function routine) in the internal address space.

The following sections give detailed information on these functions.

8-5.1 EXAMINE AND STORE

STM	Store the data contained in the accumulator to the target address specified in register pair HL.
EXM	Load the accumulator from the target address specified in the register pair HL.
STIO	Store the data contained in the accumulator to the target I/O port specified by register C.
EXIO	Load the accumulator from the target I/O port specified by register C.

The entry addresses of these subroutines (and other useful subroutines) are give in Section 8-6, User Accessible Subroutines.

The four subroutines shown above operate by performing a read or a write operation to the specified address after commanding the EM-180 hardware to make the target address space accessible during the transfer interval. The machine code listing of the EXM subroutine is shown below.

;
;Subroutine to read data from the target address
;specified by HL. Data is returned in A. The
;target read cycle is recorded in the trace memory.
EXM	PUSH BC
	LD A, 0E0H	;Delay value
	LD (DELAY),A	;Command to hardware
	LD B, (HL)	;Read from target
;
;The data read during the target memory read
;cycle above is automatically recorded in the
;trace memory. The trace memory bookkeeping
;values must be updated.
	LD A, (XADDR)	;Get trace index
	LD (XBASE), A	;Save
	DEC A
	LD (TRACE), A
;
;Put data in place and return to caller.
	LD A,B
	POP BC
	RET

8-5.2 PAUSE to RUN

The best way for the user to transfer control to a target system program is to use the existing EM-180 internal routine. The following steps are suggested:

1. Set up the user register save locations (addresses 30E0₁₆ to 30FF₁₆ in the scratchpad RAM) as desired. In particular, be sure to set the target program counter (RPC) location to the correct starting address. Other registers may be used, if desired, as a means of passing parameters to the target program.

2. If the target program needs parameters or data from the internal program, then transfer the data to the target RAM using the STORE subroutine as appropriate.

3. Perform the transfer of control to the target program by jumping to the RUN routine at address 00A5₁₆.

The RUN routine will load the processor registers, do the required coordination of the EM-180 hardware, and start the target program running with the desired register values initialized.

8-5.3 RUN to PAUSE

1. Reset the system.

2. Press the STEP key.

3. Cause a breakpoint to occur, either with one of the breakpoint comparators or by means of the external breakpoint input connection.

The first two methods are commonly used during manual operation; the third method may be used during manual operation or a sort of automatic operation in which it is desired that a Code Function set up the conditions to enable a target program to get back to the internal environment when it so desires.

The following steps are suggested as a method that will allow a program executing in the target system address space to re-enter the internal address space:

1. A Code Function program sets up one of the breakpoint comparators to monitor a pre-arranged address in the target memory space.

2. The Code Function program sets up the re-entry jump address so that when the pre-arranged address is encountered and the breakpoint occurs, control will be given back to the Code Function program instead of the Keyboard Scan routine. See Section 8-5.4, below.

3. An 80₁₆ must be stored to location 3477₁₆ to arm the breakpoint system.

4. The Code Function program gives control to the target system program which then begins running.

5. When the target system program is ready to return control to the Code Function program, it accesses the pre-arranged address and causes the breakpoint to occur. After the EM-180 software has saved the processor registers, it will jump to the address specified in Step 2 (above) and the Code Function program may proceed.

8-5.4 RE-ENTRY JUMP

In normal operatoin, the EM-180 executes an internal RUN to PAUSE routine each time the target program is halted. This routine first saves the processor registers in the scratchpad RAM save area, sets up the display to show the correct data, and finally goes to the keyboard input routine to determine the next action required. Before going to the keyboard routine, however, the RUN to PAUSE routine examines location 30A0₁₆ to see if it contains a jump instruction op-code (C3₁₆). If it does, the EM-180 will regard the jump instruction as the first instruction of a user-supplied subroutine, and will call the subroutine. (The EM-180 calls the address of the jump instruction which then jumps to the main body of the subroutine.)

The user-supplied subroutine will usually be located in the front panel EPROM, but may also be located in the user portion of the internal scratchpad RAM as the following example illustrates.

The following small program may be entered from the keyboard of the EM-180. It causes the EM-180 to beep each time it transfers from RUN to PAUSE. Enter the program with the following steps:

1. Reset the EM-180, then execute CODE F to place the emulator in "introspection" mode.

2. Enter the jump instruction:

at 30A0₁₆ enter C3₁₆

at 30A1₁₆ enter 00₁₆

at 30A2₁₆ enter 30₁₆.

These three bytes constitute a jump instruction to location 3000₁₆ in the internal address space. Location 3000₁₆ is the first location of the user portion of the scratchpad RAM.

3. At memory address 3000₁₆, enter the following four-byte program:

at 3000₁₆ enter CD₁₆

at 3001₁₆ enter D5₁₆.

at 3002₁₆ enter 00₁₆

at 3003₁₆ enter C9₁₆.

4. Reset the emulator to exit the "introspection" mode and proceed to operate the emulator. Note that each time the emulator transfers from RUN to PAUSE, the beeper will sound.

In most practical cases, the user subroutine will be located in the front panel EPROM instead of RAM as was done in this example. Also, the jump instruction may be easily written into addresses 30A0 through 30A2 by a Code Function program also residing in the EPROM. Executing the Code Function will enable the user subroutine and a second Code Function could be written to disable the subroutine by changing the jump instruction op-code to 00₁₆ (or any other code except C3₁₆).

8-6 USER ACCESSIBLE SUBROUTINES

Table 8-6.1. User Accessible Subroutines

ADDRESS	NAME	DESCRIPTION
006016	STM	Store the data contained in the accumulator to the target address specified in register pair HL. (Flags, register F are altered.)
006316	EXM	Load the accumulator from the target address specified in register pair HL. (Flags and accumulator altered.)
006616	—	(Not Used)
006916	CODEFN	Execute the built-in Code Function designated by the contents of the accumulator. For example, if the accumulator is loaded with A816, and this subroutine called, then the EM-180 wil execute Code Function A8; if the Code Function completes successfully, this subroutine will return to the calling program.
006C16	STIO	Store the data contained in the accumulator to the target I/O port specified by register C. (Flags may be altered.)
006F16	EXIO	Load the accumulator from the target I/O port specified by register C. (Flags and accumulator altered.)
007216	LWLMIT	Compares HL to the BEGIN address; the subroutine returns with CY = 1 if HL = BEGIN. (Registers A and F may be altered.)
007516	HILMIT	Compares HL to the END address; the subroutine returns with CY = 1 if HL = END. (Registers A and F may be altered.)
007816	SIA	ASCII Serial Input. Serial data entered at the serial port is returned in the accumulator. Bit seven is always zero. Registers A and F may be altered. When this routine is called, the RTS line (request-to-send) automatically goes high. The RTS line goes low again whenever the XECUTE routine is entered.
007B16	SIB	Binary Serial Input. Serial data entered at the serial port is returned in the accumulator. All eight bits are returned to the user without alteration. Registers A and F may be altered. When this routine is called, the RTS line (request-to-send) automatically goes high. The RTS line goes low again whenever the XECUTE routine is entered.

ADDRESS	NAME	DESCRIPTION
007E16	RHB	Read-Hex-Byte. This subroutine obtains two ASCII characters from the serial port. It checks to see if the characters represent valid hexadecimal digits. If they are, they are then converted to an eight-bit binary number and the subroutine returns to the calling program with this result in the accumulator. If any characters received that are not valid hexadecimal characters, an error code (EC 11) is displayed and the Diagnostic Emulator must be reset to proceed. This subroutine alters the accumulator, flags, and D register. The D register is used to accumulatre a sum check of the data received. (All the eight-bit binary values are added into register D, with overflows ignored.)
008116	CNVHEX	Convert ASCII character to binary value. This subroutine expects an ASCII character in the accumulator that represents one of the digits, 0, 1, 2, . . . , 9 or one of the letters A, B, C, D, E, F. The character is converted into a numeric value corresponding to the ASCII-hex character in the accumulator. The routine returns with the value in the accumulator. If the ASCII character originally in the accumulator does not represent one of the hexadecimal digits, an error code will be displayed and the EM-180 must be reset to proceed.
008416	—	(Not Used)
008716	CRLF	Outputs a line ending sequence to the RS-232C port which consists of a carriage return (0D16) line feed (0A16), and two null characters (0016).
008A16	TAB	This subroutine outputs ASCII space characters (2016) until the total number of printable characters output since the last carriage return character (0D16) is equal to the number specified in the byte following the call to this routine. This routine is used to format output displays to CRT or printer terminals. No registers are altered.
008D16	NIB	This subroutine converts the low-order 4 bits of the accumulator to one ASCII character representing the value in hexadecimal and outputs the character to the serial port.
009016	BYTE1	Converts the contents of the accumulator to two ASCII characters representing the value in hexadecimal, then outputs these characters to the RS-232 port. No registers are altered.

ADDRESS	NAME	DESCRIPTION
009316	HEXOUT	This subroutine is the same as the BYTE routine except that the contents of the accumulator is added to the D register for computing a checksum.
009616	SO50NL	Output 50 ASCII null characters (0016) to the serial interface. This routine is useful to produce blank tape leader on a paper tape punch interfaced to the EM-180.
009916	ERROR1	Subroutine to report an error on the display. This routine shows the characters "EC" on the address display (meaning Error Code), displays the contents of the accumulator in the data display, and emits three beeps. The routine then waits for the user to depress some mode selection key. This subroutine does not return to the calling program.
009C16	—	(Not Used)
009F16	XECUTE	This routine returns program control to the standard Diagnostic Emulator firmware and readies it for Keyboard input. If the user has changed the display, it will return to its former state. This routine does not return to the calling program.
00A216	STATE1	This routine places the Diagnostic Emulator in the TRACE VIEW mode and makes it ready to accept input from the Keyboard. This routine does not return to the calling program. (See XECUTE routine.)
00A516	RUN	This routine loads the processor registers with the values in the scratchpad RAM save area and then does a jump to the target system. The address contained in the PC save location will be the address where target system execution will begin.
00A816	KCN	User's Keyboard scan routine. Data representing the keyswitch depressed is returned in the accumulator. In addition, if the keyswitch depressed is one of the hexadecimal numeric keys, the carry bit (CY) is set to one (true) when the subroutine returns. This routine ignores the RUN, RUN BKPT and STEP keyswitches. The table shows the data returned in the accumulator for each keyswitch depression.

KEYSWITCH	DATA	KEYSWITCH	DATA
RESET	*	0	0016
RUN	**	1	0116
RUN BKPT	**	2	0216
STEP	**	3	0316
CODE	1816	4	0416
BKPT A	1916	5	0516
BKPT B	1A16	6	0616
REG	1B16	7	0716
MEM ADDR	1416	8	0816
I/O ADDR	1516	9	0916
TRACE	1616	A	0A16
LOAD DATA	1716	B	0B16
STORE	1016	C	0C16
EXAM	1116	D	0D16
DEC	1216	E	0E16
INC	1316	F	0F16

*   When RESET is depressed, the User's Code Function is aborted and the EM-188 reinitialized.
** Keyswitches RUN, RUN BKPT and STEP are ignored by this routine.

ADDRESS	NAME	DESCRIPTION
00C616	DSPCTL	Display Control. This subroutine uses the low-order four bits of the accumulator to control the blanking of the display digits. This is shown in the example below.
		DISPLAYS HIGH LOW HIGH LOW ADDR ADDR DATA DATA X X X X B B B B ACCUMULATOR If a bit of the accumulator is a one when this subroutine is called, then the display digit or pair of digits corresponding to that bit illuminates. The accumulator and flags may be altered by this routine.

00D516	BEEP	A subroutine to beep the speaker located on the keyboard printed circuit card. No registers are altered.
002816	SOUT	Data in the accumulator is sent to the serial port. In addition, this subroutine affects a one byte counting location that is reset to zero each time a carriage return code is output (0D16) and is incremented by one each time a printable ASCII character is output. This counting location is also affected and examined by the TAP routine as well as other output operations. This subroutine may also be called with an RST 5 instruction.
003016	IMSO	The data byte following the subroutine call or restart code is sent to the serial port. No registers are altered. This subroutine may also be called with an RST 6 instruction.

8-7 INTERRUPTS

1. The internal Code Function program, when it begins executing, first copies the interrupt portion of the routine to target system RAM. (If no RAM is available in the target system, the RAM Overlay may be used.)

2. The Code Function program sets up one of the breakpoint comparators to facilitate re-entry into the internal envionment.

3. The Code Function program sets up the re-entry jump address in order to gain control after the breakpoint occurs (see sec. 8-5.4).

4. The Code Function program writes an 80₁₆ to location 3477₁₆ to arm the breakpoint system.

5. The Code Function program transfers control to the program copied to the target system.

6. When the breakpoint occurs, the internal program may read results left in RAM by the target system routine and take whatever additional action is desired. See Section 8-5.3.

8-8 CODE FUNCTION EXAMPLE

EXAMPLE 1:

	ORG 2000H
	JP CODE0	;CODE 0 ENTRY
	JP XECUTE	;CODE 1
	JP XECUTE	;CODE 2
	JP XECUTE	;CODE 3
	JP XECUTE	;CODE 4
	JP XECUTE	;CODE 5
	JP XECUTE	;CODE 6
	JP XECUTE	;CODE 7
	JP XECUTE	;CODE 8
	JP XECUTE	;CODE 9
;
;INITIALIZE--
CODE0	LD HL, 6000H	;INITIALIZE MEMORY POINTER
	LD B, 00H	;INITIALIZE BYTE COUNT
;
;NOW LOOP TO CLEAR EACH TARGET MEMORY LOCATION
;FROM 6000H to 60FFH
C1	SUB A	;CLEAR ACCUMULATOR
	CALL STM	;STORE TO TARGET SYSTEM
	INC HL	;INCREMENT TO NEXT ADDRESS
	DEC B	;DECREMENT BYTE COUNT
	JP NZ, C1	;LOOP UNTIL COUNT EQUALS ZERO
;
;EXIT TO CONTROL PROGRAM
	JP XECUTE
;
;DEFINE SUBROUTINE ADDRESSES
STM	EQU 0060H
XECUTE	EQU 009FH
	END

This example illustrates the following points:

1. The program originates at location 2000₁₆ because this is the start of the address range allocated for the Diagnostic PROM.

2. The first instruction tells the program to jump to the actual starting point of the CODE 0 program. This jump instruction provies room for the other entry points, each having its own jump instruction. In this simple example, only one Code Function is implemented; consequently a full set of jump instructions, as shown, is really not needed. Notice the CODE 0 entry point has a jump instruction to the program; all other entry points jump to a routine labeled XECUTE. The XECUTE routine is one of several ways to exit a Code Function, giving control back to the Diagnostic Emulator firmware. A RET instruction could also be used.

3. The Code Function program is written in standard Z-80 assembly language.

4. Whenever the Code Function program wishes to access the target system memory space, it may most easily do so by using subroutines already persent in the Diagnostic Emulator firmware. In this example, the STM subroutine is called to perform the write operation to the target system.

5. When the Code Function program has finished executing, it returns control to the Diagnostic Emulator firmware by jumping to the XECUTE routine.

6. The EQU statements inform the assembler of the address of routines within the Diagnostic Emulator firmware¡ªin this case, the addresses of the STM and XECUTE entry points.

The second example is a 'scope loop program. This program rotates a bit through all eight positions of an output port. The port address used is selected as is usual for other built-in functions. The routine outputs a synchronizing pulse to the BKPT-A output pin of the auziliary connector just before rotating the bit and outputs a pulse to the BKPT B output pin after it has moved the bit through all eight positions of the output port. This program loops indefinitely and must be terminated with the RESET Key.

EXAMPLE 2:

	ORG 2000H
	JP CODE0
CODE0	LD SP, 03060H	;SET UP STACK
;
;OUTPUT START PULSE TO BKPT A OUTPUT
C1	LD A, 0FFH
	LD (034C0H), A	;TURN BKPT A ON
	SUB A
	LD (034C0H), A	;TURN BKPT A OFF
;
;ROTATE BIT THROUGH OUTPUT PORT
	LD A, 030FDH	;PICK UP PORT ADDRESS
	LD C, A
	LD A, 01H	;SET ACCUMULATOR BIT
C2	CALL STIO	;OUTPUT TO TARGET PORT
	ADD A, A	;SHIFT BIT LEFT
	JP NZ, C2
;
;FLOW HERE WHEN THE BIT HAS SHIFTED OUT
;OF THE ACCUMULATOR. NOW OUTPUT THE STOP
;PULSE TO THE BKPT B OUTPUT.
	LD A, 0FFH
	LD (034C4H), A	;TURN BKPT B ON
	SUB A
	LD (034C4H), A	;TURN BKPT B OFF
;
;NOW REPEAT
	JP C1
;
;DEFINE SUBROUTINE ADDRESS
STIO	EQU 0006C
	END