AppleWin debugger "cheat sheet"

117 views
Skip to first unread message

fadden

unread,
Nov 2, 2019, 1:24:17 AM11/2/19
to
I wanted to poke at something while disassembling it, and AppleWin's debugger was very helpful. There's a small set of things that are essential (setting breakpoints, looking at memory, viewing the hi-res screen while paused), and not all of them were immediately obvious or documented in the F1 help. I wrote down what I found to be the important bits, mostly for my own reference, but perhaps it will be useful for others:

https://bigflake.com/disasm/applewin-dbg.html

Michael AppleWin Debugger Dev

unread,
Nov 2, 2019, 10:42:15 AM11/2/19
to
Hey Andy

Thanks for taking the time to write a debugger cheat-sheet. That definitely will help a few people!

Here are a couple of other things that may be helpful to know for users new to the debugger:


0. You can use the U command with symbol names for disassembly:

U WAIT

1. The built-in help actually has a tutorial that I wrote many years ago.
(See the file: AppleWin.chm)

* Press F1
* Click on the "Table of Contents" to expand it
* Click on "Debugger"

You should see a bunch of different topics. Of particular interest will probably be the "Scrolling" section to start with.

2. I've tried to make the debugger accept the more common monitor commands.
e.g. You can use the same command to fill memory.
i.e.
2000:D5
2001<2000.3FFFM

3. There are some small QoL (Quality of Life) features included. With the mouse you in the disassembly region you can:

* shift click on the address to toggle visibility,
* shift click on the colon to toggle visibility, and
* shift click on the opcodes to toggle visibility.

These can be handy when you have extremely long symbol names.

4. To see a list of the 16 categories:

HELP

e.g. To see a list of all break-point related commands

HELP BREAKPOINTS

5. To see a mini-help summary for EVERY command:

HELP *

6. Most commands (should) have examples.
e.g. To show examples of how to fill memory

HELP F

i.e.

F 2000:3FFF 00

7. You can use Ctrl-V to paste commands into the debugger.
(Outside the debugger you need to use Ctrl-Shift-Insert.)

8. The search command is pretty powerful, IMHO.

S F000:FFFF 20 A8 FC
U @2
// The @2 shows the disassembly of the 2nd search result

From the above example you can also see that one can use C++ '//' style comments. :-)
(I guess I probably should add ';' as an end-of-line comment command some day.)

You can also search for 7-bit ASCII using '"' or high-bit ASCII "'" or some mixed combination!

// Find where the Applesoft END token is hiding:
S D000,4000 "EN" 'D'
ASC D0D0:D0D2
U @1

I see that " and ' string literals are backwards from Merlin32. DOH!
(In my "defense" I implemented this before I found Merlin32 but that should probably be changed at some point.)


9. You can tell the debugger to treat hex bytes as data (instead of code)
using the DB and ASC commands. To "reset" the data to be interpreted as code
use the X on any address within that data snippet.

e.g.
300:41 42 43
MA1 300
300L

DB 300:302
X 300
SYMASM ! b_0300

DB test 300:302
X 300
SYMASM ! b_0300

ASC 300:302
X 300
SYMASM ! b_0300

ASC test 300:302
X 300
SYMASM ! b_0300

Labels are auto-generated if you don't provide a name.

You can also use the built range operator ':' for simple auto-calculation!

S D000,4000 "EN"
ASC @2:@2+F
U @2

X D2C8
SYMASM ! B_D2C8

10. You can run debugger scripts via the RUN command.
I usually have SYMMAIN OFF, SYMBASIC OFF, and SYMUSER CLEAR in my scripts. Something along these lines:

- - - 8< - - -
// Version 3
echo "/////////////////////////"
echo "// //"
echo "// Montezuma's Revenge //"
echo "// //"
echo "/////////////////////////"

symmain off
symbasic off
symuser clear

db P.SpawnX b4
db P.SpawnY b5

sym GameLoop = 60dd
- - - 8< - - -

I also usually use a single letter file name to make it fast to type:

RUN R

(Ctrl-V would be another option.)

11. You can use the PROFILE command to get cycle-accurate counts.

<F7>
BPC *
BPX FCA8
BPX FCB3
<F7>

CALL-151
300:A9 01 20 A8 FC 60
300G

PROFILE
G
PROFILE LIST

<F7>

And here we see that WAIT,A=1 takes a total of 17 cycles.


There are still many things that suck about the debugger.
Feel free to create a bug report or feature request on GitHub.

Hope this helps.

Cheers,
Michael "AppleWin Debugger" Dev
Reply all
Reply to author
Forward
0 new messages