Programmer 7500/MAX_PROGRAMMERS.iso/INFO/ASMUTL/PC370.ZIP/DEBUG.DOC

Text File | 1987-04-21 | 9.9 KB | 201 lines

 TITLE 'PC/370 Interqctive Debug Facility Documentation'

 A.  Overview
 B.  Program Interface
 C.  User Interface
 D.  User Guide

 EJECT

 A.  Overview

     The PC/370 interactive debug facility is designed to provide a
     tool to help debug program errors in either 80x86 code or 370 code.
     The facility provides the basic tools namely tracing program flow
     via breakpoints defined by calls, and displaying register and memory
     contents upon request.  In addition, the facility provides a data
     and address stop option which is very useful for locating errors.

 EJECT

 B.  Program Interface

     The PC/370 interactive debug facility is implemented via a single
     module named MMDBUG which is linked into A370, L370 and E370 programs
     and is called with a single 3 byte ASCII argument located immediately after
     the near call instruction.   In the E370 emulator environment, the
     interactive debugger can be called directly from 370 programs through
     SVC 9 which must be followed by 3 byte EBCDIC argument and a 1 byte
     filler to keep instructions on half word boundary.

     There are several special calling arguments as follows:

     1.   'OFF' - turn off (kill) trace facility for speed
                  (a trace is killed by replacing call with jump over arg)
     2.   'ON ' - turn trace facility back on (stop killing traces)
     3.   'BUG' - force interactive debug mode
     4.   'IOF' - interrupts off (unsolicited keys queued for input)
     5.   'ION' - interrupts on  (any key stroke invokes user interface)
     6.   'IFL' - instruction fetch loop (special trace used in E370 to
                  identify next trace id as 370 operation trace to be
                  stored in trace table)

     The first call to MMDBUG in A370, L370, and E370 is with 'OFF'
     unless the trace option was requested (see PC370.DOC).

 EJECT

 C.  User Interface

     When MMDBUG is called without the 'OFF' argument, or when a key
     is hit without the 'IOF' argument being issued previously, the
     user interface mode is invoked and the following commands may
     be entered in upper or lower case from the console:

          A - ADDRESS STOP (PROMPTS FOR ADDRESS, LENGTH, TYPE)
          C - CONTINUE TO NEXT TRACE ENTRY
          D - DUMP MEMORY (PROMPTS FOR ADDRESS)
          F - FIND TRACE ENTRY (PROMPTS FOR TRACE ID)
          H - HELP LIST MMDBUG COMMANDS (THIS LIST)
          I - INSTRUCTION COUNTER WORD
          J - RESET NEXT 370 OR 8086 INSTRUCTION ADDRESS
          K - KILL MODE SET/RESET (CHANGES TRACE CALL TO NOP)
          L - SET/RESET TRACE LIMIT FOR Q/T MODE
          M - MODIFY MEMORY (PROMPTS FOR ADDRESS AND DATA)
          N - LIST LAST 20 TRACE ENTRIES (NOTE K,Z  AFFECT THIS LIST)
          P - SET/RESET PRINT COPY OF ALL MMDBUG I/O
          Q - SET QUIET MODE (USED WITH F, L, AND 'BUG' OPTIONS)
          R - DISPLAY REGISTERS (SEE Z OPTION)
          S - SAVE/UNSAVE CURRENT TRACE ID FROM KILL MODE
          T - SET TRACE MODE (USED WITH OPTIONS F AND L)
          W - LIST FREE MEMORY QUEUE
          X - SET/RESET ASSIST LOGGING OF INTERACTIVE DEBUG OUTPUT
          Y - MODIFY 8086/370 REGISTER (PROMPTS FOR REGISTER/DATA)
          Z - SET/RESET 8086/370 MODE
                IN 8086 MODE, R DUMPS 8086 REGISTERS AND D PRINTS
                PRINTABLE ASCII CHARACTERS IN DUMP.
                IN PC/370 MODE, R DUMPS 370 REGISTERS AND PSW
                AND D DUMPS PRINTABLE EBCDIC CHARACTERS IN DUMP.
         <cr> - dump same address again as defined in D command
         <sp> - dump forward until any key hit
         <bs> - dump backwards until any key hit
         <esc>- exit to MSDOS after attempting to close files

     Memory addresses may be entered in xxxx:xxxx or xxxxxx hex format
     without leading zeros required.  In 370 mode, the xxxxxx format always
     refers to the relative address within the current address space.  In
     80x86 mode, the xxxxxx format refers to the offset using the current
     segment.  The segment:offset is initialized to the CIX extended register
     which uses the data segment and points to the general purpose register
     area in E370 and the common vector table in A370 and L370.

 EJECT

  D.  User Guide

