18E USER'S DOCUMENTATION Copyright 1988 by Damon Gibson 8201 Castleton Boulevard Indianapolis, Indiana 46256 (317) 842-7128 TABLE OF CONTENTS Section Page I. INTRODUCTION 1 II. FEATURES AND FIXES 1 III. INSTALLATION 2 IV. NEW OR MODIFIED COMMANDS 3 A Assemble 4 J Animated Full Screen Debugging 4 S Single Step 4 X Display Machine State 4 Z Disassemble 4 N Output to I/O Port without Pre-read 4 Q Query I/O Ports 4 T Select Debug Terminal (new command) 5 V. APPENDICES 6 APPENDIX A - Hitachi HD64180 Instructions 7 APPENDIX B - System Memory Map 8 APPENDIX C - 18E Command Summary 9 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson I. INTRODUCTION 18E is an outstanding debug tool for use in developing software for Zilog Z80 and Hitachi HD64180 microprocessors. This document describes the feature, installation and operational differences between 18E and Z8E and is meant as a supplement to Z8E.DOC which very adeptly defines the Z8E debug monitor. The original monitor (Z8E) and its derivative(s) (18E) are available in the public domain in source and object code forms and may be downloaded from a number of Z-node bulletin board systems. These software packages may be freely used and distributed for any non-commercial purpose. If you find that 18E saves you so much time that you don't see how you ever got along without it, we would appreciate your $50 donation (or less if you're poor like me) for its continued support (feel free to send your upgrade suggestions with your check). Contributions suggested to: Developer of 18E Original author of Z8E ======================= ====================== Damon R. Gibson Richard Surwillo 8201 Castleton Blvd. 330 Calvin Ct. Indianapolis, IN 46256 Wycoff, NJ 07481 II. FEATURES AND FIXES: In addition to all of the capabilities of the Z8E monitor, 18E provides the following new features and fixes: - HD64180 assembly/dissambly support via modified A, J, S, X and Z commands - HD64180 I/O register access support via modified N and Q commands - Auxiliary debug terminal support (accessable via the new T command) to facilitate debugging software which makes use of the console keyboard and display - May use RUBOUT as well as BACKSPACE for line entry character delete - Fixed cursor address bug which occurred while tracing an EXX or EX AF,AF' instruction via the J command With both HD64180 and auxiliary terminal support activated (see installation section below), the 18E monitor still occupies less than 9.5K bytes. 1 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson III. INSTALLATION: Installing 18E into your CP/M (or ZRDOS) system is very similar to doing so with Z8E as described in Z8E.DOC. First tell 18E to load itself and its symbol file as follows: A>18E 18E.COM 18E.SYM The symbol file 18E.SYM contains the name and address of each parameter which may need to be modified for your system. The CASE, MAXLEN and INIT symbols correspond exactly to those included with the Z8E monitor (in Z8E.SYM) and should be configured according to the instuctions for them in Z8E.DOC. However, since 18E supports two terminals, there are two terminal- related symbols in 18E.SYM for each one in Z8E.SYM as shown in the following chart: Z8E Symbol | 18E Symbol | 18E Symbol | Main Terminal | Auxiliary Terminal --------------+-----------------+---------------------- MXYCP | MXYSTR | AXYSTR ROWB4? | MROWB4 | AROWB4 ROW | MROW | AROW COLUMN | MCOL | ACOL TTYQ | MTTYQ | ATTYQ TTYI | MTTYI | ATTYI TTYO | MTTYO | ATTYO XYCP | MXYPRG | AXYPRG To configure 18E for your main and auxiliary terminal, follow Z8E.DOC's instructions for configuring the symbols in column 1 above while substituting the symbols in columns 2 and 3 above. The default main terminal configuration uses Soroc, Wyse and Televideo compatable cursor addressing and accesses the CP/M console device via BDOS calls (just like Z8E). The default auxiliary terminal configuration uses DEC VT52 compatable cursor addressing and accesses the CP/M reader and punch devices via BDOS calls. Note since CP/M makes no provision for determining the status of the reader device without waiting forever for a character, ATTYQ is written to read the reader's status port directly and defaults to serial port 0 of the HD64180 (this is the reader port for the SB180). In addition to all this object level patching, 18E is implemented at the source code level to allow the user to optionally activate or deactivate the two new major features (Hitachi HD64180 and auxiliary terminal support). This allows the user to tailor 18E for his needs while minimizing its size (and thus maximizing the available TPA space). To do this, the user should obtain a copy of 18E.Z80 from the 18E-SRC.LBR library file. 2 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson IV. NEW OR MODIFIED COMMANDS: All 18E commands work just as defined in Z8E.DOC except as described in the following pages: 3 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson A Assemble __________________________________________________________________ 18E's A command performs just as it does in Z8E except that it now accepts Hitachi HD64180-specific instructions from the operator for assembly (see Appendix B for a list of these instructions). J Animated Full Screen Debugging S Single Step X Display Machine State Z Disassemble __________________________________________________________________ 18E's J, S, X and Z commands perform just as they do in Z8E except that they now successfully disassemble Hitachi HD64180-specific instructions (see Appendix B for a list of these instructions). N Output to I/O Port without Pre-read Q Query I/O Ports __________________________________________________________________ 18E's N and Q commands perform just as they do in Z8E except that they now support access to the HD64180's internal I/O registers. When reading an I/O port, 18E first clears the B register, places the port number in the C register and then executes an IN A,(C) instruction. When writing to an I/O port, 18E first clears the B register, places the port number in the C register, points HL to a buffer internal to 18E containing the data to be written and then executes an OUTI instruction. This method ensures that A8 to A15 are at 0 when the N or Q commands are accessing an I/O port. 4 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson T Select Debug Terminal (new command) __________________________________________________________________ The T command does not exist in Z8E and is used to implement 18E's auxiliary debug terminal feature. When 18E is first invoked, the main terminal is enabled. Then, the T command may be used to enable an auxiliary terminal. The enabled terminal displays all 18E output and is used by the operator to enter commands and data to 18E. In this way, enabling the auxiliary terminal allows the user to debug a program which makes use of the main terminal as parts of its function without fear that the debugger will "walk" on his nice clean application screen. (Of course, the user must HAVE a second terminal to take advantage of this.) The format for the T command is as follows: *T ARG1 where ARG1 is the letter A to enable the auxiliary ter- minal or the letter M to re-enable the main terminal. Any other letter will result in an error and will cause two question marks to be displayed (terminal selection does not change). Note that if the auxiliary terminal is enabled, and the user types a CTRL-C on the auxiliary terminal, a warm boot (sure cure for cold feet) will be performed and the main terminal will receive the CP/M prompt (no need to transfer control back to the main terminal via "T M" first). * * * CAUTION * * * ------------------------------------------------------------------ The user must have already configured 18E's auxiliary terminal parameters and must have a terminal (set to the proper baud rate) connected to his auxiliary port before executing a "T A" command. Failure to do this will result in a "locked up" computer which must be re-booted. ------------------------------------------------------------------ 5 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson V. APPENDICES 6 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson APPENDIX A - Hitachi HD64180 Instructions In addition to the 67 Z80 mnemonics and the 5 pseudo-ops supported by Z8E, 18E also supports the 10 Hitachi HD64180-specific mnemonics. The Z80 mnemonics are all either 2, 3 or 4 characters long while the 5 pseudo-ops are either 3 or 4 characters long. The Hitachi HD64180-specific mnemonics do not quite fit this mold in that three of them (only the Japanese know why) are 5 characters long. After careful deliberation, it was decided to implement these three "rogues" as 4 character mnemonics for 18E. The following table shows all 10 Hitachi HD64180-specific mnemonics and their 18E equivalents. HITACHI | 18E | USAGE -----------+-------+------------------------------ IN0 | IN0 | IN0 g,(m) OUT0 | OUT0 | OUT0 (m),g TST | TST | TST g or TST (HL) or TST m SLP | SLP | SLP MLT | MLT | MLT ww OTIM | OTIM | OTIM OTDM | OTDM | OTDM OTIMR | OIMR | OIMR \ 5 character OTDMR | ODMR | ODMR > mnemonics TSTIO | TSIO | TSIO m / changed to 4 Key to parameter symbols in USAGE column: g register A, B, C, D, E, H or L ww register pair BC, DE, HL or SP (m) 8 bit I/O port address m 8 bit immediate data 7 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson APPENDIX B - System Memory Map |||||||||||||||||||||||||||||||||||| FFFF || || || || || CP/M (BDOS and BIOS) || || || || || |||||||||||||||||||||||||||||||||||| || || || 18E (9.0k to 9.5k BYTES) || || || |||||||||||||||||||||||||||||||||||| || || || OPTIONAL SYMBOL TABLE || || || |||||||||||||||||||||||||||||||||||| || || || || || || || || || || || || || TPA || || || || || || || || || || || || || || || |||||||||||||||||||||||||||||||||||| --- 0100 || || || PAGE ZERO RESERVED || || || |||||||||||||||||||||||||||||||||||| ___ 0000 The size of 18E is dependent on how the H64180 and AUXPRT equates are set in the source file 18E.Z80. If both equates are set to NO (neither HD64180 or auxiliary terminal support activated) 18E will use 9k. Each of the equates will add 1/4k (256 bytes) to the length of 18E if it is set to YES for a maximum size of 9.5k. 8 18E - Z80/HD64180 DEBUG MONITOR Damon R. Gibson APPENDIX C - 18E Command Summary CMD Description Arguments A Inline Assembly StartAddr B Set Breakpoint Addr1[,Pass Count] [Addr2..AddrN] C Clear Breakpoint Addr1 [Addr2..AddrN] D Dump Memory [StartAddr] [End/Count] E Examine Memory StartAddr F Find StartAddr MatchData G Go ExecutionAddr H Display Symbol Table [FirstSymbol] I Input File FileName [,Load Address] J Full Screen/Animated Debug [/] [*] [Addr] [Timeout] K Set Memory Window StartAddr [Size] M Move Memory SourceStart SourceEnd DestStart N Output to Port NO Pre-Read [(] PortAddr [)] O Output Current Breakpoints P Exam/Modify PSW (Flag Reg) Q Query I/O Port [(] PortAddr [)] R Examine/Modify Registers RegSpecifier S Single-Step [/] [Count] T Select Debug Terminal A or T U Write Symbol Table To Disk FileName V Verify Memory SourceStart SourceEnd DestStart W Write to Disk FileName [StartAddr] [EndAddr] X Examine Machine State Y Fill Memory FromAddr ToAddr Data Z Disassemble StartAddr End/Count FileName [] Denotes Optional Argument [/] Do Not Trace Subroutine [*] Do Not Trace BDOS Call [(] [)] I/O Port Monitor Mode 9