From 8019e877ca2549141b9a2df81374344e3bd442e6 Mon Sep 17 00:00:00 2001 From: stephena Date: Tue, 13 Jan 2009 14:45:34 +0000 Subject: [PATCH] Huge updates to the documentation, particularly to the debugger portion. Many changes have been made to Stella since that document was first written, and quite a few things are now documented for the first time. This means the next release will (feature-wise) look a lot bigger than it really is :) git-svn-id: svn://svn.code.sf.net/p/stella/code/trunk@1616 8b62c5a3-ac7e-4cc8-8f21-d9a121418aba --- stella/docs/debugger.html | 402 ++++++++++-------- stella/docs/graphics/cheat.png | Bin 5908 -> 3711 bytes stella/docs/graphics/debugger_bpstatus.png | Bin 0 -> 378 bytes stella/docs/graphics/debugger_cpuregs.png | Bin 0 -> 1270 bytes stella/docs/graphics/debugger_dataops.png | Bin 0 -> 702 bytes .../docs/graphics/debugger_globalbuttons.png | Bin 0 -> 889 bytes stella/docs/graphics/debugger_iotab.png | Bin 0 -> 5996 bytes stella/docs/graphics/debugger_main.png | Bin 0 -> 33710 bytes stella/docs/graphics/debugger_ram.png | Bin 0 -> 7450 bytes stella/docs/graphics/debugger_ramsearch.png | Bin 0 -> 5075 bytes stella/docs/graphics/debugger_rom.png | Bin 0 -> 9460 bytes stella/docs/graphics/debugger_romcmenu.png | Bin 0 -> 4337 bytes stella/docs/graphics/debugger_tiainfo.png | Bin 0 -> 1720 bytes stella/docs/graphics/debugger_tiaoutcmenu.png | Bin 0 -> 2355 bytes stella/docs/graphics/debugger_tiatab.png | Bin 0 -> 11425 bytes .../docs/graphics/debugger_tiazoomcmenu.png | Bin 0 -> 1195 bytes stella/docs/graphics/options_about.png | Bin 22910 -> 0 bytes stella/docs/graphics/options_audio.png | Bin 22618 -> 3039 bytes stella/docs/graphics/options_debugger.png | Bin 0 -> 3779 bytes stella/docs/graphics/options_gameinfo.png | Bin 22743 -> 6743 bytes stella/docs/graphics/options_help.png | Bin 23428 -> 0 bytes stella/docs/graphics/options_input.png | Bin 23135 -> 5303 bytes stella/docs/graphics/options_misc.png | Bin 0 -> 3691 bytes stella/docs/graphics/options_romaudit.png | Bin 21876 -> 0 bytes stella/docs/graphics/options_ui.png | Bin 22602 -> 4156 bytes stella/docs/graphics/romaudit.png | Bin 3219 -> 3183 bytes stella/docs/index.html | 313 +++++++++----- stella/src/emucore/Settings.cxx | 15 +- stella/src/emucore/m6502/src/M6502Hi.cxx | 8 +- stella/src/emucore/m6502/src/M6502Low.cxx | 8 +- stella/src/gui/VideoDialog.cxx | 4 +- 31 files changed, 453 insertions(+), 297 deletions(-) create mode 100644 stella/docs/graphics/debugger_bpstatus.png create mode 100644 stella/docs/graphics/debugger_cpuregs.png create mode 100644 stella/docs/graphics/debugger_dataops.png create mode 100644 stella/docs/graphics/debugger_globalbuttons.png create mode 100644 stella/docs/graphics/debugger_iotab.png create mode 100644 stella/docs/graphics/debugger_main.png create mode 100644 stella/docs/graphics/debugger_ram.png create mode 100644 stella/docs/graphics/debugger_ramsearch.png create mode 100644 stella/docs/graphics/debugger_rom.png create mode 100644 stella/docs/graphics/debugger_romcmenu.png create mode 100644 stella/docs/graphics/debugger_tiainfo.png create mode 100644 stella/docs/graphics/debugger_tiaoutcmenu.png create mode 100644 stella/docs/graphics/debugger_tiatab.png create mode 100644 stella/docs/graphics/debugger_tiazoomcmenu.png delete mode 100644 stella/docs/graphics/options_about.png create mode 100644 stella/docs/graphics/options_debugger.png delete mode 100644 stella/docs/graphics/options_help.png create mode 100644 stella/docs/graphics/options_misc.png delete mode 100644 stella/docs/graphics/options_romaudit.png diff --git a/stella/docs/debugger.html b/stella/docs/debugger.html index dfc58c262..c3cacc42a 100644 --- a/stella/docs/debugger.html +++ b/stella/docs/debugger.html @@ -83,7 +83,6 @@ feature that no other 2600 debugger has; it's completely cross-platform.<
  • Bankswitch support in the debugger for the few remaining cart types that aren't supported.
  • Patch ROM support for a few cart types doesn't work. Must fix.
    • -
  • Some way to control joystick/etc. input from within the debugger.
  • 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).
    • @@ -104,12 +103,18 @@ feature that no other 2600 debugger has; it's completely cross-platform.< & 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.

    -

    For space reasons, the Prompt, TIA, and Audio displays are split into -3 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 Ctrl-Tab cycles between tabs -from left to right, and Shift-Ctrl-Tab cycles from right to left. -Pressing Tab cycles between widgets in the current tab.

    + +

    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):

    +

    + +

    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' used for something else).

    You can also enter the debugger at emulator startup by giving a breakpoint on the command line: 

    @@ -144,7 +149,9 @@ 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.
    
 
