The CDPD Public Domain Collection for CDTV 3

home *** CD-ROM | disk | FTP | other *** search

/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / debug-utils / mykesbug / mykesbug.doc < prev next >

Wrap

Text File | 1992-10-19 | 26.8 KB | 658 lines

MykesBug Debugger Version 1.10 ©1986,1987,1988,1989,1990,1991 Mike Schwartz, all rights reserved. ©1992 Joshua Dinerstein, all rights reserved. ******************************************************************************* * * * This program is freeware. You can freely distribute it as long as you * * don't charge more than nominal fee (max $3 US) for copying it and no * * additions/deletions/modifications are made to the original archive. You * * may include it in PD Libraries such as the Fred Fish Collection. This * * program is distributed without warranty of any kind. So the authors take * * no responsibility whatsoever for this program, its documentation, * * functionality or damages it may cause. The risk is entirely yours. * * * * This having been said the program has been well tested and should not * * cause any problems. * * * ******************************************************************************* 1. INTRODUCTION ~~~~~~~~~~~~~~~~ This is the first truely public release of a new debugger for the Amiga family of computers. The current version represents several weeks of work. However it still lacks some of the ultimate polish it will have as well as several features that will be implemented soon. However, what is implemented is completely stable - I've run the SAS 'C' compiler, LMK, and various other programs through the debugger with no problems. Mykesbug was originally written by Mike Schwartz and ran only on an Amiga with a 68030 and AmigaDos 2.0. I, however, really wanted to use it on an Amiga 500 under 1.3. And Mike allowed me to make the changes that I needed too to get it to run on the A500. So for the time being I have taken over the developement of Mykesbug for the Amiga computer. If you have any comments or bug reports then please send them to: Joshua Dinerstein SLMT9@cc.usu.edu or to Forge on IRC 2. WHAT IS MYKESBUG ~~~~~~~~~~~~~~~~~~~~ Mykesbug is a debugger for the Amiga family of computer. The debugger is designed to be as system independant as possible. This means that it is possible to do debugging after a program has guru'ed. Infact it is sometimes possible to correct what went wrong and have the system continue as if it had never crashed. Because of this system independance it is also possible to debug code that "takes over the system", such as demos and commercial style games. This is one of the best features in the debugger, at least in my opinion. 3. WHAT'S NEW ~~~~~~~~~~~~~~ For this first major release I have added several new features to the debugger as well as made several major changes. What I have basically done is to make the debugger run under both the 1.3 and the 2.0 version of the operating system. There is now also a 68000 compatible version of the MykesBug program. All of the features that are available under 2.0 are also available under the 1.3 version of the debugging system. There are however some slight differences in the way certain functions operate. These differences are caused by the differences in the two OS version. The differences will be covered in detail later in this text under the heading OS DIFFERENCES. For the 68000 version the display was redisigned to use a 640x200 resolution screen. This change removed the terrible interlace flicker and sped up the display rate for this slower machine, but it also cut down the amount of information that was available on the screen at any one time. Even with this smaller display size all that has been removed from the display are several registers that do not exist on the 68000. One of the benefits of this smaller screen is that it has freed up a large chunk of Chip Ram for use by other programs. Baring the re-arrangement of the display layout, the 68000 version has remained almost identical to the 68030 version. Those of you who own several amigas and have both types of processors should be able to switch back and forth between versions with no trouble at all. For a more complete list of the new features look at the revisions history under version 1.10. 4. CONTENTS ~~~~~~~~~~~~ This archive should contain the following files: Mykesbug.doc - this file mykesbug - the resident portion of the debugger debug - the debug-time portion of the debugger (CLI usage) test - a very simple demo program that I test debug with test.s - source to test program above hello - a 'C' test program to test CLI compatibility and 'C' hello.c - source to hello program umain.c - source to _main from SAS (required for source level debugging of hello) suspend.info - icon for suspend mode AppIcon (Under 2.0) 5. INSTRUCTIONS ~~~~~~~~~~~~~~~~ * WARNING: Be sure to turn Enforcer OFF, or MykesBug will fail. The CPU command from CBM also seems to make MykesBug fail when used with FASTROM option. MykesBug is the resident portion of the debugger. It exists half in OS land and half in the supervisor state. This program should be RUN with the RUN command (segment splitting or TSR functionality to be added in the next release). Once MykesBug is running, it will have revectored all of the low level CPU exception vectors so it can catch any of these exceptions. The only vector not currently handled is the privilidge violation, because of some specialized code that exists in the ROM version of the handler. This will be addressed in the next release. Mykesbug has to be run before any debugging or error trapping can be done. A good place to run MykesBug is from the Startup-Sequence. MykesBug can be installed in your startup-sequence by adding the following line: RUN <NIL: >NIL: MykesBug >nil: <nil: There are two ways to initially activate the supervisor mode debugger. The first way is to run a program that gurus, the second is to use the Debug program. The second method is the one that is usually prefered. To use the Debug program, use: {RUN} Debug program {parm...} Debug is a wedge between the CLI and MykesBug (workbench support will be added). Debug does a LoadSeg() on the program and also parses the executable file for symbol and debug hunks. Currently, only level 1 debugging hunks are processed and others ignored. The symbolic and source level debugging information and other information is stored in a debugging CONTEXT structure for use by MykesBug. This CONTEXT structure is registered with MykesBug - Note that as many CONTEXTs can be handled by MykesBug as you have RAM for (this allows multiple concurrent debugging sessions). Debug updates various parts of the CLI structure, sets a breakpoint at the first instruction in the debugged program (so MykesBug gains control right away) and then does a JSR to the loaded program. When the program returns, Debug prints the exit code and passes this on via its exit() parameter. NOTE: The resident MykesBug can be told to exit by running MykesBug a second time. I use this feature to remove an old version and install a new one. For example, Run MykesBug (installs mykesbug), Run MykesBug (Kills first MykesBug), Run MykesBug (installs mykesbug again). 5.1 MYKESBUG: ============= MykesBug operates in Supervisor mode of the 68030 and 68000. It is specifically designed to use ZERO OS functions or resources (i.e. blitter, etc.) and is designed not to interfere with the OS. The reasoning for this is that there is no excuse for a debugger to crash because the OS has been trashed. MykesBug is careful to preserve the state of the OS and hardware, to drive the hardware directly (as minimally as needed) while in operation, and to restore the OS and hardware states to allow return to the OS. 68000 support has now been added to Mykesbug. There are now 2 different version of the program Mykesbug in the archive. Mykesbug is still the 68030 version, and Mykesbug000 is the 68000 version. These 2 versions are functionaly equivalent as far as the differences between the two processors allow. The main difference is that some registers do not exist in the 68000 and therefore can't be accessed in the 68000 version. The 68030 version definately DOES NOT work on a machine with only a 68000 installed. The 68000 version, however, works on all Amiga machines. MykesBug currently uses the VBL interrupt for mouse counter reading, keyboard I/O polling (system friendly), and timing. This is the only interrupt that will be enabled while the supervisor mode debugger is running. The 68030 version of MykesBug uses its own copper list, and uses two 640x400 planes (for color support), and renders its own font with the CPU to the bitplanes (to avoid use of the OS Text() routines). The 68000 version now uses two 640x200 planes. This avoids problems with both interlace flicker and using to much chip ram on the smaller systems. The MykesBug display screen consists of 5 specific areas. 1- At the top of the screen, the current task name and status is displayed. 2- The left side of the display contains Amiga Hardware register display (currently only INTENA and DMACON). 3- Below this, on the left side, is the CPU register display (currently FFP and MMU registers are not displayed). 4- A large window to the right of the register display is used to display diassembly, hex dumps, source code, help, etc. (this is a general purpose display window). 5- The bottom two windows are used for command line input and for debugger messages. The 68030 Layout The 68000 Layout +--------------------+ +--------------------+ | 1 | | 1 | +---+----------------+ +---+----------------+ | 2 | | | 2 | | +---+ | +---+ | | | 4 | | | 4 | | 3 | | | 3 | | | | | | | | +---+----------------+ | +----------------+ +----------5---------+ | +------5---------+ +--------------------+ +---+----------------+ NOTE: The smaller screen size for the 68000 version forced the size of the main window (area 5) to be shrunk to about half of the size of the one in the 68030 version. Also the command and message lines were shrunk and offset to the right to allow enough room for the CPU registers display. 5.2 COMMAND LINE: ================= The command line entry system for MykesBug is still very preliminary and needs a bit of work. However, it is quite usable in its current form. The concept behind the command line is that you should be allowed to enter a command and then hit return to execute it. The previous command line is retained and displayed. If you start to type a new command, the previous line is erased and new command line input is begun. Otherwise, you are able to hit return again to execute the last command again. You are also allowed to edit the previous command line by using the backspace and left/right cursor keys. Also mouse support still needs to be added, but the mouse is there and works and there is even a mouse blanker so the pointer doesn't get in the (visual) way. There are several keys that are accepted during command line input that perform different features. 1- The TAB key can be hit and this causes the SYSTEM copper list (obtained from GfxBase) to be displayed by the copper until a key is hit. 2- The ^X key which clears the command line. 3- The HELP key displays on-line help in the Main window. 4- The ^C key terminates a debugging session. 5- The ^Z key suspends the current debugging session. 5- The Up and Down keys on the keypad scroll the the general purpose window (disassembly/source...) up/down. The cursor up/down keys will be used to implement command line history. Function keys are now supported, minimally. The current bindings are displayed by the he (help) command. There is now a startup script and hopefully these commands will be able to be set from this script. 5.3 IMPLEMENTED COMMANDS: ========================= The following commands have been implemented. The are pretty much self explanatory. Those commands that needed more explanation are covered again in the next section. ? Display Task Info ExecBase Display ExecBase MemList Display Mem List ResourceList Display Resource List DeviceList Display Device List IntrList Display Intr List LibList Display Lib List PortList Display Port List TaskList Display Task List symbols display all of the defined symbols as name addr Add Symbol name at addr bs addr set sticky breakpoint at addr br addr|ALL clear breakpoint at addr or clear all bd display breakpoint table dc addr display copper list {at addr} he this list (HELP KEY) db {addr} display bytes at addr go {addr} go {to addr} lm {addr} list (disassemble) memory {at addr} so {addr} display source {at addr} b? addr display byte at addr w? addr display word at addr l? addr display longword at addr bc addr run until byte changes wc addr run until word changes lc addr run until long changes mb addr val {val...} modify bytes at addr to val {val...} mw addr val {val...} modify words at addr to val {val...} ml addr val {val...} modify longs at addr to val {val...} REBOOT reboot the machine ss single step st step over ex {addr} exit debugging context {at addr} (^C) su suspend debugging session/context (^Z) mr reg val modify a register to a value All commands must be lower case (the first two letters). Symbols may be mixed case but ARE case sensitive. Use the symbols command to get the correct case if you are uncertain. 5.4 COMMAND DISCUSSION: ======================= Scrolling has been added to all of the lists that the debugger displays (ie. ExecBase, MemList, etc...). Also the use of the Pg_Up and Pg_Down keys has been added to the scrolling. This jumps the display 1 page at a time. The source display cannot be paged at this time, both the regular arrow keys and the Pg_Up/Dn keys just step the display by one in the correct direction. The ex command works in 2 seperate ways. The first way is if just the command "ex" is enter. This causes the debugger to look for a routine named "abort", "Abort", or "XCEXIT". The second way it to call "ex <label>". This causes the debugger to look only for the specified routine and exit using that routine. The ex command works by changing PC to point at the proper routine and then a GO command is executed. Under 2.0 the su command causes an AppIcon to be added to the workbench screen for the current context and the system is restored. The AppIcon's name will be the name of the task being debugged. To reactivate the debugging context, double click on the AppIcon. Under 1.3 the su command causes a small titlebar style window to be opened on the workbench screen. The screens title will be the name of the task being debugged. To reactivate the debugging context, click on the close gadget for the window. Multiple suspend windows will all appear on top of each other. The windows are draggable though, so just pull them out of the way to get to the one that you want. The st command is implemented by setting a breakpoint after the current instruction. It allows you to step over jsr,bsr, etc. It also allows you to step over a DBRA (handy!). If you st over an rts command then it set the breakpoint right at the address that it should return too. It is also now, marginally, smart enough to detect source display mode and to set the breakpoint at the next source line (This is still not quite perfect). The b?, w?, and l? commands are similar to their equivialents in the JForth environment. These cause a single value to be displayed in the prompt area. 5.5 ADDRESS EXPRESSIONS: ======================== Whenever command line input requires an address or other number, certain expressions are allowed. Any hex number may be typed in with no special qualifiers (hex is the default). If a decimal number is desired, precede it with a period (.). In addition, the following strings are recognized: (pc) where program counter points (ip) where program counter points * where program counter points (sp) where stack pointer points (NOTE: this is system stack pointer) (usp) where user stack pointer points (NOTE: this is the application's SP) (d0) where d0 points (d1) where d1 points (d2) where d2 points (d3) where d3 points (d4) where d4 points (d5) where d5 points (d6) where d6 points (d7) where d7 points (a0) where a0 points (a1) where a1 points (a2) where a2 points (a3) where a3 points (a4) where a4 points (a5) where a5 points (a6) where a6 points (a7) where a7 points No arithmetic expressions or otherwise more complex expressions are supported (yet). This means that 1+1 is illegal, as is 24(a6). Note: lower case is required for the above expressions. 5.6 MYKESBUG-STARTUP: ===================== This file contains some startup information for the debugger. The format for these commands is a command on one line and then the options if any on the next line. At the moment there are only 2 commands that are supported. These are: 1- PALETTE: This just sets the palette. Is this command is left out the debugger just uses the default system colors. 2- SUSPEND: This sets the path and name for the Icon. This is the Icon that is used in the suspend option under 2.0. For a better example of how these work simply look at the supplied MykesBug-Startup file. 6. OS DIFFERENCES ~~~~~~~~~~~~~~~~~~ The main difference is that AppIcons exist only under 2.0 and so cannot be used under 1.3. To solve this problem a simple window was added. The window has the same effect as the AppIcon it allows the debugging session to be suspended and the restarted when the window is closed. There may be multiple windows at once, one for each suspended sesion. The problem is that each window appears in the same spot. The windows are draggable and can be moved out of the way to get to the window that you want. Under 2.0 the AppIcons work like normal icons, in that they start in the upper left corner of the Worbench screen and appear under the previous icon. Both version of MykesBug, MykesBug and MykesBug000, have the 2.0 and the 1.3 code in them. They autodetect what version is being used and will use 2.0 if it is available. The Debug program works the same way. The one program will work under both versions of MykesBug as well as both versions of the OS. 7. INSTALATION ~~~~~~~~~~~~~~~ To install MykesBug I recomend that you make a new directory and place the version of MykesBug that you want to use in it. Also copy in the Debug program and the Suspend.info file. Then add this to the path command in the Shell-Startup. This will insure that you can always get to the debugger commands. Starting with this version there is also a startup script called MykesBug-Startup. When MykesBug is run is looks both in S: and in the current directory for this file. I recommend that you just copy the supplied MykesBug-Startup file into S until you are more familiar with what is in it and what it does. 8. THANKS ~~~~~~~~~~ Special thanks go out to all of the beta testers that have helped me to get this to the bug-free (Hopefully :) state that this program is now in. I would list you all here but unfortunately I mostly know nicknames from IRC so I will hold off for now. A million thanks go Mike Schwartz for writing this debugger in the first place and then for letting me have the source so that I could make the changes that I wanted too. And another million thanks for all the help that he gave me in getting ready to go. 9. BUGS/PROBLEMS ~~~~~~~~~~~~~~~~~ * The source mode display has problems because of the way level 1 debug hunks are generated by SAS. Multiple source lines may have the same PC value. This display mode is going to be replaced with a MIXED mode of source and disassembly. * MykesBug copperlist and bitplanes are permanently allocated in CHIP RAM. This makes the debugger vulnerable to wild blits, wild stores, etc. This will be fixed by having the debugger swap what CHIP RAM it needs with FAST RAM. * MykesBug is currently 41 hunks. It needs to become 1 contiguous hunk so it can easily be protected with the MMU. * Since MykesBug operates in SuperVisor mode, it does not have access to OS routines. This makes it not possible to do DOS, for example. For this reason, the Debug program will read 100% of your source files (if -D1 hunks are present) into RAM. For HUGE projects, this can either take a lot of time or may require a lot of RAM. * The disassembler has a few bugs in it and only disassembles 68000 instructions. * Keys don't autorepeat! * Mouse does NOTHING ( YET! :) * From time to time, the command line is trashed (displays garbage) when running debug (first command) or unsuspending a debug session. * 'C' compiler complains about valid syntax for the code that does SetFunction() and if the instructions aren't tweaked to just the right order, the compiler quits with a CXERR #25 message. BLINK is taking a long long time. Wonderful, no? * Workbench support for MykesBug and Debug is not fully implemented. MykesBug should create an AppIcon so you can drag programs onto it to debug them (mykesbug will run Debug automatically). Additionally, double clicking on this icon should activate the resident MykesBug debugger. * It is not clear if MykesBug works on an 040 processor. * The copper list used by MykesBug is not aware of future/enhanced chipset registers. It is likely/possible that these registers may be set to an incompatible state with the copper list. * MykesBug does not support the FPU or MMU at all. The FPU and MMU registers should be preserved and restored as the rest of the registers are. These registers should also be displayed on the screen and should be alterable with the mr command. 10. PLANNED ENHANCEMENTS ~~~~~~~~~~~~~~~~~~~~~~~~~ * PLANNED ENHANCEMENTS (Fer sher) 1. Simple Command Line History. 2. Mouse Input (lots of good ideas here). Mouse click on source/dism line will do a go (to that line) Mouse click on address part of line will simply set a breakpoint at the line. Mouse click on numbers will autotype them on the command line. Mouse click on registers... 3. "Consistency" check validate memory list validate low memory addresses check stack against bounds checksum memory regions etc. 4. "poor man's history trace" Use the trace bit and record history of program execution. 5. Command line switches for Debug program history size, etc. 6. Library breakpoint run until somebody calls AllocMem() 7. Library trace Record calls to library routines 8. Command line history and editing improvements 9. DOS library structure dumps 10. Graphics library structure dumps 11. Intuition library structure dumps 12. Stack Trace 13. Modifyable global symbol table This will allow you to comment and label OS routines :) 14. Context display Show symbols Select different context/task to debug 15. Signal command (sets signal bit of a task) 16. CLI local environment variables to be used to specify source code directories. This will prevent the need for running Debug from the same directory as the sources. 17. Full-blown 68010/68020/68030/68040/68851/68881/68882 disassembly support. 18. Display info about MMU setup and usage. * PLANNED ENHANCEMENTS (Blue Sky) 1. Fuller source level debugging support (i.e. >d1) for SAS 6.0. 2. Source level debugging support for Manx (and DICE?). 3. Enforcer/Mungewall/MemMunge features (use MMU). 4. Remote debugging via serial port 11. CHANGE HISTORY ~~~~~~~~~~~~~~~~~~~ 1.10 Changes 1. Created the 68000 version of Mykesbug. 2. Optimized the screen display to make it faster for both versions. 3. Mykesbug now shows the correct name for the program being debugged. 4. Added the use of the Page UP and Page DN keys in Help mode and in the system list display modes. 5. All of the system lists now scroll. This makes them alot more readable. (This was hard! :) 6. Added the 'symbols' command. Displays, in a scrolling list, the symbols in the loaded program. 7. The screen now refreshes properly when Single Stepped past the bottom of the dissassembly window. 8. The suspend action now works correctly under both 1.3 and 2.0. 9. Adde the file MykesBug-Startup. This allows the User to pre-set several options for the debugger. 10. The Stepping now leaves the stack clear. 1.04-1.09 Changes (These happened somewhere in here :) 1. Addition of Mixed mode display 2. Color support (there are 2 planes :) Highlight changed registers Highlight current PC in display window Highlight breakpoints 3. Display of the source file name on screen 1.03 Changes 1. *Color added to display. 2. *Cursor Up/Down in source mode - use line # 3. X Breakpoints use line # if in source mode 4. *breakpoints in supervisor context 5. *case insensitivity 6. Uses GfxBase routines to contruct CopperList. (temporarily removed) 1.02 Changes 1. MykesBug now does SetFunction on Debug() (assembly programmers can just use a TRAP instruction anywhere they want in their code, as well) 2. Added Info command, moved library base display to info display. 3. Added ExecBase command, dumps ExecBase structure. 4. Added MemList, ResourceList, DeviceList, IntrList, LibList, PortList, TaskList commands for displaying Exec lists. 5. InitDebugger and CleanDebugger now called via Supervisor() and the VBR register is used to locate the exception vectors! 6. VBL handler no longer cycles pointer color 1.01 Changes 1. 32 sticky breakpoints implemented, using bs,br, and bd commands. 2. Single Step changed to restore system before stepping. 3. Source level single step improved to work as good as CPR. 4. Source level stepover function is same as single step. 5. Copper List disassembler implemented, using dc command. Initial dc address is GfxBase->LofList. 6. Fixed bug in the mr command that prevented modification of data and address registers ('C' syntax problem :) 7. Debugger now revectors Alert() to catch OS errors as well as CPU exceptions. 8. suspend.info added to distribution 9. MykesBug now checks for the existance of suspend.info and prints instructions on how to create one if it is missing. 10. Bug fixed in suspend routine to handle case where suspend.info doesn't exist (used to try to FreeDiskObject(NULL), which is a NONO). 11. Bugs fixed in the bc,wc,lc commands. These now should work.