From 0afd6b44d09fc92e6a58c34ee10515246457609c Mon Sep 17 00:00:00 2001 From: thrust26 Date: Mon, 4 Dec 2017 11:02:36 +0100 Subject: [PATCH] 'Contents' and links do added debugger documentation some debugger doc updates --- docs/debugger.html | 261 ++++++++++++++++++++++++++++++++------------- docs/index.html | 3 +- 2 files changed, 191 insertions(+), 73 deletions(-) diff --git a/docs/debugger.html b/docs/debugger.html index ff36d303f..65204d9d3 100644 --- a/docs/debugger.html +++ b/docs/debugger.html @@ -2,16 +2,81 @@ Stella Debugger + -

Stella Integrated Debugger (a work in progress)

+
Stella
+

Release 5.1

+

Integrated Debugger

+

(a work in progress)

+
+

Contents

+
    +
  1. Features
    2. +
  2. How to use the Debugger + +
    3. +
  3. Distella Configuration Files
    4. +
  4. Tutorial: How to hack a ROM
    5. + +
+ +
+ +

Features

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 completely cross-platform.

-

Here's a (non-comprehensive) list of what the debugger can do so far:

+

Here's a (non-comprehensive) list of what the debugger can do so far:

-

Future planned features:

+

Future planned features:

-

How to use the debugger

+
+

How to use the Debugger

Pressing ` (aka backtick, backquote, grave accent) toggles the debugger on & off. When you exit the debugger, the emulation resumes at the current @@ -142,12 +211,14 @@ 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' is used for something else).

+keyboard to select which tab you want to view. Control/Cmd + Tab cycles between +tabs from left-to-right, Control/Cmd + Shift + Tab cycles right-to-left. +Pressing Tab (or Shift + Tab) cycles between widgets in the current tab (except +for in the Prompt Tab, where 'tab' is used for something else).

-

You can also enter the debugger at emulator startup by use the 'debug' command on the command line, or alternatively within the ROM launcher in 'Power-on options': +

You can also enter the debugger at emulator startup by use the 'debug' +command on the command line, or alternatively within the ROM launcher in +'Power-on options': 

   ; will enter the debugger before any instructions run
   stella -debug mygame.bin
@@ -160,15 +231,87 @@ for in the Prompt area, where 'tab' is used for something else).

-

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 +

Using the ` key will always enter the debugger at the end of +the frame (for NTSC games usually scanline 262). 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.

-

Change Tracking

+ +
+

Global Buttons

+ +

There are some buttons on the right top that always show up no matter which +tab you are looking at. This is because these are the ones which you will use +most.

+ + + +

The larger button at the left top (labeled '<') performs the rewind operation, +which will undo the previous Step/Trace/Scan/Frame advance, the smaller button at +the left bottom (labeled '>') performs the unwind operation, which will undo the +previous rewind operation. The rewind buffer is 100 levels deep by default.

+ +

The other operations are Step, Trace, Scan+1, Frame+1 and Exit (debugger).

+ +

You can also use the buttons from anywhere in the GUI via hotkeys.

+ + +

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 re-running the relevant commands in the prompt.

+ + + +
+

Change Tracking

The debugger tracks changes to the CPU registers and RAM by displaying changed locations or registers with a red background after each step, @@ -181,9 +324,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.

- -

(A) Prompt tab

+
+

(A) Prompt Tab

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

@@ -222,7 +365,7 @@ 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

+

Tab Key Auto-Complete

While entering a command, label or function, you can type a partial name and press the Tab key to attempt to auto-complete it. If you've ever used @@ -241,7 +384,7 @@ or set during debugging with the "define" command. It also works with built-in functions and those defined with the "function" command, but it doesn't (yet) work on filenames.

-

Expressions

+

Expressions

Almost every command takes a value: the "a" command takes a byte to stuff into the accumulator, the "break" command @@ -286,7 +429,7 @@ operands as 0 for false, non-zero for true, and return either 0 or 1. So $1234&$5678 results in $1230, whereas $1234&&$5678 results in 1. This is just like C or C++...

-

Prefixes

+

Prefixes

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

@@ -358,9 +501,9 @@ to change the meaning of an expression. The prefixes are:


-

Breakpoints, watches and traps, oh my!

+

Breakpoints, watches and traps, oh my!

-

Breakpoints

+

