GI_Mon

Well, I’ve just finished another proggy and now its time for my favourite bit, the instructions. Oh goody. Ah well, here goes…

GI_Mon is a monitor program designed to help you track down bugs in machine code programs (so if you’re one of the lucky people who don’t know about the insomnia and 3am bedtimes that is MC programming, you might as well exit to the FRED menu now and play a game or something). It allows you to disassemble and single-step through an MC program to find out what it does to the registers, flags, memory, etc.

The program will run at the start of any memory page above address 32767. To use the program simply load it in at the desired address (the program is on the disk under the filename “GI_Mon .O”) and CALL it. When the program is run, it reserves 2 pages in the Page Allocation Table and another 2 pages immediately above it (skipping a page if the program is loaded at an odd-numbered page) for the monitor screen. This means that the program won’t be corrupted by DOS commands or a RAMdisk. The program should run on a SAM with only 256K of RAM, but there’s no check to find out how much memory you have, and I’m not sure what will happen if you try to view/singlestep memory that you don’t have!

The program features a simple WIMP system which most people should be reasonably familiar with by now, so I’m not going to go into any great detail here. To move the pointer around the screen, use the joystick keys 6789, and to click something press 0. If you have a mouse it can be selected instead (see later). You can move a window around the desktop by clicking the title bar and dragging the outline to the required position before releasing the button. To close down a window or menu , just click anywhere outside it. Note that you can only have one open window/menu at a time.

The main screen is split up into a number of selections:

