By Michael Pohoreski.
Revision 4. July 1, 2006.
If you're new to the debugger, this tutorial will gently get you up to speed in becoming familiar with it.
If you're already familiar with the AppleWin Debugger, you'll be aware that it was probably lacking in features and ease of use. The new debugger has been given an over-haul for the new millennium with respect to aesthetics and functionality. As such, you'll probably want to read this tutorial to learn about the new features that will not only help you in debugging, but also save you time.
Let's get started on the tour!
Start AppleWin, and press F7 to enter the debugger.
The first thing you'll probably notice is the new syntax coloring in the disassembly view, and info panel. All the colors can be customized to your liking. See the Colors section for details.
On the left is the disassembly view. On the righ is the info panael, which shows registers, stack, zero-page pointers, breakpoints, watches, and 2 mini-memory views.
Since the mini-console isn't the full width of the screen, you can toggle between the full-screen console with the tilde '~' key. This style of table will be used to designate which keys the debugger will recognize.
|
Key |
Name |
Effect |
|
~ |
Tilde |
Toggle full screen console (US keyboards) |
|
ñ/ |
Shift Forward Slash |
Toggle full screen console (European keyboards) |
The debugger will print out a mini message at the bottom of the console when it is first started. Help is built-in for some of the commands (with more coming every release.) Most commands will display a help usage, if you simply type the command and press Enter.
This typeface, and color will be used to designate commands you can type into the debugger.
|
Input |
Effect |
|
HELP |
Display Help for specific command. |
|
? |
Display Help Summary. |
|
VERSION |
Display both the AppleWin and Debugger Version. |
Note: Please include both the AppleWin and Debugger version when reporting bugs about the Debugger. Sometimes a preview (Beta) version of the debugger is available before the next official AppleWin version is available. Older bugs (may already) be fixed in the new version. The version number will help both you and the developers to detect if you’re documenting a new bug, submitting an already existing bug, or re-submitting a bug that has already been fixed.
In the disassembly view, the
following keys &
commands can be used:
(The classic Apple "monitor "
disassemble command is also suported.)
|
Command |
Effect |
|
U #### |
Start disassembly from Value or Address |
|
####L |
List (unassemble) from specified address. |
|
Key |
Name |
Effect |
|
á |
Up Arrow |
Scroll up one mnemonic line. |
|
â |
Down Arrow |
Scroll down one mnemonic line. |
|
ñá |
Shift Up Arrow |
Scroll up 1 byte. |
|
ñâ |
Shift-Down Arrow |
Scroll down 1 byte. |
|
PgUp |
Page Up |
Scroll up one screen. |
|
PgDn |
Page Down |
Scroll down one screen. |
|
ñPgUp |
Shift-Page Up |
Jump to prev. page boundary (256 byte). |
|
ñPgDn |
Jump to next page boundary (256 byte). |
|
|
^PgUp |
Control-Page Up |
Jump to prev. 4K boundary (4096 bytes). |
|
^PgDn |
Control-Page Down |
Jump to next 4K boundary (4096 bytes). |
|
Home |
Home |
Jump to start of memory ($0000). |
|
End |
End |
Jump to middle of memory ($8000). |
|
à |
Right Arrow |
Follow target of current 6502 instruction. |
|
à| |
Tab |
Locate current 6502 instruction. |
You can set "bookmarks" in the disassembly view, to
quickly jump back to a favorite location. There are 10
available, ranging from 0 to 9.
|
Command |
Effect |
|
HELP BOOKMARKS |
List all commands in the bookmark category. |
|
BML |
List all bookmarks |
|
BMA |
Add address to first available bookmark slot, or update existing bookmark. |
|
BMC |
Clear (remove) bookmark |
|
BMG |
Goto specific bookmark location. |
|
Key |
Name |
Effect |
|
Ctrl-Shift-# |
Ctrl Shift Number |
Assign current cursor location to specified bookmark (0 throug 9) |
|
Ctrl-# |
Down Arrow |
Move the cursor to the bookmark (if it exists.) |
Examples:
|
Input |
Effect |
|
BMA RESET |
Add bookmark Address $FA62 (RESET) |
|
BMA 0 HOME RESET MON |
Update
bookmark 0 to Address $FC58
(HOME), |
|
BMG 1 |
Move disassembly cursor to $FA62 (RESET) |
The command line now recognizes 6502 Registers. Namely,
A, the Accumulator,
X, the 1st Index Register,
Y, the 2nd Index Register,
PC, the Program Counter,
S, the Stack Pointer, and
P, the Processor Status Register (Flags).
You can set a Register to a hex Value, Symbol, or Expression. (See the section Calculator for more examples of using expressions.) The syntax is:
|
Command |
Effect |
|
R r [=] #### |
Set Register to (a byte) Value, Symbol, or Address, or Expression. |
|
R A ## |
Set Accumulator to (a byte) Value |
|
R X ## |
Set Register X to (a byte) Value |
|
R Y ## |
Set Register Y to (a byte) Value |
|
R PC #### |
Set PC to (a full 16-bit) Address (Value) |
|
R S ## |
Set Stack Register to (an 8-Bit) Offset |
|
R P ## |
Set Processor Status Register (flags) to (a byte) Value |
Notes:
Since A
refers to the Accumulator, you need to prefix
the hex number A with either:
i) a zero '0',
or
ii) the hash '#'
symbol (same as 6502 immediate symbol.)
You can prefix a symbol with the dollar sign '$' to tell the parser it is a symbol Address instead of a Value.
If a symbol is not defined, the expression will be the corresponding hex Value, if possible.
Hex Values may be ambiguous, if their corresponding symbol is defined. To avoid confusion, don’t define symbols such as the popular $DEAD, $BEEF, $C0DE, $CAFE, etc. An example is given with A1.
Examples:
|
Input |
Effect |
|
R PC FA62 |
Set Program Counter to Value $FA62 (RESET) |
|
R PC RESET + 1 |
Set Program Counter to Address $FA63 (RESET+1) |
|
R X 2 |
Set Register to Value 2 |
|
R Y 3 |
Set Register to Value 3 |
|
R S 1FE |
Set Stack Pointer to depth of one (Stack grows down from $01FF) |
|
R S FF |
Set Stack Pointer to top of stack (Empty) |
|
R A 0A |
Set Accumulator to hex Value 0A |
|
R A #A |
Set Accumulator to hex Value 0A |
|
R X A |
Set Register X to Accumulator’s Value |
|
R A A1 |
If the
symbol A1 exists, sets Accumulator to the Address
of the symbol A1 |
|
R A $A1 |
If the
symbol A1 exists, sets the Accumulator to the Address
of symbol A1 |
|
R A #A1 |
Sets Accumulator to the hex value A1 |
Each flag can individually be set or cleared on the Processor Status Register ('P'). Cleared flags will show up with a normal background. Set flags will show with an inverse background.
Notes:
The legacy commands R? and S?, where? is a flag name (C,Z,I,D,B,R,V,N) has been left in.
Commands to set a flag:
|
Command |
Description |
|
SEC |
Set Carry |
|
SEZ |
Set Zero |
|
SEI |
Set Interrupts Disabled |
|
SED |
Set Decimal (BCD) mode |
|
SEB |
Set Break |
|
SER |
Set Reserved (not used on 6502) |
|
SEV |
Set Overflow |
|
SEN |
Set Negative |
Commands to clear a flag:
|
Command |
Description |
|
CLC |
Clear Carry |
|
CLZ |
Clear Zero |
|
CLI |
Clear Interrupts Disabled |
|
CLD |
Clear Decimal (BCD) mode |
|
CLB |
Clear Break |
|
CLR |
Clear Reserved (not used on 6502) |
|
CLV |
Clear Overflow |
|
CLN |
Clear Negative |
As you scroll around, you will notice the cursor and other lines change colors. Normally the cursor line is shown with an inverse bar, that is with a white background. Other colors have these meanings:
|
Cursor Background |
Effect |
|
White |
Address of cursor. |
|
Yellow (Bright) |
Cursor is on next 6502 instruction (At 6502 PC). |
|
Yellow (Dim) |
Line is next 6502 instruction (At 6502 PC). |
|
Red (Bright) |
Cursor is on active Breakpoint. |
Press Right Arrow to locate the current 6502 instruction. If you Page Down, you can see that Branch Indicators are displayed on the right side of the disassembly window, designated by ‘5’ or ‘6’.
Press Right Arrow to again locate the current instruction. You will also notice immediate instructions have a character single quoted, after them, such as ‘I’ at $FA75.
Pressing Space, will Trace (into) an instruction. Sometimes you trace into a JSR (subroutine), and wish you hadn't. Pressing Shift-Space will "Step Out" - that is, run until the Program Counter (PC) is equal to the return address on the stack. Pressing Left Arrow will jump the cursor to the next instruction after the original call.
Notes:
Some code will place the arguments to the subroutine after the JSR instruction. The debugger is not able to detect this and "Step Out" correctly, so use caution, if the sub-routine plays with the stack.
The debugger is not able to detect if the top 2 bytes on the stack is a valid return address, so pay careful attention if the stack is modified!
|
Key |
Name |
Effect |
|
§ |
Space |
Trace into instruction. |
|
ñ§ |
Shift-Space |
Step out of subroutine. |
|
^§ |
Ctrl-Space |
Trace over instruction. |
|
^â |
Ctrl-Down Arrow |
Run until cursor. |
|
^à |
Ctrl-Right Arrow |
Set PC to cursor. |
|
ß |
Left Arrow |
Jump cursor to return address on stack. |
|
Command |
Description |
|
G [StopAddress] |
Resume execution until PC = StopAddress. |
|
G [StopAddress] [SkipAddress,Length] |
Resume execution until PC = StopAddress. |
|
####G |
Alias for: R PC [=] address. |
|
Input |
Effect |
|
R PC FA62 |
Set Program Counter to Value $FA62 (RESET) |
|
G C600 D000,3000 |
Single-step until either PC = $C600, or PC <= $D000 |
There are two mini-memory areas on the info panel. You can view memory in Hex, (normal 7-Bit) ASCII, or Apple (8-Bit) TEXT format.
Control characters are shown in yellow. The Apple uses something called 8-Bit (High-Bit) ASCII, in which the first 128 characters (normal ASCII) are also mapped onto the last 128 characters, but with a different background. (Technically, the first 64 characters are drawn inverse, the next 64 characters flashing, and the last 128 normally.) Some programs will store text in this extended Apple format, where a High-Bit character can be used as a flag to represent an end of word.
Here is a summary:
Normal ASCII (non-control characters) will show up in cyan; High-Bit text in white.
Apple TEXT (normal ASCII) will also display with an inverse background; High-Bit with a normal background.
|
Command |
Effect |
|
M1 #### |
View mini-memory 1 in Hex at the Address |
|
M2 #### |
View mini-memory 2 in Hex at the Address |
|
MA1 #### |
View mini-memory 1 in ASCII at the Address |
|
MA2 #### |
View mini-memory 2 in ASCII at the Address |
|
MT1 #### |
View mini-memory 1 in “Apple Text” at the Address |
|
MT2 #### |
View mini-memory 1 in “Apple Text” at the Address |
|
D #### |
Alias for M1 |
Examples:
|
Input |
Effect |
|
MA1 D0D0 |
View Applesoft Tokens (Low ASCII cyan, High ASCII white) |
|
MT2 FF0A |
View Apple message displayed when booted, showing Apple Model. |
|
DATA |
Switch to the Data Window to view memory. Most scrolling keys work. |
|
CODE |
Switch to the Code Window to view the disassembler. |
You can search memory for hex values. Wildcard support is also supported via the '?' wildcard operator, including nibble searching. A single '?' by itself, means match one byte of any value. A hex value with the high nibble or low nibble of '?' will mask off the corresponding nibble. (At the moment there is no way to refer to the list of results. A future version will support _# to reference search result's addresses.)
Searching memory for text is forthcoming in a future version of the debugger.
|
Command |
Effect |
|
SH #,len byte1 … |
Search memory for 8-bit hex value(s). |
|
SH #,len word1 … |
Search memory for 16-bit value(s). |
Examples:
|
Input |
Effect |
|
SH 800,8000 C030 |
Search memory for speaker access. |
|
SH 800,8000 AD ? C0 |
Search memory for “ LDA $C0xx”. |
|
SH 800,8000 3? C0 |
Search memory for speaker access $C03x. |
|
SH 800,8000 ?1 C0 |
Search memory for soft-switch $C0x1. |
|
L _1 |
Disassemble from search result #1 address. Note: Not yet implemented! |
To change the Apple's memory, the classic "Apple Monitor"
command to enter memory is recognized,
as well as the "normal" debugger comamnd.
|
Command |
Effect |
|
####:byte1 … |
Classic "Apple Monitor" command to enter byte(s). Alias for E. |
|
E addr byte1 … |
Set memory to the 8-Bit (byte) value(s). |
|
EB symbol #### |
Alias for E. |
|
E8 symbol #### |
Alias for E. |
|
EW symbol #### |
Set memory (at the symbol Address) to the 16-Bit (word) Value(s). |
|
E16 symbol #### |
Alias for EW. |
|
NOP |
Writes an “NOP” opcode (EA) at the current Program Counter (PC) |
|
ZAP |
Alias for NOP. |
Examples:
|
Input |
Effect |
|
300:60 |
Same as Applesoft Poke 768,96 |
There is a basic mini hex calculator built in. It can do Addition, Subtraction, Division, Modulus, bit-wise And, bit-wise Or, bit-wise Exclusive Or, and bit-wise Negation, with Values, Register and Symbols. It will display results in Hex, Binary, Decimal, and as a Character (single quoted.)
The
|
Op |
Name |
Effect |
|
+ |
Plus |
Addition. |
|
- |
Minus |
Subtraction. |
| * | Asterick / Star | Multiply |
| / | Forward Slash | Calculate quotient. |
|
% |
Percent |
Calculate remainder (modulus). |
|
& |
Ampersand |
Bit-wise AND. |
|
| |
Pipe |
Bit-Wise (inclusive) OR. |
|
^ |
Caret |
Bit-Wise (exclusive) OR, also called XOR. |
|
! |
Exclamation |
Bit-Wise NOT. |
The unary bit-wise Negation operator, ‘!’ only effects the next immediate expression.
The asterisk ‘*’ is also used for the wild card operator.
|
Input |
Effect |
|
CALC 9+1 |
Calculate 9+1, in hex. |
|
R A 1 |
Set Accumulator to 1. |
|
R X 2 |
Set X to 2. |
|
R Y 3 |
Set Y to 3. |
|
CALC A+X+Y |
Calculate sum of registers. |
|
CALC 1FF-S |
Calculate Stack Depth. |
|
CALC BRKV+1 |
Calculate
address of Break Vector + 1 |
|
CALC A+#A |
Calculate Accumulator plus (decimal) 10. |
|
CALC A+0A |
Calculate Accumulator plus (decimal) 10. |
|
CALC A+$0A |
Calculate Accumulator plus (decimal) 10. |
|
CALC 0A+0A |
Calculate 10 + 10, in hex. |
|
CALC $RESET+1 |
Calculate Address of Reset + 1 (First opcode is one byte, CLD). |
|
CALC !HOME |
Calculate bit-wise NOT. |
|
CALC X & Y |
Calculate bit-wise AND of Register X , Register Y. |
|
CALC X | Y |
Calculate bit-wise OR of Register X , Register Y. |
|
CALC X ^ Y |
Calculate bit-wise XOR of Register X , Register Y. |
|
CALC X / Y |
Calculate division of Register X , Register Y. |
|
CALC X % Y |
Calculate remainder of Register X , Register Y. |
Due to the amount of information available, the debugger now features "windows." You can switch to th full screen console to read the help, or to the data window to view memory.
|
Command |
Effect |
|
WIN CONSOLE |
Switch to the full screen console. Scrolling keys work. |
|
CONSOLE |
Alias |
|
WIN CODE |
Switch to the disassembly window. |
|
CODE |
Alias |
|
WIN DATA |
Switch to the Data window to view memory. Most scrolling keys work. |
|
DATA |
Alias |
You can cycle between windows, using these keys:
|
Key |
Name |
Effect |
|
^à |
Ctrl-Tab |
Cycle to next Window. |
|
^ñà |
Ctrl-Shift-Tab |
Cycle to prev. Window |
AppleWin supports loading of ACME, and Merlin Symbol Tables. The default filename read into the Main Symbol Table is “APPLE2E.SYM”.
Looking up symbols is now easier. Can't remember an address of a symbol, or can't remember the symbol for an address? The new symbol commands makes it easy:
|
Command |
Effect |
|
SYM |
Display the number of symbols in the Main, User, and Source symbol tables. |
|
SYM #### |
Look-up the Symbol or Address, and display which Symbol Table it is in. |
|
SYMUSER LOAD |
Loads the User Symbol Table. |
|
SYMUSER CLEAR |
Clears the User Symbol Table! |
|
SYMMAIN #### |
Look-up only in the Main symbol table. |
|
SYMUSER #### |
Look-up only in the User symbol table. |
|
SYMSRC #### |
Look-up only in the Source symbol table. |
|
SYM name = #### |
Add (or update) a symbol in the User table with the new Address. |
|
SYM ! name |
Remove a symbol from the User table. |
|
E symbol ## |
Set memory (at the symbol Address) to the 8-Bit (byte) Value. |
|
EB symbol #### |
Alias for E. |
|
E8 symbol #### |
Alias for E. |
|
EW symbol #### |
Set memory (at the symbol Address) to the 16-Bit (word) Value. |
|
E16 symbol #### |
Alias for EW. |
Examples:
|
Input |
Effect |
|
SYM |
Displays number of symbols in the Main, User, and Source tables. |
|
SYMMAIN CLEAR |
Clears the main symbol table!! |
|
SYMMAIN LOAD APPLE2E.SYM |
Reloads the main symbol table. |
|
SYM FA62 |
Look up the Address $FA62 (RESET). |
|
SYM HOME |
Look up the Address $FC58 (HOME). |
|
SYM LIFE = 300 |
Define a new user symbol, called “Life” at Address $0300. |
|
E LIFE 64 |
Set 8-Bit variable (@ $0300)“Life” to 100 (decimal). |
|
EW LIFE 3E8 |
Set 16-Bit variable (@ $0300)“Life” to 1000 (decimal). |
Another new feature is source level debugging. Parsing assembly source has the option of:
Reading in your define symbols into the Source Symbol Table.
Reading in your binary program into Apple Memory.
Supported assembler source formats include: Merlin.
|
Command |
Effect |
|
SOURCE filename |
Read in the assembler source. |
|
SOURCE SYM filename |
Read in the assembler source, adding symbols. |
|
SOURCE MEM filename |
Read in the assembler source, storing bytes into memory. |
|
SOURCE SYM MEM filename |
Add both symbols, and store bytes into memory. |
|
SOURCE |
Turn off source level debugging. |
|
SOURCE2 |
Split the dissembler view, with source in bottom half. |
Assuming you have a file called “test.s” in the same directory as the AppleWin executable:
|
Input |
Effect |
|
SOURCE SYM MEM test.s |
Read in assembler source “Test.s”, with symbols added to the Source Symbol Table, and source bytes into memory. SYMSRC reports how many symbols are in the Source Symbol Table. |
You now have a variety of options when specifying a breakpoint. Breakpoints can also be disabled, and later re-enabled. This lets ones set a bunch of breakpoints, and quickly re-activate them without having to re-enter the breakpoint logic.
|
Command |
Effect |
|
BPA r [op] value |
Adds
(conditional) Breakpoint. |
|
BPX |
Add
Breakpoint trigger to stop executing when the PC is within the range of
the Address, Symbol, or Expression. i.e. Range is: [addr,addr+len) |
|
BP |
Currently
an Alias for BPX. |
|
BPM address[,len] |
Add Breakpoint trigger when memory is accessed by 6502. |
|
BPR reg [op] value |
Add Breakpoint trigger when Register’s ‘reg’ value is compared to the Value. |
|
BD |
Disable Breakpoint (grayed out). |
|
BE |
Enable Breakpoint (colored red). |
|
BC # |
Clear
specified Breakpoint. |
|
BL |
List Breakpoints. |
|
BPIO |
(In a future version, will add Breakpoint trigger on memory read or write.) |
|
BPP |
(In a future version, will add Breakpoint trigger on specific flag cleared or set.) |
The general format for the conditional breakpoint is:
BPA register [operator] value.
You can use the following comparison operators:
|
Op |
Name |
Effect |
|
= |
Equal |
Break when register is equal to value. |
|
! |
Not Equal |
Break when register is not equal to value. |
|
< |
Less Than |
Break when register is less than value. |
|
> |
Greater Than |
Break when register is greater than value. |
Breaking on any of the 6502 registers is fully supported:
|
Reg |
Name |
Effect |
|
A |
Accumulator |
Break when Accumulator is triggered. |
|
X |
Register X |
Break when Index X is triggered. |
|
Y |
Register Y |
Break when Index Y is triggered. |
|
PC |
Program Counter |
Break when PC is triggered. |
|
S |
Stack Pointer |
Break when Stack Pointer is triggered. |
|
P |
Processor Status (flags) |
Break when flags are triggered. |
BPP, Breaking on a specific flag (either set, or cleared) is forth-coming in a future version.
Examples:
|
Input |
Effect |
|
BPX < F000 |
Add Breakpoint when PC < $FA62. |
|
BPX PC < D000 |
Add Breakpoint when PC < $ D000. |
|
BPR A 0 |
Adds Breakpoint when Accumulator is zero. |
|
BPR A ! 0 |
Adds Breakpoint when Accumulator is not zero. |
|
BPR S < 1FF |
Adds Breakpoint when Stack has had something pushed onto it. |
The commands to change color schemes, and colors are:
|
Command |
Effect |
|
COLOR |
Switch to color scheme. |
|
MONO |
Switch to monochrome scheme. |
|
COLOR # |
Displays the Red, Green, and Blue values for the specified color. |
|
COLOR
# # # # |
Sets
the colors to the new Red, Green, and Blue values. |
Some people prefer monochrome (easier on the eyes, in full screen), so you may want to use that setting:
Examples:
|
Input |
Effect |
|
MONO |
Switch to the monochrome scheme. |
|
COLOR |
Switch to the color scheme. |
|
COLOR 0 10 20 40 |
Sets the console background color to slate gray: RGB 10,20,40 |
The font Type, and Spacing can be configured, to show more or less lines in the disassembly window.
|
Command |
Effect |
|
FONT MODE # |
Set disassembler line spacing for the current font. |
|
FONT “name” |
Switch disassembler to new font. |
|
FONT “name” # |
Switch disassembler to new font with specified height (in pixels) |
Examples:
|
Input |
Effect |
|
FONT MODE 0 |
“Classic” Line Spacing. Shows the fewest amount of lines. |
|
FONT MODE 1 |
“Improved” Line Spacing. (Default) |
|
FONT MODE 2 |
“Minimal” Line Spacing. Shows the most amount of lines. |
|
FONT “Arial” |
Switch disassembler font to Arial. |
|
FONT “Courier New” |
Switch disassembler font to Courier New. |
You can run custom batch or script files that contain debugger commands. Scripts files do not echo their input; to print a string to the output console window, use the ECHO command.
|
Command |
Effect |
|
RUN filename |
Runs the specified script filename; the filename may be quoted. |
|
ECHO string |
Echo the text to the debugger console. The string may optionally be quoted. |
Examples:
|
Input |
Effect |
|
RUN “Test.txt” |
Runs the script file called: “Test.txt” |
|
ECHO “Hello World” |
Prints the classic “Hello World” to the output console. |
Coming in a future revision, you can save or load your debugger settings, either piece wise, or as a whole.
|
Command |
Effect |
|
CONFIG LOAD |
Load (default) debugger configuration. |
|
CONFIG LOAD “filename” |
Load (named) debugger configuration |
|
CONFIG SAVE |
Save (default) debugger configuration. |
|
CONFIG SAVE “filename” |
Save (named) debugger configuration |
|
COLOR LOAD “filename” |
Load color configuration. |
|
COLOR SAVE “filename” |
Save color configuration |
|
BP LOAD “filename” |
Load breakpoint configuration. |
|
BP SAVE “filename” |
Save breakpoint configuration |
Hope you enjoyed the tour!