home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / bdos / dospls25.ark / DDTZ.DOC < prev    next >
Text File  |  1986-11-03  |  11KB  |  232 lines
  1.  
  2.                               DDTZ v2.5
  3.                            by C.B. Falconer
  4.                       edited by George A. Havach
  5.  
  6. Introduction:
  7. ============
  8.    DDTZ v2.5 is a  complete replacement  for DDT,  Digital  Research's
  9. famous  Dynamic Debugging Tool,  with improved functionality,  bug ex-
  10. termination, and full Z80 support.  In general,  DDTZ is fully compat-
  11. ible with the original utility, but it has extra and extended commands
  12. and many fewer quirks.  All Z80-specific instructions  can be (dis)as-
  13. sembled, though in Intel rather then Zilog format.  Furthermore,  DDTZ
  14. will correctly trace ('T' and 'U' commands) both 8080 and Z80 instruc-
  15. tions,  depending on which CPU is operating.  On startup,  the program
  16. announces which CPU it is running on.
  17.  
  18.    The program is invoked by typing
  19.  
  20.       ddtz<ret>
  21. or
  22.       ddtz [d:]filespec<ret>
  23.  
  24. In  the second form,  DDTZ will load  the specified file  into  memory
  25. starting at 0100H,  unless it's a .HEX file that sets its own load ad-
  26. dress.  Besides reporting the  NEXT  free address and  the PC (program
  27. counter) after a successful load, DDTZ also shows the number of memory
  28. pages needed for a  SAVE.  Instead of  having to write  all this down,
  29. just use  the 'Q' command  at any time to redisplay these three values
  30. for the current application.
  31.  
  32. NOTE: loading more code above the NEXT pointer revises these values.
  33.  
  34.    As in DDT,  when a program is loaded above the area holding the 'A'
  35. and 'L' (and now 'K') command code,  these commands are disabled,  and
  36. the extra memory  is released to the user.  Thus,  DDTZ can occupy  as
  37. little as 3K total memory space.  Unlike DDT,  however,  DDTZ will not
  38. overwrite itself or the system on program loads (except .HEX files).
  39.  
  40.    At initialization,  the stack pointer  (SP)  points to  a return to
  41. DDTZ,  just like for the CCP.  Thus,  programs that normally return to
  42. the CCP will be returned to DDTZ.  The 'B' command  reinitializes this
  43. condition.
  44.  
  45.    The intercept vector copies  the BDOS version number,  etc.,  so an
  46. object program  does not know that  DDTZ is running  (except for BIOS-
  47. BDOS vector size). Thus, programs that check the version number should
  48. execute correctly under DDTZ.
  49.  
  50.    All input parameters can now be entered in any of three formats:
  51.  
  52.        (1) hexadecimal (as in DDT),
  53.        (2) decimal, by adding a leading '#' character,
  54.        (3) ASCII, by enclosing between either single or double quotes;
  55.            either one or two characters are allowed.
  56.  
  57.    Leading blanks in command lines and parameters are absorbed. Either
  58. a comma or a (single) space  is  a valid delimiter.   Either uppercase
  59. or lowercase input is accepted.
  60.  
  61.    The default command  (for anything  not otherwise recognizable)  is
  62. 'H'. This allows convenient calculation, along with the other features
  63. described below.  So, to convert a number, just enter it!
  64.  
  65.    As in DDT,  the prompt character is '-', and the only error message
  66. is the query ('?'), which generally kicks you back to command mode.
  67.  
  68.  
  69. New Commands (Over DDT):
  70. =======================
  71.  
  72. NOTE: letters in parenthesis, e.g. "(U)", show the equivalent command
  73.       for DDTZM version (compatible with MSDOS debug).
  74.  
  75.    @   Sets or shows (with no parameter)  the internally stored "base"
  76.        value.  Also used with the 'S' and 'D' commands  as an optional
  77.        parameter  (though without the '@')  to display memory  from an
  78.        arbitrary base marker (offset). When set to zero (the default),
  79.        it does not affect any screen displays.
  80.  
  81.    B   B)egin:   resets  the USER stack pointer  to its initial value,
  82.        such that any program that exits by an RET will return to DDTZ.
  83.        DDTZ provides  a default stack space  of approximately 24 bytes
  84.        for user programs.
  85.  
  86.    C   C)ompare first_address,last_address,against_address:  shows all
  87.        the byte differences between two memory areas, in the format
  88.  
  89.        XXXX aa YYYY bb
  90.  
  91.        where  XXXX and YYYY  are the comparative memory addresses, and
  92.        aa  and  bb  are the corresponding byte values.  Can be used to
  93.        verify  the identity  of two files  by first loading them  into
  94.        different memory areas with the 'R' command (see below).
  95.  
  96.    K   K)eep:  stores the modified memory area to disk under the file-
  97.   (W)  name  specified by  the 'I' command,  overwriting  the original
  98.        file from which it was loaded (the user is queried before doing
  99.        so).   By default,  the image of memory from 0100H  through the
  100.        "NEXT" value -1 is saved.  "K first_address,last_address" over-
  101.        rides this and allows writing ANY memory area to a file. Almost
  102.        a necessity for CPM 3.0 (no SAVE!).
  103.        W)rite on DDTZM
  104.  
  105.    Q   Q)uery:  redisplays the "NEXT PC SAVE" report at any time.
  106.   (X)  eX)amine size on DDTZM.
  107.  
  108.    W   W)here first_address,last_address,value: searches the specified
  109.   (S)  memory area for the value (a 16-bit word, not a byte) and shows
  110.        the locations of all such.  Very useful for finding  CALL's  or
  111.        JMP's to a particular address, etc.
  112.        S)earch on DDTZM
  113.  
  114.    Y   Y)our_option parm1,parm2,address: executes an arbitrary routine
  115.        at the specified address,  with the BC and DE registers  set to
  116.        parm1 and parm2, respectively.
  117.  
  118.    Z   Displays (but does not alter) the Z80's alternate register set,
  119.        including the index registers (disabled if running on an 8080).
  120.        On Z80's,  automatically included  as the last part of the dis-
  121.        play by the 'X' command.
  122.  
  123.  
  124. Based (Offset) Displays:
  125. =======================
  126.  
  127.    The 'D' and 'S' commands  can use a stored base value (offset),  as
  128. set by  the '@' command.  The current @ value  may be overridden for a
  129. single execution of these commands by adding the base as an extra par-
  130. ameter  in the command line.  The effect is  to add this value  to the
  131. first/last address and display accordingly. The address listing on the
  132. left becomes  XXXX:YYYY,  where XXXX is the offset address and YYYY is
  133. the actual memory address being displayed.  For example, if you have a 
  134. data area  located at  42B7H  and wish to  preserve easy access,  just
  135. enter "@42b7".  Now, "d0,3f" will dump memory starting at 4237H.
  136.  
  137.  
  138. Further Changes from DDT:
  139. ========================
  140.  
  141.    A   A)ssemble now accepts  the full Z80 as well as 8080 instruction
  142.        set, although it expects them in Intel rather than Zilog format
  143.        (see notes below  under  the 'L' command).   When in doubt, try
  144.        poking in the hexcode (with the 'S' command) and then  L)isting
  145.        to see what the (dis)assembler recognizes.
  146.  
  147.    D   D)isplay or D)ump  will accept  an optional third parameter  to
  148.        set the base value for a single execution only. Format has been
  149.        cleaned up.
  150.  
  151.    H   H)ex_arithmetic  on two values  also shows  their difference in
  152.        decimal. With only one value, converts to hexadecimal, decimal,
  153.        and ASCII (low-order byte only).
  154.  
  155.    I   I)nput now allows drive specification  (d:...)  and sets up the
  156.   (N)  complete command line, including both FCB's (at addresses 005CH
  157.        and 006CH).  The tail (stored at 0081H up) is NOT upshifted.
  158.        N)ame on DDTZM
  159.  
  160.    L   L)ist now displays the raw hexcode, especially handy when exam-
  161.   (U)  ining non-code areas. Intel (8080 style) mnemonics are used, so
  162.        some disassembled instructions may look a little strange. E.g.,
  163.        the Z80's 'IN B,(C)' and 'OUT (C),B'  become  'INP B' and 'OUTP
  164.        B', respectively;  'LD (nnnn),BC' becomes 'SBCD nnnn', 'ADD IX,
  165.        BC' becomes 'DADX B', and 'JP (IX)' becomes 'PCIX'.
  166.        U)nassemble on DDTZM
  167.  
  168.    R   R)ead  now permits  loading a file into memory  with an offset,
  169.   (L)  which  is added  to  the default load address  of 0100H.   When
  170.        reading in  a .HEX file  with  a preset bias,  the  'R' command
  171.        will not transfer control to an invalid execution point.   Ano-
  172.        ther execution of the  'R' command  will reread the input file,
  173.        e.g.:
  174.  
  175.          i blah<ret>
  176.          r<ret>
  177.          ...modify the code and generally mess about...
  178.          r<ret>
  179.  
  180.        The original file  is reloaded,  and the modifications  are re-
  181.        moved.
  182.        L)oad on DDTZM.
  183.  
  184.    S   S)ubstitute  or S)et,  like D)isplay,  now accepts  an optional
  185.   (E)  second parameter  to set the base value  for a single execution
  186.        only.
  187.        E)nter on DDTZM
  188.  
  189.    T   T)rap/trace  on termination  now shows  the complete CPU state.
  190.        Traps and traces no longer lock up  when  a user RST 7 instruc-
  191.        tion is executed.  Tracing of BDOS/BIOS calls  is heavily trun-
  192.        cated, avoiding clutter and preventing system crashes.
  193.  
  194. NOTE:  The UNDOCUMENTED Z80 op-codes are not handled.  Can crash.
  195.  
  196.    X   eX)amine also shows  what two-byte values  the HL and SP regis-
  197.   (R)  ters are actually pointing to. On Z80's, displays the alternate
  198.        register set.
  199.        R)egisters on DDTZM.
  200.  
  201. NOTE:  Any use of the 'K' or 'R' command  resets the system DMA trans-
  202.        fer address to the standard default value of 0080H.
  203.  
  204.  
  205. Command Summary:
  206. ===============
  207.  
  208.    DDTZ command                                          DDTZM command
  209.    ============                                          =============
  210.    @ (base)
  211.    A)ssemble first_address                                  A
  212.    B)egin {i.e., initialize stack and return}               B
  213.    C)ompare first_address,last_address,against_address      C
  214.    D)ump first_address[,last_address[,base]]                D
  215.    F)ill first_address,last_address,value                   F
  216.    G)o_to [address][,trap1[,trap2]]                         G
  217.    H)ex_arithmetic value1(,value2)                          H
  218.    I)nput FCBs_command_line                                 N)ame
  219.    K)eep [first_address,last_address]                       W)rite
  220.    L)ist_code first_address[,last_address]                  U)nassemble
  221.    M)ove first_address,last_address,destination             M
  222.    Q)uery {i.e. display memory parameters for application}  X)amine
  223.    R)ead_file (offset)                                      L)oad
  224.    S)ubstitute_in_memory first_address[,base]               E)nter
  225.    T)race_execution [count]                                 T
  226.    U)ntrace_execution [count] (i.e. do count instr)     (NOT AVAILABLE)
  227.    W)here_is first_address,last_address,word                S)earch
  228.    X)amine/change [register|flag]                           R)egister
  229.    Y)our_option BC:=parm1,DE:=parm2,call_address            Y
  230.    Z)80_register_display                                    Z
  231.                                ( on DDTZM only --> )        Q)uit
  232. ╡P