
SINGLESTEP
by Ian Potts for Sinclair Spectrum
from Your Computer vol.5,#4 (Apr.85)

Ian Potts with a small step for your micro, a giant leap for you.


SINGLESTEP ALLOWS YOU to run through machine-code routines one
instruction at a time, thus helping you to learn machine-code
programming or to de-bug machine-code routines.

The contents of the main registers are displayed in hex, decimal and
binary and thus the effect of any operation, especially the logical
operations, is easily seen. Register contents, program counter and the
flag register can be changed at any stage, with numbers being input in
either hex or decimal.

One breakpoint address can be set which allows a long routine or loop to
be executed at full speed. Interrupts in all three modes can be
simulated. A simple machine-code loader is included which allows
machine-code routines to be inserted at the program counter address.

Type in the machine-code loader program which can then be run and saved
if correct. Now type NEW. The Basic can now be typed in, and both Basic
and machine code can be saved by entering GO TO 9900.

The A, B, C, D, E, H and L registers each have their contents displayed
in binary, hex and decimal. The IX, IY, SP - stack pointer - and PC -
program counter - register contents are displayed in the boxes in hex.
Down the right-hand side of the display is a printout of some of the
contents of memory in hex with the current value of the program counter
displayed in decimal and pointing to the correct memory location - see
figure 1 [see SINGLEST.GIF].

Also displayed is the current value of the breakpoint address, BR. The F
or Flag register shows the current status of the sign flag S, zero flag
Z, parity or overflow flag P/V, and the carry flag C. If an exchange
register instruction is carried out then an apostrophe will be displayed
by the registers affected.

First,  let's  look  at  the  single-letter commands:

S   Singlestep,  ie. carry out next machine-code instruction.
R   Restart program. Clear all registers and reset SP and PC.
Q   Quit program and exit to BASIC. GO TO START will restart the program.
I   Simulate an interrupt.
K   Continue program at full speed up to breakpoint address.

Here are the commands requiring a value to be input:

P   Change program counter to value input.
P+  Add value to program counter.
P-  Subtract value from program counter.
BR  Set breakpoint address to value input.
HEX Inserts hex code starting at program counter address.
F   Set flag register to value input - this must be four digits,
    each digit either 0 or 1.

Any register letter or register pair will set that register to the value
input. If the value input ends in H then the number is interpreted as
hex, otherwise it is taken to be decimal. HELP will display a summary of
the commands.

The stack pointer is initially set to point to the start of the code.
The machine code is not relocatable.

On entry, interrupts are enabled and IM1 is selected. Interrupts can be
disabled in a program - Singlestep will still work. When IM0 or IM2 is
selected in a program then if an interrupt is simulated, the data that
the interrupting device supplies must be input. It is assumed that the
Spectrum supplies FF when in IM2 or IM3.

Here are some simple programs to illustrate the use of Singlestep.
First, load the program. This will produce a display similar to the one
shown in figure 1 [see SINGLES1.GIF].

Hex     Mnemonic        Comment
0602    LD B,2          Load B with 2
00      LOOP: NOP       Do nothing
10 FD   DJNZ LOOP       Subtract 1 from B, if result is non-zero
                        jump FD, ie. -3

To enter this program type HEX followed by Enter. Then type 06020010FD
Enter. The machine code will now be inserted. Note that each byte must
be entered as two digits, ie. 02 for 2 etc. Now type P- Enter followed
by 5 to move back to the start of the program. Press S Enter and the B
register will now contain 2. Press S Enter and all that will happen is
that the program counter increases by 1. Press S Enter and the program
counter will now point to the start of the loop, and the B register will
now contain 1.

Continue pressing S followed by Enter until the program counter contains
55005. You have now exited from the loop.

Here is another example program.

Hex     Mnemonic        Comment
06 FF   LD B,255        Load B with 255
00      LOOP: NOP       Do nothing
10 FD   DJNZ LOOP       Loop as before

To change the first example program, type in P 55001. This moves PC to
point to the byte to be changed. HEX FF - FF is now inserted. P- 2 means
that PC now points to start of the program.

Enter S several times. As you can see it will take a long time to exit
from the loop. To execute the code at speed, enter BR 55005, which sets
the breakpoint address. K now executes the program at full speed.

Now for the third example:

D9      EXX      Exchange registers
D9      EXX      Exchange registers

To enter this program type
HEX D9D9
H 32  - puts 32 decimal into register H
D 32H - puts 32 Hex into register D
P- 2  - moves PC to point to start of program

Now  singlestep  twice,  observing  the display.

This fourth program simulates an interrupt in Mode 2.

3E 09   LD A,9
ED 47   LD I,A  Load I with the value 9
ED 5E   IM2     Set interrupt Mode 2

Load this program starting at address 54994 so that it precedes the
second program. When you simulate an interrupt you will supply the byte
FF so that the interrupt is vectored via the contents of 09FF to FF69.
So enter the following:

P FE69H     PC now points to FE69
HEX 00ED4D  m/code NOP, RETI is loaded.
P 54994     Return to start of program 4

Enter S three times to set up interrupt values. Now singlestep some way
through the loop of the second program and enter I. In response to the
prompt, enter FF. You will now jump to 65129 (FE69); you can now
continue single stepping and you will return to the point where the
routine was called.

For those who baulk at typing in all the data, I would be prepared to
supply copies of the tape at #3 each provided the name and address is
clear. Ian Potts [address removed].


Figure 2. The memory map.

		       48K
		       Low memory
		      . _ _  _ _ .
		      |          |
		      |          |
		      | Basic    |
		      | program  |
		29500 |__________|
		      |          |
		      | Stack    |
		53000 |__________|
		      |          |
		      | Machine  |
		      | code     |
		54202 |__________|
		      |          |
		      |          |
		55000 | <--      |
		      |          |
		      . _ _  _ _ .

Initial value
of program counter


--
Another Fine Product transcribed by:
Jim Grimwood, Weardale, England
http://www.users.globalnet.co.uk/~jg27paw4/
--
