                        Singlestep

              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 debug 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 registers 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.
  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.
  Also displayed is the current value of the breakpoint
address, BR. The F or Flag register shouws 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, i.e., 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 interrupt-
ing device supplies must be input. It is assumed that the
Spectrum supplies FF when in IM2 or IM3[sic].
  Here are some simple programs to illustrate the use of
Singlestep. First, load the program. This will produce a
display sinukar to the one shown in figure 1.

Hex    Mnemonic   Comment
06 02  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, i.e. -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, i.e. 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 the
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 FE69. So enter the
following:
P FE69H      PC now points to FE69
HEX 00ED4D   m/c 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.
___________________________________________________________
+----+----+----+----+            | Figure 2. The memory map
| IX | IY | SP | PC |   BR    FE |
|0000|5C3A|CF08|EA6C| 65535d  FF |              48K
+----+----+----+----+         47 |              Low memory
|  H reg  |  L reg  |         3A |
|01000000b|00000000b|         FF |             |\_/\_/^\_/|
|40H   64d|00H    0d|         FF |             |          |
+---------+---------+         4F |             |Basic     |
|  D reg  |  E reg  |   PC    0A |             |program   |
|00000000b|00000000b| 60012d<>77 |       29500 +----------+
|00H    0d|00H    0d|         03 |             |Stack     |
+---------+---------+         0A |       53000 +----------+
|  B reg  |  C reg  |         3C |             |Machine   |
|00000000b|00000000b|         16 |             |code      |
|00H    0d|00H    0d|         00 |       54202 +----------+
+---------+---------+         5F |             |          |
|  A reg  |  F reg  |         19 |       55000 |<-        |
|11111111b|S Z P/V C|         03 |             |_/\_/^\_/\|
|FFH  255d|0 0  0  0|         3A |
+---------+---------+         FC | Initial value
                              FF | of program counter
                              B8 |
                                 |
    Figure 1. The screen display |