Plug In: Debug

The Debug plug-in automatically generates (and, later, removes) a jump to a small, relocated, section of your code. It's basically a breakpoint that can be continued from and traced.

Installation
.P "DE"

Usage
.U [addr]

where addr is a valid 16-bit hexadecimal address.

When used with an address, Debug copies a few bytes of your code (depending on instruction sizes) to $03EF, and a BRK after the copy. This code snippet, starting at $03EF is called a code "knapsack." Then Debug adds a JMP $03EF at the specified address.

When used without an address, Debug copies the code back from the knapsack to its origin.

Note: A knapsack may not contain a relative branch instruction. If it the plug-in encounters a relative branch instruction at or immediately after the breakpoint, it will issue ?UNDEF'D STATEMENT ERROR.

Example

It might be difficult to understand the utility of this, so here's a concrete example:

.A 1800 LDY #"A"
.A 1802 TYA
.A 1803 JSR $FFD2
.A 1806 INY
.A 1807 CPY #"Z"+1
.A 1809 BNE $1802
.A 180B RTS
.A 180C {RETURN}
.G 1800
.ABCDEFGHIJKLMNOPQRSTUVWXYZ
--A--X--Y--P--S--PC--
.;5A 00 5B 33 F8 1800

So far so good. We have a program that prints out the alphabet. Now, install Debug and create a knapsack with

.P "DE"
.U 1803 ; At JSR $FFD2
.G 1800
A
BRK
--A--X--Y--P--S--PC--
.;41 00 41 30 F2 03F1

At this point, look at the original code with .D 1800 180B. Look at $1806 JMP $03EF. This is Debug's jump to the knapsack code. Now look at the knapsack itself:

.D 03EF 03F4
., 03EF BRK
., 03F0 NOP
., 03F1 INY
., 03F2 CPY #$5B
., 03F4 JMP $1809

When this code is jumped to from $1806, it hit the BRK. Program execution pauses, and you may examine registers, code, memory locations, etc. And then, you may resume the program with .G (with no address). Execution starts again from $03F1, and the JMP $1809 brings execution right back to your code. Try this out by entering .G, and watching A and Y increment, and seeing the output from JSR $FFD2 one letter at a time.

When the program finally hits the RTS after displaying Z, the BRK indicator will be absent, and the program will be done.

Once you have the information you need from watching the step-by-step iteration, put your program back together with .U with no address.