• The top left of the screen shows the current values of LMPR, HMPR and VMPR, the layout of the memory (the ROM or RAM pages in blocks A (0-16383), B (16384-32767), C (32768-49151) and D (49152-65535), and also the current screen page (lower 5 bits of VMPR) and the screen mode (bits 5 and 6 of VMPR plus 1). The value of these ports can be altered by clicking the appropriate number and typing in its new value (as with numbers elsewhere in the program, you can specify a hex number by preceding it with a & symbol, or a binary number by a % symbol). Note that the program can only deal with internal memory, so if you enter a value for HMPR with Bit 7 set (used to access the 1 Meg external memory) it will be rejected.
• To the right are the value of the single registers A, B, C, D, E, H, L and F in hex or decimal and in binary. Again, to change the values click on the hex/decimal number and enter a new value. Also, if you click on a binary digit for one of the registers, it will be toggled from 0 to 1 and vice versa.
• Next to these are the values of the register pairs, index registers, alternate registers and stack pointer (SP) which can be changed in the same way, and the contents of (AF), (BC), (DE), (HL), (IX) and (IY). Next to this is a list of the top seven addresses on the stack, with the top item at the bottom of the list.
• At the bottom left is the disassembly at the current PC address (which can be changed by clicking the first address in the disassembly and entering a new value), and to the bottom right is a numeric or ASCII dump (the address of the start of the memory dump can be changed in the same way).

   

  Each line of disassembly shows the address of the opcode, then the bytes of hex for the opcode, then the mnemonic. Note that the disassembler will only show “documented” Z80 instructions - if it comes across an instruction it doesn’t recognise it will use a DEFB mnemonic. The numeric dump simply shows a list of PEEL values at the address. These values can be editted by clicking on a number and entering new values. To leave this POKE mode, press ESC and the pointer will reappear. The ASCII dump uses a “.” character to denote codes outside the range 32-127, and lines of ASCII text can be editted in a similar way to numeric data. Numeric and ASCII display can be toggled between (see later).

• At the very top of the screen is a menu bar with three pulldown menus. The Options menu contains the following options:

Credits
Prints up a window with my name in it.

Palette
Allows you to reconfigure the palette colours used by the program. Just click the numbers in the grey boxes and enter new ones.

Breakpoints
Sets up breakpoints to stop a running program under certain conditions. It uses the Calculator (see below) to evaluate the expression entered in each of the five boxes in the window (any empty boxes are ignored). If the result is not zero, then the program being monitored will stop running and open a window with a message saying that a breakpoint condition has been met and which one (1-5) it was. This means that the program will allow you to set up quite complicated breakpoints without returning to BASIC, eg:

pc=32768 will stop the program if it tries to run an instruction at 32768

peek hl<>255 will stop the program if the value of (HL) is not 255

f band 1 will stop the program if the carry flag is set etc.

Calculator
When this window is open, clicking anywhere inside it will allow you to enter a calculation, and the computer will display the answer. As well as the usual +,-,* and / operations, the following extra operations are permitted:

• a\b - Gives the modulus (remainder) of a/b
• PEEK A - Gives the value of a certain memory address
• DPEEK A - Gives the double-peek value of a and a+1
• a AND b - Gives 1 if a and b are both not zero, otherwise it gives zero
• a OR b - Gives 1 if a or b are not zero, otherwise it gives zero
• a XOR b - Gives 0 if a and b are zero, or a and b are both not zero, otherwise it gives 1
• NOT a - Gives 1 if a is zero, 0 if a is not zero
• a BOR b - Binary ORs a and b
• a BAND b - Binary ANDs a and b
• a BXOR B - Binary XORs a and b

Also, the registers A, B, C, D, E, H, L, F and the register pairs AF, BE, DE, HL, IX, IY, PC and SP can be used in calculations, and give the current value of the register/pair. Note that the calculation is worked out from left to right, ie no operation has priority over another, although brackets can be used to indicate the order in which the calculation is worked out. Values used in the calculations are restricted to integer values from 0-65535

The base (hex, decimal or binary) in which the result of the calculation is given can be selected by using the commands HEX, DEC and BIN. If there is an error in typing in the calculation, a Syntax Error message will be displayed. All the calculator operations except DEC, HEX and BIN can also be used in defining breakpoint conditions.

Exit
This displays a window which asks you to confirm whether you want to quit. Clicking the Okay button will exit to BASIC but keep the page markers for the program, so you can call it again (the current values for the registers, etc. will be preserved). Clicking Cancel will get rid of the window (so will clicking outside it). Clicking Exit and Close will exit to BASIC and remove the page markers from the Page Allocation Table, freeing up the memory it was using.

The Display menu allows you to select a hexadecimal or decimal display, a numeric or ASCII memory dump at the bottom left, and keyboard or mouse control. The current settings are shown by ticks. Note that there is no check to see if you actually own a mouse, but if you accidentally select mouse control, you can change back to keyboard using CNTRL-M hot-key (see later).

The Clear menu allows you to return to default values for the registers, stack and memory paging.

• Clear Registers sets the values of the registers (including the index and alternate registers) to zero.
• Clear Stack mores the stack pointer to the bottom of the stack, getting rid of all the addresses currently on it.
• Clear Memory sets the startup paging arrangement (ROM0, Page 0, Page 1, Page 2), sets the PC and memory dump address to 32768 and sets the stack pointer to 20100 (clearing the stack).
• Clear All does all of the above.

Hot-Keys
As well as the above options, you can use the following keys while in pointer mode, but not while a window or menu is open:

• Cursor Down - Disassembles forward one line.
• Cursor Up - Disassembles backwards one line. The instruction given will not necessarily be correct, but it gets it right most of the time, and the backwards disassemble is quite fast.
• F0 - Nudges disassemble forward one byte.
• F1 - Nudges disassemble backwards one byte.
• F4 - Scrolls memory dump forward one line.
• F7 - Scrolls memory dump backwards one line.
• F9 - Single-steps the instruction at the top of the disassembly.
• F8 - Displays the screen currently selected by VMPR and runs through the instructions until it comes across an error or a breakpoint. Press ESC while in this mode to interrupt the program and display the values of the registers, etc. See later for further details on the single-step
• SPACE Bar - Holding down the space bar will display the current screen without running any instructions.
• CNTRL-P - Calls up the Palette window (same as selecting the palette option from the Options menu.
• CNTRL-C - Calls up the Calculator window.
• CNTRL-B - Calls up the Breakpoint window.
• CNTRL-X - Calls up the Exit window.
• CNTRL-H - Toggles Hex/Decimal display.
• CNTRL-N - Toggles Numeric/ASCII dump.
• CNTRL-M - Toggles Keyboard/Mouse control.

The Single-Step
The single-step function enables you to run an MC program one instruction at a time. It can cope with paging, and will allow you to single-step instructions from anywhere in the SAM’s internal memory (including ROM0 and ROM1). Like the disassembler, it can only deal with documented Z80 instructions, and if you try to single-step an unrecognised instruction an error will result. Most other instructions will run normally with a few exceptions:

• OUT instructions to the ports 250 (LMPR), 251 (HMPR) and 252 (VMPR) change the low memory paging, high memory paging and current screen respectively in the usual way.
• OUT instructions to port 248 (CLUT) with the high byte in the range 0-16 will change the palette colurs that the output screen is displayed in (initially the palette table contains the default MODE 4 palette values). OUT instructions to any other ports are ignored and skipped over.
• IN instructions to ports 250, 251 and 252 will read the values of these ports. IN instructions to other ports will be executed “as they stand” from within the monitor program, so things like key scanning should work.
• IN commands, writes to the I and R registers and the commands EI, DI and HALT are skipped over by the monitor (since they could seriously mess things up).
• Output to the screen must obivously be done by POKEing the relevant addresses in the screen, so I’m not sure what effect using the ROM routines to print to the screen will have if VMPR is not set up to point to the page that was being used by BASIC. To be honest, I hardly ever use the ROM routines anyway. Experiment and find out.

Okay, I hope that this has give you some idea of how to use the program. It’s not very difficult to get used to, so you’ll just have to experiment. I hope somebody gets something out of this program - it took me ages to write. If anyone has any questions, comments, criticisms, etc about it, please send them to me (address at end of file) or FRED.