Breakpoints

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 @@ -386,7 +529,7 @@ breakpoint on & off, like a light switch.

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

-

Conditional Breaks

+

Conditional Breaks

A conditional breakpoint causes the emulator to enter the debugger when some arbitrary condition becomes true. "True" means "not zero" here: @@ -434,7 +577,7 @@ the number comes from "listbreaks" or by entering the same conditional break aga conditional break, the reason will be displayed in the status area near the TIA Zoom display (area H).

-

Functions

+

Functions

There is one annoyance about complex expressions: once we remove the conditional break with "delbreakif" or "clearbreaks", @@ -463,7 +606,7 @@ presses both Select and Reset:

and expression for each function. Functions can be removed with "delfunction label", where the labels come from "listfunctions".

-

Built-in Functions

+

Built-in Functions

Stella has some pre-defined functions for use with the "breakif" command. These allow you to break and enter the debugger on various @@ -499,7 +642,7 @@ Stella debugger.

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

-

Pseudo-Registers

+

Pseudo-Registers

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 @@ -539,7 +682,7 @@ beginning of the 64th scanline.

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

-

Watches

+

Watches

A watch is an expression that gets evaluated and printed before every prompt. This is useful for e.g. tracking the contents of a @@ -559,7 +702,7 @@ also delete them all with the "clearwatches" command.

without dereferencing it: Labels are constants, and CPU registers are already visible in the CPU Widget

-

Traps

+

Traps

A trap is similar to a breakpoint, except that it catches accesses to a memory address, rather than specific location in the @@ -598,7 +741,7 @@ can remove a trap with "deltrap number", where the number comes from all traps at once with the "cleartraps" command.


-

Save your work!

+

Save your work!

Stella offers several commands to save your work inside the debugger for later re-use. @@ -672,7 +815,7 @@ Any previously saved state can be loaded with "loadstate" plus the slot number (0-9).


-

Prompt commands:

+

Prompt Commands

Type "help" to see this list in the debugger.
Type "help 'cmd'" to see extended information about the given command.

@@ -774,7 +917,7 @@ clearsavestateifs - Clear all savestate points
-

(B) 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).

@@ -827,7 +970,7 @@ are visualized in the debugger in the queued writes area of the TIA tab.


-

(C) I/O 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 @@ -845,7 +988,7 @@ reflecting this result.


-

(D) Audio Tab

+

(D) Audio Tab

This tab lets you view the contents of the TIA audio registers and the effective volume resulting from the two channel volumes.

@@ -857,7 +1000,7 @@ volume resulting from the two channel volumes.


-

(E) TIA Display

+

(E) 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, @@ -895,7 +1038,7 @@ as illustrated:


-

(F) TIA Info

+

(F) TIA Info

To the right of the TIA display (E) there is TIA information, as shown:

The indicators are as follows (note that all these are read-only):

@@ -923,7 +1066,7 @@ Position, and will range from 0 to 228).
-

(G) TIA Zoom

+

(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 @@ -941,7 +1084,7 @@ a context menu in the TIA Display.


-

(H) Breakpoint/Trap Status

+

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

@@ -953,7 +1096,7 @@ See the "Breakpoints" section for details.


-

(I) CPU Registers

+

(I) CPU Registers

This displays the current CPU state, as shown:

All the registers and flags are displayed, and can be changed by @@ -974,7 +1117,7 @@ learn :)


-

(J) Data Operations buttons

+

(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.

@@ -997,7 +1140,7 @@ respond to these same keyboard shortcuts. If in doubt, give them a try.


-

(K) M6532/RIOT RAM

+

(K) M6532/RIOT RAM

This is a spreadsheet-like GUI for inspecting and changing the contents of the 2600's zero-page RAM.

You can navigate with either the mouse or the keyboard arrow keys. @@ -1019,8 +1162,7 @@ The remaining buttons to the right are further explained in section (L).

-
-

(L) M6532/RIOT RAM (search/compare mode)

+

(L) M6532/RIOT RAM (search/compare mode)

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.

@@ -1053,7 +1195,7 @@ decreased by 1:


-

(M) ROM Disassembly

+

(M) ROM Disassembly

This area contains 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.

The disassembly is often quite extensive, and whenever possible tries to automatically @@ -1184,7 +1326,7 @@ in either binary or hexidecimal. -

Limitations

+

Limitations