--==[ Raven ]==-- v1.0 6-12-97 68000 Debugger, Exception Processor, and Tracer for the TI-92. By Bryan Turner (copywrite 1997) bcturner@eos.ncsu.edu This software is freeware, you may distribute it to any interested parties, as long as it is not sold, I retain all rights to the original work within this project. (second-hand work is stored in a separate file where applicable) Raven is compatable with Fargo 0.1.13, it should install fine with either version of the core.o file. IF IT DOES NOT INSTALL PLEASE CONTACT ME WITH YOUR 'core.o' FILE! Raven makes a copy of the screen, which takes up over 3K of memory. This buffer must be created at installation and remain allocated at all times. Unfortunately this makes Raven technicly 3K larger than it actually is. Later versions may compress this image, but I'm stuck with this for now. Raven should be intuitive! Other than some missing user interface components (like a string telling you why Raven was entered, and labels on the PC, SR and instruction list), the flow of work should be very easy. If there are any areas which cause frustration or annoyance when working, please contact me. -------------------- First, the problems: -------------------- - Installer edits core.o. It is very inflexible and will not work if your core.o is even slightly different that the one I used for testing. (this is neccisary since editing code in memory is tricky buisness, but I'll make the process more flexible in the next release) - Raven has some bugs. *sigh* - Exception processor does not always replace Fargo interrupts for some reason, and it makes the shift/on combo fail requiring you to type the name of programs. Worse yet, it may also break that feature too! I can't get a clear picture of when each event occurs, but if you notice a specific set of actions which always cause this effect, please let me know. - Shell can be debugged (this might be a feature, but it can be annoying if you're trying to turn off the calc from the shell) - Escaping from a program back to the shell only works for one level ie: escape from shell back to TI-OS, or from app to shell but not from app to shell, then again from shell to TI-OS. This shouldn't be a problem for most programmers, but shell writers may find it annoying (contact me, there is a solution). - Hex Editor is S---L---O---W. I havn't written the 6pt hex display routines yet, so I'm relying on ROM right now (sorry). - Hex Editor's cursor only spans the first half of the screen in the editor. It's only slightly anoying (not half as anoying as the amount of time it takes to get to the bottom of the screen using putchar calls to ROM!!) - Doesn't display the reason why an exception occured (ie: Bus Error, Illegal Instruction, User Break, etc..). It knows but I'm examining a method to use the strings already stored in ROM to reduce code size. --------- FEATURES! --------- + Full exception coverage! All possible exceptions from which errors are generated, or calc freezes occur are caught. + Properly handles all exceptions (Not every exception is alike). + Hex Editor! Fix stuff in memory! Play! Mangle! Whatever! + Register Editor! (see above line) + Status Register display with easily readable string format. + Exit from program to shell, or return to your program! + Correctly handles GRAYLIB programs! (exit and return) + Trace your program one instruction at a time! --------------------------- How to Install the Debugger --------------------------- Simply copy the TI-92 Program file to the calculator, and select the installer from the Fargo Shell screen. The Installer will display a message concerning the result of the operation. If it was successful, the installer will instruct you to delete it. It's OK, just delete it! The exception processor and editor have been copied to a different place in memory and are no longer subject to bieng moved about by TI-OS (neccisary for a debugger). So the installer and it's baggage are no longer needed. You will notice your free memory did decrease, but by an amount less than the installer (since the installer code is only used once, it is not copied). Any time the calculator is reset, both Fargo and the debugger will need to be re-installed. I may be distributing an edited core.o file with the debugger already installed - this would allow the use of the standard putfargo.bat method of installing into a backup. ------------------ Using the Debugger ------------------ Once installed, run any Fargo program from the Shell or from TI-OS. Press and hold the 'ON' button for a moment. If all went well, Raven should appear. Description of Hex Edit Screen ------------------------------ Each line of the Hex Editor is of the following format: 000000 0000 4440 0040 0100 ..D@.@.. The first column is the memory address of the first byte of this line. The second column is the first word of memory at the address. The third, fourth and fifth columns are the successive memory words. The sixth column is an ascii representation of the 8 bytes which are stored at this line's address. Periods represent non-printable characters. Commands from Hex Edit Screen ----------------------------- Left Pad : Shift to Register Edit Screen Up/Down Pad : Scroll Hex view up/down by 8 bytes 2nd + Up/Dn Pad : Scroll by $100 bytes Diamond + Pad : Scroll by $1000 bytes Shift + Pad : Scroll by $10000 bytes F1 - F8 : Jump to bookmark Diamond + F1-F8 : Set bookmark to current address Apps : Enter Hex Edit Mode: Pad Up/Dn/Left/Right to move cursor 0-9 A-F a-f to enter digit Apps : exit the edit mode ** ONLY edits first half of screen. ** Manually scroll to continue (turn off ** edit mode, scroll down, turn edit on again). Escape : Escape to shell Enter : Return to program 't' : Trace (step through one instruction) Description of Register Edit Screen ----------------------------------- The Register Edit screen is roughly broken up into three parts: Data Registers Address Registers ...... ....... ...... ....... Status Register & Program Counter Instruction List The Data Register group lists the registers D0-D7 and their 32-bit contents (not all 32 bits may be in use at this time). Similarly, the Address Register group lists A0-A7. Address Registers are allways accessed as full 32-bit quantities. The Status Register & Program Counter line may look like the following: SmxNzvc 2708 3C01F80C The first item is the Status String, each character represents a useful bit in the Status/Condition Code Register: S - Supervisor Mode Z - Zero M - Master V - oVerflow X - eXtend C - Carry N - Negative If the bit is SET, the string will represent it as an UPPERCASE letter. If the bit is CLEAR, the string will have a LOWERCASE letter. The second item is the actual contents of the Status Register (it's only 16 bits). This is presented to show other bits (such as the interrupt level, and the Trace bit). The third item is the Program Counter. This value may be off by up to two bytes. The reasons for this are numerous, but basicly the instruction which was interrupted may not have finished yet (in the case of Bus/Address errors), or it may have completed already and incremented the PC correctly. Suffice to say this is pretty close to the right spot though. **** The HIGH BYTE of the Program Counter contains the Interrupt which caused Raven to be loaded. In this case, $3C = Uninitialized Interrupt. A User Break (hitting the ON button) will always have $00 in this byte (even though it is actually caused by the Auto-Int 6 $78 vector). The instruction list line provides 4 words from the current location of the PC. If you know 68K assembly well enough, this will help emensely, if not then you'll have to pull out a disassembly of your program (which puts instructions next to their hex equivelents), and follow along that way. Commands from Register Edit Screen ---------------------------------- Right Pad : Shift to Hex Edit Screen Apps : Enter Register Edit mode: Pad Up/Dn/Lft/Right to move cursor 0-9 A-F a-f to enter digit Apps : exit editing mode Escape : Escape to shell Enter : Return to program 't' : Trace (step through one instruction) ------------------------------- Advice, Wisdom, Comments, etc.. ------------------------------- It's beta, it's beta, it's beta.... Did I mention this is a BETA?? I can't stress this enough. It's ugly, slow, clunky, and HUGE (almost 3k with installer). Much will improve if there is interest from the programming community. Also, if the need for a full debugger is minimal, but the need for a system stabalizer is high enough, a similar program could add the features of pause and exit for non-programmer types. It's one thing to install and enter a debugger, and quite another to actually use one to any usefull end. I've attempted to give the programmer a set of tools with which to perform usefull tasks, and expedite the process of writing programs. Learning the tricks and techniques for finding errors and fixing them is a long and difficult road. If you need help, or a new tool added to the bucket, please let myself and the Fargo community know. Most likely someone can help. I WILL NOT BE ADDING A DISSASEMBLER. I expect no return from this product, and the investment needed for a working dissasembler is far too much to warrant it's inclusion. If anyone produces a disassembler in the future, I will gladly add it to the debugger (with all proper acknowledgements, etc). Future enhancements? Fix the bugs! ;) Visual/Interface improvements. FASTER! Smaller! (hopefully) Breakpoints Debugger String entries (display a string in the debugger when you encounter an error in your program logic) Memory searching ---------------- About the Author ---------------- With over a decade of programming experience on the Macintosh platform, I have come to know 68000 assembly very well. By far the most usefull program I've come across is MacsBug by Apple Computer. A debugger which is similar to (but much more sophisticated than) this debugger. I'm 21, and currently a Senior attending North Carolina State University earning a Bachelor of Science in Computer Science with a minor in Buisness Administration. I have extensive field experience with programming, GUIs, and customer service/support. I've fallen in love with the Macintosh and it's associated technologies which have driven most of (if not all of) my interest in Human Interface Design and programming. Many systems excell the MacOS in OS components (Semetric Multiprocessing, memory-file mapping, etc..) but none yet matches the level of simplicity and power granted to the most basic Mac users. Nor does any system offer the level of plug and play simplicity the Mac has for system installation, hardware configuration and GUI preferences. I'm also active in many other activities outside of my computer hobbies/work. A quick list might turn out like this: Paintball, Raving, Camping, Society for Creative Anachronism, Music, Reading, my Girlfriend, Hacking, Aquariums, and much more! Drop me a line with some comments, criticisms, or whatever, and I'll get back to you. --Bryan Turner bcturner@eos.ncsu.edu