Files:
STEPPER - BASIC
BINDECH - BASIC
BINDECL - BASIC

65C12 Machine Code Monitor for BBC Master/Compact.

Note: This program will not work on an ordinary BBC model B or B+.

'STEPPER' is a program which enables the user to SINGLE STEP through a machine code program one instruction at a time. Selected memory area, program counter, register contents, flag register status, stack pointer and stack contents are all updated and displayed on the COMMAND SCREEN after each instruction has executed.

The program contains a DISASSEMBLER which can be called at any time when required. The program also disassembles each instruction prior to execution when in STEP MODE.

Memory contents, register contents, individual flag bits, can all be altered to set up any pre-condition prior to single stepping an instruction.

SINGLE STEP MODE has three modes of operation ........

1. Subroutines are treated as one step. This allows the result of calling a subroutine to be seen immediately.
2. Subroutines are called and stepped through as normal. This also allows the user to see how the stack handles JSR calls etc.
3. Only instructions which affect the program counter are executed. This allows the user to trace a programs path through ROM without the fear of crashing out. The user is free to alter the flag bits as required to determine the path taken as the ROM is stepped through.

A means of setting a BREAKPOINT is also included to allow execution of a section of code. Single stepping and breakpoint operation can be freely mixed.

The program contains two special features called:

1. WINDOW MODE
2. SHADOW OVERLAY

WINDOW MODE allows VDU driver output ie. JSR OSWRCH, machine code equivalents of PLOT COMMANDS etc., to be viewed in real time either by single stepping, breakpoint execution or combinations of both.

SHADOW OVERLAY works in conjunction with Window Mode to allow the effect of any machine code instruction that produces screen output by directly addressing screen memory to be viewed on the screen. This is achieved by PAGEING IN SHADOW MEMORY prior to executing an instruction ie. STA &4000 and PAGEING IT OUT AGAIN after the instruction has executed. With SHADOW OVERLAY ON, all instructions which reference &3000-&8000 will address SHADOW SCREEN MEMORY. See Shadow Overlay Reference Chart.

Execution of code via the breakpoint command will also force in SHADOW MEMORY if SHADOW OVERLAY is switched on.

In cases where a program may want to store data into normal memory ie. NON SHADOW MEMORY, Shadow Overlay can be SWITCHED OFF. NB. THE [E] EXECUTE FUNCTION WILL NOT WORK IF CODE IS STORED AT &6500 ONWARDS WITH SHADOW OVERLAY OFF. [DO NOT STORE DIRECTLY TO MEMORY BELOW &6500 WITH SHADOW OVERLAY OFF AS THIS COULD CORRUPT THE BASIC PROGRAM. ZERO PAGE USER MEMORY IS ALWAYS AVAILABLE OR PAGES &0B TO &0C IF ECONET IS NOT IN USE.

Programs can be stored between &0B00-&0CFF if they will fit. If not they must be stored at &6500 onwards. User zero page &70-&8F is free for use.

Programs must be stored at location &6500 onwards. User zero page &70-&8F is free for use.

When returning to the COMMAND SCREEN from WINDOW MODE the WINDOW SCREEN is saved to SIDEWAYS RAM. Re-selecting WINDOW MODE will restore the WINDOW SCREEN intact,including the text cursor position.

The Command Screen displays:

a. Contents of ACCUMULATOR in Hex.
Contents of X REGISTER in Hex.
Contents of Y REGISTER in Hex.
Contents of ACCUMALATOR in BINARY with CARRY FLAG. This allows the effect of rotate instructions etc. to be seen more clearly].

b. Contents of FLAG REGISTER AS individual bits [set/reset].
c. STACK POINTER plus EIGHT BYTES of STACK CONTENTS.
d. PROGRAM COUNTER plus DISSASEMBLED OBJECT CODE of next instruction to be executed.
e. MEMORY DISPLAY which can be SCROLLED, including two bytes of memory displayed in binary.

Pressing any of the keys below will select the function required.

[Z] Clears out SIDEWAYS RAM for a new WINDOW display.
[T] Resets all STEPPERS parameters to default values.
[B] Sets up addresses for BREAKPOINT option. When set the addresses are displayed on the top right of the COMMAND SCREEN. The breakpoint is inserted only when the 'E' key is pressed. The original memory is restored once the code has executed. [Breakpoints cannot be set in ROM].
[E] Executes code between addresses set by the 'B' command. Control returns to Stepper Program after code execution has finished. If no breakpoint has bet set then 'UNSET' is displayed on the top right of the screen. The 'E' command can also be used from the WINDOW screen. [EXECUTE will only function with SHADOW OVERLAY OFF if code under test is stored at &6500+]
[O] Toggles SHADOW OVERLAY on/off. [Can also be used in STEP MODE].
[P] Loads PROGRAM COUNTER as required [4 digit Hex. number with leading zeros.]
[M] Selects onscreen MEMORY DISPLAY to show 64 locations of memory from address entered. [4 digit Hex. number with leading zeros]. The memory display can also be two way scrolled with the Vertical Up/Down Arrow keys.
[V] Selects SCREEN MODE for WINDOW display, [Can be any Shadow Screen Mode 0-7, Shadow Mode 0 is selected by default]. When selecting a new screen mode for the WINDOW display the sideways ram banks used to store the window screen are cleared ready for a fresh display.
[S] Selects STEP MODE, the following keys operate within STEP MODE.

