stella/docs/debugger.html

<html>
<head>
	<title>Stella Debugger</title>
</head>
<body>

<h1>Stella Integrated Debugger (a work in progress)</h1>

<p>The debugger in Stella may never be complete, as we're constantly
adding new features requested by homebrew developers.  However, even in its
current form it's still quite powerful, and is able to boast at least one
feature that no other 2600 debugger has; it's <b>completely</b> cross-platform.</p>

<h2>Here's a list of what the debugger can do so far:</h2>
<ul>
	<li>Display registers and memory</li>
	<li>Dump state of TIA and RIOT, with things like joystick directions and
		NUSIZx decoded into English (more-or-less).</li>
	<li>Change registers/memory, including toggles for flags in P register</li>
	<li>Single step/trace</li>
	<li>Breakpoints - break running program and enter debugger when the
		Program Counter hits a predefined address. You can set as many
		breakpoints as you want.</li>
	<li>Conditional breakpoints - Break running program when some arbitrary
		condition is true (e.g. "breakif {a == $7f &amp;&amp; c}" will break when the
		Accumulator value is $7f and the Carry flag is true, no matter where
		in the program this happens). Unlike the cond breaks in PCAE, Stella's
		are *fast*: the emulation will run at full speed unless you use lots
		of breakif's at the same time, or have a slow CPU.</li>
	<li>Watches - View contents of a location/register before every
		debugger prompt.</li>
	<li>Traps - Like breakpoints, but break on read/write/any access to
		*any* memory location.</li>
	<li>Frame advance (automatic breakpoint at beginning of next frame)
		You can advance multiple frames with one command.</li>
	<li>Disassembly</li>
	<li>Support for DASM symbol files (created with DASM's -s option),
		including automatically loading symbol files if they're named
		romname.sym</li>
	<li>Built-in VCS.H symbols, if no symbol file is loaded</li>
	<li>Symbolic names in disassembly</li>
	<li>Symbolic names accepted as input</li>
	<li>Tab completion for commands and symbol names</li>
	<li>Graphical editor for RIOT and extended RAM. Acts a lot like a spreadsheet.
		Input in hex, with displays for label/decimal/binary for
		currently-selected location.</li>
	<li>GUI CPU state window</li>
	<!--Cheat system (similar to MAME) (still needs a way to save/load cheats)-->
	<li>Reset the 6502</li>
	<li>Start emulator in debugger (via command-line option "-debug")</li>
	<li>Save CLI session to a text file.</li>
	<li>Supports hex, decimal, and binary input and output almost everywhere.
		(disassembly is still hex)</li>
	<li>Support for bank switching. You can see how many banks a cart has,
		and switch banks. There's still more to be done here though.</li>
	<li>Registers/memory that get changed by the CPU during debugging are
		highlighted when they're displayed.<li>
	<li>Scanline advance (like frame advance, break at beginning
		of next scanline).</li>
	<li>TIA display is updated during step/trace, so we can see our
		scanlines being drawn as it happens. This isn't 100% perfect: unlike
		a real TIA, the one in Stella only updates when it's written to.</li>
	<li>Graphical TIA tab, with register names and GUI buttons for
		various bits (e.g. click ENAM0 to turn it on).</li>
	<li>GUI Disassembly window, scrollable, with checkboxes for breakpoints.</li>
	<li>Script (batch) file support, including auto-running a script file
		named after the ROM image.</li>
	<li>Saving the current debugger state to a script file (including
		breakpoints, traps, etc).</li>
	<li>Built-in functions for use with "breakif", to support common conditions
		(such as breaking when the user presses Game Select...)</li>
	<li>Patching ROM in-place.</li>
	<li>Save patched ROM ("saverom filename.bin").</li>
</ul>

<h2>Future planned features:</h2>

<ul>
	<li>GUI for cheat codes (Cheetah and normal codes).</li>
	<li>Perhaps 2 panes in the disassembly window (so you can see 2 parts of the
		code at once).</li>
	<li>Add bookmark support to disassembly window.</li>
	<li>Bankswitch support in the debugger for the few remaining cart types
		that aren't supported.</li>
	<li>Patch ROM support for a few cart types doesn't work. Must fix.</li>
	<li>Source-level debugging: if a DASM .lst file is available, we'll show
		the listing in the ROM tab instead of a disassembly. This is already
		available in a very crude form ("loadlist" and "list" commands).</li>
	<li>More "special variables" for the expression parser.</li>
	<li>Possibly a mini-assembler</li>
	<li>Support for extra RAM in all remaining cart types.</li>
	<li>Possibly support for recording and playing back input files, like
		MAME. This isn't a debugger feature per se, but it'll make it easier
		to reliably trigger a bug so you can debug it.</li>
	<li>Graphics ROM view, so you can see your sprite data (it might still
		be upside-down though :)</li>
	<li>Various new GUI enhancements</li>
</ul>

<h2>How to use the debugger</h2>

<p>Pressing ` (aka backtick, backquote, grave accent) toggles the debugger on
&amp; off. When you exit the debugger, the emulation resumes at the current
program counter, and continues until either a breakpoint/trap is hit,
or the ` key is pressed again.</p>

<p>The main debugger window will look similar to the following (note that the
letters here are for reference in the document below; they aren't actually
present in the debugger):</p>
<p><img src="graphics/debugger_main.png"></p>

<p>For space reasons, the Prompt, TIA, I/O and Audio displays are split into
4 tabs, only one of which is visible at a time. You can use the mouse or
keyboard to select which tab you want to view.  Pressing Shift with the left
or right arrow keys cycles between tabs from right-to-left and left-to-right,
respectively.  Pressing Tab cycles between widgets in the current tab (except
for in the Prompt area, where 'tab' is used for something else).</p>

<p>You can also enter the debugger at emulator startup by giving a breakpoint on the command line:
<pre>
  ; will enter the debugger the first time the instruction at "kernel" runs
  stella -break kernel mygame.bin

  ; $fffc is the 6502/6507 init vector. This command will break and enter the
  ; debugger before the first 6507 instruction runs, so you can debug the
  ; startup code:
  stella -break "*($fffc)" mygame.bin
</pre>
</p>

<p>Using the ` key will always enter the debugger at the end of the
frame (scanline 262, for NTSC games). This is because Stella only checks
for keystrokes once per frame. Once in the debugger, you can control
execution by stepping one instruction, scanline, or frame at a time
(or more than one at a time, using commands in the prompt).  You can
also set breakpoints or traps, which will cause the emulator to enter
the debugger when they are triggered, even if it happens in mid-frame.</p>

<h2>Change Tracking</h2>

<p>The debugger tracks changes to the CPU registers and RAM by displaying
changed locations or registers with a red background after each step,
trace, scanline, or frame advance. This sounds simple, and it is, but
it's also amazingly useful.</p>

<p>One clarification about the change tracking: it only tracks when values
have <b>changed</b>. If the ROM writes a value into a RAM location that
already contained the same value, that's not considered a change (old
value was $whatever, new value is the same, so nothing got tracked). This
may change in a future version of Stella.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<h2><u>(A)</u> Prompt tab</h2>

<p>This is a command-line interface, similar to the DOS DEBUG command
or Supermon for the C=64.</p>

<p>Editing keys work about like you'd expect them to in Windows, but many
Bash-style commands are also supported:</p>

<table border="1" cellpadding="3">
	<tr><td>Home</td><td>Move cursor to beginning of line</td></tr>
	<tr><td>End</td><td>Move cursor to end of line</td></tr>
	<tr><td>Delete</td><td>Remove character to right of cursor</td></tr>
	<tr><td>Backspace</td><td>Remove character to left of cursor</td></tr>
	<tr><td>Control-a</td><td>Same function as 'Home'</td></tr>
	<tr><td>Control-e</td><td>Same function as 'End'</td></tr>
	<tr><td>Control-d</td><td>Same function as 'Delete'</td></tr>
	<tr><td>Control-k</td><td>Remove all characters from cursor to end of line</td></tr>
	<tr><td>Control-u</td><td>Remove all characters from cursor to beginning of line</td></tr>
	<tr><td>Control-w</td><td>Remove entire word to left of cursor</td></tr>
	<tr><td>Shift-PgUp</td><td>Scroll up through previous commands one screen/page</td></tr>
	<tr><td>Shift-PgDown</td><td>Scroll down through previous commands one screen/page</td></tr>
	<tr><td>Shift-Up</td><td>Scroll up through previous commands one line</td></tr>
	<tr><td>Shift-Down</td><td>Scroll down through previous commands one line</td></tr>
	<tr><td>Shift-Home</td><td>Scroll to beginning of commands</td></tr>
	<tr><td>Shift-End</td><td>Scroll to end of commands</td></tr>
</table>
<p>You can also scroll with the mouse.  Copy and paste is not yet supported.</p>

<p>To see the available commands, enter "help".  Bash-style tab completion is
supported for commands and labels (see below).</p>

<p>For now, there are some functions that only exist in the prompt. We
intend to add GUI equivalents for all (or almost all?) of the prompt
commands in future releases. People who like command prompts will be able to
use the prompt, but people who hate them will have a fully functional
debugger without typing (or without typing much, anyway).</p>

<h4>Tab completion</h4>

<p>While entering a command or label, you can type a partial name and
press the Tab key to attempt to auto-complete it. If you've ever used
"bash", this will be immediately familiar. If not, try it: load up
a ROM, go to the debugger, type "print w" (but don't press Enter),
then hit Tab. The "w" will change to "WSYNC" (since this is the only
built-in label starting with a "w"). If there are multiple possible
completions (try with "v" instead of "w"), you'll see a list of them,
and your partial name will be completed as far as possible.</p>

<p>Tab completion works on all labels: built-in, loaded from a symbol file,
or set during debugging with the "define" command. However, it does not
yet work on functions defined with the "function" command, nor does it
work on filenames.</p>

<h4>Expressions</h4>

<p>Almost every command takes a value: the "a" command takes a
byte to stuff into the accumulator, the "break" command
takes an address to set/clear a breakpoint at. These values
can be as a hex constant ($ff, $1234), or as complex as
"the low byte of the 16-bit value located at the address
pointed to by the binary number 1010010110100101" (which
would be "@&lt;\1010010110100101"). You can also use registers
and labels in expressions.</p>

<p>You can use arithmetic and boolean operators in expressions. The
syntax is very C-like. The operators supported are:</p>

<pre>
      + - * /  (add, subtract, multiply, divide: 2+2 is 4)
      %        (modulus/remainder: 3%2 is 1)
      &amp; | ^ ~  (bitwise AND, OR, XOR, NOT: 2&amp;3 is 2)
      &amp;&amp; || !  (logical AND, OR, NOT: 2&amp;&amp;3 is 1, 2||0 is 0)
      ( )      (parentheses for grouping: (2+2)*3 is 12)
      * @      (byte and word pointer dereference: *$80 is the byte stored
                at location $80)
      [ ]      (array-style byte pointer dereference: $80[1] is the byte
                stored at location ($80+1) or $81)
      &lt; &gt;      (prefix versions: low and high byte. &lt;$abcd is $cd)
      == &lt; &gt; &lt;= &gt;= !=
               (comparison: equality, less-than, greater-than, less-or-equals,
                greater-or-equals, not-equals)
      &lt;&lt; &gt;&gt;    (bit shifts, left and right: 1&lt;&lt;1 is 2, 2&gt;&gt;1 is 1)
</pre>

<p>Division by zero is not an error: it results in zero instead.</p>

<p>None of the operators change the values of their operands. There
are no variable-assignment or increment/decrement operators. This
may change in the future, which is why we used "==" for equality
instead of just "=".</p>

<p>The bitwise and logical boolean operators are different in that the
bitwise operators operate on all the bits of the operand (just like
AND, ORA, EOR in 6502 asm), while the logical operators treat their
operands as 0 for false, non-zero for true, and return either 0 or 1.
So $1234&amp;$5678 results in $1230, whereas $1234&amp;&amp;$5678 results in 1.
This is just like C or C++...</p>

<h4>Prefixes</h4>

<p>Like some programming languages, the debugger uses prefixed characters
to change the meaning of an expression. The prefixes are:</p>

<ul>
	<li>Dereference prefixes:<br>

		<p>"*"<br>
    	  Dereference a byte pointer. "*a" means "the byte at the address that
	      the A register points to". If A is 255 (hex $ff), the result will be
    	  the value currently stored in memory location 255. This operator
	      will be very familiar to you if you're a C or C++ programmer. It's
    	  equivalent to the PEEK() function in most 8-bit BASICs. Also, the
	      debugger supports array-like byte dereferences: *address can be
    	  written as address[0]. *(address+1) can be written as address[1],
	      etc.</p>

		<p>"@"<br>
    	  Dereference a pointer to a word. This is just like the "*" byte deref,
	      except it refers to a 16-bit value, occupying 2 locations, in
    	  low-byte-first format (standard for the 6507).</p>

		<p>The following are equivalent:</p>
		<pre>
         @address
         *address+$100**(address+1)
         address[0]+#256*address[1]
		</pre>

		<p>(TODO: add (indirect),y and (indirect,x) syntax)</p>
	</li>

	<li>Hi/Lo Byte Prefixes:<br>
		<p>"&lt;"<br>
		Take the low byte of a 16-bit value. This has no effect on an 8-bit
		value: "a" is equal to "&lt;a". However, "&lt;$1234" equals "$34".</p>

		<p>"&gt;"<br>
		Take the high byte of a 16-bit value. For 8-bit values such as
		the Accumulator, this will always result in zero. For 16-bit values,
		"&lt;$1234" = "$12".</p>
	</li>

	<li>Number Base Prefixes:<br>
		<p>"#"<br>
		Treat the input as a decimal number.</p>

		<p>"$"<br>
		Treat the input as a hex number.</p>

		<p>"\"<br>
		Treat the input as a binary number.</p>

		<p>These only have meaning when they come before a number, not a
		label or a register. "\1010" means 10 decimal. So do "$0a" and
		"#10". "a" by itself is always the Accumulator, no matter what
		the default base is set to.</p>

		<p>If you don't specify any number base prefix, the number is
		assumed to be in the default base. When you first start Stella,
		the default base is 16 (hexadecimal). You can change it with the
		"base" command. If you want to change the default base to decimal permanently,
		you can put a "base #10" command in your "autoexec.stella" file (see
		the section on "Startup").</p>

		<p>Remember, you can use arbitrarily complex expressions with any
		command that takes arguments (except the ones that take filenames,
		like "loadsym").</p>
	</li>
</ul>


<h3>Breakpoints, watches and traps, oh my!</h3>

<h4>Breakpoints</h4>

<p>A breakpoint is a "hotspot" in your program that causes the emulator
to stop emulating and jump into the debugger. You can set as many
breakpoints as you like. The command is "break xx" where xx is any
expression. If you've created a symbol file, you can use labels.</p>

<p>Example: you've got a label called "kernel". To break there,
the command is "break kernel". After you've set the breakpoint,
exit the debugger ("quit" or click the Exit button). The emulator
will run until it gets to the breakpoint, then it will enter the
debugger with the Program Counter pointing to the instruction
at the breakpoint.</p>

<p>Breakpoints happen *before* an instruction is executed: the
instruction at the breakpoint location will be the "next"
instruction.</p>

<p>To remove a breakpoint, you just run the same command you used to
set it. In the example, "break kernel" will remove the breakpoint.
The "break" command can be thought of as a *toggle*: it turns the
breakpoint on &amp; off, like a light switch.</p>

<p>You could also use "clearbreaks" to remove all the breakpoints. Also,
there is a "listbreaks" command that will list them all.</p>

<h4>Conditional Breaks</h4>

<p>A conditional breakpoint causes the emulator to enter the debugger when
some arbitrary condition becomes true. "True" means "not zero" here:
"2+2" is considered true because it's not zero. "2-2" is false, because
it evaluates to zero. This is exactly how things work in C and lots
of other languages, but it might take some getting used to if you've
never used such a language.</p>

<p>Suppose you want to enter the debugger when the Game Reset switch is
pressed. Looking at the Stella Programmers' Guide, we see that this
switch is read at bit 0 of SWCHB. This bit will be 0 if the switch is
pressed, or 1 otherwise.</p>

<p>To have an expression read the contents of an address, we use the
dereference operator "*". Since we're looking at SWCHB, we need
"*SWCHB".</p>

<p>We're only wanting to look at bit 0, so let's mask off all the other
bits: "*SWCHB&amp;1". The expression now evaluates to bit 0 of SWCHB. We're
almost there: this will be 1 (true) if the switch is NOT pressed. We
want to break if it IS pressed...</p>

<p>So we invert the sense of the test with a logical NOT operator (which
is the "!" operator): !(*SWCHB&amp;1). The parentheses are necessary as
we want to apply the ! to the result of the &amp;, not just the first term
(the "*SWCHB").</p>

<p>"breakif !(*SWCHB&amp;1)" will do the job for us. However, it's an ugly mess
of letters, numbers, and punctuation. We can do a little better:</p>

<p>"breakif { !(*SWCHB &amp; 1 ) }" is a lot more readable, isn't it? If
you're going to use readable expressions with spaces in them,
enclose the entire expression in curly braces {}.</p>

<p>Remember that Stella only checks for input once per frame, so a break
condition that depends on input (like SWCHB) will always happen at the
end of a frame. This is different from how a real 2600 works, but most
ROMs only check for input once per frame anyway.</p>

<p>Conditional breaks appear in "listbreaks", numbered starting from
zero.  You can remove a cond-break with "delbreakif number", where
the number comes from "listbreaks".</p>

<p>Any time the debugger is entered due to a trap, breakpoint, or
conditional break, the reason will be displayed in the status area above
below the TIA Zoom display.</p>

<h4>Functions</h4>

<p>There is one annoyance about complex expressions: once we
remove the conditional break with "delbreakif" or "clearbreaks",
we'd have to retype it (or search backwards with the up-arrow key)
if we wanted to use it again.</p>

<p>We can avoid this by defining the expression as a function, then using
"breakif function_name":</p>

<pre>
	function gameReset { !(*SWCHB &amp; 1 ) }
	breakif gameReset
</pre>

<p>Now we have a meaningful name for the condition, so we can use it again.
Not only that: we can use the function as part of a bigger expression.
Suppose we've also defined a gameSelect function that evaluates to true
if the Game Select switch is pressed. We want to break when the user
presses both Select and Reset:</p>

<pre>
	breakif { gameReset &amp;&amp; gameSelect }
</pre>

<p>If you've defined a lot of complex functions, you probably will
want to re-use them in future runs of the debugger. You can save all
your functions, breakpoints, conditional breaks, and watches with the
"save" command. If you name your saved file the same as the ROM filename
and place it in the ROM directory, it'll be auto-loaded next time you
load the same ROM in Stella. The save file is just a plain text file
called "filename.stella", so you can edit it and add new functions, etc.
You can also create a file called "autoexec.stella" which will be loaded
when the debugger starts, no matter what ROM you have loaded. This file
should live in the "base directory" (which is the current directory on
Windows or $HOME/.stella on UNIX), <b>not</b> the ROM directory.</p>

<h4>Built-in Functions</h4>

<p>Stella has some pre-defined functions for use with the "breakif"
command.  These allow you to break and enter the debugger on various
conditions without having to define the conditions yourself.</p>

<p>Built-in functions and pseudo-registers always start with an _
(underscore) character. It is suggested that you don't start labels in
your game's source with underscores, if you plan to use them with the
Stella debugger.</p>

<table border="1" cellpadding="3">
<tr><th>Function</th><th>Definition</th><th>Description</th></tr>
<tr><td> _joy0left</td><td> !(*SWCHA &amp; $40)</td><td> Left joystick moved left</td></tr>
<tr><td> _joy0right</td><td> !(*SWCHA &amp; $80)</td><td> Left joystick moved right</td></tr>
<tr><td> _joy0up</td><td> !(*SWCHA &amp; $10)</td><td> Left joystick moved up</td></tr>
<tr><td> _joy0down</td><td> !(*SWCHA &amp; $20)</td><td> Left joystick moved down</td></tr>
<tr><td> _joy0button</td><td> !(*INPT4 &amp; $80)</td><td> Left joystick button pressed</td></tr>
<tr><td> _joy1left</td><td> !(*SWCHA &amp; $04)</td><td> Right joystick moved left</td></tr>
<tr><td> _joy1right</td><td> !(*SWCHA &amp; $08)</td><td> Right joystick moved right</td></tr>
<tr><td> _joy1up</td><td> !(*SWCHA &amp; $01)</td><td> Right joystick moved up</td></tr>
<tr><td> _joy1down</td><td> !(*SWCHA &amp; $02)</td><td> Right joystick moved down</td></tr>
<tr><td> _joy1button</td><td> !(*INPT5 &amp; $80)</td><td> Right joystick button pressed</td></tr>
<tr><td> _select</td><td> !(*SWCHB &amp; $01)</td><td> Game Select pressed</td></tr>
<tr><td> _reset</td><td> !(*SWCHB &amp; $02)</td><td> Game Reset pressed</td></tr>
<tr><td> _color</td><td> *SWCHB &amp; $08</td><td> Color/BW set to Color</td></tr>
<tr><td> _bw</td><td> !(*SWCHB &amp; $08)</td><td> Color/BW set to BW</td></tr>
<tr><td> _diff0b</td><td> !(*SWCHB &amp; $40)</td><td> Left difficulty set to B (easy)</td></tr>
<tr><td> _diff0a</td><td> *SWCHB &amp; $40</td><td> Left difficulty set to A (hard)</td></tr>
<tr><td> _diff1b</td><td> !(*SWCHB &amp; $80)</td><td> Right difficulty set to B (easy)</td></tr>
<tr><td> _diff1a</td><td> *SWCHB &amp; $80</td><td> Right difficulty set to A (hard)</td></tr>
</table>

<p>Don't worry about memorizing them all: the Prompt "help" command
will show you a list of them.</p>

<h4>Pseudo-Registers</h4>

<p>These "registers" are provided for you to use in your conditional breaks.
They're not registers in the conventional sense, since they don't exist in
a real system.  For example, while the debugger keeps track of the number
of scanlines in a frame, a real system would not (there is no register
that holds 'number of scanlines' on an actual console).</p>
<table border="1" cellpadding="3">
<tr><th>Function</th><th>Description</th></tr>
<tr><td> _bank</td><td> Currently selected bank</td></tr>
<tr><td> _rwport</td><td> Last address to attempt a read from the cart write port</td></tr>
<tr><td> _fcount</td><td> Number of frames since emulation started</td></tr>
<tr><td> _cclocks</td><td> Color clocks on a scanline</td></tr>
<tr><td> _scan</td><td> Current scanline count</td></tr>
<tr><td> _vsync</td><td> Whether vertical sync is enabled (1 or 0)</td></tr>
<tr><td> _vblank</td><td> Whether vertical blank is enabled (1 or 0)</td></tr>
</table>

<p><b>_scan</b> always contains the current scanline count. You can use
this to break your program in the middle of your kernel. Example:</p>
<pre>
    breakif _scan==#64
</pre>
<p>This will cause Stella to enter the debugger when the TIA reaches the
beginning of the 64th scanline.</p>

<p><b>_bank</b> always contains the currently selected bank. For 2K or 4K
(non-bankswitched) ROMs, it will always contain 0. One useful use is:</p>

<pre>
    breakif { pc==myLabel &amp;&amp; _bank==1 }
</pre>

<p>This is similar to setting a regular breakpoint, but it will only trigger
when bank 1 is selected.</p>

<h4>Watches</h4>

<p>A watch is an expression that gets evaluated and printed before
every prompt. This is useful for e.g. tracking the contents of a
memory location while stepping through code that modifies it.</p>

<p>You can set up to 10 watches (in future the number will be unlimited).
Since the expression isn't evaluated until it's used, you can include
registers: "watch *y" will show you the contents of the location
pointed to by the Y register, even if the Y register changes.</p>

<p>The watches are numbered. The numbers are printed along with the
watches, so you can tell which is which. To delete a watch use the
"delwatch" command with the watch number (1 to whatever). You can
also delete them all with the "clearwatches" command.</p>

<p>Note that there's no real point in watching a label or CPU register
without dereferencing it: Labels are constants, and CPU registers
are already visible in the CPU Widget</p>

<h4>Traps</h4>

<p>A trap is similar to a breakpoint, except that it catches
accesses to a memory address, rather than specific location in the
program. They're useful for finding code that modifies TIA registers
or memory.</p>

<p>An example: you are debugging a game, and you want to stop the
emulation and enter the debugger whenever RESP0 is strobed. You'd use
the command "trap RESP0" to set the trap, then exit the debugger. The
emulator will run until the next time RESP0 is accessed (either read
or write). Once the trap is hit, you can examine the TIA state to
see what the actual player 0 position is, in color clocks (or you
can in the future when we implement that feature in the TIA dump!)</p>

<p>Unlike breakpoints, traps stop the emulation *after* the instruction
that triggered the trap. The reason for this is simple: until the
instruction is executed, the emulator can't know it's going to hit a
trap. After the trap is hit, the instruction is done executing, and
whatever effects it may have had on e.g. the TIA state have already
happened...  but we don't have a way to run the emulated VCS in reverse,
so the best we can do is stop before the next instruction runs.</p>

<p>Traps come in two varieties: read access traps and write access traps.
It is possible to set both types of trap on the same address (that's
what the plain "trap" command does). To set a read or write only trap,
use "trapread" or "trapwrite". To remove a trap, you just attempt
to set it again: the commands actually toggle the trap on &amp; off. You
can also get rid of all traps at once with the "cleartraps" command.</p>

<p>Use "listtraps" to see all enabled traps.</p>

<h3>Prompt commands:</h3>

<p>Type "help" to see this list in the debugger.</p>

<pre>
            a - Set Accumulator to value xx
         bank - Show # of banks (with no args), Switch to bank (with 1 arg)
         base - Set default base (hex, dec, or bin)
        break - Set/clear breakpoint at address (default: current pc)
      breakif - Set breakpoint on condition
            c - Carry Flag: set (to 0 or 1), or toggle (no arg)
        cheat - Use a cheat code (see Stella manual for cheat types)
  clearbreaks - Clear all breakpoints
   cleartraps - Clear all traps
 clearwatches - Clear all watches
    colortest - Color Test
            d - Decimal Flag: set (to 0 or 1), or toggle (no arg)
       define - Define label
   delbreakif - Delete conditional break created with breakif
     delwatch - Delete watch
       disasm - Disassemble from address (default=pc)
         dump - Dump 128 bytes of memory at address
         exec - Execute script file
        frame - Advance emulation by xx frames (default=1)
     function - Define expression as a function for later use
         help - This cruft
+        list - List source (if loaded with loadlist)
   listbreaks - List breakpoints
    listtraps - List traps
  listwatches - List watches
+    loadlist - Load DASM listing file
    loadstate - Load emulator state (0-9)
      loadsym - Load symbol file
            n - Negative Flag: set (to 0 or 1), or toggle (no arg)
           pc - Set Program Counter to address
         poke - Set address to value. Can give multiple values (for address+1, etc)
        print - Evaluate and print expression in hex/dec/binary
          ram - Show RAM contents (no args), or set address xx to value yy
        reset - Reset 6507 to init vector (does not reset TIA, RIOT)
       rewind - Rewind state to last step/trace/scanline/frame advance
         riot - Show RIOT timer/input status
          rom - Change ROM contents
          run - Exit debugger, return to emulator
+       runto - Run until first occurrence of string in disassembly
            s - Set Stack Pointer to value xx
         save - Save breaks, watches, traps as a .stella script file
      saverom - Save (possibly patched) ROM to file
      saveses - Save console session to file
    savestate - Save emulator state (valid args 0-9)
      savesym - Save symbols to file
     scanline - Advance emulation by xx scanlines (default=1)
         step - Single step CPU (optionally, with count)
+         tia - Show TIA state (NOT FINISHED YET)
        trace - Single step CPU (optionally, with count), subroutines count as one instruction
         trap - Trap read and write accesses to address
     trapread - Trap read accesses to address
    trapwrite - Trap write accesses to address
        undef - Undefine label (if defined)
            v - Overflow Flag: set (to 0 or 1), or toggle (no arg)
        watch - Print contents of address before every prompt
            x - Set X Register to value xx
            y - Set Y Register to value xx
            z - Zero Flag: set (to 0 or 1), or toggle (no arg)
</pre>

<!-- <p>Commands marked with a * are unimplemented.</p> -->
<p>Commands marked with a + are partially implemented.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(B)</u> TIA Tab</h2>

<p>When selected, this tab shows detailed status of all the TIA registers
(except for audio; use the Audio tab for those).</p>
<p><img src="graphics/debugger_tiatab.png"></p>

<p>Most of the values on the TIA tab will be self-explanatory to a 2600
programmer. The top line (with all the hex values) displays the raw
values read from the TIA locations, as they would be seen by the CPU.<p>

<p>Many of the variables inside the TIA can only be written to by the
6502.  The debugger lets you get inside the TIA and see the contents
of these variables. These include the color registers, player/missile
graphics and positions, and the playfield.</p>

<p>You can control almost every aspect of the TIA from here, too: most
of the displays are editable. You can even toggle individual bits in
the GRP0/1 and playfield registers (remember to double-click).</p>

<p>The group of buttons labelled "Strobes" allows you to write to any
of the strobe registers at any time.</p>

<p>The collision registers are displayed in decoded format, in a table.
You can see exactly which objects have hit what. These are read-only
displays; you can't toggle the bits in the current release of Stella. Of
course, you can clear all the collisions with the CXCLR Strobe button.</p>

<p>To the right of each color register, you'll see a small rectangle
drawn in the current color. Changing a color register will change the
color of this rectangle.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(C)</u> I/O Tab</h2>

<p>When selected, this tab shows detailed status of the Input, Output,
and Timer portion of the RIOT/M6532 chip (the RAM portion is accessed
in another part of the debugger).</p>
<p><img src="graphics/debugger_iotab.png"></p>

<p>As with the TIA tab, most of the values here will be self-explanatory to a 2600
programmer, and almost all can be modified.  However, the SWCHx registers need
further explanation:<p>
<p>SWCHA(W) can be directly modified; here, the (W) stands for write.  Similarly,
SWACNT can be directly modified.  However, the results of reading back from
the SWCHA register are influenced by SWACNT, and SWCHA(R) is a read-only display
reflecting this result.</p>
<p>SWCHB cannot be directly modified; it will be indirectly modified by setting
the various difficulty switches, color/BW button, select/reset, etc.  SWBCNT
is hardwired as read-only, and is not shown.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(D)</u> Audio Tab</h2>

<p>This tab lets you view the contents of the TIA audio registers. In
the current release of Stella, these are read-only displays. This tab
will grow some features in a future release.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(E)</u> TIA Display</h2>

<p>In the upper left of the debugger, you'll see the current frame of
video as generated by the TIA. If a complete frame hasn't been drawn,
the partial contents of the current frame will be displayed up to the
current scanline, with the contents of the old frame (in black &amp;
white) filling the rest of the display.  Note that if 'phosphor mode'
has been enabled for a ROM, you will see the effect here as well.  That
is, no flicker will be shown for 30Hz display, even though a real
system would alternate between drawing frames (and hence produce
flicker).</p>

<p>You can use the "Scan+1" button, the prompt "scan" command, or the
Alt-L key-combo to watch the TIA draw the frame one scanline at a time.</p>

<p>You can also right-click anywhere in this window to show a context menu,
as illustrated:</p>
<p><img src="graphics/debugger_tiaoutcmenu.png"></p>
<p>The options are as follows:</p>
<ul>
	<li><b>Fill to scanline</b>: If you've already started a partial frame
	draw (ie, the frame is already partially 'greyed' out), selecting this
	option will draw all scanlines up to the vertical position where the
	mouse was clicked.  Note that if you weren't in partial-frame mode,
	this option will have no effect.</li>
	<li><b>Set breakpoint</b>: Will set a conditional breakpoint at the
	scanline where the mouse was clicked.  Currently, you'll need to use
	the Prompt Tab to turn the breakpoint off again.</li>
	<li><b>Set zoom position</b>: Influences what is shown in the TIA
	zoom area (further described in part (G).  The zoom area will
	contain the area centered at the position where the mouse was
	clicked.</li>
</ul>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(F)</u> TIA Info</h2>
<p>To the right of the TIA display (E) there is TIA information, as shown:</p>
<p><img src="graphics/debugger_tiainfo.png"></p>
<p>The indicators are as follows:</p>
<ul>
<li><b>Frame</b>: The current frame number, since this ROM was loaded or reset.</li>
<li><b>F. Cyc</b>: The number of CPU cycles that have been executed this frame, since
VSYNC was cleared at scanline 0.</li>
<li><b>Scanline</b>: The scanline that's currently being drawn. Scanline 0 is the one
on which VSYNC is cleared (after being set for 3 scanlines, as per the Stella
Programmer's Guide)</li>
<li><b>S. Cyc</b>: The number of CPU cycles that have been executed since the beginning
of the current scanline.</li>
<li><b>VSYNC &amp; VBLANK</b>: Self explanatory.</li>
<li><b>Pixel Pos</b>: The current number of visible color clocks that have been displayed on
the current scanline, starting from the beginning of the Horizontal Blank period.
During HBLANK, this value will be negative (representing the number of clocks
until the first visible one). Since there are 68 color clocks per HBLANK and
160 visible clocks per scanline, the Pixel Position will range from -68 to 159.</li>
<li><b>Color Clk</b>: The current number of total color clocks since the beginning of this
scanline's HBLANK. This counter starts at zero, but otherwise displays the same
information as the Pixel Position (so Color Clock will always be 68 more than Pixel
Position, and will range from 0 to 228).</li>
</ul>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(G)</u> TIA Zoom</h2>
<p>Below the TIA Info (F) is the TIA Zoom area. This allows you to enlarge
part of the TIA display, so you can see fine details.  Note that unlike
the TIA display area, this one <b>does</b> generate frames as the real
system would.  So, if you've enabled 'phosphor mode' for a ROM, it
won't be honoured here (ie, you'll see alternating frames at 30Hz display,
just like on a real system).</p>
<p>You can also right-click anywhere in this window to show a context menu,
as illustrated:</p>
<p><img src="graphics/debugger_tiazoomcmenu.png"></p>
<p>These options allow you to zoom in on the image for even greater detail.
If you click on the output window, you can scroll around using the cursor,
PageUp/Dn and Home/End keys.  You can also select the zoom position from
a context menu in the TIA Display.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(H)</u> Breakpoint/Trap Status</h2>
<p>Below the TIA Zoom (G), there is a status line that shows the reason the
debugger was entered (if a breakpoint/trap was hit), as shown:</p>
<p><img src="graphics/debugger_bpstatus.png"></p>
<p>The output here will generally be self-explanatory.  Due to space concerns,
conditional breakpoints will be shown as "CBP: ...", normal breakpoints
as "BP: ...", read traps as "RTrap: ..." and write traps as "WTrap: ...".
See the "Breakpoints" section for details.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(I)</u> CPU Registers</h2>
<p>This displays the current CPU state, as shown:</p>
<p><img src="graphics/debugger_cpuregs.png"></p>
<p>All the registers and flags are displayed, and can be changed by
double-clicking on them (to the left). Flags are toggled on double-click.
Selected registers here can also be changed by using the "Data Operations" buttons,
further described in (J).  All items are shown in hex.  Any label defined for the
current PC value is shown to the right.  Decimal and binary equivalents
are shown for SP/A/X/Y to the right (first decimal, then binary).</p>
<p>There's not much else to say about the CPU widget: if you know 6502
assembly, it's pretty self-explanatory. If you don't, well, you should
learn :)</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(J)</u> Data Operations buttons</h2>
<p>These buttons can be used to change values in either CPU Registers (I), or
the RIOT RAM (K), depending on which of these widgets is currently active.
<p><img src="graphics/debugger_dataops.png"></p>
<p>Each of these buttons also have a keyboard shortcut (indicated in square
brackets).  In fact, many of the inputboxes in various parts of the debugger
respond to these same keyboard shortcuts.  If in doubt, give them a try.</p>
<pre>
  0   [z]    - Set the current location/register to zero.
  Inv [i !]  - Invert the current location/register [toggle all its bits].
  Neg [n]    - Negate the current location/register [twos' complement negative].
  ++  [+ =]  - Increment the current location/register
  --  [-]    - Decrement the current location/register
  &lt;&lt;  [&lt; ,]  - Shift the current location/register left.
  &gt;&gt;  [&gt; .]  - Shift the current location/register right.

  Any bits shifted out of the location/register with &lt;&lt; or &gt;&gt;
  are lost (they will NOT end up in the Carry flag).
</pre>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(K)</u> M6532/RIOT and extended RAM</h2>
<p>This is a spreadsheet-like GUI for inspecting and changing the contents
of the 2600's RAM. You can view 128 bytes of RAM at a time, starting with
the RAM built in to the console (zero-page RAM).  If a cartridge contains
extended RAM, a scrollbar will be activated, allowing to scroll in
sequence through each 128 byte 'bank' of RAM.  The address in the upper left
corner indicates the offset (in terms of the read port) for the bank
currently being displayed.</p>
<p>You can navigate with either the mouse or the keyboard arrow keys.
To change a RAM location, either double-click on it or press Enter while
it's highlighted. Enter the new value (hex only for now, sorry), then
press Enter to make the change. If you change your mind, press Escape
and the original value will be restored.  The currently selected RAM cell
can also be changed by using the Data operations buttons/associated
shortcut keys (J).</p>
<p><b>Note:</b> Many extended RAM schemes involve different addresses for
reading versus writing RAM (read port vs. write port).  The UI takes care
of this for you; although the addresses shown are for the read port,
modifying a cell will use the write port.  Also, some bankswitching
schemes can swap RAM and ROM dynamically during program execution.  In
these cases, the values shown may not always be for RAM, and may point
to ROM instead.  In the latter case, the data cannot be modified.</p>
<p><img src="graphics/debugger_ram.png"></p>
<p>The 'Undo' button in the upper right should be self-explanatory; it will
undo the most previous operation to one cell only.  The 'Rev' button is
more comprehensive.  It will undo <i>all</i> operations on <i>all</i> cells
since you first made a change.</p>
<p>The UI objects at the bottom refer to the currently selected RAM cell.
The 'label' textbox shows the label attached to this RAM location (if any),
and the other textboxes show the decimal and binary equivalent value.
The remaining buttons to the right are further explained in section (L).</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(L)</u> M6532/RIOT and extended RAM (search/compare mode)</h2>
<p>The RAM widget also lets you search memory for values such as lives or remaining
energy, but it's also very useful when debugging to determine which
memory location holds which quantity.</p>
<p><img src="graphics/debugger_ramsearch.png"></p>
<p>To search RAM, click 'Srch' and enter a byte value into the search editbox (0-255).
All matching values will be highlighted in the RAM widget.  If 'Search' is clicked
and the input is empty, all RAM locations are highlighted.</p>

<p>The 'Cmp' button is used to compare the given value using all
addresses currently highlighted.  This may be an absolute number (such as 2),
or a comparitive number (such as -1).  Using a '+' or '-' operator
means 'search addresses for values that have changed by that amount'.</p>
<p>The 'Rset' button resets the entire operation; it clears the highlighted
addresses and allows another search.</p>
<p>The following is an example of inspecting all addresses that have
decreased by 1:</p>
<ul>
	<li>Click 'Srch' with empty input.  All address/values are highlighted</li>
	<li>Exit debugger mode and lose a life, let your energy decrease, or
		do whatever it is you're trying to debug</li>
	<li>Enter debugger mode again, click 'Cmp' and and enter a '-1' for input.
		This finds all values that have decreased by 1 (as compared to their current
		values)</li>
	<li>Repeatedly following these steps may help to narrow number of
		addresses under consideration, and eventually you'll find the
		memory address you're looking for</li>
	<li>Click 'Rset' when you're finished</li>
</ul>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2><u>(M)</u> ROM Listing</h2>
<p>The ROM Widget is a disassembly of the current bank of ROM. If a symbol
file is loaded, the disassembly will have labels. Even without a symbol
file, the standard TIA/RIOT labels will still be present.</p>
<p><img src="graphics/debugger_rom.png"></p>

<p>Each line of disassembly has four fields:</p>
<ul>
<li>Breakpoint - This is the area at the far left, to the left of the
address. Normally there will be nothing there: this indicates that there's
no breakpoint set at that address. You can set and clear breakpoints by
clicking in this area. When a breakpoint is set, there will be a
red circle in this area. These are the same breakpoints as used
by the "break" command, <b>not</b> the conditional "breakif" breakpoints
(which makes sense: cond-breaks can break on any condition, the Program
Counter isn't necessarily involved).</li>
<li>Address (which may be a label or a hex address)</li>
<li>Hex bytes. These are the raw machine code bytes for the instruction.</li>
<li>Instruction. This is a standard 6502 mnemonic (possibly with operand).
This field also contains the cycle count for the instruction (separated by a
semicolon).</li>
</ul>

<p>The 6502 mnemonic will be UPPERCASE for all standard instructions,
or lowercase for "illegal" 6502 instructions (like "dcp"). Since there's
no way to tell code from data, you'll likely see a lot of illegal opcodes
if you scroll to a data table in ROM.</p>

<p>Beware: the cycle counts don't take into account any penalty cycles
for crossing page boundaries. All branches are shown as 2 cycles, which
is how long they take if the branch isn't taken. Branches that are
taken will actually take 3 cycles (plus a penalty cycle if they cross
page boundaries).</p>

<p>You can scroll through the disassembly with the mouse or keyboard. To
center the display on the current PC, press the Space bar.</p>

<p>Any time the Program Counter changes (due to a Step, Trace, Frame
or Scanline advance, or manually setting the PC), the disassembly will
scroll to the current PC location.</p>

<p>Even though ROM is supposed to be Read Only Memory, this is an
emulator: you can change ROM all you want within the debugger.  The hex
bytes in the ROM Widget are editable. Double-click on them to edit
them. When you're done, press Enter to accept the changes or Escape to
cancel them.  Any time you edit ROM, there may be a short pause while
the ROM Widget disassembles the current bank again.</p>

<p>Speaking of banks: Above the disassembly there's an indicator for the
current bank and total number of banks. If there's more than one bank,
you can manually switch banks by double-clicking the bank number and enter
a new number (or using the shortcuts keys for inputboxes as described
in section (J). This won't work if the ROM only has one bank, of course.</p>

<p>The ROM listing also contains a context menu, accessible by right-clicking
anywhere in the listing:</p>
<p><img src="graphics/debugger_romcmenu.png"></p>
<p>Currently, there are two options:</p>
<ul>
	<li><b>Save ROM</b>: A textbox will appear for you to enter filename,
and then the ROM will be saved. Note that the filename is considered
relative to the <b>current</b> directory, not the ROM or base directory.
You can enter a full path, though, in which case it doesn't matter.</li>
	<li><b>Set PC</b>: Set the Program Counter to the address of the
disassembly line where the mouse was clicked.</li>
</ul>

<h3>Limitations</h3>

<ul>

<li>The ROM Widget only works on ROM. If your game runs code from RAM,
the ROM Widget will get "confused" while the PC is pointing to RAM. It
will highlight instructions in ROM instead. If the PC points to (for
example) $80, the ROM Widget will display the instruction at $F080
instead. No permanent harm is done: once your RAM routine returns, the
ROM Widget will work normally again. You can still disassemble RAM with
the "disasm" command from the Prompt.</li>

<li>The standard VCS memory map has the cartridge port at locations
$F000-$FFFF.  However, not all the address lines exist on a 6507, so
the cartridge port is "mirrored" at every other 4K chunk of address
space ($1000, $3000, up to $D000).  Some programmers find it easier
to think of the different banks of ROM as being at different addresses
(such as: Bank 0 at $D000 and bank 1 at $F000). When such a ROM runs,
the Program Counter can point to one of the mirrors instead of the main
area at $F000. This is perfectly OK, and everything works just fine,
except that the ROM Widget will show the "real" address instead of the
mirrored one. For instance, if the PC contains $D010, the ROM Widget
will highlight the instruction at $F010. This is the same instruction,
since $D010 reads the same ROM location as $F010. However, the breakpoint
indicator may be wrong: breakpoints are set on actual addresses. If
there were a breakpoint set at $F010, it wouldn't be triggered by the
PC hitting $D010 (but the ROM Widget will show a breakpoint indicator
if the PC hits $D010, even though it shouldn't)</li>

</ul>

<p>These limitations will be addressed in a future release of Stella.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2>Global Buttons</h2>

<p>There are also buttons on the right that always show up no matter which
tab you're looking at. These are always active. They are: Step, Trace,
Scan+1, Frame+1 and Exit.  The larger button to the left (labeled '&lt;')
performs the rewind operation, which will undo the previous Step/Trace/Scan/Frame
advance.  The rewind buffer is currently 100 levels deep.</p>
<p><img src="graphics/debugger_globalbuttons.png"></p>

<p>When you use these buttons, the prompt doesn't change. This means the
status lines with the registers and disassembly will be "stale". You
can update them just by pressing Enter in the prompt.</p>

<p>You can also use the Step, Trace, Scan+1, Frame+1 and Rewind buttons from
anywhere in the GUI via the keyboard, with Alt-S, Alt-T, Alt-L, Alt-F and Alt-R.</p>


<!-- /////////////////////////////////////////////////////////////////////////  -->
<br>
<h2>Tutorial: How to hack a ROM</h2>

<p>Here is a step-by-step guide that shows you how to use the debugger to
actually do something useful. No experience with debuggers is necessary,
but it helps to know at least a little about 6502 programming.</p>

<ol>
	<li>Get the Atari Battlezone ROM image. Make sure you've got the
		regular NTSC version. Load it up in Stella and press TAB to get to
		the main menu. From there, click on "Game Information". For "Name", it
		should say "Battlezone (1983) (Atari)" and for MD5Sum it should say
		"41f252a66c6301f1e8ab3612c19bc5d4". The rest of this tutorial assumes
		you're using this version of the ROM; it may or may not work with the
		PAL version, or with any of the various "hacked" versions floating around
		on the 'net.</li>

	<li>Start the game. You begin the game with 5 lives (count the tank
		symbols at the bottom of the screen).</li>

	<li>Enter the debugger by pressing the ` (backquote) key. Don't get
		killed before you do this, though.  You should still have all 5 lives.</li>

	<li>In the RAM display, click the "Search" button (labelled 'Srch') and enter "5" for input.
		This searches RAM for your value and highlights all addresses that match
		the input.  You should see two addresses highlighted: "00a5" and "00ba".
		These are the only two addresses that currently have the value 5, so they're
		the most likely candidates for "number of lives" counter. (However, some
		games might actually store one less than the real number of lives, or
		one more, so you might have to experiment a bit.  Since this is a "rigged
		demo", I already know Battlezone stores the actual number of lives.
		Most games do, actually).</li>

	<li>Exit the debugger by pressing ` (backquote) again. The game will
		pick up where you left off.</li>

	<li>Get killed! Ram an enemy tank, or let him shoot you. Wait for
		the explosion to finish. You will now have 4 lives.</li>

	<li>Enter the debugger again.  Click the "Compare" button (labelled 'Cmp') in RAM widget and enter
		a value of 4.  Now the RAM widget should only show one highlighted address:
		"00ba".  What we did was search within our previous results (the ones that
		were 5 before) for the new value 4. Address $00ba used to have the value 5,
		but now it has 4. This means that Battlezone (almost certainly) stores the
		current number of lives at address $00ba.</li>

	<li>Test your theory. Go to the RAM display and change address $ba to
		some high number like $ff (you could use the Prompt instead: enter "ram
		$ba $ff"). Exit the debugger again (or advance the frame). You should now see lots of lives
		at the bottom of the screen (of course, there isn't room to display $ff
		(255) of them!)... play the game, get killed a few times, notice that
		you have lots of lives.</li>

	<li>Now it's time to decide what sort of "ROM hack" we want to
		accomplish. We've found the "lives" counter for the game, so we can
		either have the game start with lots of lives, or change the game
		code so we can't get killed (AKA immortality), or change the code
		so we always have the same number of lives (so we never run out, AKA
		infinite lives). Let's go for infinite lives: it's a little harder than
		just starting with lots of lives, but not as difficult as immortality
		(for that, we have to disable the collision checking code, which means
		we have to find and understand it first!)</li>

	<li>Set a Write Trap on the lives counter address: "trapwrite $ba"
		in the Prompt. Exit the debugger and play until you get killed. When
		you die, the trap will cause the emulator to enter the debugger with the
		Program Counter pointing to the instruction *after* the one that wrote
		to location $ba.</li>

	<li>Once in the debugger, look at the ROM display.  The PC should be at address
		$f238, instruction "LDA $e1". You want to examine a few instructions before
		the PC, so scroll up using the mouse or arrow keys.  Do you see
		the one that affects the lives counter? That's right, it's the "DEC $ba"
		at location $f236.</li>

	<li>Let's stop the DEC $ba from happening. We can't just delete the
		instruction (it would mess up the addressing of everything afterwards,
		if it were even possible), but we can replace it with some other
		instruction(s).

		<p>Since we just want to get rid of the instruction, we can replace it with
		NOP (no operation). From looking at the disassembly, you can see that
		"DEC $ba" is a 2-byte long instruction, so we will need two one-byte
		NOP instructions to replace it. From reading the prompt help (the "help"
		command), you can see that the "rom" command is what we use to patch ROM.

		<p>Unfortunately, Stella doesn't contain an assembler, so we can't just
		type NOP to put a NOP instruction in the code. We'll have to use the
		hex opcode instead.

		<p>Now crack open your 6502 reference manual and look up the NOP
		instruction's opcode... OK, OK, I'll just tell you what it is: it's $EA
		(234 decimal). We need two of them, so the bytes to insert will look like:

		<pre>    $ea $ea</pre>

		<p>Select the line at address $f236 and enter 'ROM patch' mode.  This is done
		by either double-clicking the line, or pressing enter.  Then delete the bytes
		with backspace key and enter "ea ea".  Another way to do this would have been
		to enter "rom $f236 $ea $ea" in the Prompt widget.
	</li>

	<li>Test your patch. First, set location $ba to some number of
		lives that can be displayed on the screen ("poke $ba 3" or enter directly into
		the RAM display). Now exit the debugger and play the game. You should see 3
		lives on the screen.</li>

	<li>The crucial test: get killed again! After the explosion, you
		will *still* see 3 lives: Success! We've hacked Battlezone to give us
		infinite lives.</li>

	<li>Save your work. In the prompt: "saverom bzhack.bin". You now
		have your very own infinite-lives version of Battlezone. The file will
		be saved in the current directory (NOT your ROM directory), so you might
		want to move it to your ROM directory if it isn't the current directory.
		This can also be accomplished by right-clicking on the ROM widget and
		selecting 'Save ROM'.</li>

	<li>Test the new ROM: exit Stella, and re-run it. Open your ROM
		(or give its name on the command line) and play the game. You can play
		forever! It worked.</li>
</ol>

<p>Now, try the same techniques on some other ROM image (try Pac-Man). Some
games store (lives+1) or (lives-1) instead of the actual number,
so try searching for those if you can't seem to make it work. Also,
some cartridge types include their own RAM. The debugger doesn't (yet)
know how to access on-cartridge RAM, so you'll have to use the "bank" and
"ram" commands to manually search the address space for the value you're
looking for (future versions of the debugger will be smarter about this).</p>

<p>If you successfully patch a ROM in the debugger, but the saved version
won't work, or looks funny, you might need to add an entry to the
stella.pro file, to tell Stella what bankswitch and/or TV type to use.
That's outside the scope of this tutorial :)</p>

<p>Of course, the debugger is useful for a lot more than cheating and
hacking ROMs. Remember, with great power comes great responsibility,
so you have no excuse to avoid writing that game you've been thinking
about for so long now :)</p>