Manual Debugger

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

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 breakpoint 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.

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 omitted, 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

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 location 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 instructions. 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.

Display the contents of all Z80 registers.

The : command has the following modifiers:

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

Continue the program from address, or the contents of PC if address is omitted. Used after a breakpoint.
As for c, but execute only count instructions, or 1 if count is omitted. Thus this single steps the debugee.
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 execution. When the next breakpoint is encountered, this temporary breakpoint will be removed.

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.


An example of the use of the debugger follows<nowiki>:<nowiki>

        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

    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/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

       123        Enter the same number again
       Breakpoint      _printf+3
       _printf+3:      push    ix
       : $c
       : 7b=d        7b was the argument above
        123          Now we have the correct value

        : :c Continue the program

       123          Which prints the correct value



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 hexadecimal 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 command should do. Modifier is another character which determines more specifically what the command is. Extrastuff is dependent on the particular command, and is usually omitted.


Expressions may consist of:

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

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.


A hexadecimal integer. It must start with a digit, otherwise 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.


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.


The negation of EXPR.


The bitwise complement of EXPR.


The sum of E1 and E2.


The value of E1 less the value of E2.


The value of E1 multiplied by E2.


E1 divided by E2.


E1 anded with E2.

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

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:

Print as Z80 instructions
h or b
Print as hexadecimal bytes.
Print as octal bytes.
Print as decimal bytes.
H or W
Print as hexadecimal words.
Octal words.
Decimal words.
Print each byte as an ascii character.
Print as ascii characters if printable, as @x if not, where x is the corresponding alphabetic character, e.g. @C for 3.
Print a string of characters up to a null.
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:

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

When such a command is issued, the value of dot is temporarily incremented by the total number of bytes displayed. A subsequent command consisting solely of a RETURN or LINEFEED 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 command may not be issued if the current format is not a byte or word type. Thus memory may not be modified in the i format. 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:

Print a C stack backtrace. Note that this is not reliable when used on an optimized program since the optimizer changes stack manipulation code. There may appear to be fewer arguments than there really are. Long arguments will always appear as two integer arguments.
Display currently set breakpoints
Set the limit for symbol matches to the given address. This determines the maximum value of offset when printing out a value as sym+offset.
Set the terminal width to address. The default is 80 decimal.