-
    Prompt tab
    
+
+
+
    (A) Prompt tab
    
 
 
    This is a command-line interface, similar to the DOS DEBUG command
 or Supermon for the C=64.
    
@@ -158,61 +165,17 @@ scroll with the mouse. Copy and paste is not (yet?) supported.
    
 be abbreviated: instead of "clearbreaks", you can type "clear" or
 even just "cl". However, "c" by itself is the Toggle Carry command.
    
 
-
    Bash-style tab completion is supported for commands and labels (see below)
    
+
    Bash-style tab completion is supported for commands and labels (see below).
+Other Bash-style commands are also supported, as follows:
    
+
 
 
    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 by the time we release Stella 2.0. 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).
    
-
-
+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).
    
 
 
    Tab completion
    
 
@@ -641,15 +604,14 @@ can also get rid of all traps at once with the "cleartraps" command.
    
 
 
    Commands marked with a + are partially implemented.
    
 
-
    Most commands can be abbreviated just by typing a partial command:
-"st" for "step", or "f" for "frame". Where there are conflicts, generally
-the shortest name is chosen (so "tra" is "trap", not "trapread"). When
-in doubt, press TAB.
    
 
-
    TIA Tab
    
+
+
    
+
    (B) TIA Tab
    
 
 
    When selected, this tab shows detailed status of all the TIA registers
 (except for audio; use the Audio tab for those).
    
+
    
 
 
    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
@@ -677,141 +639,232 @@ Strobe button.
    
 drawn in the current color. Changing a color register will change the
 color of this rectangle.
    
 
-
    Audio Tab
    
+
+
+
    
+
    (C) I/O Tab
    
+
+
    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).
    
+
    
+
+
    As with the TIA tab, most of the values here will be self-explanatory to a 2600
+programmer, and almost all can be modified.
    
+
+
+
+
    
+
    (D) Audio Tab
    
 
 
    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.
    
 
-
    CPU Widget
    
 
-
    This shows the current CPU state. All the registers and flags are
-displayed, and can be changed by double-clicking on them. Flags are
-toggled on double-click.
    
+
+
    
+
    (E) TIA Display
    
 
-
    The 0, Inv, Neg, ++, --, <<, and >> buttons affect the
-currently-selected register (see RAM Widget below).
    
+
    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 &
+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).
    
 
+
    You can use the "Scan+1" button or the prompt "scan" command to watch
+the TIA draw the frame one scanline at a time.
    
+
+
    You can also right-click anywhere in this window to show a context menu,
+as illustrated:
    
