CPU window

The CPU window is available from the View menu.

The CPU window is available for you to view the internal workings of your machine code programs.

Advanced users only!

If you have little or no previous knowledge of z80 assembly then it is recommended that you don't use this window - it is very easy to lose your work by altering things at the machine level in this way.

However, if you have no idea what z80 assembly is, but would like to understand how to use this debugger, then read on.

In order to maintain a very high degree of accuracy, BasinC utilises a method called emulation. This means that in order to mimic the behaviour of the original Sinclair Spectrum, a program takes the machine code instructions (opcodes) used by the Spectrum and executes tasks in a similar manner. In this way, by simply providing a memory model and a ROM image (which is nothing more than a z80 "program"), authentic Spectrum behaviour results.

The debugger converts bytes in memory to their mnemonic equivalents and allows you to control how the emulated z80 CPU follows the path through the ROM and watch it's internal workings. This method of "slowing down" and analysing the code is invaluable for finding bugs in machine code programs.

The CPU window provides a disassembly of the code in memory, and a list of the registers used, and a breakdown of the flags register. Also provided are a few control buttons which you can use to step through your code. You can also set Breakpoints very similar to the BASIC Editor by double clicking an address.

The CPU window can be configured to show all values in Hexadecimal or Decimal, using the View button at the bottom left of the window.

The Disassembly

The largest area of the CPU window is the disassembly. Disassembling is the process by which bytes in memory are converted to their mnemonic values, "english" representations of the jobs they do, and the parameters they take.

A sample disassembly:

You can get this display yourself by typing "0" into the "Disassembly of memory at" edit field, and pressing Return.

Note: The field you type your address into has more functionality than it at first appears. You can type in any register name, any label name, and and system variable name to get a disassembly at that position in memory.

From this diagram, you can see that the emulated CPU is at position 0 (zero) in memory - the small green dot indicates the value of the "PC" register (or Program Counter). It is this instruction that will be executed next. The addresses of the instructions are displayed in the grey "gutter" at the left of the window.

From BasinC, a command:

PRINT PEEK 0

Would yield the result "243", which is by no small coincidence the first value after the green "PC" dot. This value, when encountered by the emulated CPU, tells it to disable interrupts. This complex sounding operation is simply telling the CPU to ignore the timed 50hz (every 50th of a second) pulse which literally interrupts program flow, stores where you came from, jumps somewhere else, then jumps back again. The name of the instruction is, of course, "DI".

Note: Instruction (or opcode) names, such as DI, are not stored in memory - just the bytes, in this case 243, are stored.

On the next line down, at address 1 (one), another single-byte instruction follows - a value of 175, which equates to the instruction "XOR A". XOR'ing a value means to "Invert" the state of the bits in each byte, using a second value. The XOR opcode operates on the A register, and so XOR'ing the A register with itself will effecively set the "A" register to 0 (zero). Note that the instuction has only one byte - the "A" part is an implicit parameter. XOR B would have the bye value of 168, instead of 175.

The next instuction is more complex, but BasinC realises that it takes two bytes as a parameter, and so keeps them on the same line. As you can see, the instruction is LD DE, 65535

This instruction will take the two following bytes and encode them into a word value. This means taking the first byte, and adding it to 256 times the second byte. In this case, the calulation is 255+(256*255) which is 65535.

Lastly, the final instruction in this example is a jump instruction. Again, two bytes are taken as a parameter (203 and 17) and combined to get the result 4555. However, rather than writing "JP 4555", BasinC has written "JP START-NEW". This is because BasinC replaces known values with labels, which are marked areas in memory which have names associated with them. The ROM has several documented names (or labels) and uses these when in the ROM region of memory.

You might also notice that the name is typed in bold type. This is an indication that if you click on the name, the CPU window will jump to that address in memory, where you will be greeted with a disassembly of the START-NEW routine.

The Registers region

To the right of the window is a set of edit fields with two-letter names. These allow you to inspect and modify the emulated Z80's register set. These are a set of "variables" used by the chip to transfer and work on the bytes read from memory.

To edit a register, you can simply type into any of the edit fields. You will be warned if you input any values that would be out of range for that register. Any registers that have been modified (either by you, or by a single-step operation, or since the last time the CPU window was shown) will be highlighted.

Clicking any of the registers names (of the registers that can hold meaningful 16bit addresses) will force a disassembly at the location they address.

The registers are:

PC - The Program Counter. This is the address in memory where the emulated z80 will read it's next byte from.

