diff --git a/Changes.txt b/Changes.txt index 9eaac039c..7ffa4daee 100644 --- a/Changes.txt +++ b/Changes.txt @@ -12,11 +12,11 @@ Release History =========================================================================== -3.2.2 to 3.3: (November xx, 2010) +3.2.2 to 3.3: (November 15, 2010) * Added the following Distella 'directives', which are used to override - and specifically tell the debugger how to treat address space (SKIP, - CODE, GFX, PGFX, DATA, ROW). See the debugger documentation for more + and specifically tell the debugger how to treat address space (CODE, + GFX, PGFX, DATA, ROW). See the debugger documentation for more information. * Disassembly from the debugger is now tracked by the emulation core, @@ -45,7 +45,7 @@ * Added the following commands to the debugger prompt: - clearconfig, listconfig, loadconfig, saveconfig (used for Distella configuration files) - - skip, code, data, gfx, pgfx, row + - code, data, gfx, pgfx, row (directives used to override automatic disassembly types) - jump (jumps to a specific address in the disassembly) - type (gives detailed info for disassembly type of an address) @@ -53,9 +53,9 @@ * The debugger prompt commands 'trap', 'trapread' and 'trapwrite' now accept a range of addresses as well as a single address. - * Added 'data source' address output for the CPU A/X/Y registers. This - is useful for quickly seeing what an operand address resolves into - with an LDx command. + * Added 'data source' address output for the CPU SP/A/X/Y registers. + This is useful for quickly seeing what an operand address resolves + into with various load commands. * Many commands in the debugger prompt are now case-insensitive; further improvements will be made in a future release. @@ -71,6 +71,9 @@ * Program counter/instruction addresses can now be toggled in the disassembly. + * Disassembled instructions involving relative branches now show only + one byte for the operand, not two bytes. + * Fixed bug in several text input fields, whereby binary data couldn't be input (a '\' was required, but the character was blocked). @@ -90,7 +93,8 @@ video modes, not just when starting the application. * Added support for building a Windows version compatible with Windows - 98 and 2000 (compiled with Visual Studio 2005). + 98 and 2000 (compiled with Visual Studio 2005). Testing is very + limited, since I no longer have access to these systems. * Fixed build issues for Innosetup in Windows XP. diff --git a/Readme.txt b/Readme.txt index e27c48810..2988e2e35 100644 --- a/Readme.txt +++ b/Readme.txt @@ -9,4 +9,4 @@ the Stella Website at: Enjoy, The Stella Team -November xx, 2010 +November 15, 2010 diff --git a/debian/changelog b/debian/changelog index b1a5a863f..762b9a93e 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,7 +2,7 @@ stella (3.3-1) stable; urgency=high * Version 3.3 release - -- Stephen Anthony Wed, 25 Aug 2010 18:38:25 +0200 + -- Stephen Anthony Mon, 15 Nov 2010 18:38:25 +0200 stella (3.2.1-1) stable; urgency=high diff --git a/docs/debugger.html b/docs/debugger.html index e07b02609..08ddbe362 100644 --- a/docs/debugger.html +++ b/docs/debugger.html @@ -27,7 +27,7 @@ feature that no other 2600 debugger has; it's completely cross-platform.< breakpoints as you want.
  • Conditional breakpoints - Break running program when some arbitrary - condition is true (e.g. "breakif 'a == $7f && c'" will break when the Accumulator value is $7f and the Carry flag is true, no matter where + condition is true (e.g. "breakif {a == $7f && c}" will break when the Accumulator value is $7f and the Carry flag is true, no matter where in the program this happens). Unlike the cond breaks in PCAE, Stella's are *fast*: the emulation will run at full speed unless you use lots of breakif's at the same time, or have a slow CPU.
    • @@ -41,8 +41,22 @@ feature that no other 2600 debugger has; it's completely cross-platform.<
  • Frame advance (automatic breakpoint at beginning of next frame) You can advance multiple frames with one command.
    • -
  • Disassembly from Distella, with support for determining code vs. - data sections.
    • +
  • Supports Distella 'configuration directives', which may be used to + override automatic code/data determination in the disassembly. For now, + the following directives are supported: CODE, GFX, PGFX, DATA, ROW. + These directives can be entered at the debugger prompt, or (automatically) + loaded and saved in configuration files.
    • + +
  • Extensive disassembly support, both from the emulation core and with help + from Distella. Where possible, the disassembly differentiates between code, + player graphics and playfield graphics (ie, addresses stored in GRPx and PFx) + and data (addresses used as an operand of a command). Code sections are also + differentiated between actual code, and 'tentative' code (ie, areas that may + represent code sections, but haven't actually been executed yet). Such + tentative code is marked with a '*' symbol.
    • + +
  • Supports visual representation of the bitmap data of graphics areas, + as well as the ability to directly edit these areas in either hex or binary.
  • Support for DASM symbol files (created with DASM's -s option), including automatically loading symbol files if they're named @@ -68,6 +82,8 @@ feature that no other 2600 debugger has; it's completely cross-platform.< currently selected bank, and manually change banks.
  • Registers/memory that get changed by the CPU during debugging are highlighted when they're displayed.
  • +
  • Data sources for the CPU SP/A/X/Y registers, showing the resolved/source + address of of load operands.
  • Scanline advance (like frame advance, break at beginning of next scanline).
  • TIA display is updated during step/trace, so we can see our @@ -98,8 +114,9 @@ feature that no other 2600 debugger has; it's completely cross-platform.<
  • Possibly support for recording and playing back input files, like MAME. This isn't a debugger feature per se, but it'll make it easier to reliably trigger a bug so you can debug it.
    • +
  • Various new GUI enhancements
    • @@ -415,7 +432,7 @@ if we wanted to use it again.

    "breakif function_name":

    -	function gameReset ' !(*SWCHB & 1 ) '
+	function gameReset { !(*SWCHB & 1 ) }
 	breakif gameReset
    @@ -426,7 +443,7 @@ if the Game Select switch is pressed. We want to break when the user presses both Select and Reset:

    -	breakif ' gameReset && gameSelect '
+	breakif { gameReset && gameSelect }

    User-defined functions appear in "listfunctions", which shows the label @@ -534,7 +551,7 @@ beginning of the 64th scanline.

    (non-bankswitched) ROMs, it will always contain 0. One useful use is:

    -    breakif ' pc==myLabel && _bank==1 '
+    breakif { pc==myLabel && _bank==1 }

    This is similar to setting a regular breakpoint, but it will only trigger @@ -605,11 +622,14 @@ can also get rid of all traps at once with the "cleartraps" command.

    c - Carry Flag: set (0 or 1), or toggle (no arg) cheat - Use a cheat code (see manual for cheat types) clearbreaks - Clear all breakpoints + clearconfig - Clear Distella config directives [bank xx] cleartraps - Clear all traps clearwatches - Clear all watches cls - Clear prompt area of text and erase history + code - Mark 'CODE' range in disassembly colortest - Show value xx as TIA color d - Decimal Flag: set (0 or 1), or toggle (no arg) + data - Mark 'DATA' range in disassembly define - Define label xx for address yy delbreakif - Delete conditional breakif xx delfunction - Delete function with label xx @@ -619,25 +639,32 @@ can also get rid of all traps at once with the "cleartraps" command.

    exec - Execute script file xx frame - Advance emulation by xx frames (default=1) function - Define function name xx for expression yy + gfx - Mark 'CFX' range in disassembly help - This cruft + jump - Scroll disassembly to address xx listbreaks - List breakpoints + listconfig - List Distella config directives [bank xx] listfunctions - List user-defined functions listtraps - List traps + loadconfig - Load Distella config file [from file xx] loadstate - Load emulator state xx (0-9) loadsym - Load symbol file named xx n - Negative Flag: set (0 or 1), or toggle (no arg) pc - Set Program Counter to address xx + pgfx - Mark 'PGFX' range in disassembly print - Evaluate/print expression xx in hex/dec/binary ram - Show ZP RAM, or set address xx to yy1 [yy2 ...] reset - Reset 6507 to init vector (excluding TIA/RIOT) rewind - Rewind state to last step/trace/scanline/frame riot - Show RIOT timer/input status rom - Set ROM address xx to yy1 [yy2 ...] + row - Mark 'ROW' range in disassembly run - Exit debugger, return to emulator runto - Run until string xx in disassembly runtopc - Run until PC is set to value xx s - Set Stack Pointer to value xx save - Save breaks, watches, traps to file xx + saveconfig - Save Distella config file [to file xx] saverom - Save (possibly patched) ROM to file xx saveses - Save console session to file xx savestate - Save emulator state xx (valid args 0-9) @@ -645,9 +672,10 @@ listfunctions - List user-defined functions step - Single step CPU [with count xx] tia - Show TIA state (NOT FINISHED YET) trace - Single step CPU over subroutines [with count xx] - trap - Trap read and write accesses to address xx - trapread - Trap read accesses to address xx - trapwrite - Trap write accesses to address xx + trap - Trap read/write access to address(es) xx [to yy] + trapread - Trap read access to address(es) xx [to yy] + trapwrite - Trap write access to address(es) xx [to yy] + type - Show disassembly type for address xx [to yy] undef - Undefine label xx (if defined) v - Overflow Flag: set (0 or 1), or toggle (no arg) watch - Print contents of address xx before every prompt @@ -827,6 +855,11 @@ Selected registers here can also be changed by using the "Data Operations" butto further described in (J). All items are shown in hex. Any label defined for the current PC value is shown to the right. Decimal and binary equivalents are shown for SP/A/X/Y to the right (first decimal, then binary).

    +

    The column to the far right shows the 'source' of contents of the respective +registers. For example, consider the command 'LDA ($80),Y'. The operand of +the command resolves to some address, which isn't always easy to determine at +first glance. The 'Src Addr' area shows the actual resulting operand/address +being used with the given opcode.

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

    @@ -929,6 +962,22 @@ decreased by 1:

    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.

    +

    The disassembly is often quite extensive, and whenever possible tries to automatically +differentiate between code, graphics, data and unused bytes. There are actually two +levels of disassembly in Stella. First, the emulation core tracks accesses as a game +is running, making for very accurate results. This is known as a dynamic analysis. +Second, the built-in Distella code does a static analysis, which tentatively fills +in sections that the dynamic disassembler missed (usually because the addresses haven't +been accessed at runtime yet).

    +

    As such, code can be marked in two ways (absolute, when done by the emulation core), +and tentative (when done by Distella, and the emulation core hasn't accessed it yet). +Such 'tentative' code is marked with the '*' symbol, indicating that it has the potential +to be accessed as code sometime during the program run. This gives very useful information, +since it can indicate areas toggled by an option in the game (ie, when a player dies, +when difficulty level changes, etc). It can also indicate whether blocks of code after +a relative jump are in fact code, or simply data.

    + +

    The top area contains two items: @@ -947,7 +996,9 @@ If set to 'Never', the entire address space is treated as code. If set to The 'Automatic' setting is a combination of the previous two. First, an attempt is made to resolve data sections. If this results in the current program counter not being present in the disassembly, then a second disassembly is -done, without resolving data sections. +done, without resolving data sections. Note that this option applies only to +addresses determined by Distella; addresses marked as code or graphics by the +emulation core will stay as such, no matter what this setting says.

    Each line of disassembly has four fields:

    @@ -962,16 +1013,37 @@ by the "break" command, not the conditional "breakif" breakpoints Counter isn't necessarily involved).
  • Labels: Any labels assigned to the given address, either generated automatically by Distella, read from a DASM symbol file or custom -labels created by the user.
    • -
  • Instruction: This is a standard 6502 mnemonic (possibly with operand). -This field also contains the cycle count for the instruction (separated by a -semicolon).
    • -
  • Hex bytes: These are the raw machine code bytes for the instruction. -Note that only instructions that have been fully disassembled will have -bytes in this field.
    • +labels created by the user. If 'PC addresses' is enabled, the address will +be shown in grey. +
  • Disassembled bytes: This is either a standard 6502 mnemonic (possibly with operand), +or information about graphics and/or data. For instructions, the cycle count will be +included, separated by a semicolon. For graphics, a bitmap of the data, and the address +of the data is included. For actual data, only the address is included.
    • +
  • Hex bytes: These are the raw machine bytes for the code/graphics/data. +Note that only code, graphics or data will show bytes and can be edited.
    • -

    The 6502 mnemonic will be UPPERCASE for all standard instructions, +

    At this point, we should explain the various 'types' that the disassembler +can use. These are known as 'directives', and partly correspond to configuration +options from the standalone Distella program. They are listed in order of +decreasing hierarchy:

    + + + + + + +
    CODEAddresses which have appeared in the program counter, or +which tentatively can appear in the program counter. These can be edited in hex.
    GFXAddresses which contain data stored in the player graphics registers +(GRP0/GRP1). These addresses are shown with a bitmap of the graphics, which +can be edited in either hex or binary. The bitmap is shown as large blocks.
    PGFXAddresses which contain data stored in the playfield graphics registers +(PF0/PF1/PF2). These addresses are shown with a bitmap of the graphics, which +can be edited in either hex or binary. The bitmap is shown as small dashes.
    DATAAddresses used as an operand for some opcode.. These can be edited +in hex.
    ROWAddresses not used as any of the above. These are shown up +to 16 per line, and cannot be edited.
    + + +

    For code sections, the 6502 mnemonic will be UPPERCASE for all standard instructions, or lowercase for "illegal" 6502 instructions (like "dcp"). If resolving of data sections has been disabled for any reason, you'll likely see a lot of illegal opcodes if you scroll to a data table in ROM. This can also @@ -999,7 +1071,7 @@ bytes in the ROM Widget are editable. Double-click on them to edit them. When you're done, press Enter to accept the changes (in which case the cart will be re-disasembled) or Escape to cancel them. Note that only instructions that have been fully disassembled -can be edited. In particular, blank lines or lines with '.byte' directives +can be edited. In particular, blank lines or 'ROW' directives cannot be edited. If you wish to edit the latter, then the 'Resolve data' item should be set to 'Never' first. Also note that certain ROMs can have sections of address space swapped in and out dynamically. As such, changing @@ -1023,6 +1095,15 @@ disassembly line where the mouse was clicked.

  • RunTo PC: Single-step through code until the Program Counter matches the address of the disassembly line where the mouse was clicked.
    • + +
  • Toggle PC addresses: Show or hide blank labels as Program Counter +addresses.
    • + +
  • Toggle GFX binary/hex: Switch between editing GFX and PGFX sections +in either hexidecimal or binary.
    • + +
  • Re-disassemble: Self-explanatory; force the current bank to be +disassembled, regardless of whether anything has changed.

    • Limitations

    @@ -1072,6 +1153,56 @@ can update them just by re-running the relevant commands in the prompt.

    anywhere in the GUI via the keyboard, with Alt-S, Alt-T, Alt-L, Alt-F and Alt-R.

    + +
    +

    Distella Configuration Files

    +

    As mentioned in ROM Listing (M), Stella supports the following directives: +CODE/GFX/PGFX/DATA/ROW. While the debugger will try to automatically mark address +space with the appropriate directive, there are times when it will fail. There are +several options in this case:

    +
      +
    1. Manually set the directives: Directives can be set in the debugger +prompt with the code/gfx/pgfx/data/row commands. These accept an address range +for the given directive type. Setting a range with the same type a second time +will remove that directive from the range.
      2. +
    2. Use configuration files: Configuration files can be used to automatically +load a list of directives when a ROM is loaded. These files can be generated with the +'saveconfig' command, and loaded with the 'loadconfig' command. There are also +'listconfig' and 'clearconfig' commands to show and erase (respectively) the current +directive listing. Upon opening the debugger for the first time, Stella attempts +to load a configuration file from several places. For this example, assume a ROM +named "rr.a26", with properties entry "River Raid". Attempts will be made as follows: +
        +
      • ROM dir based on properties entry name: River Raid.cfg
        • +
      • ROM dir based on actual ROM name: rr.cfg
        • +
      • CFG dir based on properties entry name: configdir/River Raid.cfg
        • +
      +

      The location of 'configdir' will depend on the version of Stella, as follows:

      + +

      + + + + + + + + + + + + +
      Linux/Unix~/.stella/cfg/
      Macintosh~/Library/Application Support/Stella/cfg/
      Windows%APPDATA%\Stella\cfg\    + OR
      + _BASEDIR_\cfg\ + (if a file named 'basedir.txt' exists in the application + directory containing the full pathname for _BASEDIR_) +
      + +

      3. +
    + +

    Tutorial: How to hack a ROM

    diff --git a/docs/graphics/debugger_cpuregs.png b/docs/graphics/debugger_cpuregs.png index ea2f588ff..a8bd87e37 100644 Binary files a/docs/graphics/debugger_cpuregs.png and b/docs/graphics/debugger_cpuregs.png differ diff --git a/docs/graphics/debugger_main.png b/docs/graphics/debugger_main.png index 20f897e42..2aa7f9304 100644 Binary files a/docs/graphics/debugger_main.png and b/docs/graphics/debugger_main.png differ diff --git a/docs/graphics/debugger_rom.png b/docs/graphics/debugger_rom.png index 79bebe268..862c05ff5 100644 Binary files a/docs/graphics/debugger_rom.png and b/docs/graphics/debugger_rom.png differ diff --git a/docs/graphics/debugger_romcmenu.png b/docs/graphics/debugger_romcmenu.png index 566eafffa..6003a9fb7 100644 Binary files a/docs/graphics/debugger_romcmenu.png and b/docs/graphics/debugger_romcmenu.png differ diff --git a/docs/index.html b/docs/index.html index 31b5c599a..d74835209 100644 --- a/docs/index.html +++ b/docs/index.html @@ -52,7 +52,7 @@


    -
    February 1999 - August 2010
    +
    February 1999 - November 2010
    The Stella Team
    Stella Homepage
    @@ -258,7 +258,7 @@
  • Emulates CX-22 / CX-80 style trackballs and Amiga Mouse using your computer's mouse
  • Support for real Atari 2600 controllers using the - Stelladaptor
    • + Stelladaptor
  • Support for the speech portion of a real AtariVox device connected to your PC using a USB adaptor
    • @@ -1937,7 +1937,7 @@ 
    -statedir <dir>
    - Set the directory in which to save state files. + Set the directory in which to access state files. @@ -1957,7 +1957,12 @@ 
    -eepromdir <dir>
    - Set the directory in which to save EEPROM files. + Set the directory in which to access EEPROM files. + + + + 
    -cfgdir <dir>
    + Set the directory in which to access Distella config files. @@ -2504,7 +2509,7 @@

    Stella supports real Atari 2600 joysticks, paddles and driving controllers - using the Stelladaptor device.

    + using the Stelladaptor device.

    Stella can use up to two Stelladaptors; any extra ones are ignored. Stelladaptor devices will be automatically detected and configured. Devices diff --git a/src/debugger/CartDebug.cxx b/src/debugger/CartDebug.cxx index 9481621a0..4b4ab396f 100644 --- a/src/debugger/CartDebug.cxx +++ b/src/debugger/CartDebug.cxx @@ -737,13 +737,14 @@ string CartDebug::loadConfigFile(string file) buf >> directive; if(BSPF_startsWithIgnoreCase(directive, "ORG")) { + // TODO - figure out what to do with this buf >> hex >> start; -// TODO - figure out what to do with this } else if(BSPF_startsWithIgnoreCase(directive, "SKIP")) { + // For now, treat this as CODE buf >> hex >> start >> hex >> end; -// addDirective(CartDebug::SKIP, start, end, currentbank); + addDirective(CartDebug::CODE, start, end, currentbank); } else if(BSPF_startsWithIgnoreCase(directive, "CODE")) { diff --git a/src/macosx/Info-Stella.plist b/src/macosx/Info-Stella.plist index 148c63f84..aa1713f05 100644 --- a/src/macosx/Info-Stella.plist +++ b/src/macosx/Info-Stella.plist @@ -53,7 +53,7 @@ CFBundleSignature StLa CFBundleVersion - 3.2.1 + 3.3 NSMainNibFile SDLMain.nib NSPrincipalClass diff --git a/src/unix/stella.SlackBuild b/src/unix/stella.SlackBuild index 847221769..cbbeac76c 100644 --- a/src/unix/stella.SlackBuild +++ b/src/unix/stella.SlackBuild @@ -13,7 +13,7 @@ die() { exit 1 } -VERSION=3.2.1 +VERSION=3.3 ARCH=${ARCH-i486} BUILD=1 diff --git a/src/unix/stella.spec b/src/unix/stella.spec index 0205b5c2d..1e21d5b9d 100644 --- a/src/unix/stella.spec +++ b/src/unix/stella.spec @@ -1,5 +1,5 @@ %define name stella -%define version 3.2.1 +%define version 3.3 %define rel 1 %define enable_gl 1 @@ -108,6 +108,9 @@ rm -rf $RPM_BUILD_DIR/%{name}-%{version} %_datadir/icons/large/%{name}.png %changelog +* Mon Nov 15 2010 Stephen Anthony 3.3-1 +- Version 3.3 release + * Wed Aug 25 2010 Stephen Anthony 3.2.1-1 - Version 3.2.1 release diff --git a/src/win32/stella.rc b/src/win32/stella.rc index 029fb763a..31b805bf9 100755 --- a/src/win32/stella.rc +++ b/src/win32/stella.rc @@ -36,8 +36,8 @@ IDI_ICON ICON "stella.ico" // VS_VERSION_INFO VERSIONINFO - FILEVERSION 3,2,1,0 - PRODUCTVERSION 3,2,1,0 + FILEVERSION 3,3,0,0 + PRODUCTVERSION 3,3,0,0 FILEFLAGSMASK 0x3fL #ifdef _DEBUG FILEFLAGS 0x1L @@ -55,12 +55,12 @@ BEGIN VALUE "Comments", "The multi-platform Atari 2600 emulator. Stella is released under the GPLv2." VALUE "CompanyName", "The Stella Team (http://stella.sourceforge.net)" VALUE "FileDescription", "Stella" - VALUE "FileVersion", "3.2.1" + VALUE "FileVersion", "3.3" VALUE "InternalName", "Stella" VALUE "LegalCopyright", "Copyright (C) 1995-2010 The Stella Team" VALUE "OriginalFilename", "Stella.exe" VALUE "ProductName", "Stella" - VALUE "ProductVersion", "3.2.1" + VALUE "ProductVersion", "3.3" END END BLOCK "VarFileInfo"