This is a package which provides a simple debugger for Rex addins.
Copyright (C) 2002 Graham R. Cobb. The package is distributed under the GPL (see the copyright notices and the COPYING file).
Debugger For Rex 6000 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Debugger For Rex 6000 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
The Debugger distribution contains three main files in the top level directory (as well as sources and some informational files):
debug.h -- This is the header file for programs calling the debugger traps.
It must be copied to a suitable "include" directory
(e.g. rexdk/include/rex/).
debug.lib -- This is the precompiled library file containing the traps.
Addins which call the debugger traps must link against this library.
It must be copied to rexdk/lib/clibs/ and can be linked using
-ldebug on the zcc command line.
debugger.rex -- This is a Rex addin which contains the Debugger code.
This addin must be loaded on the Rex before addins can successfully call the debugger traps.
The package also contains the source for the Debugger.
For Debugger Version 1.0.
It is not possible to set breakpoints using this debugger. The debugger is accessed by putting calls to debugger traps in the addin being debugged. These calls may be conditional (e.g. on some error condition) or may be unconditional (so the debugger is always invoked at that point).
The debugger traps are functions which can be called from C or assembler code.
They are designed to take up as little code space as possible, although the basic form
(dbgtrap()) will take the least code space to call.
The three forms of the trap are:
dbgtrap()
dbgtrap_n(a, b, c)
dbgtrap_s(s, a, b)
The smallest call, from C code, is as follows:
#asm
call dbgtrap
#endasm
If the debugger addin is not loaded, the trap will continue automatically.
unsigned short dbgtrap(void);
unsigned short dbgtrap_n(int a, int b, int c);
unsigned short dbgtrap_s(unsigned char *s, int b, int c);
The dbgtrap_n form takes three integers as parameters.
These are displayed at the top of the debugger screen and are useful for displaying addresses of
data, numeric values or codes to indicate the breakpoint which has been trapped.
The dbgtrap_s form takes a string and two integers as parameters.
These are also displayed at the top of the debugger screen.
Whatever value the user puts (or leaves) in HL before continuing from the debugger.
When the debugger is entered, the screen is cleared (the previous screen display is lost). The debugger screen shows an entry line at the top of the screen. This shows the parameters from the trap, if any.
The next 4 lines show the CPU registers at the time of the trap: A, F, BC, DE, HL, A', F', BC', DE', HL', IX, IY, Bank1, Bank2 and PC.
The next line shows the stack pointer and the top 6 words of the stack.
The next two lines show memory contents (as ASCII and as Hex). The first two fields of line 8 are the bank number and offset of the memory location to be examined. Bank 0 is interpreted to mean the address space of the caller. So 00: 8000: means the first byte of the addin code and 00: A000: is the memory mapped by the Bank 2 register.
Any of the registers or memory locations can be modified by touching the numeric value on the screen. This will bring up a keyboard which can be used to enter the new value in hex.
Touching the first two fields in line 8 (the memory display) allows you to specify a different bank or offset to display. Touching the other fields in that line allows you to modify memory (if it is writeable).
Changes to the stack pointer (SP) cause the stack display to change but do not cause the caller's stack pointer to change.
All other register changes (including PC) are reflected in the caller, when it resumes. Note that because of the way the C compiler calls external routines, most register changes will be ignored, except for the PC and HL. The value of HL appears as the return value of the trap function.
The buttons have the following effect:
HOME -- exit the debugger and the calling addin (using exit(0))
BACK -- continue executing the calling addin at the specified PC
SELECT -- not currently used
UP -- scroll memory display back by 0x000C bytes (i.e. six words).
DOWN -- scroll memory display forward by 0x000C bytes (i.e. six words).
When the BACK button is used to continue execution,
all registers are restored to the values appearing on the screen except SP (which is not modified).
The screen is cleared (DsClearScreen())
and all events are cleared (DsEventClear()).
First release.