Club 100 Library - 415/939-1246 BBS, 937-5039 Newsletter, 932-8856 Voice Originally QBUG by Jay Holovacs 8/30/85 Revised DEBUG by Robert Benson 3/10/88 DEBUG simplifies the debugging of "machine language" programs on the Model 100 by providing interactive user information and control of the 8085's Registers, Stack and your program. DEBUG accomplishes this by accessing the code in your program through a M/L support routine rather than by a direct CALL. The values which you select are transferred to the Stack and Registers, then your program is called. While returning the current Stack and Register values are saved for viewing later. In general "machine language" programs should be debugged with much more care than their Basic counter parts, below are some suggestions: 1) Always work from a printed copy of the M/L code. Consult it meticulously, don't rely on memory. 2) Never execute a new stretch of code without first backing up everything in RAM. Proper use of DEBUG can greatly reduce the chances of a system crash, but occasional it will happen. 3) Execute small stretches of code at a time, setting the breakpoints at key locations. Always set a breakpoint at a conditional jump (JN, JNZ, JNC) with each new set of values and check for flags in REGESTERS. I find it helpful to repeatedly use the same data and execution point while moving the breakpoint further down the line and as segments are verified then choose new execution points. 4) When testing any M/L routine that affects BASIC (a hook into the background task for example) always use a dummy address in RAM. You can easily insert and read values in such an area without the danger of a system crash. Only when the routine performs as expected should the real addresses be put in place. Proper use of labels in your source code will make for reassembly without incident. RUNNING DEBUG Before running DEBUG load your M/L code, set HIMEM and depress CAPS/LOCK key. All values must be in Hex, the BKSP key may be used in the normal manner. When first initializing DEBUG there will be a brief pause as the support routine is loaded, then the DEBUG menu will appear. Any function except QUIT can be used and aborted repeatedly before executing your M/L code, simply press the letter for that function and follow the instructions. BREAKPOINT: This sets the ending address for your test run, execution stops just before the address that you select. If a breakpoint is already set it will be displayed on entry and can be left unchanged by just pressing [ENTER] alone to return to the menu, if a new breakpoint is selected the old one will be cleared automatically. Selecting a breakpoint replaces 3 bytes of your programs code with a JMP to the strat routine in the M/L support and stores your code in a clean up area of the support. When a breakpoint is cleared your code is automatically put back in its original location unless your program runs away for some reason, breakpoints are cleared after every run and must be reset before another. WARNING: Do not exit any way but through a breakpoint, the clean up routine is essential for the restoration of your original code. REGISTERS: This allows you to examine the contents of the registers and flag before and after executing a section of code. As the value in each register appears you have the opportunity to change it by typing a new one and pressing [ENTER] or leaving it unchanged by just pressing [ENTER] alone to view the next one. MEMORY: This allows you to view and change the M/L code at any address in your program, when prompted type a desired address and press the dowm arrow or up arrow keys to advance or backup. Addresses, values and their characters are displayed and can be changed just by typing in a new value and moving on. To view an address far removed from the present one just return to the menu by pressing the [ESC] key and repeat the process. STACK: This allows you to view up to 5 items remaining on top of the Stack after an execution, they are the sole result of your M/L code. While the Stack can be inspected from this option, it can only be loaded at the beginning of EXECUTE. EXECUTE: This sets the starting address of the M/L code to be tested. Upon entry you will be prompted for a starting address, you may abort at this point by just pressing [ENTER] alone. EXECUTE will automatically go to BREAKPOINT if one is not already set. After the starting address is entered you will have an opportunity to place up to 5 items on top of the Stack, these must be 2 byte values. Pressing [ENTER] alone or entering "0" will bypass this step and start execution. After execution you will be returned to the menu and the breakpoint cleared. QUIT: Always exit to the 100's main Menu through QUIT as this will clear any pending breakpoints and leaves your code intact. TECHNICAL NOTES: DEBUG will not accept a execution point, breakpoint or memory location outside of your program area. The major differance between version 3.1 of this program and previous ones is that this one loads the M/L support into a reserved buffer in machine memory. Previous versions loaded it right below MAXRAM making it impossible to work on most second party programs as they invariably were located there also and were not reloctable. When selecting a breakpoint bear in mind that you cannot return up through more layers of the Stack than you have called. DEBUG uses the warm start address as its flag to determine what part of the Stack is the code you are processing, if you should accidently return through this a warm start will be executed saving the system from a crash. This is not bulletproof however, if you use a lot of PUSH's and POP's you could conceivably go through that protection. It is entirely possible for an error in the users M/L program to overwrite any part of RAM, if you start having trouble with the system preform a cold start.