When a programmer writes an assembly language program instead of directly referring to a memory address over and over again they use a symbolic name instead. For example, instead of always directly hard-coding $C000 everywhere to read the keyboard they would instead write:
ORG $300
KEYBOARD EQU $C000
300:AD 00 C0 .1 LDA KEYBOARD
303:10 FB BPL .1
305:8D 00 04 STA $0400
306:60 RTS
Let's try this out in the debugger. Make sure AppleWin is running. Press F2 (to reboot), then Ctrl-F2 (to break), and F7 (to enter the debugger.) If you don't want to type in the following hex code, you can select it, copy it (Ctrl-C), and paste it into the Debugger console (Ctrl-V).
300:AD 00 C0 10 FB 8D 00 04 60
300L
Press F7 to exit the debugger, then type:
HOME:CALL 768
Press Enter. The emulated computer will wait for your to press a key and then echo it in the top left.
When debugging assembly programs since you typically don't have the source file availabe you can tell the debugger how to interpret a memory address as a variable name or symbol. A symbol is the symbolic name and the address assigned to it.
AppleWin supports loading of the assemblers ACME, and Merlin's symbol tables -- a collection of symbols, one per line, organized and collectively called a symbol table. The semi-colon is a comment-till-end-of-line. The file format per line is: ADDRESS SYMBOL
e.g.
; IO Map
C000 KEYBOARD
There are 9 symbol tables to help organize "modules"; each symbol table individually can be turned off/on independently.
MAIN APPLE2E.SYM BASIC A2_BASIC.SYM ASM A2_ASM.SYM User1 A2_USER1.SYM User2 A2_USER2.SYM Src1 A2_SRC1.SYM Src2 A2_SRC2.SYM DOS33 A2_DOS33.SYM PRODOS A2_PRODOS.SYM
On startup the debugger reads 3 symbol tables by default: Main, Basic, User1.
Looking up symbols is easy. If you can't remember an address of a symbol, or the reversse -- can't remember the symbol for an address -- you can use the following symbol commands: (#### referes to either a hex address or a symbolic name)
|
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 |
Reloads the User Symbol Table: A2_USER1.SYM |
|
SYMUSER CLEAR |
Clears the User Symbol Table from RAM. |
|
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. |
|
MEB symbol ## |
Set memory (at the symbol Address) to the 8-Bit (byte) Value. |
|
MEW 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 Symbol Home ($FC58). |
|
SYM LIFE = 300 |
Define a new user symbol, called “Life” at Address $0300. |
|
MEB LIFE 64 |
Set 8-Bit variable (@ $0300)“Life” to 100 (decimal). |
|
MEW LIFE 3E8 |
Set 16-Bit variable (@ $0300)“Life” to $3E8 = 1000 (decimal). |