# AppleWin Debugger Tutorial

By Michael Pohoreski.

Revision 3. Mar 12, 2006.

## Table of Contents

- Introduction
- Entering the Debugger
- Scrolling
- Registers
- Flags
- Execution
- Memory
  - Viewing Memory
  - Searching Memory
  - Changing Memory
- Symbols
- Calculator
- Breakpoints
- Configuration
  - Colors
  - Fonts
  - Scripts
  - Settings

## Introduction

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!

## Entering the Debugger

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.

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 Shift-Accent | Toggle full screen console (US keyboards)
ñ/ ñ@ | Shift Forward Slash Shift At | 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.

## Scrolling

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 | Shift-Page Down | 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 | Locate current 6502 instruction.
à| | Tab | Locate current 6502 instruction.

## Registers

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 If the symbol A1 doesn't exist, sets Accumulator to the hex Value A1
R A $A1 | If the symbol A1 exists, sets the Accumulator to the Address of symbol A1 If the symbol A1 doesn't exist, sets Accumulator to the hex Value A1
R A #A1 | Sets Accumulator to the hex value A1

## Flags

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

## Execution

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. Additionally, if the PC exits the range [SkipAddress,Length], execution will be halted.
####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

## Memory

### Viewing Memory

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.

### Searching Memory

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!

### Changing Memory

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

## Calculator

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.)

Op | Name | Effect
+ | Plus | Addition.
- | Minus | Subtraction.
% | Percent | Calculate remainder (modulus).
/ | Forward Slash | Calculate quotient.
& | Ampersand | Bit-wise AND.
| | Pipe | Bit-Wise (inclusive) OR.
^ | Caret | Bit-Wise (exclusive) OR, also called XOR.
! | Exclamation | Bit-Wise NOT.

## Notes:

- The unary bit-wise Negation operator, ‘!’ only effects the next immediate expression.

- There is (currently) no multiplication operator, due to the asterisk ‘*’ being 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 (First byte is a jump instruction.)
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.

## Windows

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

## Symbols

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).

## Source

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.

## Breakpoints

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. Default operator is equal ‘=’ (In a future version, will dispatch to BPX, BPR, BPP, or BPIO.)
BPX BPX expression BPX address[,len] BPX [op] symbol | 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) Default length is 1. Default comparision operator is equal ‘=’
BP | Currently an Alias for BPX. (In a future version, will also support Loading and Saving of breakpoints.)
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. Note: The asterisk ‘*’ may be used o clear all breakpoints.
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.

## Notes:

- 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.

## Configuration

### Colors

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 # # # # COLOR # R G B | Sets the colors to the new Red, Green, and Blue values. First # is the color.

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

### Fonts

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.

### Scripts

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.

### Settings

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!