The PC/370 interactive debug facility can assist you in locating
errors within your 370 assembler programs.  But first there are
some more basic things to check:

  1.  Are you sure that you are executing the latest version of
      the source program.  To be absolutely sure, code the date
      and time in a print statement at the beginning of the program
      and then reassemble (A370) and relink (L370) and execute the
      program again.

  2.  Does the program run to normal termination?  If so then you
      can run the program again specifying a T as the only parameter
      on the execute command to initiate the interactive debug
      facility.  Another way to invoke the interactive debug option
      is to specify option D in the linkage editor.   This method should
      be used if the program requires a parameter other than T.

  3.  If the program terminated abnormally, the interactive debug
      facility is automatically initiated along with a display of
      the PSW and the failing instruction.  To calculate the
      relative address of the failing instruction in the program,
      subtract the program load address of X'0200' (Note you will
      have to look at the link edit listing to get the starting
      address if the failing instruction is in a subroutine.

  4.  To trace execution of the program, enter T.  To stop the
      trace at any point hit any key.

  5.  To continue execution of the program normally, enter Q.

  6.  To dump the current contents of the registers, enter R.

  7.  To dump any 32 byte area in memory, enter A followed by
      the starting address in hex xxxx.

  8.  To continue to dump memory from the current location forward,
      hit the space key.  To dump backwards, hit the backspace key.
      To stop the dump, hit any key.

  9.  To stop the program at a specific address, enter A followed
      by the address in hex xxxx followed by the option code A.
      Then use Q or T to continue execution until the address is found.

 10.  To stop the program when a specific data field in memory is
      changed, enter A followed by the address in xxxx followed by
      the option code E for equal data or N for not-equal data.
      Next entry the legnth of the data compare in hex when prompted.
      If option E is selected, enter the hex value of the data you
      want to search for when prompted.  Next press Q or T to contine
      execution until the data compare specified triggers debug user
      interface again.  To stop at a specifc instruction count in a
      370 program, use the I command to display the instruction counter
      word and then use data equal address stop on the word.

 11.  To turn off any address stop option, enter A.

 12.  To list the last 20 instruction trace table entries, enter N.
      If running in 370 mode (option Z toggles mode), only the 370
      instruction traces will be stored and listed via option N.
      In 80x86 mode, all traces will be stored and listed.
      Note that this list may be incomplete if the program
      was started without debug active since option K is the default.
      Option K kills each trace entry to debug the first time debug
      is entered for that trace point.  Option K makes the program
      run much faster at the expense of losing repeated trace points.
      However, with release 1.2 you can use Find to locate selected
      trace id's and use Save to protect id from kill mode.  This
      option allows much faster execution while still being able to
      trace selected id's.  A very useful id to save is IFL which will
      then trace each 370 instruction during kill mode while killing
      all of the lower level ids for reasonable speed yet full
      visibility of 370 instructions.  Faster still is to save only
      one 370 instruction id such as TRT.  This is very useful in
      conjunction with address stop, since the address stop overhead
      is only incurred for the selected saved id's.

 13.  To set a fixed limit on the number of trace entries before
      entering debug command mode again, enter L and count in hex xxxx.
      Next enter Q or T to continue until count reached zero.  If
      zero count is entered, the limit is not checked.

 14.  To modify memory, enter M followed by address in hex xxxx.
      Next enter hex data bytes followed by return key.

 15.  To display the 8086 registers, type Z to switch to 8086 mode.
      Now type R.  In 8086 mode, storage dumps translate data to ASCII
      instead of EBCDIC for character display.  In 8086 mode, N lists all
      trace entries instead of just IFL 370 instruction traces.  In 8086
      mode, Y changes 8086 registers instead of 370 registers.  To return
      to 370 mode, type Z again.

 16.  The W command displays free memory in the 8086 data segment for
      80886 mode and the free memory in the current address space in 370
      mode.  Note these are two totally separate free areas.  The 8086
      free area is limited to <= 64k addressable by the DS regiser and
      uses 4 byte free queue elements (next,length).  The 370 free area
      extends from the end of 370 code to <= beginning of the E370 64k
      segment in high memory and uses 8 byte 370 format free queue elements
      (next,length) on 8 byte boundaries.  The first free queue element in
      a 370 address space is pointed to by ASCASF field in address space
      control block located at X'104' in low memory (may be zero if no free
      memory currently available).

Please send any suggestions for improving this documentation.