1. Horizontal Left Arrow Key.
2. Horizontal Right Arrow Key.
3. Vertical Up Arrow Key.
4. [ W ] Key.
5. [ O ] Key.

The Arrow Keys are used to SINGLE STEP through each machine code instruction in turn, but there is a difference between each key.

[ Left arrow key ]
Any SUBROUTINE encountered, including any nested subroutines, will be treated as a single step, allowing the total result to be seen immediately.

[ Right arrow key ]
SUBROUTINES are called and stepped through as normal. This also allows the user to see how the program counter and stack are manipulated when calling and returning from subroutines. [It should be noted that calling and stepping through MOS routines using this key may have upredictable effects]. Operating system calls ie. OSWRCH [JSR &FFEE] should normally be called using the left arrow key.

[ Up arrow key ]
This key is similar to the right key except that no code is executed other than JMP, JSR, and BRANCH instructions. This allows you to skip over any instruction that doesn't alter the program counter. It also allows a programs path to be traced through ROM safely while disassembling each instruction in turn. Branch instructions still respond to the Set/Reset status of the Flag Register. As the status of the flags can be toggled via the [ F ] command, the path a branch will take can be determined by the user. NB. SINGLE STEPPING AN 'RTS' OP CODE WITHOUT A RETURN ADDRESS ON THE STACK WILL LOAD THE PROGRAM COUNTER WITH AN UNPREDICTABLE VALUE. IF THIS HAPPENS, RETURN TO COMMAND MODE AND PRESS [ T ] TO RESET STACK POINTER AND RESTORE DEFAULT VALUES.

[ O Key ]
This key toggles SHADOW OVERLAY On or Off as required while stepping through a machine code program. [SEE SHADOW OVERLAY REFERENCE CHART].

[ W Key ]
This key selects WINDOW MODE. Window Mode allows the output of all routines that use the VDU Driver to be displayed on screen. With SHADOW OVERLAY ON, all instructions that reference &3000 to &8000 will address SHADOW SCREEN MEMORY. This allows the effect of code that produces graphics by directly addressing screen memory to be viewed on the window screen. Up, Left, Right arrow keys and the [ E ] command will all operate in WINDOW MODE. The '+' and '-' keys can be used to switch the cursor On or Off as required.

The COMMAND SCREEN screen can be returned to at any time by pressing the [ Q ] key. The WINDOW SCREEN is saved automatically to SIDEWAYS RAM BANKS 4 & 5. Reselecting WINDOW MODE will restore the Window Display intact. Stepping can then continue uninterrupted.

PRESSING [ Z ] WHEN IN COMMAND MODE WILL CLEAR SIDEWAYS RAM, THIS EFFECTIVELY CREATES A CLEAR WINDOW SCREEN.

[C] This allows the contents of any R/w memory location to be CHANGED.

[A] Load ACCUMULATOR.
[X] Load X REGISTER.
[Y] Load Y REGISTER.
[F] This allows the individual bits of the FLAG REGISTER to be set/reset as required. When selected, pressing [NV-BDIZC] will toggle the appropiate bit.

[D] This key calls the 65C12 DISASSEMBLER. Disassembly starts from the TOP LEFT address of the COMMAND SCREEN memory display. This address is set by via the 'M' key or by TWO WAY SCROLL using the UP/DOWN ARROW keys from the COMMAND SCREEN. Disassembler output can also be be directed to a lineprinter if required. Pressing 'Q' for 'QUIT' will return control to the COMMAND SCREEN.

[Q] THE COMMAND 'Q' FOR 'QUIT CAN BE ENTERED AT ANY TIME AND THIS WILL RETURN CONTROL TO THE COMMAND SCREEN. IF YOU MAKE A MISTAKE PRESS 'Q', RE-SELECT FUNCTION AND RE-ENTER DATA.

This program uses PAGES Nine and Ten (&0900 to &0AFF) normally used for RS432/232, Cassette input/output, Speech, Envelopes 5-16. (See ADV. Ref. Manual One, Page F.6-4). The BASIC variable 'PAGE' is raised from &0E00 to &0F00 Hex.

Code to be tested should be loaded into memory via the BASIC ASSEMBLER or the MOS '*LOAD' function before CHAINING the 'STEPPER' monitor program. If necessary PAGE is reset to &0F00 when loading the 'STEPPER' program.

STEPPER'S program counter defaults to &0B00 when first run. This setting may be changed by re-assigning the integer variable 'prgcntr%' contained within 'PROCinitialise' and re-saving the BASIC program to disc. NB. use filename 'STEPPER'.

If possible store code under test in pages ELEVEN and TWELVE, [&0B00 to &0CFF]. If this is not possible use &6500 onwards.