AF - The AF register pair consist of the Accumulator and the Flags register. The accumulator is the register used in most 8 bit arithmetic opcodes (such as XOR). The Flags register stores information about the results an opcode may have created, such as carry, zero, sign etc.

BC - A 16bit register pair, with both 8bit registers being also available. Usually used as a counter, but can be used in memory operations in a similar manner to HL.

DE - Again, a 16bit register pair. Although both the component 8bit registers can be used, it is mostly used as the destination address in a memory move or copy operation. Can also be used in some opcodes as HL is.

HL - One more 16bit register pair, similar in operation to BC and DE, but mostly used by opcodes as the source memory address for move and copy methods. Also used for general memory reading/writing in it's (HL) form, as well as the many 16bit arithmetic opcodes.

IX / IY - The Index Registers. These are a pair of 16bit registers (though they can be accessed as pairs of 8bit registers using IXH, IXL, IYH, IYL) whose primary purpose is to hold data structure addresses. By loading one of these registers with an address, you can access bytes at offsets from it using the common form IX+D or IY+D. The Sinclair ROM makes extensive use of the IY register when accessing the system variables.

SP - The Stack Pointer. The stack is a region of memory used to PUSH and POP values onto. The top-most item (or address) is pointed to by SP. Pushing a value on decreases SP by 2 memory locations, popping increases SP by 2. Also used by the CALL opcode to enter subroutines (the stack is used to hold the return address), and by the RET opcode set to make a return from a CALL.

AF', BC', DE', HL' - The "Shadow Set". These registers are not available for use directly by opcodes - they must be swapped with the regular (non-shadow) registers first using the EX and EXX opcodes.

IR - The Interrupt vector register and the Refresh register. These registers are rarely used, and not many opcodes make use of them. I is used as the high byte of a pointer to a region of memory used as an interrupt table. The interrupt address is taken from this table, whilst the Spectrum is operating in IM 2 (See below). The R register is a counter which counts instructions executed. It increments roughly once every 4 TStates (strictly speaking, every M1 cycle - which includes any opcode prefixes such as $ED, $CB etc, but not doubly shifted opcodes such as $DDCB). R is not used by the hardware as a full byte - it uses only the lower 7 bits of the register. A detailed description of the R register is somewhat beyond the scope of this manual.

IM - The Interrupt Mode. This byte value can be set to 0, 1, or 2 which corresponds to the interrupt modes supported by the Spectrum. IM0 is of little use, as it has to be triggered by an external source (and not many Spectrum emulators allow this). IM1 is the regular ROM routine, which triggers a CALL to address 56. IM2 is the routine that uses the I register to compute the offset into a table of interrupt addresses, and CALLs that.

The Flags Register

The flags register holds information (in "switch", or on/off) form about the last - usually arithmetic - opcode that was executed. As it is a byte value, each of the bits can hold information. They are represented by checkboxes in the CPU window, and like the other more general registers you can toggle their state by clicking on them. As you do this, you may notice that the AF register pair changes it's value.

The eight flags are:

S - The Sign flag. If the result of the last arithmetic opcode was negative, this will be set. Essentially, a copy of Bit 7 of that result.

Z - The Zero flag. Like the sign flag, affected by the result of the last arithmetic opcode, and is set if the result was zero.

5 - One of the undocumented flag bits. Basically a copy of bit 5 of the result of the last arithmetic operation, but there are exceptions to this.

H - The Half-Carry flag. Used internally by the z80, it is set when the result of the last arithmetic operation "overflowed" from bit 3 to bit 4.

3 - The other one of the undocumented flag bits. This, like flag bit 5, is usually a copy of bit 3 of the result of the last arithmetic opcode.

N - This is set if the last arithmetic operation was a subtraction.

C - The Carry flag. This is set if the last arithmetic operation "overflowed", such as adding a large number to another number, such that the result was larger than 255, or subtracting a large number from a small one.

Program flow control buttons

Run - Close the CPU window, and allow emulation to continue.

Run to - You may have noticed that you can "select" lines of code in the disassembly area. By selecting an address, you can use this button to close the CPU window and have it re-open automatically when the emulated z80 CPU reaches the line you highlighted.

Step - Single steps through your machine code program one opcode at a time.

Step Over - Runs emulation until the next opcode is ready to run. There is a subtle difference between this and the single step operation - this one will wait for a return from a CALLed subroutine, and will wait for a HALT to complete before re-opening the CPU window.

Exit Func - This will run until the emulated CPU executes a RET (cc) instruction. Note that it will disregard any RET found after a CALL, and will only re-open the CPU window when emulation leaves the current subroutine level - in other words, it only exits the current level of nesting.