+
    
+
    The options are as follows:
    
+
+
+
+
+
    
+
    (F) TIA Info
    
+
    To the right of the TIA display (E) there is TIA information, as shown:
    
+
    
+
    The indicators are as follows:
    
+
+
+
+
+
    
+
    (G) TIA Zoom
    
+
    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 does 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).
    
+
    You can also right-click anywhere in this window to show a context menu,
+as illustrated:
    
+
    
+
    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.
    
+
+
+
+
    
+
    (H) Breakpoint/Trap Status
    
+
    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:
    
+
    
+
    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.
    
+
+
+
+
    
+
    (I) CPU Registers
    
+
    This displays the current CPU state, as shown:
    
+
    
+
    All the registers and flags are displayed, and can be changed by
+double-clicking on them. Flags are toggled on double-click.  Selected registers
+here can also be changed by using the "Data Operations" buttons, further
+described in (J).
    
 
    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 :)
    
 
-
    RAM Widget
    
 
+
+
    
+
    (J) Data Operations buttons
    
+
    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.
+
    
+
    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.
    
+
    +  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
+  <<  [< ,]  - Shift the current location/register left.
+  >>  [> .]  - Shift the current location/register right.
+
+  Any bits shifted out of the location/register with << or >>
+  are lost (they will NOT end up in the Carry flag).
+
    
+
+
+
+
    
+
    (K) M6532/RIOT RAM
    
 
    This is a spreadsheet-like GUI for inspecting and changing the contents
 of the 2600's RAM. All 128 bytes of RAM are visible on the screen at
 once. 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.
    
+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).
    
+
    
+
    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 all operations on all cells
+since you first made a change.
    
+
    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).
    
 
-
    Nearby there are also some buttons to do various things to the
-currently-selected memory location from the RAM widget or
-CPU register from the CPU widget (whichever was most recently
-selected). The buttons are:
    
 
-
    -  0   - Set the current location/register to zero.
-  Inv - Invert the current location/register (toggle all its bits).
-  Neg - Negate the current location/register (twos' complement negative).
-  ++  - Increment the current location/register
-  --  - Decrement the current location/register
-  <<  - Shift the current location/register left.
-  >>  - Shift the current location/register right.
-
-  Any bits shifted out of the location/register with << or >>
-  are lost (they will NOT end up in the Carry flag).
-
    
-
-
    This widget also lets you search memory for values such as lives or remaining
+
+
    
+
    (L) M6532/RIOT RAM (search/compare mode)
    
+
    The RIOT 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.
    
-
-
    To search RAM, click 'Search' and enter a byte value into the search editbox (0-255).
+
    
+
    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
-when the input is empty, all RAM locations are searched.
    
+and the input is empty, all RAM locations are highlighted.
    
 
-
    The 'Compare' button is used to compare the given value using all
+
    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'.
    
-
+
    The 'Rset' button resets the entire operation; it clears the highlighted
+addresses and allows another search.
    
 
    The following is an example of inspecting all addresses that have
-decreased by 1:
-
+decreased by 1:
    
 
 
-
    TIA Display
    
-
-
    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 &
-white) filling the rest of the display.
    
-
-
    You can use the "Scan+1" button or the prompt "scan" command to watch
-the TIA draw the frame one scanline at a time.
    
-
-
    To the right of the video display, there are indicators for:
    
-
-
-
    Below the indicators is the TIA Zoom area. This allows you to enlarge
-part of the TIA display, so you can see fine details. To set the zoom
-region, right-click on the TIA display and choose "Set Zoom Position". To
-set the magnification level, right-click on the TIA Zoom area and choose
-2x, 4x, or 8x from the pop-up menu.
    
-
-
    Below the TIA Zoom, there is a status line that shows the reason the
-debugger was entered (if a breakpoint/trap was hit). This isn't really
-part of the TIA display; see "Breakpoints" below for details.
    
-
-
    
-
-
    ROM Widget
    
 
+
+
    
+
    (M) ROM Listing
    
 
    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.
    
+
    
 
 
    Each line of disassembly has four fields: