home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / debug / 18e.lbr / 18E.DZC / 18E.DOC
Text File  |  1988-01-25  |  20KB  |  725 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                             18E USER'S DOCUMENTATION
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                                  Copyright 1988
  27.  
  28.                                        by
  29.  
  30.                                   Damon Gibson
  31.  
  32.                             8201 Castleton Boulevard
  33.  
  34.                           Indianapolis, Indiana  46256
  35.  
  36.                                  (317) 842-7128
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                                 TABLE OF CONTENTS
  74.  
  75.                 Section                                        Page
  76.  
  77.           I.  INTRODUCTION                                       1
  78.  
  79.          II.  FEATURES AND FIXES                                 1
  80.  
  81.         III.  INSTALLATION                                       2
  82.  
  83.          IV.  NEW OR MODIFIED COMMANDS                           3
  84.  
  85.                 A       Assemble                                 4
  86.  
  87.                 J       Animated Full Screen Debugging           4
  88.  
  89.                 S       Single Step                              4
  90.  
  91.                 X       Display Machine State                    4
  92.  
  93.                 Z       Disassemble                              4
  94.  
  95.                 N       Output to I/O Port without Pre-read      4
  96.  
  97.                 Q       Query I/O Ports                          4
  98.  
  99.                 T       Select Debug Terminal (new command)      5
  100.  
  101.           V.  APPENDICES                                         6
  102.  
  103.                 APPENDIX A - Hitachi HD64180 Instructions        7
  104.  
  105.                 APPENDIX B - System Memory Map                   8
  106.  
  107.                 APPENDIX C - 18E Command Summary                 9
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  137.  
  138.  
  139.         I.  INTRODUCTION
  140.  
  141.         18E is  an outstanding debug  tool for use  in developing software
  142.         for Zilog Z80 and Hitachi HD64180 microprocessors.  
  143.  
  144.         This  document describes the feature, installation and operational
  145.         differences between 18E  and Z8E and  is meant as  a supplement to
  146.         Z8E.DOC which very adeptly defines the Z8E debug monitor.  
  147.         
  148.         The  original  monitor  (Z8E)  and  its  derivative(s)  (18E)  are
  149.         available in the public domain in source and object code forms and
  150.         may  be downloaded from a number of Z-node bulletin board systems.
  151.         These software packages may be freely used and distributed for any
  152.         non-commercial purpose.  
  153.  
  154.         If you find that 18E saves you so much time that you don't see how
  155.         you ever got along  without  it,  we  would  appreciate  your  $50
  156.         donation (or less if  you're  poor  like  me)  for  its  continued
  157.         support (feel free to send  your  upgrade  suggestions  with  your
  158.         check).
  159.  
  160.         Contributions suggested to:
  161.  
  162.             Developer of 18E                Original author of Z8E
  163.             =======================         ======================
  164.             Damon R. Gibson                 Richard Surwillo
  165.             8201 Castleton Blvd.            330 Calvin Ct.
  166.             Indianapolis, IN  46256         Wycoff, NJ  07481
  167.  
  168.  
  169.         II.  FEATURES AND FIXES:
  170.         
  171.         In addition to all  of the  capabilities of  the Z8E  monitor, 18E
  172.         provides the following new features and fixes:
  173.  
  174.                 - HD64180  assembly/dissambly support via modified
  175.                   A, J, S, X and Z commands 
  176.  
  177.                 - HD64180 I/O register access support via modified
  178.                   N and Q commands 
  179.  
  180.                 - Auxiliary debug terminal support (accessable via
  181.                   the  new  T  command)  to  facilitate  debugging
  182.                   software which makes use of the console keyboard
  183.                   and display 
  184.  
  185.                 - May use  RUBOUT  as well as  BACKSPACE  for line 
  186.                   entry character delete
  187.  
  188.                 - Fixed  cursor address  bug which  occurred while
  189.                   tracing  an EXX or EX AF,AF' instruction via the
  190.                   J command
  191.  
  192.         With both HD64180  and auxiliary  terminal support  activated (see
  193.         installation  section below), the 18E  monitor still occupies less
  194.         than 9.5K bytes.  
  195.  
  196.                                         1
  197.  
  198.                                         
  199.  
  200.  
  201.  
  202.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  203.  
  204.  
  205.         III.  INSTALLATION:
  206.  
  207.         Installing 18E into your CP/M (or ZRDOS) system is very similar to
  208.         doing so with Z8E as described in Z8E.DOC.  
  209.  
  210.         First tell 18E to load itself and its symbol file as follows:
  211.  
  212.             A>18E 18E.COM 18E.SYM
  213.  
  214.         The  symbol file  18E.SYM contains  the name  and address  of each
  215.         parameter which may need to be modified for your system.  
  216.         
  217.         The CASE, MAXLEN and INIT  symbols  correspond  exactly  to  those
  218.         included   with  the  Z8E  monitor  (in  Z8E.SYM)  and  should  be
  219.         configured according to the instuctions for them in Z8E.DOC.  
  220.         
  221.         However, since 18E supports two terminals, there are two terminal-
  222.         related symbols in 18E.SYM for each one in Z8E.SYM as shown in the
  223.         following chart: 
  224.  
  225.               Z8E Symbol  |  18E Symbol     |  18E Symbol
  226.                           |  Main Terminal  |  Auxiliary Terminal
  227.             --------------+-----------------+----------------------
  228.               MXYCP       |  MXYSTR         |  AXYSTR             
  229.               ROWB4?      |  MROWB4         |  AROWB4             
  230.               ROW         |  MROW           |  AROW               
  231.               COLUMN      |  MCOL           |  ACOL               
  232.               TTYQ        |  MTTYQ          |  ATTYQ              
  233.               TTYI        |  MTTYI          |  ATTYI              
  234.               TTYO        |  MTTYO          |  ATTYO              
  235.               XYCP        |  MXYPRG         |  AXYPRG             
  236.  
  237.         To configure 18E for your  main  and  auxiliary  terminal,  follow
  238.         Z8E.DOC's  instructions for  configuring the  symbols in  column 1
  239.         above while substituting the symbols in columns 2 and 3 above.  
  240.  
  241.         The default main  terminal  configuration  uses  Soroc,  Wyse  and
  242.         Televideo compatable  cursor  addressing  and  accesses  the  CP/M
  243.         console device via BDOS calls (just like Z8E).  
  244.  
  245.         The   default  auxiliary  terminal  configuration  uses  DEC  VT52
  246.         compatable cursor addressing and  accesses  the  CP/M  reader  and
  247.         punch  devices via BDOS calls.  Note since CP/M makes no provision
  248.         for  determining the status  of the reader  device without waiting
  249.         forever for a  character, ATTYQ  is written  to read  the reader's
  250.         status  port directly and defaults to serial port 0 of the HD64180
  251.         (this is the reader port for the SB180).  
  252.  
  253.         In  addition to all this object level patching, 18E is implemented
  254.         at  the source code level to allow the user to optionally activate
  255.         or deactivate the two new  major  features  (Hitachi  HD64180  and
  256.         auxiliary terminal support).  This allows the user to tailor 18E
  257.         for his needs while minimizing its size (and thus maximizing the
  258.         available TPA space).  To do this, the user should obtain a copy
  259.         of 18E.Z80 from the 18E-SRC.LBR library file.
  260.  
  261.  
  262.                                         2
  263.  
  264.                                         
  265.  
  266.  
  267.  
  268.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  269.  
  270.  
  271.         IV.  NEW OR MODIFIED COMMANDS:
  272.  
  273.         All  18E  commands work just  as  defined  in  Z8E.DOC  except  as
  274.         described in the following pages: 
  275.         
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                                         3
  329.  
  330.                                         
  331.  
  332.  
  333.  
  334.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  335.  
  336.  
  337.         A       Assemble                                
  338.         __________________________________________________________________
  339.  
  340.         18E's A command performs just as it does in Z8E except that it now
  341.         accepts  Hitachi HD64180-specific  instructions from  the operator
  342.         for assembly (see Appendix B for a list of these instructions).  
  343.  
  344.         
  345.         J       Animated Full Screen Debugging          
  346.         S       Single Step                             
  347.         X       Display Machine State                   
  348.         Z       Disassemble                             
  349.         __________________________________________________________________
  350.  
  351.         18E's J, S, X and Z commands perform just as they do in Z8E except
  352.         that  they now  successfully disassemble  Hitachi HD64180-specific
  353.         instructions (see Appendix B for a list of these instructions).  
  354.  
  355.         
  356.         
  357.         N       Output to I/O Port without Pre-read     
  358.         Q       Query I/O Ports                         
  359.         __________________________________________________________________
  360.  
  361.         18E's N and Q commands perform just as they do in Z8E except that
  362.         they now support access to the HD64180's internal I/O registers.
  363.  
  364.         When  reading an I/O port, 18E first clears the B register, places
  365.         the  port number in the  C register and then  executes an IN A,(C)
  366.         instruction.  
  367.  
  368.         When writing  to an  I/O port,  18E first  clears the  B register,
  369.         places  the port number in  the C register, points  HL to a buffer
  370.         internal to 18E  containing  the  data  to  be  written  and  then
  371.         executes an OUTI instruction.  
  372.  
  373.         This  method ensures  that A8  to A15  are at  0 when  the N  or Q
  374.         commands are accessing an I/O port.  
  375.  
  376.  
  377.  
  378.  
  379.                 
  380.                 
  381.                 
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                                         4
  395.  
  396.                                         
  397.  
  398.  
  399.  
  400.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  401.  
  402.  
  403.         T       Select Debug Terminal (new command)     
  404.         __________________________________________________________________
  405.  
  406.  
  407.         The T command does not exist in Z8E and is used to implement 18E's
  408.         auxiliary debug terminal feature.  
  409.  
  410.         When 18E is  first invoked, the  main terminal is  enabled.  Then,
  411.         the T command may be used to enable an auxiliary terminal.  
  412.  
  413.         The enabled terminal  displays all 18E  output and is  used by the
  414.         operator to enter commands and data to 18E.  In this way, enabling
  415.         the auxiliary  terminal allows the  user to debug  a program which
  416.         makes use of  the main terminal  as parts of  its function without
  417.         fear  that the debugger will "walk"  on his nice clean application
  418.         screen.   (Of course, the user must HAVE a second terminal to take
  419.         advantage of this.) 
  420.          
  421.         The format for the T command is as follows: 
  422.  
  423.                 *T  ARG1 <cr>
  424.  
  425.                   where ARG1 is the letter A to enable the auxiliary ter-
  426.                   minal or the letter M to re-enable the main terminal.  
  427.  
  428.                   Any other letter will result in an error and will cause
  429.                   two question marks to be displayed  (terminal selection 
  430.                   does not change).
  431.  
  432.         Note that if the auxiliary terminal is enabled, and the user types
  433.         a  CTRL-C on the  auxiliary  terminal, a warm boot  (sure cure for 
  434.         cold feet)  will be  performed and the main terminal  will receive
  435.         the  CP/M  prompt  (no  need to transfer control back  to the main
  436.         terminal via "T M" first).  
  437.         
  438.                               * * *  CAUTION  * * *
  439.  
  440.         ------------------------------------------------------------------
  441.         The  user must  have already  configured 18E's  auxiliary terminal
  442.         parameters  and must have a terminal (set to the proper baud rate)
  443.         connected  to his auxiliary port before executing a "T A" command.
  444.         Failure to do this  will result  in a  "locked up"  computer which
  445.         must be re-booted.  
  446.         ------------------------------------------------------------------
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                                         5
  461.  
  462.                                         
  463.  
  464.  
  465.  
  466.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  467.  
  468.  
  469.         V.  APPENDICES
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                                         6
  527.  
  528.                                         
  529.  
  530.  
  531.  
  532.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  533.  
  534.  
  535.         APPENDIX A - Hitachi HD64180 Instructions
  536.  
  537.         In addition to the 67 Z80 mnemonics and the 5 pseudo-ops supported
  538.         by   Z8E,  18E  also  supports  the  10  Hitachi  HD64180-specific
  539.         mnemonics.  
  540.  
  541.         The Z80 mnemonics  are all either 2, 3 or 4 characters long  while
  542.         the 5  pseudo-ops are  either 3 or 4 characters long.  The Hitachi
  543.         HD64180-specific  mnemonics  do not quite  fit this mold  in  that
  544.         three of them (only the Japanese know why) are 5 characters long.
  545.  
  546.         After careful deliberation, it  was  decided  to  implement  these
  547.         three "rogues"  as 4 character  mnemonics for 18E.   The following
  548.         table shows all  10 Hitachi  HD64180-specific mnemonics  and their
  549.         18E equivalents.  
  550.  
  551.                 HITACHI  |  18E  |  USAGE
  552.               -----------+-------+------------------------------
  553.                   IN0    |  IN0  |  IN0 g,(m)
  554.                   OUT0   |  OUT0 |  OUT0 (m),g
  555.                   TST    |  TST  |  TST g or TST (HL) or TST m
  556.                   SLP    |  SLP  |  SLP
  557.                   MLT    |  MLT  |  MLT ww
  558.                   OTIM   |  OTIM |  OTIM
  559.                   OTDM   |  OTDM |  OTDM
  560.                   OTIMR  |  OIMR |  OIMR      \   5 character
  561.                   OTDMR  |  ODMR |  ODMR       >  mnemonics
  562.                   TSTIO  |  TSIO |  TSIO m    /   changed to 4
  563.  
  564.               Key to parameter symbols in USAGE column:
  565.  
  566.                 g       register A, B, C, D, E, H or L
  567.  
  568.                 ww      register pair BC, DE, HL or SP
  569.  
  570.                 (m)     8 bit I/O port address
  571.  
  572.                 m       8 bit immediate data
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                                         7
  593.  
  594.                                         
  595.  
  596.  
  597.  
  598.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  599.  
  600.  
  601.         APPENDIX B - System Memory Map
  602.  
  603.  
  604.                        ||||||||||||||||||||||||||||||||||||     FFFF
  605.                        ||                                ||
  606.                        ||                                ||
  607.                        ||      CP/M (BDOS and BIOS)      ||
  608.                        ||                                ||
  609.                        ||                                ||
  610.                        ||||||||||||||||||||||||||||||||||||
  611.                        ||                                ||
  612.                        ||    18E (9.0k to 9.5k BYTES)    ||
  613.                        ||                                ||
  614.                        ||||||||||||||||||||||||||||||||||||
  615.                        ||                                ||
  616.                        ||     OPTIONAL SYMBOL TABLE      ||
  617.                        ||                                ||
  618.                        ||||||||||||||||||||||||||||||||||||
  619.                        ||                                ||
  620.                        ||                                ||
  621.                        ||                                ||               
  622.                        ||                                ||
  623.                        ||                                ||
  624.                        ||                                ||
  625.                        ||              TPA               ||
  626.                        ||                                ||
  627.                        ||                                ||
  628.                        ||                                ||
  629.                        ||                                ||
  630.                        ||                                ||
  631.                        ||                                ||
  632.                        ||                                ||
  633.                        ||||||||||||||||||||||||||||||||||||  --- 0100
  634.                        ||                                ||
  635.                        ||      PAGE ZERO  RESERVED       || 
  636.                        ||                                || 
  637.                        ||||||||||||||||||||||||||||||||||||  ___ 0000
  638.  
  639.  
  640.  
  641.         The  size of 18E is dependent on how the H64180 and AUXPRT equates
  642.         are set in the source file 18E.Z80.  If both equates are set to NO
  643.         (neither HD64180 or auxiliary terminal support activated) 18E will
  644.         use 9k.  Each  of the  equates will  add 1/4k  (256 bytes)  to the
  645.         length of 18E if it is set to YES for a maximum size of 9.5k.  
  646.         
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                                         8
  659.  
  660.                                         
  661.  
  662.  
  663.  
  664.         18E - Z80/HD64180 DEBUG MONITOR                    Damon R. Gibson
  665.  
  666.  
  667.         APPENDIX C - 18E Command Summary
  668.  
  669.         CMD  Description                  Arguments
  670.  
  671.          A   Inline  Assembly             StartAddr 
  672.          B   Set Breakpoint               Addr1[,Pass Count]  [Addr2..AddrN]
  673.          C   Clear Breakpoint             Addr1               [Addr2..AddrN]
  674.          D   Dump Memory                  [StartAddr]         [End/Count] 
  675.          E   Examine Memory               StartAddr
  676.          F   Find                         StartAddr           MatchData
  677.          G   Go                           ExecutionAddr
  678.          H   Display Symbol Table         [FirstSymbol]
  679.          I   Input File                   FileName            [,Load Address]
  680.          J   Full Screen/Animated Debug   [/] [*] [Addr]      [Timeout]
  681.          K   Set Memory Window            StartAddr           [Size]
  682.          M   Move Memory                  SourceStart   SourceEnd   DestStart
  683.          N   Output to Port NO Pre-Read   [(] PortAddr [)]
  684.          O   Output Current Breakpoints
  685.          P   Exam/Modify PSW (Flag Reg)
  686.          Q   Query I/O Port               [(] PortAddr [)]
  687.          R   Examine/Modify Registers     RegSpecifier
  688.          S   Single-Step                  [/]  [Count]
  689.          T   Select Debug Terminal        A or T
  690.          U   Write Symbol Table To Disk   FileName    
  691.          V   Verify Memory                SourceStart   SourceEnd   DestStart
  692.          W   Write to Disk                FileName      [StartAddr] [EndAddr]
  693.          X   Examine Machine State
  694.          Y   Fill Memory                  FromAddr      ToAddr      Data
  695.          Z   Disassemble                  StartAddr     End/Count   FileName
  696.  
  697.  
  698.  
  699.  
  700.         []        Denotes Optional Argument
  701.         [/]       Do Not Trace Subroutine
  702.         [*]       Do Not Trace BDOS Call  
  703.         [(] [)]   I/O Port Monitor Mode
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                                         9
  725.