Original TI92 version by Tleilax
Conversion and updates by DBA
TABLE OF CONTENTS
IntroductionDB92 installed in a fixed memory area
DB92 is a debugger that runs on the TI92+ and TI89. It is a DoorsOS program. It features a disassembler, symbolic debugging... It is still a beta-version. Please report bugs to DBA NOT to Tleilax.
The .ZIP package should contain the following files :
- db92.9xz : program
- db92.doc : this file
- symb.inc : macros for symbolic debugging
- autosymb.exe : program that scans source file to find symbolic informations
- autosymb.cpp : source of this program
- db92inst.9xz : utility to install db92 into fixed memory area.
It is possible to install db92 into a fixed memory area. It has many advantages. See db92 in fixed memory section.
The name of the program to be debugged should be contained in a TEXT variable named 'todb92'. If this varible doesn't exist, DB92 loads a program named 'test' (maybe it won't work that way in the future). If 'test' doesn't exist, PC points to $000000. If the program is a DoorsOS compatible, then DB92 will point on the program entry, else the program is considered as a TIOS one and DB92 will point at the begining of the program.
The debugged program runs in USER mode, but it is still possible to redefine interrupt priorities ('privilege violation' exception is used to allow that). As the debugger needs to take interrupt 6 into account (to test the ON key), it is not possible to set the interrupt priority bits to a value greater than 5, so don't be surprised if after executing a 'move #$2700,sr' you see $0500 in sr.
Trap #1 is also redirected to avoid Auto-int 6 to be shut down.
Note that the debugger allows the program to access directly the SR register without throwing a 'Privilege violation' error. So, if you debug a part of the program that is supposed to run in USER mode (that is, out of a trap or Auto-int routine), you will still be able to access SR without generating an error (I will try to fix that someday).
The screen is divided into three parts :
- Code
- Left pane
- Bottom pane
The left pane can contain the 'Registers' window and the 'Breakpoints' window. The bottom pane can contain 'Dump' windows (Handles or simple dump) or 'Symbolic' windows ( 'Labels' and 'Variables' windows).
Data entering
You sometimes need to enter hexadecimal numbers. the number you enter is displayed in the title bar of the active window. Valid keys are 0..9, a..f (upper case letters are ignored), backspace, ENTER to valid and ESC to cancel.
General Keys
These keys can be pushed from everywhere into DB92.
| F1 |
|
| F2 |
|
| F3 |
|
| F5 |
|
| Diamond+F5 |
|
| F6 |
|
| F7 |
|
| F8 |
|
| ESC |
|
| APPS |
|
| Lock+left/right |
|
| r |
|
| u |
|
| Shift+s |
|
| Shift+l |
|
| ON+ESC |
|
Menu
The menu currently has 3 items :
- Bottom window : Lists the possibilities for bottom pane
Code Window
The instruction pointed to by PC is preceded by '>'. The bar in inverted video marks the selected instruction.
| Up/Down |
|
| Left/Right |
|
| Diamond+Down |
|
| F4 |
|
| g |
|
| s |
|
| p |
|
| b |
|
| c |
|
| e |
|
| +/- |
|
Registers window
Selected register is preceded by '>'. To change its value, press ENTER then enter the new value.
| Up/Down |
|
| Enter |
|
| g |
|
| e |
|
| a |
|
| d |
|
| p |
|
Dump Window
To display this window, use the menu if necessary (APPS key). At the beginning, the adress is that of the entry point of the debugged program.
| Enter |
|
|
|
| Up/Down/Left/Right |
|
| Hex numbers |
|
|
|
| Up/Down |
|
| Diamond+Up/Down |
|
| Left/Right |
|
| g |
|
| h |
|
| s |
|
| n |
|
| t |
|
| z |
|
| +/- |
|
| p |
|
| l |
|
Note (1): To perform this operation you need to have executed autosymb.exe and to have included the .sdb file into your source.If done just search for the header 'dinf', when found push 'l'.(see 'Symbolic debugging' section).
Variables window
To display this window, use the menu if necessary (APPS key). Contains the adresses, names and values of the variables that were recorded in the symbolic information table (see 'Symbolic debugging' section).
| Up/Down |
|
| Diamond+Up/Down |
|
| Enter |
|
| s |
|
| n |
|
| g |
|
| e |
|
| h |
|
Labels window
To display this window, use the menu if necessary (APPS key). Containes the adresses and names of the labels that were recorded in the symbolic information table.
| Up/Down |
|
| Diamond+Up/Down |
|
| Enter |
|
| s |
|
| n |
|
| e |
|
| h |
|
Handles window
To display this window, use the menu if necessary (APPS key). Each line in this window contains the following fields : Handle number, Address of the corresponding memory block, and a Hexa/Ascii dump of a part of that block.
| Up/Down |
|
| Diamond+Up/Down |
|
| Left/Right |
|
| g |
|
| z |
|
Graph ripper
Shows the graph at a selected memory location. The current adress and width are displayed at the bottom.
| Up/Down/Left/Right |
|
| Diamond+Up/Down |
|
| +/- |
|
| Any hexa digit (lower case) |
|
Breakpoints
There are two kinds of breakpoints :
- RAM for inconditionnal breakpoints placed in ram. This kind of breakpoint uses TRAP 13 : the instruction at the breakpoint adress is replaced by a TRAP 13 instruction.
- ROM for breakpoints above $200000 or conditionnal breakpoints. Those breakpoints use the TRACE ability of the 68000, as it is impossible to write a TRAP 13 instruction in rom... This kind of breakpoint slows down program execution A LOT!!!
| Up/Down |
|
| d |
|
| g |
|
| e |
|
| s |
|
If the program is interrupted during a Step (by ON+ESC), the breakpoint put by the Step is not removed : it is possible to continue execution until the corresponding RTS is reached by pressing 'r'. Breakpoints are toggled with the key 'b' while the 'Code' window is active. The 'Breakpoints' window (accessible by the Menu) shows the adresses of the breakpoints.
ROM calls
| Up/Down |
|
| Diamond+Up/Down |
|
| Enter |
|
| e |
|
| s |
|
| n |
|
| c |
|
| h |
|
Files
| Up/Down |
|
| Diamond+Up/Down |
|
| Left/Right |
|
| Enter |
|
| e |
|
| s |
|
| l |
|
The debugger installs managers for the following errors :
- Address error
- Illegal instruction
- Division by zero
- Bus error
- Line 1111
Usually, the TI-92 displays a message and freezes. With those managers, you just have to press a key to go back to the debugger. It doesn't prevent unexpected results however. For adress error and bus error, the instruction pointed to by pc after the exception is usually the instruction following the instruction which caused the exception.
The debugger aloso uses those vectors :
- Trap 13
- Privilege violation
- Trace
- Auto int 6
When the end of the program is reached, a message is displayed. Press a key to go back to the debugger. PC points again at the beginning of the program.
The 'Swap' library contains two routines that swap the screens :
- Prog_Screen swaps to the program's screen default behaviour : sets screen adress to tios::lcd_main.
- Debug_Screen swaps back to the debugger's screen default behaviour : does nothing.
This library allows the debugged program to adjust the screen settings it needs to be displayed properly (contrast, line size, hardware graylevels...) The library contains some free space where the debugged program can store data needed to perform the swapping, such as the program's screen adress.
The label before this free space is 'Data'. The program can access this data by including the 'swap' library to its library list. The source of the library should be included in the .ZIP package. If you use a library such as graylib or any routine that uses an AutoInt to swap screens, you don't have to rewrite the 'swap' library, as your interrupt handler deals with the screen (it also works when you look at your program's screen using F5 key).
DB92 allows the programmer to include symbolic debug informations in the program. The informations are displayed when available in the Code window : When the debugger encounters a branch instruction with an adress that matches to a label's adress, it replace the adress by the label's name (plus character ':' ). When it encounters a memory access that corresponds to the adress of a variable, it replaces the adress by the variable's name (plus character '_') ONLY if the adressing mode is 'Absolute long' or 'PC relative with offset', which are the most used adressing modes when a variable is directly referenced in the source listing.
The symbolic informations are included in the program itself. Some macros are provided to help you using this feature (they are in symb.inc) : Variables are declared in a block that begins with 'dbv_begin' and ends by 'dbv_end'. Each variable is declared with 'dbv_add var_name,var_type' where 'var_type' is the size of the variable (dbv_BYTE, dbv_WORD or dbv_LONG).
Labels are declared in a bloc that begins with 'dbl_begin' and ends by 'dbl_end'. Each label is declared with 'dbl_add label_name'. The last macro is 'db92_symbols'. It must be placed JUST BEFORE your program's entry point. It contains the adresses of the Variables and Labels blocs and notifies the debugger that symbolic informations are present.
Actually, you usually won't have to use these macros : 'autosymb' is a program that scans your source file for labels and variables and automatically builds a file that you can include just before your program's entrypoint. It is a really simple program, it doesn't even searches for included files. I included the source file in the package so that you can improve it.
The program 'db92inst.9xz' is a utility that copies 'db92' to fixed memory area. It has two important advantages :
The drawbacks now :
Once db92 is copied you can invoke it in two ways :
I hadn't much time to test deeply this program yet. I have not found any serious bug but I'm pretty sure there are lots. Note:this version has been tested with the 'Tiger' emulator, and 1.00, 1.01 and 1.05 ROMs. (For 1.05 ROM it is NOT the same binary program, please verify that the DB92.9xz you've is the good one)
Be careful when you debug programs that allocate memory : first, if there is an error in the freeing routine, the debugger will probalbly crash when you quit ; second, don't forget that if you single step the program or if you stop it by ON+ESC, the allocated memory is not freed. So if there is no reason to avoid it, don't quit the debugger before your program has properly ended (it doesn't mean that you shouldn't interrupt your program, it means that if you did so, you have to press 'r' again). The usual case of prema ture exit is when you found THE bug and you are in a hurry to download the corrected version ;) (or at least that is how I see the thing...)
I would like to thank all the people who have worked and probably still work for the developpement of the Fargo shell. And :
Jonas Minnberg for the Tiger emulator
Thibaut Terlon for lending me his TI92 for a moment
Mathieu Lacage and Sacha Kaercher for their suggestions/bug reports
/07/1999 v 0.9.0 fixed bugs, added features, added bugs.
Newest version by DBA v 0.7.1 fixed bugs, added features
(...)
v 0.2.1 fixed bugs, added features
v 0.1.3 fixed bugs, added features
v 0.1.2 fixed bugs, added features
v 0.1.1 first public release
Original author: guillaume.pothier@eleve.emn.fr (before july 2001...)
Further development: DBA; Fred and Kty
Report bugs to:
| Fred | imfred@mailcity.com | ICQ # 33467465 |
| Kty | kty@mailcity.com | ICQ # 45376616 |
Please let us know if you find bugs. Any suggestions are also welcome.
Tleilax |
DBA |