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