Debugger
In addition to providing the facility to play Atari 2600 games, Gopher2600 also provides a powerful debugger. Comprehensive documentation for the debugger has yet to be written but this page gives a brief overview.
The screenshot below shows a typical window layout of the debugger.
The menu bar at the top provides more windows, some of which are specific to certain
cartridge mappers. For example, for cartridges with a ARM7TDMI an ARM
disassembly window is provided.
The emulation can be controlled through the window labelled Control. The green Run button will set the emulation running. When running the button will turn into a green Halt button, which will stop the emulation immediately.
The Step button will move the emulation forward or backwards (the << button) one quantum. The quantum can be changed with the toggle next to the Step button. The two possible quantum states are CPU Instruction and Colour Clock (see section below).
The Step Over button is like the Step button except that it won't "follow" the program to a subroutine called by the JSR instruction. Instead, the program will run to the "return address" of the sub-routine.
Successful operation of the Step Over button assumes that the 6507 program does not monkey with the CPU stack. If the stack is altered then Step Over may simply run forever and required manual stopping with the Halt button.
The Frame and Scanline buttons will step forward or backwards either one frame of one scanline at a time.
The Performance slider can be used to limit the frame rate of the debugger. In the case where the requested performance is too high, the status message will indicate that.
Finally, the Capture input button can be used to ensure that mouse and keyboard input is used by the emulation itself, rather than the debugger. For example, using the cursor keys on the keyboard to control Pitfall Harry, in the game Pitfall, will not work unless input has been captured.
Hardware controllers (such as an Xbox360 controller) can always be used to control the emulation without capturing input.
For most development purposes the normal CPU Instruction quantum is fine-grained enough and fits in with how programmers normally think about programming the 6507. However, it is occasionally useful to inspect the program from the Colour Clock level in order to gain a better understanding of the program.
A side-effect of the finer grain quantum is the slower operation of the debugging loop. This is because every check and debugger update happens after every colour clock rather than after every CPU instruction. As such, it's not recommended to run at this level unless necessary.
Another effect of the Colour Clock quantum is how breakpoints, traps and watches are handled. In this quantum a breakpoint of an address will trigger mid instruction, when the PC register is updated. Similarly for watches, the emulation will halt at the instant (the colour clock) the address is accessed.
The TV Screen shows the graphical output of the emulated console. As an option, this window will also show a CRT preview, meaning how the pixels might look though a real CRT TV, as opposed to pixel perfect representation.
This window can also be used to help debug, with the Debug Colours option. When active, this option will cause the pixels to be coloured according to which TIA element caused the pixel to be drawn.
Using the mouse to hover over the screen will show information about the underlying pixel, in a tooltip window.
The overlay selector box allows you to augment the TV screen with a layer of additional information. The WSYNC overlay for instance, makes clear when WSYNC is active.
The final use of the TV Screen window is to rewind (or fast forward) to the moment when the underlying pixel is to be generated. This is uniquely useful for Atari2600 development, I believe, because of the lack of frame buffer - the TV screen is intimately tied to the flow of the the 6507 program.
The Timeline window shows a statistical summary of past frames. For instance, the number of scanlines used by a frame. Precise numbers can be seen by hovering the mouse over the window but very often the graphical representation is enough to glean useful information. For example, an unwavering blue line indicates that the scanline count is consistent from frame to frame - any deviation in the blue line indicates that the scanline count is unstable and may result in screen rolling.
The other use for the Timeline window is to rewind (or fast forward) to previous frames. The TV Screen window can be used to rewind to a specific scanline and colour clock but the Timeline is required to rewind to a specific frame. To rewind, simply click on the window at the point to rewind to.
As an alternative to GUI interaction the debugger can also be controlled through a terminal. This is available through the terminal window. The rest of this section describes the operation of the terminal in detail.
The debugger can also be started in a "headless" mode from the command line. See the -term option.
Help is available with the HELP command. Help on a specific topic is available by specifying a keyword. The list below shows the currently defined keywords. The rest of the section will give a brief run down of debugger features.
[ $f080 cld ] >> help
AUDIO BALL BREAK BUS CARTRIDGE CLEAR
COMPARISON COPROC CPU DISASM DROP DWARF
GOTO GREP HALT HELP INSERT KEYPAD
LAST LIST LOG MEMMAP MEMUSAGE MISSILE
ONHALT ONSTEP ONTRACE PANEL PATCH PEEK
PERIPHERAL PLAYER PLAYFIELD PLUSROM POKE QUANTUM
QUIT RAM RESET REWIND RIOT RUN
SCRIPT STEP STICK SWAP SYMBOL TIA
TRACE TRAP TV WATCH
The debugger allows tab-completion in most situations. For example, pressing W followed by the Tab key on your keyboard, will autocomplete the WATCH command. This works for command arguments too. It does not currently work for filenames, or symbols. Given a choice of completions, the Tab key will cycle through the available options.
Addresses can be specified by decimal or hexadecimal. Hexadecimal addresses can be written 0x80 or $80. The debugger will echo addresses in the first format. Addresses can also be specified by symbol if one is available. The debugger understands the canonical symbol names used in VCS development. For example, WATCH WRITE VBLANK will halt execution whenever VBLANK (including all the mirrors) is written to.
Watches are one of the three facilities that will halt execution of the emulator. The other two are TRAP and BREAK. Both of these commands will halt execution when a "target" changes or meets some condition. An example of a target is the Programmer Counter or the Scanline value. See HELP BREAK and HELP TRAP for more information.
Scripts can be recorded and played back with the SCRIPT command. All commands are available when in script recording mode, except RUN and further SCRIPT RECORD command. Playing back a script while recording a new script is possible.