CODE ADDRESS
If Econet not in use then store code under test in pages 0B,0C. (0B00-0CFF). If Econet in use store code under test in page 65 onwards. (&6500 onwards).

EFFECT
Options available when code under test is stored in above locations.

E
Code can be executed via the 'E' command.

S
Code can be single stepped as normal.

WINDOW
Display dependant on SHADOW OVERLAY.

ALL
Window Screen will display the effect of any code that addresses screen memory directly including any vdu driver output.

VDU DRIVER ONLY
Only vdu driver output can be displayed on the window screen. No direct access to screen memory.

CODE ADDRESS: 0B00-0CFF
OVERLAY: On
EFFECT: All instructions which reference 3000-8000 will address SHADOW SCREEN memory.
E: Y
S: Y
WINDOW: ALL

CODE ADDRESS: 0B00-0CFF
OVERLAY: Off
EFFECT: All instructions will reference normal memory.
E: Y
S: Y
WINDOW: VDU DRIVER OP.ONLY

CODE ADDRESS: 6500+
OVERLAY: On
EFFECT: Code cannot be executed in this area with SHADOW OVERLAY ON, as code will be overlaid by Shadow memory.
E: N
WINDOW: NONE
EFFECT: Code can be SINGLE STEPPED as normal. Any code that references 3000-8000 will address SHADOW SCREEN memory.
S: Y
WINDOW: ALL

CODE ADDRESS: 6500+
OVERLAY: Off
EFFECT: Code can be executed by the 'E' command. All instructions will address normal memory.
N: Y
WINDOW: VDU DRIVER OP. ONLY
EFFECT: Code can be single stepped. All instructions will address normal memory.
S: Y
WINDOW: VDU DRIVER OP. ONLY

To assist in demonstrating 'STEPPER' the disc also contains a test machine code program. For convenience, two versions are supplied. A dissasembled listing is also supplied to assist in testing the Stepper Program.

Their filenames are BinDecl : This assembles to &0B00
BinDech : This assembles to &6500

BinDecl/h Simply takes any two byte unsigned number contained in zero page locations &70,&71 and displays it on the screen in decimal. Any leading zeros are replaced with spaces. (To give vertical alignment for printing coloumns).

a. CHAIN "BINDECL"
b. CHAIN "STEPPER"

1. Press 'M' and enter 0070 (User zero page).
2. Press 'C' and enter 0070, then enter FE,FF, press 'Q'. The memory locations &70,&71 do now contain &FE,&FF. The number was entered in reverse format ie. Low byte first, the actual number is &FFFE Hex. Locations &72 to &76 are used to store the converted BCD digits.
3. STEPPER'S program counter should show &0B00, press 'T' if not. (If using BinDech, press 'P' enter 6500).
4. Press 'S' to enter STEP MODE.
5. Pressing the Left Arrow Key step through the program noteing locations &72 to &76 etc., until the PC. shows &0B1C, (&651C if using BinDech). Press 'W' to enter WINDOW MODE, continue stepping until PC. shows 0B1F, (651F if using BinDech). The decimal number 65534 should be displayed on screen.
6. Press 'Q' to return to COMMAND SCREEN. (Note. Reselecting Step Mode then pressing 'W' will restore the WINDOW SCREEN intact).
7. Press 'T' to reset the PC. (For BinDech, press 'P' enter 6500). Try a different value in &70,&71 and repeat 1-6 using the right arrow key, noting STACK POINTER and STACK CONTENTS. When the PC shows &0B44 (&6544 for BinDech) press 'W' to enter WINDOW MODE. Continue stepping using left arrow key until PC. shows &0B1F (&651F). The left arrow key is used from &0B44 (&6544) because of the MOS call JSR &FFFE (JSR oswrch).

BREAKPOINT OPERATION (Switch Off SHADOW OVERLAY if using BinDech).

1. Press 'B' enter 0B00, then 0B1F, (For BinDech 6500, 651F).
2. Set up locations &70,&71 as above.
3. Press 'M' enter 0070.
4. Press 'E' to execute code to breakpoint, note locations &72-&76.
5. BREAKPOINT FROM WINDOW MODE.
   Press 'T' (For Bin_Dec_hi 'P' enter 6500).
6. Re-enter breakpoint as in 1.
7. Set up locations &70,&71 again.
8. Press 'W' to enter WINDOW MODE.
9. Press 'E' to execute code to breakpoint, decimal number displayed instantly on screen.
10. Press 'Q' to return to COMMAND SCREEN.

BinDech

a. CHAIN "BINDECH"
b. CHAIN "STEPPER"

1. As above but use values in brackets.
2. Press 'O' TO TOGGLE SHADOW OVERLAY OFF when executing code with the BREAKPOINT OPTION in High Memory, ie &6500 onwards.

NB. REGARDING MACHINE CODE EQUIVALENTS OF VDU DRIVER COMMANDS

VDU DRIVER COMMANDS, ie. PLOT,MOVE,DRAW etc. require that the parameters which follow the command itself are sent in one continuous stream. Therefor these commands cannot be stepped through unless they are executed within a subroutine as a single step via the left arrow key or executed via the 'E' command using the breakpoint option.