      
      
      
      
      
      
               4SEHIGH DESERT ENGINEERING
      
                               1630 So. Downs
                           Ridgecrest, Ca.  93555
                               (619)-375-83955QF
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                                   HDEBUG
                              TRS-80  MODEL 4
                               DEBUG/MONITOR
                                      
                                      
                                      
                                      
                                      
                                      
                                      
                          RELEASE TO PUBLIC DOMAIN
                                      
      HDEBUG and its  documentation  were  released  for  free  public
      distribution on Jan. 2, 1987 and is not for resale. This program
      and its documentation remain to be the property of  High  Desert
      Engineering.  For any information regarding this program or  its
      release, please contact the author at the above address.
      
      
                                             D. A. Bymoen
      
















      HDEBUG Operating Instructions                             Page 1

                   E********  -INDEX TO HDEBUG-  ********F
      
      
      INTRODUCTION TO HDEBUG  ---------------------------------  2
      
      INSTALLING AND USING HDEBUG  ----------------------------  3
      
      COMMAND LEVEL INSTRUCTIONS  -----------------------------  5
      
      MATH COMMAND INSTRUCTIONS  ------------------------------  10
      
      PROGRAM EXECUTION COMMANDS  -----------------------------  12
      
      SCREEN DISPLAY COMMANDS  --------------------------------  14
      
      BREAKPOINT CONTROL COMMANDS  ----------------------------  17
      
      DISASSEMBLER COMMANDS  ----------------------------------  21
      
      










































      HDEBUG Operating Instructions                             Page 2

                E********  -INTRODUCTION TO HDEBUG-  ********F
      
      HDEBUG is a very powerful machine language debug/monitor that is
      designed for use by the serious  assembly  language  programmer.
      HDEBUG is designed for use with the TRS-80 Mod  IV.  HDEBUG  for
      the TRS-80 Mod IV is compatible with TRSDOS 6.x and DOSPLUS  IV.
      Compatibility with other DOS's has not been verified.  It is not
      compatible with CP/M.
      
      HDEBUG has features that allow the assembly language  programmer
      to perform  complex  debug  procedures  that  are  difficult  or
      impossible with  other  debugs  or  monitors.    Some  of  these
      features are as follows:
      
          1.   Setting of up  to  ten  breakpoints  with  up  to  five
               different modes.
      
          2.   Automatic trace of a user program, with optional output
               to a printer or file.
      
          3.   Powerfull locate, compare, and modify features.
      
          4.   Execute DOS commands without losing HDEBUG control.
      
          5.   Disassembly of a users program.
      
          6.   Determine load and transfer address of /CMD files.
      
          7.   Allows saving users program video display.
      
          8.   Perform math or boolean operations while in debug mode.
               
          9.   Convert HEX to DECIMAL and DECIMAL to HEX.
      
          10.  Save HDEBUG configuration for easy setup or for a later
               debug session.
      
      Significant effort has gone into making HDEBUG user friendly and
      easy to operate without  sacrificing  power  or  utility.    Any
      comments or suggestions from users are welcome  and  an  attempt
      will be made to  incorporate  good  suggestions  into  the  next
      release of HDEBUG.
      
      High  Desert  Engineering  will  tailor  HDEBUG  to  most    any
      application a user may wish.  If  it  is  desired  to  obtain  a
      version tailored  to  a  specific  job  or  application,  please
      contact us for more information.  There may be a small  fee  for
      this service.














      HDEBUG Operating Instructions                             Page 3

             E********  -INSTALLING AND USING HDEBUG-  ********F
      
      Three versions of HDEBUG  have  been  assembled.    One  version
      (HDEBUGO/CMD) uses a system of overlays to conserve memory.   Of
      the other two versions, one loads in  high  memory  (HDEBUG/CMD)
      and the other loads in low memory (HDEBUGL/CMD). All versions of
      HDEBUG have the same power and  capability.    The  user  simply
      needs to select the version  appropriate  for  the  application.
       Only the high memory version has  been  formally  released  for
      free public availability.  If a user desires one  of  the  other
      versions it will be necessary to contact HDE at the  address  on
      the cover page.
      
      To invoke HDEBUG/CMD  from  the  DOS  prompt,  type  in  "HDEBUG
      <ENTER>". The same procedure is applicable to the other versions
      of HDEBUG.  HDEBUG uses approximately 10K bytes of memory.   For
      large application programs  it  may  be  necessary  to  use  the
      overlay version  of  HDEBUG.  This  version  uses  a  system  of
      overlays to minimize the memory requirements needed  to  perform
      all the HDEBUG functions.  This will  slow  the  performance  of
      certain commands as it requires a disk  operation  to  load  the
      particular overlay.  The disk with the HDEBUG overlays  must  be
      resident in one drive  for  correct  operation  of  the  overlay
      version. Transfering the overlays to MEMDISK makes  access  much
      faster.
      
      When HDEBUG is executed, it loads a  configuration  file  called
      HDEBUG/CNF.  This initializes the HDEBUG configuration.  If  the
      configuration file does not exist, HDEBUG will give the  message
      "FILE NOT FOUND". Any allowable configuration can  be  saved  in
      this or other configuration file, for the users desired  default
      or  alternate  configuration.  A  user  configuration  file   is
      generated with the SAVE command.
      
      HDEBUG  has  two  command  modes,  the  EXTENDED  mode  and  the
      IMMEDIATE mode.  The default is  the  EXTENDED  mode.    In  the
      EXTENDED mode all commands must be terminated with <ENTER>.   In
      the IMMEDIATE mode all commands are immediately  executed  by  a
      single keystroke.  The IMMEDIATE mode is  used  primarily  while
      manually single stepping through a program.  The IMMEDIATE  mode
      is utilized by holding the <CLEAR> key down while  pressing  the
      desired key.
      
                           EXAMPLE:  <CLEAR> <I>
      
      This executes a single Z-80 instruction.  All  commands  can  be
      executed from the  EXTENDED  mode,  but  only  single  character
      commands may be executed from the IMMEDIATE mode.  Commands  may
      be entered in either upper or  lower  case.    Unless  otherwise
      indicated, all commands are entered at the prompt "HDEBUG>>".
      
      The HDEBUG commands are outlined in the following sections. They
      are grouped according to type  and  are  in  alphabetical  order
      within each type.  In general  if  an  option  or  parameter  is
      specified by the command it will be required.  If it is enclosed
      by "[ ]" it is optional and the  command  will  have  a  default
      parameter.  The user  is  encouraged  to  experiment  with  each





      HDEBUG Operating Instructions                             Page 4

      instruction or  command  until  its  operation  or  function  is
      understood.
      
      When a parameter is specified  such  as  "dddd"  for  data,  the
      number of characters within the quotes is normally  the  maximum
      number  of  characters  that  HDEBUG  will  process.    If  more
      characters are entered, HDEBUG will either reject the command or
      will only process the last characters entered.  As  an  example,
      if for address "aaaa" the number "01D03A"  was  entered,  HDEBUG
      would process it as "D03A" (hex).
      
      All numbers used with HDEBUG command and display  modes  are  in
      hexidecimal.   To  assist  the  user,  conversion  routines  are
      included for converting to decimal and back again.  HDEBUG  also
      includes math utilities that allow the user  to  add,  subtract,
      multiply, or divide hexidecimal numbers.  Boolean math functions
      are also included for OR, AND, and XOR.
      
      When HDEBUG  is  activated  the  user  will  notice  an  "ALIVE"
      indicator in the upper right cornor.  While  this  indicator  is
      working, HDEBUG is alive and well.  If a situation occurs  where
      control has been lost by HDEBUG and the user  wishes  to  regain
      control, press <SHIFT> <F1>.  This will normally  regain  HDEBUG
      control if the "ALIVE" indicator is operating.
      
      For many applications it  is  necessary  to  know  where  HDEBUG
      resides in memory.  It is easy to determine by using the "CHECK"
      command.  This will give the user the exact load address for any
      version of HDEBUG or its overlays.
      
                         EXAMPLE: CHECK HDEBUGO/CMD
      
      This gives the load address of the overlay  version  of  HDEBUG.
      The same procedure applys for the load  address  of  the  HDEBUG
      overlays.
      
      HDEBUG honors HIGH$ memory.  If for some reason HDEBUG  violates
      HIGH$ it will not execute.  If this happens, it  is  recommended
      the user reboot to be certain of clean, error free operation. 























      HDEBUG Operating Instructions                             Page 5

              E********  -COMMAND LEVEL INSTRUCTIONS-  ********F
      
      CHECK = FILE LOAD ADDRESS -       " CHECK filename/ext "
      
          Displays  the  load  and  transfer  addresses  of  the  file
          "filename/ext".  The file is not  loaded  into  memory.  The
          load and transfer address and any text  headers  present  in
          the file are displayed.  This  command  does  not  work  for
          ASCII files.
      
      CLOSE = CLOSE OPEN FILES --       " CLOSE "
      
          Closes any files that have been opened by the ROUTE command.
          HDEBUG only supports one FCB, therefore only one  OPEN  file
          at a time is allowed.
      
      CM = COMPARE MEMORY -------       " CM adr1 adr2 " 
      
          Compare two areas of memory and display  their  differences.
          The differences are displayed in the  split  screen  display
          mode. The upper screen displays the area of memory  relative
          to "adr1" and the lower screen displays the area  of  memory
          relative to "adr2".  Refer to the Screen Display section for
          more details on the screen display modes.
      
                           EXAMPLE:  CM 3000 4000
      
          Compares the memory beginning at address  3000  with  memory
          beginning at address 4000.  The  first  difference  will  be
          displayed.  To continue the search after the display,  press
          <SPACEBAR>.  To return to the  HDEBUG  command  mode,  press
          <BREAK>.
      
      DOS = EXECUTE DOS COMMAND ---     " DOS doscommand "
      
          Allows the use of DOS commands or  library  functions  while
          remaining in HDEBUG.  Other /CMD files may  be  executed  as
          long as they terminate with a return function  the  same  as
          the DOS  library  functions.    See  the  Mod  IV  Technical
          Reference Manual for correct procedures and techniques.
      
                            EXAMPLE:  DOS DIR :1
      
          Displays the directory of disk drive #1.
      
      E = EXIT TO DOS -------------     " E "
      
          Exit to DOS.   Leaves  HDEBUG  active  with  all  parameters
          unchanged.  Open files are not closed.    To  regain  HDEBUG
          control press <SHIFT> <F1>.
      
                                 -CAUTION-
      
          It is possible for application programs to load over HDEBUG.
          If this  happens,  an  error  will  result  when  HDEBUG  is
          reactivated.






      HDEBUG Operating Instructions                             Page 6

      FM = FILL MEMORY ------------     " FM bbbb eeee dd "
      
          Fills memory beginning  at  address  "bbbb"  and  ending  at
          address "eeee" with data "dd".
      
      
                         EXAMPLE:  FM 3000 3FFF 00
      
          Fills memory beginning at address 3000 and ending at address
          3FFF with data 00.  
      
                                 -CAUTION-
      
          HDEBUG makes no checks of the "fill" memory area to  prevent
          overwriting HDEBUG or other programs in memory.
      
      IN = INPUT FROM PORT --------     " IN pp "
      
          Inputs data from port "pp" and displays the data.
      
      LA = LOCATE ASCII string ----     " LA aaaa asciistring "
      
          Locate a ascii string in memory.  Enter the search beginning
          address followed by the string to locate.  Where  "aaaa"  is
          the beginning address for the search  and  "asciistring"  is
          the ascii string to be searched for.
      
                       EXAMPLE: LA 1234 Hello there 
      
          Locates ascii string "Hello there".  The search  will  begin
          at memory address "1234".    All  locations  of  this  ascii
          string will be displayed, up to a maximum of 255  locations.
          NOTE: A match will always  be  found  at  the  HDEBUG  input
          buffer area if it is  located  above  the  search  beginning
          address.
      
      LH = LOCATE HEX string ------     " LH aaaa hexstring "
       
          Same as "LA" except used to locate HEX strings. 
      
      LOAD = LOAD FILE ------------     " LOAD filename/ext "
      
          Loads file "filename/ext" into memory  for  execution  under
          control of HDEBUG. The load and transfer addresses  and  any
          text headers that may  be  present  in  the  /CMD  file  are
          displayed. The program counter is not  set  to  the  program
          transfer address.
      
                                 -CAUTION-
      
          This command does not  prevent  a  file  from  loading  over
          system memory or HDEBUG.  If there is any doubt about  where
          a program loads, first use the "CHECK" command.









      HDEBUG Operating Instructions                             Page 7

      MA = MODIFY ASCII -----------     " MA [aaaa] "
      
          Modify memory in ASCII mode.  A page  of  memory  containing
          the data at address "aaaa" is displayed.  The major  portion
          of the display will be  the  contents  of  the  memory  page
          displayed in HEX.  The right hand side of the  display  will
          be the ASCII equivalent of the hex display.  There  will  be
          two cursors.  One cursor will be indicating the HEX byte and
          the other will indicate the ASCII equivalent.   The  cursors
          can be moved with the  arrow  keys.    To  modify  a  memory
          location simply type in the correct data.  If the address is
          ommited from the input command line HDEBUG will  default  to
          the memory page specified for "View Area 1".
      
                             EXAMPLE:  MA 53EB
      
          Displays the contents of memory  beginning  at  5300.    The
          cursor appears over the first byte of the display  for  both
          hex and ascii.  To move the cursor to  the  address  desired
          press the appropriate arrow keys.  To modify the byte  under
          the cursor, type in the data.  To return to  HDEBUG  command
          mode, press <BREAK>.
      
      MH = MODIFY HEX -------------     " MH [aaaa] "
      
          Same as "MA" except in HEX.
      
      MM = MOVE MEMORY ------------     " MM bbbb eeee dddd "
      
          Moves memory contents beginning at address "bbbb" and ending
          at address "eeee" to destination address "dddd".  
      
                        EXAMPLE:  MM 3000 3FFF 5000
      
          Moves the contents of memory beginning at address  3000  and
          ending at address  3FFF  to  memory  location  beginning  at
          address 5000.
      
                                 -CAUTION-
      
          HDEBUG makes no checks of the  destination  memory  area  to
          prevent overwriting HDEBUG or other programs in memory.
      
      OUT = OUTPUT TO PORT --------     " OUT pp dd "
      
          Outputs data "dd" to port "pp".
      
      P = PRINT SCREEN ------------     " P "
      
          Press <P> to dump the screen contents  to  to  the  printer.
          This command is also available  within  the  subcommands  to
          provide an easy way of  documentating  the  users  displays.
          Pressing <P> at any time when HDEBUG has control  will  dump
          the screen contents to the printer.  Pressing  <SHIFT>  <F2>
          at any time the "ALIVE" indicator  is  operating  will  also
          dump the screen to the printer.
      





      HDEBUG Operating Instructions                             Page 8

      Q = QUIT  -------------------     " Q "
      
          Quit the debug session, deactivate HDEBUG, Exit to  DOS  and
          remove all HDEBUG hooks. All  breakpoints  are  cleared  and
          open files are closed.
      
      REG = SET REGISTER ----------     " REG pp dddd "
      
          Causes register pair "pp" to be set to "dddd".  
      
                           EXAMPLE: REG BC 1234 
      
          Sets register pair "BC" to the value "1234".
      
      RESET = RESET HDEBUG --------     " RESET [opt] [filespec] "
      
          Reset HDEBUG to initial default conditions by either loading
          a configuration file, or performing a software reset to  the
          program.  This will effectively restart  HDEBUG  for  a  new
          session.  The options are as follows:
      
               <none>    Default condition.  This reloads the  default
                         configuration file, HDEBUG/CNF.
               -I        Performs a software reset  on  HDEBUG.    All
                         parameters are  set  to  an  ititial  default
                         condition.
               filespec  Loads  a  user  defined  configuration  file,
                         named "filespec". If the  configuration  file
                         cannot be found, HDEBUG displays the  message
                         "FILE NOT FOUND".
      
      ROUTE = ROUTE TO FILE -------     " ROUTE  [filespec] "
      
          Routes printer output to a file.  If the file  specification
          is not included, the command defaults to CLOSE.   This  then
          closes any open files.  HDEBUG only supports one file FCB so
          only one open file at a time  is  allowed.    If  the  ROUTE
          option has been selected, it will be closed if a disassembly
          to a file is made.  Open files are closed  when  the  HDEBUG
          session is terminated with the "Q" command.
      
          This feature can be very  effectively  used  in  conjunction
          with a word processor or text editor. The created  file  can
          be loaded into the editor and the  locate  features  can  be
          used to find specific patterns.

















      HDEBUG Operating Instructions                             Page 9

      RUN = RUN PROGRAM -----------     " RUN filename/ext "
      
          Loads file "filename/ext" into memory  for  execution  under
          control of HDEBUG. Program initialization is the same as the
          DOS "RUN" command. The load and transfer addresses  and  any
          text headers that may  be  present  in  the  /CMD  file  are
          displayed. The  program  counter  is  set  to  the  transfer
          address so the user program  can  be  executed  by  the  "G"
          command.
      
                                 -CAUTION-
      
          This command does not  prevent  a  file  from  loading  over
          system memory or HDEBUG.  If there is any doubt about  where
          a program loads, first use the "CHECK" command.
      
      SAVE = SAVE CONFIGURATION ---     " SAVE [filespec] "
      
          Saves the current configuration to the file specified. If no
          HDEBUG configuration file  is  specified,  a  default  file,
          "HDEBUG/CNF" is saved.  When HDEBUG is  initially  executed,
          the file HDEBUG/CNF will be automatically loaded.   To  load
          a configuration  other  than  the  default,  use  the  RESET
          command. 
      
          NOTE:  If no file extension has been specified, TRSDOS  will
          add the extension "/LMF".
      
      STAT = HDEBUG STATUS --------     " STAT "
      
          Display the current command  status  of  HDEBUG.    This  is
          useful if the user is not  certain  of  the  current  HDEBUG
          configuration.  HDEBUG configuration  can  be  saved  for  a
          later debug session  by  the  SAVE  command.  When  a  debug
          session is restarted, a saved configuration  can  be  loaded
          using the RESET command and the debug session continued. 


























      HDEBUG Operating Instructions                            Page 10

              E********  -MATH COMMAND INSTRUCTIONS-  ********F
      
      ADD = ADD NUMBERS -----------     " ADD num1 num2 "
      
          Add numbers "num1" and "num2" and display  the  sum.    This
          command is for hex numbers only.  The input, num1 and  num2,
          must be less than FFFF hex.  If the result is  greater  than
          FFFF hex, the result displayed is the excess over 10000 hex.
          
      AND = AND NUMBER ------------     " AND num1 num2 "
      
          Perform a boolean AND function on the hex numbers "num1" and
          "num2" and display the result.
      
      COMP = COMPLEMENT NUMBER ----     " COMP [opt] nnnn "
      
          Complement the number "nnnn" and display the  result.    The
          following options apply:
      
               <none>    Default mode.    This  considers  the  number
                         "nnnn" an unsigned number. 
               -T        This mode considers the number "nnnn"  to  be
                         in two's complement form.  This command  then
                         changes the sign of the hex number "nnnn".
      
      DH = DECIMAL to HEX ---------     " DH [opt] ddddd "
      
          Converts the input decimal number "ddddd" to hexidecimal and
          display the result.  The following options apply:
      
               <none>    Default mode.  Conversion is  performed  with
                         no  sign.    All  numbers   are    considered
                         positive.  In this mode, the largest  decimal
                         number that may  be  input  is  65535.    Any
                         larger number is displayed as the excess over
                         65536.
               -T        Selects two's complement mode.  This converts
                         the two's complement decimal number  to  hex.
                         In this mode, the  largest  positive  decimal
                         number that may  be  input  is  32767.    Any
                         larger  positive  number  is  displayed    as
                         negative. The largest  negative  number  that
                         may be input is -32768.
      
                           EXAMPLE:  DH -T -21345
      
               Converts the number -21345 (decimal) to AC9F (hex).
      
      HD = HEX to DECIMAL ---------     " HD [opt] hhhh "
      
          Converts the input hexidecimal number "hhhh" to decimal  and
          displays the result.  The following options apply:
      
               <none>    Default mode.  Conversion is  performed  with
                         no  sign.    All  numbers   are    considered
                         positive.  In  this  mode,  the  largest  hex
                         number that may be input is FFFF.  Any larger





      HDEBUG Operating Instructions                            Page 11

                         number is displayed as the excess over  10000
                         (hex).
               -T        Selects two's complement mode.  This converts
                         the two's complement hex number  to  decimal.
                         In this mode,  the  largest  positive  number
                         that may be input is 7FFF (hex).  Any  larger
                         positive number is displayed as negative. The
                         largest negative number that may be input  is
                         8000 (hex). 
      
                            EXAMPLE:  HD -T D734
      
               Converts the number D734 (hex) to -10444 (decimal).
      
      LR = LAST RESULTS -----------     " LR "
      
          Displays the results of the last math operation.
      
      OR = OR NUMBER --------------     " OR num1 num2 "
      
          Perform a boolean OR function on the hex numbers "num1"  and
          "num2" and display the result.
      
      SUB = SUBTRACT NUMBERS ------     " SUB num1 num2 "
      
          Subtract "num2" from "num1" and display the  result.    This
          command is for hex numbers only.  The input, num1 and  num2,
          must be less than FFFF hex.  If the result is less than zero
          the result is a two's complement negative number.
      
      XOR = EXCLUSIVE OR NUMBERS --     " XOR num1 num2 "
      
          Perform a boolean XOR function on the hex numbers "num1" and
          "num2" and display the result.




























      HDEBUG Operating Instructions                            Page 12

              E********  -PROGRAM EXECUTION COMMANDS-  ********F
      
      B = BUMP PROGRAM COUNTER ----     " B  "
      
          Step the program counter to  the  next  instruction  without
          executing the instruction.
      
      C = CALL --------------------     " C "
      
          Same as "I" command except a complete subroutine "CALL" will
          be executed. If the instruction is not a "CALL" then  HDEBUG
          will default to the single step, "I", mode.  When the  TRACE
          mode has been selected HDEBUG will perform a continuous  "C"
          command.  See the TRA command for more detail on  the  TRACE
          mode.
      
      G = GO ----------------------     " G [aaaa] "
      
          Causes execution to be started at the address specified.  If
          address "aaaa" is not specified, HDEBUG will default to  the
          current program counter address.
      
      I = INCREMENT ---------------     " I "
      
          Single step or "INCREMENT" through a program.  This executes
          the instruction at the program counter and  returns  control
          to HDEBUG.  The display is updated after each "I".  When the
          TRACE mode is selected HDEBUG will continuously single  step
          the users program.  See the TRA command for more  detail  on
          the TRACE mode.
      
      J = JUMP --------------------     " J [aaaa] [bkp10] [bkp11] "
      
          Causes execution to be started at  address  "aaaa"    If  no
          address is input HDEBUG will default and begin execution  at
          the current program counter address.   This  command  allows
          the  setting  of  two  temporary  breakpoints  "bkp10"   and
          "bkp11". If no address or breakpoints are input this command
          defaults to the "G" command.  If it is desired to allow  the
          address "aaaa" to default to  the  current  program  counter
          while specifying a breakpoint, enter a ",".
      
                         EXAMPLE:  J 3456 4567 5678
      
          Jump to address 3456 with temporary breakpoints set at  4567
          and 5678.
      
                           EXAMPLE:  J A3E5 A500
      
          Jump to address A3E5 with  a  temporary  breakpoint  set  at
          A500.
      
                          EXAMPLE:  J , 5000 5500
      
          HDEBUG begins execution at the current program counter  with
          temporary breakpoints set at 5000 and 5500.
      





      HDEBUG Operating Instructions                            Page 13

          LIMITATIONS: The temporary breakpoints  specified  with  the
          "J" command are  cleared  at  the  FIRST  encounter  of  ANY
          breakpoint.  This means if any breakpoint (bkpt 0-9), is hit
          before BKPT10 or BKPT11 are hit, then BKPT10 and BKPT11  are
          cleared at that time.  When execution continues to the point
          where BKPT10 or 11 were set, execution will not  be  halted.
          BKPT10 & 11 will have already been cleared.  BKPT10 & 11 are
          normally used for the TRACE, Increment and Call modes.
      
      TRA = AUTO TRACE ------------     " TRA [opt] "
      
          Sets HDEBUG to the automatic "TRACE" execution  mode.    The
          next "I" or "C" command will cause HDEBUG  to  automatically
          execute "I" or "C" commands.  It will  continue  to  perform
          automatic program trace until a  breakpoint  with  a  "STOP"
          mode is reached or the user presses <BREAK>.  The  following
          options apply:
      
               <none>    Default mode.  Defaults to the -S mode.
               -S        Sets the HDEBUG "TRACE" execution mode.
               -R        The same  as  -S  except  the  registers  are
                         output to the printer for a hardcopy  of  the
                         trace.
               -P        The same as the  -S  mode  except  the  whole
                         screen is output to the printer.
               -X        Clears the "TRACE" execution mode.




































      HDEBUG Operating Instructions                            Page 14

               E********  -SCREEN DISPLAY COMMANDS-  ********F
      
      CLS = CLEAR DISPLAY ---------     " CLS "
      
          Clears the HDEBUG display.   This  should  not  normally  be
          necessary, however, sometimes the HDEBUG display can  become
          garbled.  This completely clears the screen so  that  HDEBUG
          or the user program can write to a clean video display.
      
      D = VIEW USER DISPLAY -------     " D "
      
          Restores the user video display for temporary viewing.  This
          command is the same as "DSP -V".   The  main  difference  is
          this command allows viewing the user video display from  the
          IMMEDIATE command mode.
      
      DSP = SAVE USER DISPLAY -----     " DSP [opt] [aaaa] "
      
          Saves the user or application display  when  HDEBUG  regains
          control from  the  user  program.    If  this  mode  is  not
          selected, the user program video display is lost when HDEBUG
          outputs its video display.  When this mode is  selected  the
          user display is saved and may be viewed under the control of
          HDEBUG.  The options are as follows:
      
               <none>    Default mode.  Defaults to the "-S" option.
               -S        This option  saves  the  application  program
                         display at the memory location  specified  by
                         the user.  The address of the  save  location
                         may be examined by the "STAT" command.
               -C        Clears the user display save area.
               -V        View the user program display.  To return  to
                         the HDEBUG command mode press any  key.    To
                         get a print out of the display press "P".
               -X        Cancels the "DSP" mode and  clears  the  save
                         display memory area.
               aaaa      The user specified save display memory  area.
                         The address "aaaa" is any  valid  address  in
                         memory and is the low address of a 1920  byte
                         block.  
      
                            EXAMPLE: DSP -S A000
      
          Activates the Save Display feature  with  the  save  display
          area beginning at address A000.
      
                                 -CAUTION-
      
          HDEBUG will accept any address, even in the DOS overlay area
          or  within  HDEBUG  itself.    Incorrectly  specifying  this
          address will cause incorrect operation.
      
      F = FULL SCREEN DISPLAY -----     " F [adr1] "
      
          Sets the upper screen or "View Area 1" to  the  full  screen
          mode, displaying memory at address "adr1".  If  the  address
          is not specified  HDEBUG  will  default  to  the  previously





      HDEBUG Operating Instructions                            Page 15

          specified "View Area 1" address.  The view register mode "R"
          is canceled by this command.
      
      F1 = FULL SCREEN DISPLAY ----     " F1 [adr1] "
      
          Same as " F " except it specifically applies to memory "View
          Area 1".
      
      F2 = FULL SCREEN DISPLAY ----     " F2 [adr2] "
      
          Same as " F1 " except it applies to memory "View Area 2".
      
      R = VIEW REGISTER MODE ------     " R [opt] "
      
          Configures HDEBUG to view  or  display  the  Z-80  registers
          only. The normal screen video memory  display  is  canceled.
          The main advantage of this mode is much faster execution  of
          HDEBUG and better viewing  of  the  user  application  video
          without invoking the "DSP" mode. The options are as follows:
          
               <none>    Default mode. Defaults to the "-S" option.
               -S        Sets the view register mode.
               -U        Update the memory display.  This displays the
                         memory  according  to  the  display    format
                         selected  previously  by  the  "F"  or    "S"
                         commands.
               -X        Cancels  the  View  Register  mode  and  sets
                         HDEBUG back to the normal display mode.  This
                         View Register mode will also be  canceled  by
                         any  command  that  reconfigures  HDEBUG   to
                         display either full or split screen mode.
      
      S = SPLIT SCREEN DISPLAY ----     " S [adr1] [adr2] "
      
          This is the default display mode that is activated by "RESET
          -I".    This  displays  two  memory  view  areas  that   are
          controlled by the "S1" & "S2" commands.  If addresses "adr1"
          and "adr2" are ommitted,  the  previously  specified  memory
          "View Areas" are displayed.  The view register mode  "R"  is
          canceled by this command.
      
      S1 = SET UPPER SCREEN -------     " S1 [adr1] "
      
          Set upper screen to display memory  for  "View  Area  1"  at
          address  "adr1".    If  address  "adr1"  is  ommitted,   the
          previously specified memory "View Areas" are displayed.  The
          view register mode "R" is canceled by this command.
      
      S2 = SET LOWER SCREEN -------     " S2 [adr2] "
      
          Set lower screen to display memory  for  "View  Area  2"  at
          address  "adr2".    If  address  "adr2"  is  ommitted,   the
          previously specified memory "View Areas" are displayed.  The
          view register mode "R" is canceled by this command.








      HDEBUG Operating Instructions                            Page 16

      T = TOGGLE DISPLAY ----------     " T "
      
          Swaps or toggles the screen display for "View Area  1"  with
          "View Area 2".  The view register mode "R"  is  canceled  by
          this command.
      
      U = UPDATE DISPLAY ----------     " U "
      
          Continuously updates the display.  This is used primarily to
          view changes in memory under the control  of  an  interrupt.
          The display is in the full screen display mode and is  "View
          Area 1".  The display may be scrolled through memory by  ";"
          and "-" commands.
      
      Y = REG. POINTER DISPLAY ----     " Y [adr1] "
      
          This selects the video display utilizing the register  pairs
          as pointers to memory.  Six additional lines of  memory  are
          displayed  from  address  "adr1".    If  address  "adr1"  is
          ommitted, the previously specified memory for "View Area  1"
          is displayed. The view register mode "R" is canceled by this
          command. 
      
      ; = SCROLL POSITIVE ---------     " ; "
      
          Scrolls "View Area 1" memory display positive.
      
      - = SCROLL NEGATIVE ---------     " - "
      
          Scrolls "View Area 1" memory display negative.
      
      + = SCROLL POSITIVE ---------     " + "
      
          Scrolls "View Area 2" memory display positive.
      
      = = SCROLL NEGATIVE ---------     " = "
      
          Scrolls "View Area 2" memory display negative.
























      HDEBUG Operating Instructions                            Page 17

             E********  -BREAKPOINT CONTROL COMMANDS-  ********F
      
      CB = CLEAR BREAKPOINT -------     " CB # "
      
          Clears the breakpoint indicated by "#", where "#" represents
          a breakpoint number from 0-9 or "-A"  for  all  breakpoints.
           
      
      CH = CLEAR HIT COUNTER ------     " CH # " 
      
          Clears the breakpoint HIT counter indicated  by  "#",  where
          "#" represents a breakpoint number from 0-9 or "-A" for  all
          breakpoints.  This command sets the breakpoint HIT  counters
          to 0.
      
      DB = DISPLAY BREAKPOINTS ----     " DB [opt] "
      
          This command will display the breakpoints according  to  the
          option selected.  The options are as follows:
      
               <none>    Defaults to "-A"
               -A        Display all breakpoints
               #         Where "#" represents a breakpoint number from
                         0-9.
      
          If a breakpoint has not been set it  will  be  displayed  as
          "CLEAR".  The display for each set breakpoint will have  the
          following form:
      
               aaaa oo m ssss hhhh           aaaa = address
                                             oo   = op-code
                                             m    = mode
                                             ssss = SET count (hex)
                                             hhhh = HIT count (hex)
      
               aaaa      The address of the breakpoint.  This  address
                         must  be  the  first  byte  of    the    Z-80
                         instruction.
               oo        The op-code of the Z-80 instruction where the
                         breakpoint is set.
               m         The mode of the breakpoint.  These modes  are
                         as follows:
      
                         S         STOP  -  Stop  at  breakpoint  hit.
                                   Halts program execution at  address
                                   "aaaa"  and  returns  control    to
                                   HDEBUG.
                         C         CONTINUE - Stops program  execution
                                   when  the  HIT  count  (hhhh)    is
                                   greater than or equal  to  the  SET
                                   count (ssss).  Control is  returned
                                   to  HDEBUG  and  the  display    is
                                   updated only after the SET count is
                                   reached.
                         D         DISPLAY -  Same  as  the  "C"  mode
                                   except the display  is  updated  at
                                   each breakpoint hit.





      HDEBUG Operating Instructions                            Page 18

                         R         PRINT REGISTERS - Same as  the  "D"
                                   mode  except  the  registers    are
                                   dumped  to  the  printer  at   each
                                   breakpoint hit.
                         P         PRINT SCREEN - Same as the "D" mode
                                   except the entire screen is  dumped
                                   to the printer at  each  breakpoint
                                   hit.
      
               ssss      The breakpoint SET count in hexidecimal. This
                         count represents  the  number  of  times  the
                         breakpoint will be hit  before  execution  is
                         halted.    See  the  "SB"  command  for  more
                         information on the SET count.
               hhhh      The breakpoint HIT  count.    The  number  of
                         times  a  breakpoint  has  been  hit   during
                         program execution.   When  "hhhh"  equals  or
                         exceeds "ssss",  program  execution  will  be
                         halted and control is regained by HDEBUG.
      
          After the breakpoints are displayed a hard copy can be  made
          by pressing "P".
      
      SB = SET BREAKPOINT ---------     " SB # aaaa [m] [ssss] "
      
          The following options apply:
      
               #         Represents the breakpoint number ranging from
                         0-9.
               aaaa      Address where breakpoint is to be set.   This
                         must be the address of the first byte of  the
                         Z-80 instruction.
               m         Sets the mode of a breakpoint.    If  omitted
                         the mode defaults  to  "S".    The  following
                         modes may be set:
      
                         <none>    Default setting.  Defaults to "S".
                         S         STOP  -  Stop  at  breakpoint  hit.
                                   Halts execution at  address  "aaaa"
                                   and returns control to HDEBUG.
                         C         CONTINUE - Stops program  execution
                                   when  the  HIT  count  (hhhh)    is
                                   greater than or equal  to  the  SET
                                   count (ssss).  Control is  returned
                                   to the  user  and  the  display  is
                                   updated only after the SET count is
                                   reached.
                         D         DISPLAY -  Same  as  the  "C"  mode
                                   except the display  is  updated  at
                                   each breakpoint hit.
                         R         PRINT REGISTERS - Same as  the  "D"
                                   mode  except  the  registers    are
                                   dumped  to  the  printer  at   each
                                   breakpoint hit.








      HDEBUG Operating Instructions                            Page 19

                         P         PRINT SCREEN - Same as the "D" mode
                                   except the entire screen is  dumped
                                   to the printer at  each  breakpoint
                                   hit.
      
               ssss      Sets count for the breakpoint SET count.  The
                         breakpoint HIT counter  is  incremented  each
                         time a breakpoint is hit.  When the HIT count
                         (hhhh),  equals  or  exceeds  the  SET  count
                         (ssss), then HDEBUG halts  execution  of  the
                         application program.  Setting (ssss) equal to
                         zero prevents HDEBUG from  halting  the  user
                         program at any HIT count.  A SET count  equal
                         to zero is the equivilant of a SET  count  of
                         infinity.  This option applies  only  to  the
                         continuous modes (C, D, R and P) and does not
                         apply to the "STOP" mode (S). If no SET count
                         is entered, it is default to zero.  NOTE: SET
                         count and HIT count are in hex.
      
      
                     EXAMPLE: SB 1 8000 D 0100 <enter>
      
          This sets "breakpoint one" to address "8000"  with  the  "D"
          mode (update display at each hit) and the SET count to  100.
          Note that the SET count is in hex.  If  a  "breakpoint  one"
          was previously set, it will be cleared before the new one is
          set. Duplicate breakpoints  are  not  allowed  and  will  be
          prompted to the user as an entry error.
      
      SM = SET BREAKPOINT MODE ----     " SM # m "
      
          Where # represents a  breakpoint  number  from  0-9.    This
          command sets the breakpoint mode to "m".  Refer to the  "SB"
          and "DB" commands for more details  and  definition  of  the
          mode (m).
      
      SS = SET "SET" COUNT --------     " SS # ssss "
      
          Where # represents a  breakpoint  number  from  0-9.    This
          command sets the breakpoint SET counter to "ssss".  Refer to
          the "SB" and "DB" commands for more details  and  definition
          of the SET count (ssss).
      
      STOPPING EXECUTION
      
          User program  execution  may  be  stopped  by  pressing  the
          <BREAK> key.  This causes HDEBUG to stop  program  execution
          the next time a breakpoint is hit.  This is the only way  to
          stop program execution if a SET count of  "0"  was  selected
          when a breakpoint was set.   If no breakpoints are active or
          if the users program is executing in an area of memory where
          no breakpoints are set, this feature will not work.
      
          At times the user will not be able to regain HDEBUG  control
          by the above method.  This happens primarily when a  routine
          is executing in an area of memory where no  breakpoints  are





      HDEBUG Operating Instructions                            Page 20

          set.  HDEBUG utilizes  a  method  of  interacting  with  the
          keyboard driver to allow the user to regain control. Control
          is regained by pressing <SHIFT> <F1>.  
      
          NOTE: The above procedure will  work  only  if  the  "ALIVE"
          indicator is operating.  If the  "ALIVE"  indicator  is  not
          operating HDEBUG will have to  be  reloaded  and  the  debug
          session will have to be started over.    The  user  is  also
          cautioned against trying to  regain  HDEBUG  control  during
          disk I/O.
      
      ADDITIONAL BREAKPOINT NOTES
      
          When using the "J" command two additional breakpoints can be
          set.    These  additional  breakpoints  are  one  time  only
          breakpoints  and  will  be  automatically  cleared  whenever
          HDEBUG regains control or if ANY breakpoint is hit. 
      
          Breakpoints must be set after a file is  loaded  to  memory.
          Breakpoints set previous to a "LOAD" may be invalid.  HDEBUG
          checks the validity of all set breakpoints.  If HDEBUG finds
          an invalid breakpoint it will not allow the user to  execute
          any of  the  "PROGRAM  EXECUTION  COMMANDS".    It  will  be
          necessary to correct the error before HDEBUG will allow  the
          user to continue the debug session.
      
          Because of the method used to  handle  breakpoints  and  the
          single step "I" and "C" commands, it is  necessary  for  the
          user to avoid any instructions that loop back on themselves.
          
                      EXAMPLE:      SELF   JP    SELF
                      EXAMPLE:      SELF   DJNZ  SELF
      
          HDEBUG cannot halt execution on any instruction that  points
          to itself.  Control will be lost and may not be regained.
      
      BREAKPOINT DISPLAY ON HIT
      
          When a breakpoint is hit with options S, D, R or P set,  the
          screen display will be updated and the  breakpoint  will  be
          displayed in the lower part of the screen.





















      HDEBUG Operating Instructions                            Page 21

                E********  -DISASSEMBLER COMMANDS-  ********F
      
      Two lines of disassembled Z-80 code are displayed on the  bottom
      right of the screen.  The upper is the last instruction executed
      under the control of HDEBUG.  The bottom is the next instruction
      to be executed under the control of HDEBUG. The primary  use  of
      this feature is for single stepping through  a  program.    Each
      instruction is then displayed as it is executed.    Additionally
      the user can use the disassembler to disassemble  a  program  in
      memory.  The  following  commands  will  output  a  disassembler
      listing to either the display, printer or file.
      
      DASM - DISASSEMBLE -------   " DASM [opt] bbbb [eeee] [file] "
      
          Disassemble object code  beginning  at  address  "bbbb"  and
          ending at address "eeee".  If the ending address  "eeee"  is
          omitted, HDEBUG will continue the disassembly to the end  of
          memory.  Pressing <BREAK> at any time will cause disassembly
          to stop.  The disassembler options are as follows:
      
               <none>    Default mode.  Defaults to the -S mode.
               -S        The disassembled output is displayed  on  the
                         screen,  one screen at a time.  To  continue,
                         press <SPACE>, to stop press <BREAK>.
               -P        Sends the disassembler output to the printer.
                         To stop, press <BREAK>.
               -F        Sends the disassembler output to a file.   If
                         the -F option is selected,  a  file  must  be
                         specified.    If  the  ROUTE  mode  has  been
                         previously selected, a CLOSE command will  be
                         automatically  executed  before   disassembly
                         will begin.  HDEBUG only  supports  one  OPEN
                         file.
               bbbb      Beginning address of the disassembly.
               eeee      Ending address of the disassembly.    If  the
                         ending address is not specified, HDEBUG  will
                         disassemble to the end of memory.  If the  -F
                         mode has been selected,  the  ending  address
                         may be omitted if a "," is used.
               file      Destination file spec. for  the  disassembled
                         code. The created file is in ASCII format and
                         can be loaded into most  word  processors  or
                         text  editors  for  modification  and   later
                         assembly.
      
                     EXAMPLE:   DASM -F F500 , JUNK/ASM
      
          This disassembles Z-80 code in memory beginning  at  address
          F500 and writes it to a file named  JUNK/ASM.    Disassembly
          will continue to the top of memory (FFFF), or until  <BREAK>
          is pressed.
      
                         EXAMPLE:   DASM 5678 6789
      
          Disassembles memory beginning at address 5678 and ending  at
          address 6789. The first column of the display is the address
          of the disassembled code.  The second column is the  op-code





      HDEBUG Operating Instructions                            Page 22

          for the instruction and the third  column  is  the  assembly
          language mnemonic.
      
      
      
      
      
      P
      TRS-80 and TRSDOS are a trademark of Tandy Corp.
      DOSPLUS is a trademark of Micro Systems Software, Inc.
      Q
      
      
      
      
      
      
      
      
      FINAL NOTE:
      The overlay  version  noted  in  this  manual  is  available  to
      interested users.  If a user desires this version, contact D. A.
      Bymoen at the address on  the  cover  page.    Any  comments  or
      information on suggested changes, usage, corrections or bugs  is
      welcome.
      
      
      
      
      
      
      
                          RELEASE TO PUBLIC DOMAIN
      
      
      HDEBUG and its  documentation  were  released  for  free  public
      distribution on Jan. 2, 1987 and is not for resale. This program
      and its documentation remain to be the property of  High  Desert
      Engineering. For any information regarding this program  or  its
      release, please contact the author at the address on  the  cover
      page.
      
      
                                             D. A. Bymoen
      

















                                                               