GI_Mon version 3.0 instructions ------------------------------- Hi. At the last show, Stefan Drissen suggested that I write an improved version of my machine-code monitor program, GI_Mon, so here it is... I wedged the program into a slightly improved WIMP environment I was working on, added a simple assembler facility and a search option, as well as a few other bits and pieces which are explained in more detail later on. Otherwise, it is fairly similar to the original, so if you already use it you should be able to quickly skim through these instructions. GI_Mon is a utility to help machine-code programmers to track down bugs in a program by running it an instruction at a time to see what effect it has on the registers, memory, flags, stack, etc. (so if you're not into writing machine-code, it isn't going to be much help - go away and learn it!). To use the program, simply load the code file at the start of a page and CALL it. It reserves 2 pages in the Page Allocation Table for the program code, and another 2 pages immediately above this (skipping a page if the program is loaded at an odd-numbered page) for the monitor screen. The program is based around a simple WIMP environment, with the pointer controlled by either the joystick keys 67890, or a mouse (see later). Pulldown menus are accessed by moving the pointer to the appropriate position at the top of the screen, and windows can be moved around the desktop by clicking on the title bar and dragging the outline to the required position. To close a window or menu, just click anywhere outside it. Of course, most windows have buttons/things to be editted (usually in grey boxes) which are generally selected by clicking them. I'll go into more detail about what the individual menu/window options do later. The main screen is split up into a number of sections. At the top left of the screen is the current values for the LMPR, HMPR and VMPR (ports 250, 251 and 252 respectively), the pages in blocks A,B,C and D, and the current screen page and mode. The LMPR, HMPR, screen page and mode can (like most of the rest of the main screen) be changed by clicking them and entering new values. To the right are the current values of the registers, register pairs and values of the memory addresses pointed to by the register pairs (which can of course all be changed in the same way). The single registers A, B, C, D, E, H, L and F are also shown in binary, and individual bits can be toggled by simply clicking them. At the top right of the screen are the top seven items on the stack, with the top item at the bottom of the list. At the bottom left of the screen is a disassembly of the instructions at the current PC (Program Counter) address. Note that the disassembler only recognises "documented" Z80 opcodes and if it comes across an opcode it doesn't recognise it will use a DEFB mnemonic. To change the PC address, click the number at the top left of the disassembly and change it. You can also change the disassembly by clicking an instruction and entering a new one - this gives in effect a (very simple) assembler! Good eh? Actually, I think it would be quite useful for people learning to code to use this feature to enter a few instructions or a short routine, then use the single-step to see what happens. Press ESC at the input prompt to exit the assembly mode. Next to the disassembly listing is a memory dump - this can be either ASCII or numeric - see the Display menu, later. To change the address of the dump, edit the top address. You've probably guessed by now that you can change the memory contents by editting the numbers/lines of ASCII (unless it's in the ROM!). Again, you need to press ESC to stop changing memory contents. Some notes on editting: When in input mode, EDIT will clear the input field, SYMBOL+EDIT will restore whatever was in the field when you clicked it. ESC will exit input mode discarding any changes you made to the field. Numbers can be entered in decimal, or in hexadecimal by preceding the number by "&", or binary by preceding the number by "%". Generally, if you enter bad input anywhere, the program will discard it and restore the original contents of the field. The program is not case-sensitive. Now on to the various menus/options: The Options Menu ~~~~~~~~~~~~~~~~ This contains the following options: Credits ~~~~~~~ Version number and my credit. Palette ~~~~~~~ Allows you to change the palette colours used by the monitor program - just click the boxes and enter new values. Calculator ~~~~~~~~~~ Calls up the calculator window. To use it, click anywhere inside the window and enter a calculation. As well as the usual +, -, / and * the following extra operations are permitted. a\b: Gives the modulus (remainder) of a/b. BAND, BOR, BXOR: Binary AND, OR and XOR. AND, OR, XOR, NOT: Logical AND, OR, XOR and NOT - similar to the corresponding BASIC commands and usually used in specifying breakpoint conditions. PEEK, DPEEK: Give the PEEK and DPEEK value of a certain address. You can use the registers, register pairs, PC, SP, LMPR, HMPR and VMPR in calculations. Note that all operations have the same priority, although you can use brackets to specify which parts of a calculation should be carried out first. You can also use the comparison operators =, <, >, <=, >=. These return 1 if the comparison is true, otherwise they return 0. For example, HL=0 returns 1 if the value of the register pair HL is zero. These tend to be more useful in breakpoint conditions (see below). The base in which the result of calculations is shown (hex, decimal or binary) can be changed using the commands HEX, DEC and BIN. Finally, you can enter text into the calculator by starting the line with a semi-colon - so the calculator doubles as a note-pad. Breakpoints ~~~~~~~~~~~ Uses the calculator to evaluate the expressions in each of the five boxes after an instruction has been single-stepped. If any of the expressions returns a non-zero value, the program being monitored stops running and a message is printed telling you which of the five breakpoint conditions were met. This allows you to set up quite complicated breakpoints, eg. pc=32768: Stops the program if it ends up at address 32768. peek hl<>255: Stops the program if the value of (HL) is not 255. f band 64: Stops the program if the zero flag is set. Of course, you can use AND, OR, NOT etc. to string conditions together to make a longer one, eg. (pc=32768) and (f band 64) You can use any of the commands used by the calculator (except HEX, DEC and BIN) to define breakpoint conditions. Search ~~~~~~ Allows you to search the memory for a sequence of bytes - you can enter 8 or 16-bit numbers, or strings (enclosed in quotes), eg. "GI_Mon",1,255,12345,0 The "Okay" button searches through the 64K of memory starting at the address in the "Start" box - if it finds a match it will clear the search window and set the memory dump address to the address of the match. The "Next" button does the same thing, except it starts the search at the current memory dump address. A search can be abondoned by pressing ESC. Check Stack ~~~~~~~~~~~ When this feature is enabled (ie it has a tick next to it) the single-step will return a "Stack Overflow" error message if the program being tested tries to pop from an empty stack. However, sometimes it is necessary to disable this feature to run certain routines which mess around with the Stack Pointer (SP). If you do disable this feature though, be careful that you don't single-step past the end of your code, since the monitor will not recognise the final RET in your program! Exit ~~~~ Exits the program. You will be asked to confirm this with the following options: Okay: Exits the program but keeps the Page Allocation Table markers in place - use this if you want to leave temporarily but return to the program later. Cancel: Closes the window Exit and Close: Exits the program and removes the Page Allocation Table markers - use this if you have finished using GI_Mon altogether. The Display Menu ~~~~~~~~~~~~~~~~ This allows you to toggle between the following sets of options - current settings are shown by ticks: Hexadecimal/Decimal: Select values on the main screen to be represented in either hex or decimal. ASCII/Number Dump: Select whether the memory dump shows ASCII or numeric values. Keyboard/Mouse: Select between keyboard or mouse control - the program doesn't actually check to see if you own a mouse, but if you accidentally select mouse control you can get back keyboard control by pressing CNTRL+M. The Clear Menu ~~~~~~~~~~~~~~ This resets various things back to their initial values. Reset Registers sets all the register values to zero. Reset Stack discards all the values currently on the stack. Reset Paging sets the LMPR to 31, HMPR to 1, PC and memory dump address to 32768 and SP to 20100. Clear All does all of the above. The Font Menu ~~~~~~~~~~~~~ The Change Font option grabs the font being used by BASIC for use in the monitor program. The old font is stored so you can get it back by selecting the Reset Font option (so if you don't like the monitor font, load some other font into BASIC, call the monitor and select Change Font). Keys ~~~~ You can use the following keys while in pointer mode (but not while a menu or window is open): F9: Single-steps the instruction at the current PC address. F8: Displays the screen specified by the current VMPR value and runs the program being monitored until a breakpoint condition or an error has been met, or ESC is pressed. F6: If the instruction at the PC address is not a CALL or RST instruction, this has the same effect as pressing F9. If it is, the monitor runs the program until it reaches the address after the CALL (ie the program returns from the called routine) or an error or breakpoint is met. This can be useful if you are testing a routine which calls other routines which you know work, since you can run the routines as single instructions instead of having to wade through each one. F7: Scrolls the memory dump back one line. F4: Scrolls the memory dump forwards one line. F1: Nudges the disassembly back one byte. F0: Nudges the disassembly forwards one byte. Up arrow: Scrolls the disassembly back one instruction (note that the instruction obtained will not always be correct). Down arrow: Scrolls the disassembly forwards one instruction. SPACE: Holding down SPACE will display the screen in VMPR without running any instructions. These keys provide short-cuts to options already on the menus: CNTRL+P: Calls up the Palette window. CNTRL+B: Calls up the Breakpoints window. CNTRL+C: Calls up the Calculator window. CNTRL+S: Calls up the Search window. CNTRL+X: Calls up the Exit window. CNTRL+H: Toggles between hexadecimal and decimal display. CNTRL+N: Toggles between numeric and ASCII memory dump. CNTRL+M: Toggles between mouse and keyboard control. SYMBOL+N: Same as selecting Next from the Search window. The Single-Step ~~~~~~~~~~~~~~~ This steps through the instructions of a machine-code program one at a time, to see the effects on registers, etc, from anywhere in the SAM's internal memory. Like the disassembler, it can only deal with documented Z80 opcodes. Most other instructions work normally, with some exceptions: OUT commands to ports 250, 251 and 252 (LMPR, HMPR and VMPR) change memory paging in the usual way. OUT commands to port 248 (CLUT) with the high-byte in the range 0-15 changes the palette of the output screen. All other OUT commands are ignored by the monitor. IN commands to ports 250, 251 and 252 will read current values from these ports - IN commands to other ports will be read directly from within the monitor program. The IM commands and DI/EI change the interrupt status shown somewhere near the top of the screen - since the monitor makes no attempt to implement interrupt calls, this doesn't serve any purpose except to show you what values the program being tested would have set these values to. HALT, LD R,A and LD I,A are ignored by the monitor. Errors are produced by the single-step if it comes across an unrecognised opcode, or the program being tested attempts to pop from an empty stack (unless stack checking has been disabled). And that's it! (I think...) If anyone has any comments/questions or finds any bugs in this program, please feel free to write and I'll try to sort them out. My addresses are: (Home) 8, Chester Crescent, (Term) Flat 2, Helmshore, 14 Chester St, Rossendale, Coventry, Lancs, CV1 4DJ BB4 4HE. (or email mauiw@csv.warwick.ac.uk)