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="#Features">Features</a></li>
|
||||||
<li><a href="#HowToDebugger">How to use the Debugger</a>
|
<li><a href="#HowToDebugger">How to use the Debugger</a>
|
||||||
<ul>
|
<ul>
|
||||||
|
<li><a href="#Startup">Startup</a></li>
|
||||||
<li><a href="#GlobalButtons">Global Buttons</a></li>
|
<li><a href="#GlobalButtons">Global Buttons</a></li>
|
||||||
<li><a href="#ChangeTracking">Change Tracking</a></li>
|
<li><a href="#ChangeTracking">Change Tracking</a></li>
|
||||||
<li><a href="#PromptTab">Prompt Tab</a>
|
<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
|
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>
|
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>
|
<br>
|
||||||
<h2><a name="GlobalButtons">Global Buttons</a></h2>
|
<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,
|
assumed to be in the default base. When you first start Stella,
|
||||||
the default base is 16 (hexadecimal). You can change it with the
|
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,
|
"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
|
you can put a "base #10" command in your "autoexec.script" file (for details
|
||||||
the section on "Startup").</p>
|
see <a href="#Startup"><b>Startup</b></a>).</p>
|
||||||
|
</li>
|
||||||
<p>Remember, you can use arbitrarily complex expressions with any
|
|
||||||
command that takes arguments.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
</ul>
|
||||||
|
<p>Remember, you can use arbitrarily complex expressions with any
|
||||||
|
command that takes arguments.</p>
|
||||||
|
|
||||||
</br>
|
</br>
|
||||||
<h3><a name="BreakpointsEtc">Breakpoints, watches and traps, oh my!</a></h3>
|
<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>
|
</br>
|
||||||
<h3><a name="SaveWork">Save your work!</a></h3>
|
<h3><a name="SaveWork">Save your work!</a></h3>
|
||||||
Stella offers several commands to save your work inside the debugger for
|
<p>Stella offers several commands to save your work inside the debugger for
|
||||||
later re-use.
|
later re-use.</p>
|
||||||
|
|
||||||
<h4>save</h4>
|
<ul>
|
||||||
<p>If you've defined a lot of complex functions, you probably will
|
<li>
|
||||||
want to re-use them in future runs of the debugger. You can save all
|
<b><a name="savecmd">save</a></b>: If you've defined a lot of complex functions, you probably will
|
||||||
your functions, breakpoints, conditional breaks, traps and watches with the
|
want to re-use them in future runs of the debugger. You can save all
|
||||||
"save" command. If you name your saved file the same as the ROM filename
|
your functions, breakpoints, conditional breaks, traps and watches with the
|
||||||
and place it in the ROM directory, it will be auto-loaded next time you
|
"save" command. If you name your saved file the same as the ROM filename
|
||||||
load the same ROM in Stella. The save file is just a plain text file
|
and place it in the ROM directory, it will be auto-loaded next time you
|
||||||
called "rom_filename.script", so you can edit it and add new functions, etc.</p>
|
load the same ROM in Stella. The saved file is just a plain text file
|
||||||
<p>While "save" is ROM specific, you can also create a file called
|
called "<rom_filename>.script", so you can edit it and add new functions, etc.
|
||||||
"autoexec.script" which will be loaded when the debugger starts, no matter
|
<p>Note: While "save" is ROM specific, you can also create a file called
|
||||||
what ROM you have loaded. The location of this file will depend on the
|
"autoexec.script" which will be loaded when the debugger starts, no matter
|
||||||
version of Stella, as follows:</p>
|
what ROM you have loaded.<p>
|
||||||
|
See <a href="#Startup"><b>Startup</b></a> for details.
|
||||||
<p><table cellpadding="3" border="1">
|
</li>
|
||||||
<tr>
|
<li>
|
||||||
<td><b>Linux/Unix</b></td>
|
<b>saveconfig</b>: The "saveconfig" command creates a
|
||||||
<td><i>~/.stella/autoexec.script</i></td>
|
<a href="#DistellaConfiguration"><b>DiStella Configuration File</b></a> which is
|
||||||
</tr>
|
based on Stella's dynamic and static analysis of the current ROM.
|
||||||
<tr>
|
<p>This will be automatically loaded the next time your start the debugger.
|
||||||
<td><b>Macintosh</b></td>
|
From there on, you can continue analyzing the ROM and then use "saveconfig"
|
||||||
<td><i>~/Library/Application Support/Stella/autoexec.script</i></td>
|
again to update the configuration. You can also use "loadconfig" to load it
|
||||||
</tr>
|
manually.
|
||||||
<tr>
|
<p>Note that this is not tested for multi-banked ROMs.</p>
|
||||||
<td><b>Windows</b></td>
|
</li>
|
||||||
<td><i>%APPDATA%\Stella\autoexec.script</i>
|
<li>
|
||||||
<b>OR</b><br>
|
<b>savedis</b>:
|
||||||
<i>_BASEDIR_\autoexec.script</i>
|
While your are playing or debugging a game, Stella will gather dynamic
|
||||||
(if a file named 'basedir.txt' exists in the application
|
information about the ROM. It can then use that information together with
|
||||||
directory containing the full pathname for _BASEDIR_)
|
a static analysis of the ROM and therefore create a better disassembly
|
||||||
</td>
|
than DiStella alone. "savedis" allows you to save that disassembly as the
|
||||||
</tr>
|
result of this combined analysis.
|
||||||
</table>
|
<p>Note that this currently only works for single banked ROMs. For larger
|
||||||
<p>Note that these '.script' script files are only accessed if you enter
|
ROMs, the created disassembly is incomplete.</p>
|
||||||
the debugger at least once during a program run. This means you can create
|
</li>
|
||||||
these files, and not worry about slowing down emulation unless you're
|
<li>
|
||||||
actively using the debugger.</p>
|
<p><b>saverom</b>:
|
||||||
|
If you have manipulated a ROM, you can save it with "saverom". The file is
|
||||||
<h4>saveconfig</h4>
|
named "<rom_filename>.a26".</p>
|
||||||
The "saveconfig" command creates a <a href="#DistellaConfiguration"><b>DiStella Configuration File</b></a> which is
|
</li>
|
||||||
based on Stella's dynamic and static analysis of the current ROM.
|
<li>
|
||||||
<p>This will be automatically loaded the next time your start the debugger.
|
<p><b>saveses</b>:
|
||||||
From there on, you can continue analyzing the ROM and then use "saveconfig"
|
The "saveses" command dumps the whole prompt session into a file named
|
||||||
again to update the configuration. You can also use "loadconfig" to load it
|
"<YYYY-MM-DD_HH-mm-ss>.txt". So you can later lookup what you did exactly
|
||||||
manually.
|
when you were debugging at that time.</p>
|
||||||
<p>Note that this is not tested for multi-banked ROMs.</p>
|
</li>
|
||||||
|
<li>
|
||||||
<h4>savedis</h4>
|
<p><b>savestate</b>:
|
||||||
While your are playing or debugging a game, Stella will gather dynamic
|
This command works identical to the save state hotkey (F9) during emulation.
|
||||||
information about the ROM. It can then use that information together with
|
Any previously saved state can be loaded with "loadstate" plus the slot
|
||||||
a static analysis of the ROM and therefore create a better disassembly
|
number (0-9).</p>
|
||||||
than DiStella alone. "savedis" allows you to save that disassembly as the
|
</li>
|
||||||
result of this combined analysis.
|
</ul>
|
||||||
<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>
|
|
||||||
</br>
|
</br>
|
||||||
|
|
||||||
<h3><a name="PromptCommands">Prompt Commands</a></h3>
|
<h3><a name="PromptCommands">Prompt Commands</a></h3>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue