mirror of
https://github.com/AppleWin/AppleWin.git
synced 2024-11-19 04:08:45 +00:00
296 lines
12 KiB
HTML
296 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<title>AppleWin Debugger Tutorial</title>
|
||
<meta http-equiv="CONTENT-TYPE" content="text/html; charset=windows-1252">
|
||
</head>
|
||
<body style="DIRECTION: ltr" lang="en-US">
|
||
<h2><a name="Symbols"></a>Symbols</h2>
|
||
<p>
|
||
When a programmer writes an assembly language program instead of directly referring to a memory address over and over again they use a <b>symbolic name</b> instead.
|
||
For example, instead of always directly hard-coding $C000 everywhere to read the keyboard they would instead write:
|
||
</p>
|
||
<p><font color="#00b8ff"><font face="courier"><b><pre style="background: rgb(0,0,0) 0% 50%;">
|
||
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
|
||
</pre></b></font></font></p>
|
||
<p>
|
||
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).
|
||
</p>
|
||
<p><font color="#00b8ff"><font face="Courier"><b><pre style="BACKGROUND: rgb(0,0,0) 0% 50%;">
|
||
300:AD 00 C0 10 FB 8D 00 04 60
|
||
300L
|
||
</pre></b></font></font></p>
|
||
<p>
|
||
Press F7 to exit the debugger, then type:
|
||
</p>
|
||
<p><font color="#00b8ff"><font face="Courier"><b><pre style="BACKGROUND: rgb(0,0,0) 0% 50%;">
|
||
HOME:CALL 768
|
||
</pre></b></font></font></p>
|
||
<p>
|
||
Press Enter. The emulated computer will wait for your to press a key and then echo it in the top left.
|
||
</p>
|
||
<p>
|
||
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 <b>symbol</b> is the symbolic name and the address assigned to it.
|
||
</p>
|
||
<p>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: <b>ADDRESS SYMBOL</b></p>
|
||
<p>e.g.</p>
|
||
<p><font color="#00b8ff"><font face="courier"><b><pre style="background: rgb(0,0,0) 0% 50%;">
|
||
; IO Map
|
||
C000 KEYBOARD
|
||
</pre></b></font></font></p>
|
||
<p>
|
||
There are <b>9</b> symbol tables to help organize "modules"; each symbol table individually can be turned off/on independently.
|
||
<pre>
|
||
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
|
||
</pre></p>
|
||
<p>On startup the debugger reads 3 symbol tables by default: Main, Basic, User1.</p>
|
||
</p>
|
||
<p>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)
|
||
</p>
|
||
<p><br>
|
||
<br>
|
||
</p>
|
||
<table border="0" cellpadding="2" cellspacing="0" width="80%">
|
||
<COLGROUP>
|
||
<col width="64">
|
||
<col width="192">
|
||
<tbody>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="25%">
|
||
<p><font color="#ffffff"><b>Command</b></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="75%">
|
||
<p style="FONT-STYLE: normal"><font color="#ffffff"><b>Effect</b></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYM</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Display
|
||
the number of symbols in the Main, User, and Source symbol tables.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYM
|
||
####</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Look-up
|
||
the Symbol or Address, and display which Symbol Table it is in.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYMUSER
|
||
LOAD</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Reloads
|
||
the User Symbol Table: <b>A2_USER1.SYM</b></span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYMUSER
|
||
CLEAR</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%;">Clears
|
||
the User Symbol Table from RAM.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYMMAIN
|
||
####</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Look-up
|
||
only in the Main symbol table.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYMUSER
|
||
####</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Look-up
|
||
only in the User symbol table.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYMSRC
|
||
####</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Look-up
|
||
only in the Source symbol table.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYM
|
||
name = ####</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Add
|
||
(or update) a symbol in the User table with the new Address.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">SYM
|
||
! name</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i><span style="BACKGROUND: 0% 50%; ">Remove
|
||
a symbol from the User table.</span></i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b><span style="BACKGROUND: 0% 50%; ">MEB
|
||
symbol ##</span></b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i>Set memory (at the symbol Address) to the 8-Bit (byte) Value.</i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#cccccc">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b>MEW symbol ####</b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i>Set memory (at the symbol Address) to the 16-Bit (word) Value.</i></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#999999">
|
||
<td width="25%">
|
||
<p><font color="#000000"><font face="Courier"><b>E16 symbol ####</b></font></font></p>
|
||
</td>
|
||
<td width="75%">
|
||
<p><i>Alias for EW.</i></p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p><br>
|
||
<br>
|
||
</p>
|
||
<p><font size="4"><b>Examples</b>:</font></p>
|
||
<table bgcolor="#000000" border="0" cellpadding="2" cellspacing="0" width="799">
|
||
<COLGROUP>
|
||
<col width="276">
|
||
<col width="515">
|
||
<tbody>
|
||
<tr bgcolor="#00b8ff">
|
||
<td bgcolor="#30c0ff" width="276">
|
||
<p><font color="#000000"><b>Input</b></font></p>
|
||
</td>
|
||
<td bgcolor="#30c0ff" width="515">
|
||
<p><font color="#000000"><b>Effect</b></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b>SYM</b></font></font></p>
|
||
</td>
|
||
<td width="515">
|
||
<p><font color="#ffffff"><i>Displays number of symbols in the Main, User, and Source
|
||
tables.</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b>SYMMAIN CLEAR</b></font></font></p>
|
||
</td>
|
||
<td width="515">
|
||
<p><font color="#ffffff"><i>Clears the main symbol table!!</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b>SYMMAIN LOAD APPLE2E.SYM</b></font></font></p>
|
||
</td>
|
||
<td width="515">
|
||
<p><font color="#ffffff"><i>Reloads the main symbol table.</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b>SYM FA62</b></font></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="515">
|
||
<p><font color="#ffffff"><i>Look up the Address $<b><font color="#ffff00">FA62</font></b> (RESET).</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b><span style="BACKGROUND: rgb(0,0,0) 0% 50%; ">SYM
|
||
HOME</span></b></font></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="515">
|
||
<p><font color="#ffffff"><i>Look up the Symbol Home ($<b><font color="#ffff00">FC58</font></b>).</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b><span style="BACKGROUND: rgb(0,0,0) 0% 50%;">SYM
|
||
LIFE = 300</span></b></font></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="515">
|
||
<p><font color="#ffffff"><i>Define a new user symbol, called <20>Life<66> at Address $0300.</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="276">
|
||
<p><font color="#00b8ff"><font face="Courier"><b><span style="BACKGROUND: rgb(0,0,0) 0% 50%;">MEB
|
||
LIFE 64</span></b></font></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="515">
|
||
<p><font color="#ffffff"><i>Set 8-Bit variable (@ $<b><font color="#ffff00">0300</font></b>)<29>Life<66>
|
||
to 100 (decimal).</i></font></p>
|
||
</td>
|
||
</tr>
|
||
<tr bgcolor="#000000">
|
||
<td bgcolor="#000000" width="276">
|
||
<p><font color="#00b8ff"><font face="courier"><b><span style="background: rgb(0,0,0) 0% 50%; ">MEW
|
||
LIFE 3E8</span></b></font></font></p>
|
||
</td>
|
||
<td bgcolor="#000000" width="515">
|
||
<p><font color="#ffffff"><i>Set 16-Bit variable (@ $<b><font color="#ffff00">0300</font></b>)<29>Life<66>
|
||
to $3E8 = 1000 (decimal).</i></font></p>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>
|
||
<br>
|
||
|
||
</p>
|
||
</body>
|
||
</html>
|