DEBUGMAN.TXT

       1. Debugger Reference Manual


            HI-TECH C is supplied  with  an  interactive  debugging
       tool  oriented toward C programs. It is not a "source level"
       debugger, i.e. it has no knowledge of  the  C  source  code,
       however it does have the facility to handle C symbols and to
       show the C function calling sequence.

            The command structure is modelled on that of  the  Unix
       debugger  known  as  adb.  It provides facilities to display
       memory in various radices or as  instructions,  to  set  and
       remove  breakpoints,  which may have a repeat count and/or a
       command associated with them. It is possible to set a break-
       point which will stop only if a certain condition is true.

            The debugger may be used on any .COM file,  however  in
       order  to  take  advantage of the symbolic facilities, it is
       necessary to generate a symbol file,  usually  with  the  -F
       option  to the C command. This file consists of one line per
       symbol, with the hexadecimal value of the  symbol  preceding
       the symbol on the line.

       1.1. Invoking Debug

            The debugger is invoked by the command  DEBUG.  It  may
       have  zero, one or two file arguments. The first argument is
       the name of a file in .COM format to be be debugged, and the
       second  a symbol file name. If the symbol file name is omit-
       ted, no symbols will be available. If the .COM  format  file
       is omitted, no code will be loaded. Some examples:

            DEBUG fred.com
            DEBUG bill.com l.sym


       1.2. Run Time Organization

            DEBUG relocates itself below the  BDOS  when  executed,
       allowing  the  debugee to be loaded at the start of the TPA,
       as usual. The symbol table, if loaded, grows downwards  from
       the  base of the relocated debugger. The BDOS entry at loca-
       tion 5 is changed to reflect the base of  the  symbol  table
       rather  than the base of the BDOS. Thus the symbol table and
       the debugger are not owerwritten by the debugee's stack.

            Breakpoints are inserted in the code as RST 8  instruc-
       tions. A jump is placed at location 8 to the debugger's trap
       handler. This is unfortunate if your system happens  to  use
       RST  8  for  interrupts, but this is probably no more likely
       than that it uses any other restart location.











   Page 2         HI-TECH C (Z80) USER'S MANUAL


   1.3. Commands

        The basic debugger command syntax is:

        address , count command modifier extrastuff


        This may seem a little obscure, so read on. Address and
   count are expressions, in their simplest form simply hexade-
   cimal numbers. Both address and count are optional,  but  if
   count  is  to  be  specified with no address, the comma must
   appear.

        Command is a single character specifying what the  com-
   mand  should  do. Modifier is another character which deter-
   mines more specifically what the command is.  Extrastuff  is
   dependent on the particular command, and is usually omitted.

   1.3.1. Expressions

        Expressions may consist of:

   .    The value of the current location (not necessarily  the
        current  PC  or  last  breakpoint,  this is an internal
        current value).

   SYMBOL
        The value of a symbol,  as  looked  up  in  the  symbol
        table.   If  the  symbol  is not found, the same symbol
        prepended by and underscore will be  looked  for.  This
        allows  C symbols to be referred to without the leading
        underscore tacked on by the compiler.

   INTEGER
        A hexadecimal integer. It must start with a digit, oth-
        erwise the debugger will think it is a symbol.

   <REGNAME
        This yields the contents of the specified Z80 register.
        The  register  names  are the usual Z80 names, in lower
        case only. See the $r command below.

   (EXPR)
        Parentheses may be uses to enclose expressions to force
        evaluation order.

   *EXPR
        The contents of the  word  at  address  EXPR.  This  is
        indirection analogous to the C indirection operator.

   -EXPR
        The negation of EXPR.











                      HI-TECH C (Z80) USER'S MANUAL          Page 3


       ~EXPR
            The bitwise complement of EXPR.

       E1+E2
            The sum of E1 and E2.

       E1-E2
            The value of E1 less the value of E2.

       E1*E2
            The value of E1 multiplied by E2.

       E1%E2
            E1 divided by E2.

       E1&E2
            E1 anded with E2.

            The usual precedence relationships  apply;  parentheses
       may be used to alter the order of evaluation.

       1.3.2. Command Characters

            The main command character used is /. This is  used  to
       display  memory  in  various radices or as instructions. The
       exact format is determined by the modifier character, or the
       previous  format  used if the modifier character is omitted.
       The modifiers are:

       i    Print as Z80 instructions

       h or b
            Print as hexadecimal bytes.

       o    Print as octal bytes.

       d    Print as decimal bytes.

       H or W
            Print as hexadecimal words.

       O    Octal words.

       D    Decimal words.

       c    Print each byte as an ascii character.

       C    Print as ascii characters if printable, as @x  if  not,
            where x is the corresponding alphabetic character, e.g.
            @C for 3.

       s    Print a string of characters up to a null.











   Page 4         HI-TECH C (Z80) USER'S MANUAL


   a    Print the address as a symbolic value.

        If address is specified, the display  starts  from  the
   specified address. Count bytes, instructions, words, strings
   or whatever will be printed, or 1 if count is  omitted.  For
   example:

        fred,10/b
        123/i

   The first command prints 16 bytes from the  address  of  the
   symbol fred.  The second displays one instruction from loca-
   tion 123H.

        When such a command is issued, the value of dot is tem-
   porarily incremented by the total number of bytes displayed.
   A subsequent command consisting solely of a RETURN  or  LINE
   FEED will make the temporary increment of dot permanent, and
   execute a / command. Thus RETURN may be used to  step  along
   in  memory, displaying memory in the same format as the last
   / command.

        The / command may also be used to alter memory. /w EXPR
   will  write  the  value  of  expr into memory at the current
   location (dot). Either a word or  a  byte  will  be  written
   depending on the last format used for a / command. A /w com-
   mand may not be issued if the current format is not  a  byte
   or  word type. Thus memory may not be modified in the i for-
   mat. One day there will be an in-line  assembler  built  in,
   but not yet.

        The ] command is like the /  command,  except  that  it
   displays  I/O  ports rather than memory. It may be used with
   only the h, b, o or d formats.  In addition, ]w may be  used
   to write to an I/O port.

        The $ command has various modifiers as described below:

   c    Print a C stack backtrace. Note that this is not  reli-
        able when used on an optimized program since the optim-
        izer changes stack manipulation code. There may  appear
        to be fewer arguments than there really are. Long argu-
        ments will always appear as two integer arguments.

   b    Display currently set breakpoints

   s    Set the limit for symbol matches to the given  address.
        This determines the maximum value of offset when print-
        ing out a value as sym+offset.

   w    Set the terminal width to address. The  default  is  80
        decimal.











                      HI-TECH C (Z80) USER'S MANUAL          Page 5


       r    Display the contents of all Z80 registers.

            The : command has the following modifiers:

       r    Run the program from address. If  address  is  omitted,
            try  for  the  symbol  start.  If  it is not found, the
            debugger will complain. With this  command,  extrastuff
            will  be supplied as an argument string to the program,
            i.e. in the default buffer at 80H.  You  should  ensure
            there is a space between the r and extrastuff. E.g.:

                        100:r arg1 arg2

       c    Continue the program from address, or the  contents  of
            PC if address is omitted. Used after a breakpoint.

       s    As for c, but execute only count instructions, or 1  if
            count is omitted. Thus this single steps the debugee.

       b    Set a breakpoint at address. If count is supplied,  the
            breakpoint  will  not  stop until it has been hit count
            times. Extrastuff may be a  command  to  execute  every
            time  the breakpoint is hit. If the command sets dot to
            zero, then the breakpoint will stop even  if  count  is
            not zero.

       .    Set a temporary breakpoint at address and continue exe-
            cution.   When the next breakpoint is encountered, this
            temporary breakpoint will be removed.

       d    Clear the breakpoint at address.

            The command > allows the  values  of  registers  to  be
       changed.  Both word and byte registers may be specified. The
       interrupt flag may also be changed.  0 means  off,  1  means
       on.

       1.4. Example

            An example of the use of the debugger follows:



       A>type tst.c
       main()
       {
           int     i, j;

           scanf("%d", &i);
           printf("%d\n", j); Note the error - j should be i
       }

       A>c -f tst.c      Compile requesting a symbol file










   Page 6         HI-TECH C (Z80) USER'S MANUAL


   A>debug tst.com l.sym Default symbol file name is l.sym
   ZDEBUG
   : printf/i     Disassemble at printf
   _printf:        call    csv
   :              Step down with RETURN
   _printf+3:      push    ix
   : :b           Set a breakpoint here
   : :r           Run the program - no arguments
   123             Scanf waits for input - enter 123
   Breakpoint      _printf+3
   _printf+3:      push    ix  Stopped at the breakpoint
   : $c           Get a stack trace
   _printf(1872,0)      1872 is the format string "d\n"
   _main()
   : main/i       Look at main() now
   _main:          call    csv
   :              Step down with RETURN
   _main+3:        ld      hl,FFFC
   :
   _main+6:        add     hl,sp
   : ,10          Disassemble 16 instructions
   _main+7:        ld      sp,hl
   _main+8:        push    ix
   _main+A:        pop     hl
   _main+B:        dec     hl
   _main+C:        dec     hl
   _main+D:        push    hl
   _main+E:        ld      hl,186F
   _main+11:       push    hl
   _main+12:       call    _scanf
   _main+15:       ld      hl,4
   _main+18:       add     hl,sp
   _main+19:       ld      sp,hl
   _main+1A:       ld      l,(ix+-4) here j is loaded
   _main+1D:       ld      h,(ix+-3)
   _main+20:       push    hl    And pushed onto the stack
   _main+21:       ld      hl,1872
   : main+1a/i
   _main+1A:       ld      l,(ix+-4)
   : /h           Look at the bytes as hex
   _main+1A:       DD        Indexing prefix byte
   :              Step down with RETURN
   _main+1B:       6E
   :
   _main+1C:       FC        The index offset = -4
   : /w 0fe       Change to -2
   :
   _main+1D:       DD
   :
   _main+1E:       66
   :
   _main+1F:       FD
   : /w 0ff   Change the hi byte to -1 to address i instead of j
   : :r       Run it again









                      HI-TECH C (Z80) USER'S MANUAL          Page 7


       123        Enter the same number again
       Breakpoint      _printf+3
       _printf+3:      push    ix
       : $c
       _printf(1872,7B)
       _main()
       : 7b=d        7b was the argument above
        123          Now we have the correct value
       : :c        Continue the program
       123          Which prints the correct value

       A>