mirror of https://github.com/stella-emu/stella.git
"Startup" section to debugger doc added
This commit is contained in:
thrust26
parent
260a8b7bb0
commit
a91bcbadc9
|
|
@ -16,6 +16,7 @@
|
|||
<li><a href="#Features">Features</a></li>
|
||||
<li><a href="#HowToDebugger">How to use the Debugger</a>
|
||||
<ul>
|
||||
<li><a href="#Startup">Startup</a></li>
|
||||
<li><a href="#GlobalButtons">Global Buttons</a></li>
|
||||
<li><a href="#ChangeTracking">Change Tracking</a></li>
|
||||
<li><a href="#PromptTab">Prompt Tab</a>
|
||||
|
|
@ -240,6 +241,68 @@ execution by stepping one instruction, scanline, or frame at a time
|
|||
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>
|
||||
|
||||
<h3><a name="Startup">Startup</a></h3>
|
||||
At startup, the debugger automatically tries load a number of files which
|
||||
will provide additional information for the debugger and can make debugging
|
||||
more convenient.
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
"autoexec.script"</br>
|
||||
Use this plain text file to define e.g. your own functions or settings.
|
||||
They will be loaded at startup for each ROM.
|
||||
|
||||
<p>The location of this file will depend on the OS as follows:</p>
|
||||
<p>
|
||||
<table cellpadding="3" border="1">
|
||||
<tr>
|
||||
<td><b>Linux/Unix</b></td>
|
||||
<td><i>~/.stella/autoexec.script</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Macintosh</b></td>
|
||||
<td><i>~/Library/Application Support/Stella/autoexec.script</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Windows</b></td>
|
||||
<td><i>%APPDATA%\Stella\autoexec.script</i>
|
||||
<b>or</b><br>
|
||||
<i>_BASEDIR_\autoexec.script</i>
|
||||
(if a file named 'basedir.txt' exists in the application
|
||||
directory containing the full pathname for _BASEDIR_)
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
"<rom_filename>.script"</br>
|
||||
In this ROM specific, plain text file you can store breaks, traps, watches
|
||||
etc. for future re-use. Use the "save" command to create this file using
|
||||
the current settings. You can also manually edit the file and add more commands.
|
||||
</br></br>
|
||||
</li>
|
||||
<li>
|
||||
"<rom_filename>.cfg"</br>
|
||||
This file is described in <a href="#DistellaConfiguration">
|
||||
<b>Distella Configuration Files</b></a>.
|
||||
</br></br>
|
||||
</li>
|
||||
<li>
|
||||
"<rom_filename>.lst"</br>
|
||||
</li>
|
||||
<li>
|
||||
"<rom_filename>.sym"</br>
|
||||
If you provied the -l and -s parameters DASM will create these two files during
|
||||
assembly. Stella uses the file content to display the correct labels.
|
||||
</li>
|
||||
</ul>
|
||||
<p>Note that all files are only accessed if you enter
|
||||
the debugger at least once during a program run. This means you can create
|
||||
these files, and not worry about slowing down emulation unless you're
|
||||
actively using the debugger.</p>
|
||||
|
||||
|
||||
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
||||
<br>
|
||||
<h2><a name="GlobalButtons">Global Buttons</a></h2>
|
||||
|
|
@ -486,13 +549,12 @@ to change the meaning of an expression. The prefixes are:</p>
|
|||
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.script" file (see
|
||||
the section on "Startup").</p>
|
||||
|
||||
<p>Remember, you can use arbitrarily complex expressions with any
|
||||
command that takes arguments.</p>
|
||||
</li>
|
||||
you can put a "base #10" command in your "autoexec.script" file (for details
|
||||
see <a href="#Startup"><b>Startup</b></a>).</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Remember, you can use arbitrarily complex expressions with any
|
||||
command that takes arguments.</p>
|
||||
|
||||
</br>
|
||||
<h3><a name="BreakpointsEtc">Breakpoints, watches and traps, oh my!</a></h3>
|
||||
|
|
@ -736,77 +798,61 @@ all traps at once with the "cleartraps" command.</p></p>
|
|||
|
||||
</br>
|
||||
<h3><a name="SaveWork">Save your work!</a></h3>
|
||||
Stella offers several commands to save your work inside the debugger for
|
||||
later re-use.
|
||||
<p>Stella offers several commands to save your work inside the debugger for
|
||||
later re-use.</p>
|
||||
|
||||
<h4>save</h4>
|
||||
<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, traps 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 will be auto-loaded next time you
|
||||
load the same ROM in Stella. The save file is just a plain text file
|
||||
called "rom_filename.script", so you can edit it and add new functions, etc.</p>
|
||||
<p>While "save" is ROM specific, you can also create a file called
|
||||
"autoexec.script" which will be loaded when the debugger starts, no matter
|
||||
what ROM you have loaded. The location of this file will depend on the
|
||||
version of Stella, as follows:</p>
|
||||
|
||||
<p><table cellpadding="3" border="1">
|
||||
<tr>
|
||||
<td><b>Linux/Unix</b></td>
|
||||
<td><i>~/.stella/autoexec.script</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Macintosh</b></td>
|
||||
<td><i>~/Library/Application Support/Stella/autoexec.script</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Windows</b></td>
|
||||
<td><i>%APPDATA%\Stella\autoexec.script</i>
|
||||
<b>OR</b><br>
|
||||
<i>_BASEDIR_\autoexec.script</i>
|
||||
(if a file named 'basedir.txt' exists in the application
|
||||
directory containing the full pathname for _BASEDIR_)
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>Note that these '.script' script files are only accessed if you enter
|
||||
the debugger at least once during a program run. This means you can create
|
||||
these files, and not worry about slowing down emulation unless you're
|
||||
actively using the debugger.</p>
|
||||
|
||||
<h4>saveconfig</h4>
|
||||
The "saveconfig" command creates a <a href="#DistellaConfiguration"><b>DiStella Configuration File</b></a> which is
|
||||
based on Stella's dynamic and static analysis of the current ROM.
|
||||
<p>This will be automatically loaded the next time your start the debugger.
|
||||
From there on, you can continue analyzing the ROM and then use "saveconfig"
|
||||
again to update the configuration. You can also use "loadconfig" to load it
|
||||
manually.
|
||||
<p>Note that this is not tested for multi-banked ROMs.</p>
|
||||
|
||||
<h4>savedis</h4>
|
||||
While your are playing or debugging a game, Stella will gather dynamic
|
||||
information about the ROM. It can then use that information together with
|
||||
a static analysis of the ROM and therefore create a better disassembly
|
||||
than DiStella alone. "savedis" allows you to save that disassembly as the
|
||||
result of this combined analysis.
|
||||
<p>Note that this currently only works for single banked ROMs. For larger
|
||||
ROMs, the created disassembly is incomplete.</p>
|
||||
|
||||
<h4>saverom</h4>
|
||||
If you have manipulated a ROM, you can save it with "saverom". The file is
|
||||
named '<rom_filename>.a26'.
|
||||
|
||||
<h4>saveses</h4>
|
||||
The "saveses" command dumps the whole prompt session into a file named
|
||||
"YYYY-MM-DD_HH-mm-ss.txt". So you can later lookup what you did exactly
|
||||
when you were debugging at that time.
|
||||
|
||||
<h4>savestate</h4>
|
||||
<p>This command works identical to the save state hotkey (F9) during emulation.
|
||||
Any previously saved state can be loaded with "loadstate" plus the slot
|
||||
number (0-9).</p>
|
||||
<ul>
|
||||
<li>
|
||||
<b><a name="savecmd">save</a></b>: 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, traps 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 will be auto-loaded next time you
|
||||
load the same ROM in Stella. The saved file is just a plain text file
|
||||
called "<rom_filename>.script", so you can edit it and add new functions, etc.
|
||||
<p>Note: While "save" is ROM specific, you can also create a file called
|
||||
"autoexec.script" which will be loaded when the debugger starts, no matter
|
||||
what ROM you have loaded.<p>
|
||||
See <a href="#Startup"><b>Startup</b></a> for details.
|
||||
</li>
|
||||
<li>
|
||||
<b>saveconfig</b>: The "saveconfig" command creates a
|
||||
<a href="#DistellaConfiguration"><b>DiStella Configuration File</b></a> which is
|
||||
based on Stella's dynamic and static analysis of the current ROM.
|
||||
<p>This will be automatically loaded the next time your start the debugger.
|
||||
From there on, you can continue analyzing the ROM and then use "saveconfig"
|
||||
again to update the configuration. You can also use "loadconfig" to load it
|
||||
manually.
|
||||
<p>Note that this is not tested for multi-banked ROMs.</p>
|
||||
</li>
|
||||
<li>
|
||||
<b>savedis</b>:
|
||||
While your are playing or debugging a game, Stella will gather dynamic
|
||||
information about the ROM. It can then use that information together with
|
||||
a static analysis of the ROM and therefore create a better disassembly
|
||||
than DiStella alone. "savedis" allows you to save that disassembly as the
|
||||
result of this combined analysis.
|
||||
<p>Note that this currently only works for single banked ROMs. For larger
|
||||
ROMs, the created disassembly is incomplete.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><b>saverom</b>:
|
||||
If you have manipulated a ROM, you can save it with "saverom". The file is
|
||||
named "<rom_filename>.a26".</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><b>saveses</b>:
|
||||
The "saveses" command dumps the whole prompt session into a file named
|
||||
"<YYYY-MM-DD_HH-mm-ss>.txt". So you can later lookup what you did exactly
|
||||
when you were debugging at that time.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><b>savestate</b>:
|
||||
This command works identical to the save state hotkey (F9) during emulation.
|
||||
Any previously saved state can be loaded with "loadstate" plus the slot
|
||||
number (0-9).</p>
|
||||
</li>
|
||||
</ul>
|
||||
</br>
|
||||
|
||||
<h3><a name="PromptCommands">Prompt Commands</a></h3>
|
||||
|
|
|
|||
Loading…
Reference in New Issue