AppleWin Debugger Tutorial

By Michael Pohoreski.

Revision 4.  July 1, 2006.

Table of Contents

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.

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

Follow target of current 6502 instruction.

à|

Tab

Locate current 6502 instruction.


Bookmarks

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),
add/set bookmark 1 to address
$FA62 (RESET), and
add/set 
bookmark 2 to address $FF65 (RESET)

BMG 1

Move disassembly cursor to $FA62 (RESET)


Registers

The command line now recognizes 6502 Registers.  Namely,

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:


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:


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:


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:


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

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

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.


Notes:


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:

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:

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:


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!