From 1341f07a36fb0491878bf4e08c04d3cc33536829 Mon Sep 17 00:00:00 2001 From: thrust26 Date: Sat, 2 Dec 2017 11:34:58 +0100 Subject: [PATCH] trap doc updated double spaces after . removed --- docs/debugger.html | 214 +++++++++++++------------ docs/index.html | 390 ++++++++++++++++++++++----------------------- 2 files changed, 303 insertions(+), 301 deletions(-) diff --git a/docs/debugger.html b/docs/debugger.html index fdaf8d96e..ce6ae0861 100644 --- a/docs/debugger.html +++ b/docs/debugger.html @@ -7,7 +7,7 @@

Stella Integrated Debugger (a work in progress)

The debugger in Stella may never be complete, as we're constantly -adding new features requested by homebrew developers. However, even in its +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.

@@ -42,17 +42,17 @@ feature that no other 2600 debugger has; it's completely cross-platform.< You can advance multiple frames with one command.
  • Supports Distella 'configuration directives', which may be used to - override automatic code/data determination in the disassembly. For now, + 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, + 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 + 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 + 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, @@ -142,9 +142,9 @@ 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 +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 +respectively. Pressing Tab cycles between widgets in the current tab (except for in the Prompt area, 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': @@ -164,7 +164,7 @@ for in the Prompt area, where 'tab' is used for something else).

    frame (scanline 262, for NTSC games). 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 +(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.

    @@ -209,11 +209,11 @@ Bash-style commands are also supported:

    Shift-HomeScroll to beginning of commands Shift-EndScroll to end of commands -

    You can also scroll with the mouse. Copy and paste is not yet supported.

    +

    You can also scroll with the mouse. Copy and paste is not yet supported.

    -

    To see the available commands, enter "help". For extended help, type "help cmd", -where 'cmd' is the command you wish to know about. The available commands are listed -at the end of this section. Bash-style tab completion is supported for commands, +

    To see the available commands, enter "help". For extended help, type "help cmd", +where 'cmd' is the command you wish to know about. The available commands are listed +at the end of this section. Bash-style tab completion is supported for commands, labels and functions (see below).

    For now, there are some functions that only exist in the prompt. We @@ -427,7 +427,7 @@ end of a frame. This is different from how a real 2600 works, but most ROMs only check for input once per frame anyway.

    Conditional breaks appear in "listbreaks", numbered starting from -zero. You can remove a cond-break with "delbreakif number", where +zero. You can remove a cond-break with "delbreakif number", where the number comes from "listbreaks" or by entering the same conditional break again.

    Any time the debugger is entered due to a trap, breakpoint, or @@ -460,7 +460,7 @@ presses both Select and Reset:

    User-defined functions appear in "listfunctions", which shows the label -and expression for each function. Functions can be removed with +and expression for each function. Functions can be removed with "delfunction label", where the labels come from "listfunctions".

    If you've defined a lot of complex functions, you probably will @@ -494,14 +494,14 @@ of this file will depend on the version of Stella, as follows:

    Note that these '.stella' script files are only accessed if you enter -the debugger at least once during a program run. This means you can create +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.

    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 +command. These allow you to break and enter the debugger on various conditions without having to define the conditions yourself.

    Built-in functions and pseudo-registers always start with an _ @@ -538,7 +538,7 @@ will show you a list of them.

    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 -a real system. For example, while the debugger keeps track of the number +a real system. For example, while the debugger keeps track of the number of scanlines in a frame, a real system would not (there is no register that holds 'number of scanlines' on an actual console).

    @@ -603,8 +603,8 @@ or memory.

    Traps can also combined with a condition ("trapif"). If an access to a memory address is caught, the condition is evaluated additionally. -Only if the condition is true too, the emulations stops. -

    +Only if the condition is true too, the emulations stops. For details +about conditions see Conditional Breaks described above.

    An example: you are debugging a game, and you want to stop the emulation and enter the debugger whenever RESP0 is strobed. You'd use @@ -619,17 +619,18 @@ that triggered the trap. The reason for this is simple: until the instruction is executed, the emulator can't know it's going to hit a trap. After the trap is hit, the instruction is done executing, and whatever effects it may have had on e.g. the TIA state have already -happened... but we don't have a way to run the emulated VCS in reverse, +happened... but we don't have a way to run the emulated VCS in reverse, so the best we can do is stop before the next instruction runs.

    Traps come in two varieties: read access traps and write access traps. It is possible to set both types of trap on the same address (that's what the plain "trap" command does). To set a read or write only trap, -use "trapread(if)" or "trapwrite(if)". To remove a trap, you just attempt -to set it again: the commands actually toggle the trap on & off. You -can also get rid of all traps at once with the "cleartraps" command.

    +use "trapread(if)" or "trapwrite(if)". -

    Use "listtraps" to see all enabled traps.

    +

    All traps appear in "listtraps", numbered starting from zero. You +can remove a trap with "deltrap number", where the number comes from +"listtraps" or by entering the identical trap again. You can get rid of +all traps at once with the "cleartraps" command.

    Prompt commands:

    @@ -658,6 +659,7 @@ clearsavestateifs - Clear all savestate points delbreakif - Delete conditional breakif <xx> delfunction - Delete function with label xx delsavestateif - Delete conditional savestate point <xx> + deltrap - Delete trap <xx> delwatch - Delete watch <xx> disasm - Disassemble address xx [yy lines] (default=PC) dump - Dump data at address <xx> [to yy] [0..7, dumps to file] @@ -743,7 +745,7 @@ clearsavestateifs - Clear all savestate points developer.

    Many of the variables inside the TIA can only be written to by the -6502. The debugger lets you get inside the TIA and see the contents +6502. The debugger lets you get inside the TIA and see the contents of these variables. These include the color registers, player/missile graphics and positions, and the playfield.

    @@ -794,10 +796,10 @@ in another part of the debugger).

    As with the TIA tab, most of the values here will be self-explanatory to a 2600 -developer, and almost all can be modified. However, the SWCHx registers need +developer, and almost all can be modified. However, the SWCHx registers need further explanation:

    -

    SWCHx(W) can be modified; here, the (W) stands for write. Similarly, -SWACNT/SWBCNT can be directly modified. However, the results of reading back from +

    SWCHx(W) can be modified; here, the (W) stands for write. Similarly, +SWACNT/SWBCNT can be directly modified. However, the results of reading back from the SWCHx register are influenced by SWACNT/SWBCNT, and SWCHx(R) is a read-only display reflecting this result.

    @@ -822,7 +824,7 @@ volume resulting from the two channel volumes.

    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' +white) filling the rest of the display. Note that if 'phosphor mode' or TV effects are enabled, you won't see the effects here; this shows the raw TIA image only.

    @@ -837,13 +839,13 @@ as illustrated:

  • Fill to scanline: If you've already started a partial frame draw (ie, the frame is already partially 'greyed' out), selecting this option will draw all scanlines up to the vertical position where the - mouse was clicked. Note that if you weren't in partial-frame mode, + mouse was clicked. Note that if you weren't in partial-frame mode, this option will have no effect.
  • Toggle breakpoint: Will toggle a conditional breakpoint at the scanline where the mouse was clicked. You can to use the Prompt Tab to turn the breakpoint off again.
  • Set zoom position: Influences what is shown in the TIA - zoom area (further described in part (G). The zoom area will + zoom area (further described in part (G). The zoom area will contain the area centered at the position where the mouse was clicked.
  • Save snapshot: Saves the TIA image currently shown, @@ -884,9 +886,9 @@ Position, and will range from 0 to 228).

    • (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 +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 +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, @@ -894,7 +896,7 @@ 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 +PageUp/Dn and Home/End keys. You can also select the zoom position from a context menu in the TIA Display.

    @@ -904,7 +906,7 @@ a context menu in the TIA Display.

    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, +

    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.

    @@ -918,13 +920,13 @@ See the "Breakpoints" section for details.

    All the registers and flags are displayed, and can be changed by double-clicking on them (to the left). Flags are toggled on double-click. Selected registers here can also be changed by using the "Data Operations" buttons, -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 +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 +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 +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 @@ -938,8 +940,8 @@ learn :)

    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.

    +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].
@@ -963,13 +965,13 @@ of the 2600's zero-page RAM.
    
 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.  The currently selected RAM cell
+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 'Revert' button is
-more comprehensive.  It will undo all operations on all cells
+undo the most previous operation to one cell only. The 'Revert' 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),
@@ -985,19 +987,19 @@ 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).
-All matching values will be highlighted in the RAM widget.  If 'Search' is clicked
+All matching values will be highlighted in the RAM widget. If 'Search' is clicked
 and the input is empty, all RAM locations are highlighted.
    
 
 
    The 'Compare' button is used to compare the given value using all
-addresses currently highlighted.  This may be an absolute number (such as 2),
-or a comparative number (such as -1).  Using a '+' or '-' operator
+addresses currently highlighted. This may be an absolute number (such as 2),
+or a comparative number (such as -1). Using a '+' or '-' operator
 means 'search addresses for values that have changed by that amount'.
    
 
    The 'Reset' 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:
    
 
      
-	
    • Click 'Search' with empty input.  All address/values are highlighted
      • 
+	
    • Click 'Search' with empty input. All address/values are highlighted
      • 
 	
    • Exit debugger mode and lose a life, let your energy decrease, or
 		do whatever it is you're trying to debug
      • 
 	
    • Enter debugger mode again, click 'Compare' and and enter a '-1' for input.
@@ -1014,28 +1016,28 @@ decreased by 1:
      
 
      
 
      (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.
      
+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.
+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,
+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
+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 "Bank state" is self-explanatory, and shows a summary of the current
-bank information.  For normal bankswitched ROMs, this will be the current bank number,
-however more advanced schemes will show other types of information here.  More detailed
+bank information. For normal bankswitched ROMs, this will be the current bank number,
+however more advanced schemes will show other types of information here. More detailed
 information is available in Detailed Bankswitch Information (N).
      
 
 
      Each line of disassembly has four fields:
      
@@ -1050,32 +1052,32 @@ 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.  If 'PC addresses' is enabled, the address will
+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.
      • 
+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.
      • 
 
    
 
 
    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
+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:
    +which tentatively can appear in the program counter. These can be edited in hex. +(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. - + -
    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 +(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 +
    ROWAddresses not used as any of the above. These are shown up to 8 per line, and cannot be edited.
    @@ -1083,7 +1085,7 @@ to 8 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 automatic resolving of code 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 +of illegal opcodes if you scroll to a data table in ROM. This can also occur if the disassembler hasn't yet encountered addresses in the PC. If you step/trace/scanline/frame advance into such an area, the disassembler will make note of it, and disassemble it correctly from that point on.

    @@ -1103,17 +1105,17 @@ or Scanline advance, or manually setting the PC), the disassembly will scroll to the current PC location.

    Even though ROM is supposed to be Read Only Memory, this is an -emulator: you can change ROM all you want within the debugger. The hex +emulator: you can change ROM all you want within the debugger. The hex 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 'ROW' directives -cannot be edited. Also note that certain ROMs can have -sections of address space swapped in and out dynamically. As such, changing +can be edited. In particular, blank lines or 'ROW' directives +cannot be edited. Also note that certain ROMs can have +sections of address space swapped in and out dynamically. As such, changing the contents of a certain address will change the area pointed to at -that time. In particular, modifying an address that points to internal -RAM will change the RAM, not the underlying ROM. A future release may +that time. In particular, modifying an address that points to internal +RAM will change the RAM, not the underlying ROM. A future release may graphically differentiate between RAM and ROM areas.

    The ROM Disassembly also contains a Settings dialog, accessible by right-clicking @@ -1149,14 +1151,14 @@ in either binary or hexidecimal.

  • The ROM Widget only works on ROM or zero-page RAM separately. If your game runs code from zero-page RAM, the disassembly will show addresses $80 to $FF (zero-page -RAM address space) only. Once your RAM routine returns, the ROM Widget will switch -back to ROM space ($1000 - $1FFF and mirrors). The same is true of the "disasm" +RAM address space) only. Once your RAM routine returns, the ROM Widget will switch +back to ROM space ($1000 - $1FFF and mirrors). The same is true of the "disasm" command; it will show either ROM or RAM space, not both at the same time.
  • The standard VCS memory map has the cartridge port at locations -$F000-$FFFF. However, not all the address lines exist on a 6507, so +$F000-$FFFF. However, not all the address lines exist on a 6507, so the cartridge port is "mirrored" at every other 4K chunk of address -space ($1000, $3000, up to $D000). Some developers find it easier +space ($1000, $3000, up to $D000). Some developers find it easier to think of the different banks of ROM as being at different addresses (such as: Bank 0 at $D000 and bank 1 at $F000). When such a ROM runs, the Program Counter can point to one of the mirrors instead of the main @@ -1175,7 +1177,7 @@ the same address.

    • (N) Detailed Bankswitch Information

    -

    This area shows a detailed breakdown of the bankswitching scheme. Since +

    This area shows a detailed breakdown of the bankswitching scheme. Since the bankswitch schemes can greatly vary in operation, this tab will be different for each scheme, but its specific functionality should be self-explanatory. An example of both 4K (non-bankswitched) and DPC (Pitfall II) is as follows:

    @@ -1192,22 +1194,22 @@ Go ahead and try to change something!

    (O) Detailed Cartridge extended RAM Information

    If applicable, this area shows a detailed breakdown of any extra RAM supported by -the bankswitching scheme. Since the bankswitch schemes can greatly vary in operation, +the bankswitching scheme. Since the bankswitch schemes can greatly vary in operation, this tab will be different for each scheme, but its specific functionality should be -self-explanatory. An example of both F8SC (8K Atari + ram) and DPC (Pitfall II) is +self-explanatory. An example of both F8SC (8K Atari + ram) and DPC (Pitfall II) is as follows:

    The RAM is shown in a grid similar to how zero-page RAM is shown in M6532/RIOT RAM -(K) and (L). See those sections for a description of usage. +(K) and (L). See those sections for a description of usage.

    In the cases where RAM is always mapped into the same place in the cartridge -address space (such as Sara-chip), the RAM addresses are labeled as such. In other +address space (such as Sara-chip), the RAM addresses are labeled as such. In other cases, such as when the RAM is either quiescent (and mapped in at different places), or not viewable by the 6507 at all, the RAM addresses are labeled as the cart sees them. -In the examples above, F8SC RAM is labeled starting at its read port, or $F080. However, +In the examples above, F8SC RAM is labeled starting at its read port, or $F080. However, the RAM in the DPC scheme is not viewable by the 6507, so its addresses start from $0. @@ -1239,21 +1241,21 @@ Control-R and Control-Shift-R.


    Distella Configuration Files

    As mentioned in ROM Disassembly (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 +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 +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. 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 +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: +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
        • @@ -1307,15 +1309,15 @@ but it helps to know at least a little about 6502 programming.

        symbols at the bottom of the screen).
      • Enter the debugger by pressing the ` (backquote) key. Don't get - killed before you do this, though. You should still have all 5 lives.
        • + killed before you do this, though. You should still have all 5 lives.
      • In the RAM display, click the "Search" button and enter "5" for input. This searches RAM for your value and highlights all addresses that match - the input. You should see two addresses highlighted: "00a5" and "00ba". + the input. You should see two addresses highlighted: "00a5" and "00ba". These are the only two addresses that currently have the value 5, so they're the most likely candidates for "number of lives" counter. (However, some games might actually store one less than the real number of lives, or - one more, so you might have to experiment a bit. Since this is a "rigged + one more, so you might have to experiment a bit. Since this is a "rigged demo", I already know Battlezone stores the actual number of lives. Most games do, actually).
        • @@ -1325,9 +1327,9 @@ but it helps to know at least a little about 6502 programming.

      • Get killed! Ram an enemy tank, or let him shoot you. Wait for the explosion to finish. You will now have 4 lives.
        • -
      • Enter the debugger again. Click the "Compare" button in RAM widget and enter - a value of 4. Now the RAM widget should only show one highlighted address: - "00ba". What we did was search within our previous results (the ones that +
      • Enter the debugger again. Click the "Compare" button in RAM widget and enter + a value of 4. Now the RAM widget should only show one highlighted address: + "00ba". What we did was search within our previous results (the ones that were 5 before) for the new value 4. Address $00ba used to have the value 5, but now it has 4. This means that Battlezone (almost certainly) stores the current number of lives at address $00ba.
        • @@ -1355,9 +1357,9 @@ but it helps to know at least a little about 6502 programming.

        Program Counter pointing to the instruction *after* the one that wrote to location $ba. -
      • Once in the debugger, look at the ROM display. The PC should be at address +
      • Once in the debugger, look at the ROM display. The PC should be at address $f238, instruction "LDA $e1". You want to examine a few instructions before - the PC, so scroll up using the mouse or arrow keys. Do you see + the PC, so scroll up using the mouse or arrow keys. Do you see the one that affects the lives counter? That's right, it's the "DEC $ba" at location $f236.
        • @@ -1382,9 +1384,9 @@ but it helps to know at least a little about 6502 programming.

            $ea $ea
        -

        Select the line at address $f236 and enter 'ROM patch' mode. This is done - by either double-clicking the line, or pressing enter. Then delete the bytes - with backspace key and enter "ea ea". Another way to do this would have been +

        Select the line at address $f236 and enter 'ROM patch' mode. This is done + by either double-clicking the line, or pressing enter. Then delete the bytes + with backspace key and enter "ea ea". Another way to do this would have been to enter "rom $f236 $ea $ea" in the Prompt widget. diff --git a/docs/index.html b/docs/index.html index 4016d5652..05836b070 100644 --- a/docs/index.html +++ b/docs/index.html @@ -232,8 +232,8 @@ developed for Linux by Bradford W. Mott, it is now maintained by Stephen Anthony. Stella allows you to enjoy all of your favorite 2600 games once again by emulating the 2600's hardware with - software. Stella is written in C++, which allows it to be ported to other - operating systems and architectures. Since its original release Stella has + software. Stella is written in C++, which allows it to be ported to other + operating systems and architectures. Since its original release Stella has been ported to AcornOS, AmigaOS, DOS, FreeBSD, Linux, MacOS, OpenStep, OS/2, Unix, and Windows, as well as consoles such as Sega Dreamcast, GP2X, Nintendo DS and Playstation Portable (among others). @@ -371,8 +371,8 @@

        Other

        Stella is extremely portable, and in its lifetime has been ported to almost every - platform where the SDL library exists. It is 32/64-bit and endian clean in Linux/Unix, MacOSX - and Windows. The Stella Team is interested in hearing about any problems you may + platform where the SDL library exists. It is 32/64-bit and endian clean in Linux/Unix, MacOSX + and Windows. The Stella Team is interested in hearing about any problems you may encounter with diverse operating systems and CPU types.

        @@ -380,8 +380,8 @@

        2. Installation

        -

        Stella is distributed in both source and binary form. In general, you should always - download and install the appropriate binary version. Compiling from source is only +

        Stella is distributed in both source and binary form. In general, you should always + download and install the appropriate binary version. Compiling from source is only recommended for developers, or if the binary version doesn't work for some reason. Once you have a Stella distribution you should follow the instructions for your operating system given below.

        @@ -458,15 +458,15 @@

        Cartridges

        -

        Most games for the Atari 2600 came on cartridges. A cartridge usually +

        Most games for the Atari 2600 came on cartridges. A cartridge usually consists of a single Read Only Memory (ROM) chip which contains the data and - code for the game. Plugging a cartridge into the Atari 2600 allows the 2600's + code for the game. Plugging a cartridge into the Atari 2600 allows the 2600's microprocessor to access the program stored on the cartridge.

        In a similar way you must "plug" a copy of a cartridge into Stella when you - want to play it. Having a ROM image / BIN file, of the cartridge allows you to - do this. A ROM image is a file, which contains the actual data and code read - from the cartridge. There are several ways to obtain a ROM image of a + want to play it. Having a ROM image / BIN file, of the cartridge allows you to + do this. A ROM image is a file, which contains the actual data and code read + from the cartridge. There are several ways to obtain a ROM image of a cartridge:

          @@ -492,19 +492,19 @@

          Supercharger games were not stored on cartridges instead they were stored on cassette tapes. The Supercharger, which plugged into the Atari 2600's cartridge slot, loaded games into its 6K of Random Access Memory (RAM) using a - standard audio cassette player. The Supercharger also supported multi-loading, + standard audio cassette player. The Supercharger also supported multi-loading, which allowed games to be broken into several segments and loaded at different - times. This was useful for large games which had distinct parts such as role + times. This was useful for large games which had distinct parts such as role playing games.

          Most of the available Supercharger ROM images are stored in 8448 bytes files. However, ROM images of multi-load games are sometimes stored in a set of 8448 byte files. The names of these files have a two character sequence number in - them which indicates what load they are. The sequence starts with zero, skips + them which indicates what load they are. The sequence starts with zero, skips a few numbers and then increments by one.

          Stella supports multi-load games, however, the set of ROM images must be - combined into a single ROM image file. For example to create a multi-load ROM + combined into a single ROM image file. For example to create a multi-load ROM image file for Survival Island you would do the following under Unix: 

             % cat survivl0.bin survivl6.bin survivl7.bin > survivl.bin
          @@ -534,7 +534,7 @@

          Integrated GUI

          -

          Stella contains an integrated GUI for all ports. Commandline support is also +

          Stella contains an integrated GUI for all ports. Commandline support is also available for those who want to use it.

          If you start Stella and do not specify a ROM image, it will start in @@ -542,21 +542,21 @@

          If this is your first time starting Stella, you will be asked to select the - default ROM directory to use. This is where you have all your ROMs, - collected as described in the previous section. Several dialogs will be shown, similar + default ROM directory to use. This is where you have all your ROMs, + collected as described in the previous section. Several dialogs will be shown, similar to the following:

             

          -

          The browser should be self-explanatory. The 'Go Up' button moves to the parent +

          The browser should be self-explanatory. The 'Go Up' button moves to the parent folder (if it exists), and the 'Base Dir' button moves to the base directory where, - by default, all Stella-related files are stored. Double-clicking an item will - enter that directory. Click 'Choose' to select the location, or 'Cancel' to exit - the browser. Note that if you don't select a ROM directory now, you will be prompted + by default, all Stella-related files are stored. Double-clicking an item will + enter that directory. Click 'Choose' to select the location, or 'Cancel' to exit + the browser. Note that if you don't select a ROM directory now, you will be prompted again the next time Stella is started.

          At this point, you may want to set the locations for snapshots and other - external paths. This is described in more detail in + external paths. This is described in more detail in Advanced Configuration - Snapshot Settings and Advanced Configuration - Config Paths. These settings are optional, and can be left at the defaults if you won't be using @@ -564,13 +564,13 @@

          Once you've correctly set the default ROM directory, you can start emulation by selecting a ROM and pressing 'Enter' or clicking 'Select', or double-clicking a ROM. - Note that some games require you to 'Reset' the console before you start playing. In this + Note that some games require you to 'Reset' the console before you start playing. In this case, you need to hit the virtual reset switch, which by default is the F2 key. Also, some games may require that you press the joystick fire button to begin, - which by default is the Left Control or Space key(s). If a game uses a + which by default is the Left Control or Space key(s). If a game uses a more complex controller, see Getting Started - Keyboard Layout - for more information. To exit a game and re-enter the ROM launcher, press the 'Escape' + for more information. To exit a game and re-enter the ROM launcher, press the 'Escape' key.

          Using the 'Search' textbox in the upper-right of the ROM launcher, the @@ -584,12 +584,12 @@ 'virtual' switches in Stella (ie, the commands associated with the function keys as described in Getting Started - Keyboard Layout). - However, another alternative is available. Pressing the '\' key toggles + However, another alternative is available. Pressing the '\' key toggles a command menu dialog as follows:

          This dialog contains a set of buttons that represent the same functionality - as the function keys. You may find this useful if you cannot remember all + as the function keys. You may find this useful if you cannot remember all the function key events, or you wish to use Stella without a keyboard (ie, in a standalone gaming system).

        @@ -598,7 +598,7 @@

        The Atari 2600 console controls and controllers are mapped to the computer's - keyboard as shown in the following tables. However, most of these events can be + keyboard as shown in the following tables. However, most of these events can be remapped to other keys on your keyboard or buttons on your joystick (see Advanced Configuration - Event Remapping). The tables below show the default settings.

        @@ -1647,7 +1647,7 @@

        Some Atari (virtual) controllers are simulated with more than one computer controller, and there are several special cases where controllers are active in certain modes only, as the table - below shows. Items marked as (+ extra) indicate that the computer controller may not have + below shows. Items marked as (+ extra) indicate that the computer controller may not have enough buttons/axes/etc. to fully emulate the device, so extra functionality must be mapped to other controllers.

        @@ -1763,9 +1763,9 @@

        The default options in Stella are meant to cater to as many situations as - possible. As such, you may never need to change many of its options. However, + possible. As such, you may never need to change many of its options. However, Stella is very configurable, and if you want to change its behaviour in some way, - there's likely a configuration option to do so. The remainder of this (lengthy) + there's likely a configuration option to do so. The remainder of this (lengthy) section details every configurable option.

        1. Using the Command Line

        @@ -1817,7 +1817,7 @@ 
        -framerate <number>
        - Display the given number of frames per second. Normally, Stella + Display the given number of frames per second. Normally, Stella will determine framerate based on number of scanlines. Setting this to 0 automatically enables auto-frame calculation (ie, framerate based on scanlines). @@ -1828,14 +1828,14 @@ Determines type of wait to perform between processing frames. Sleep will release the CPU as much as possible, and is the preferred method on laptops (and other low-powered devices) - and when using VSync. Busy will emulate z26 busy-wait + and when using VSync. Busy will emulate z26 busy-wait behaviour, and use all possible CPU time, but may eliminate graphical 'tearing' in software mode. 
        -uimessages <1|0>
        - Enable or disable display of message in the UI. Note that messages + Enable or disable display of message in the UI. Note that messages indicating serious errors override this setting, and are always shown. @@ -1847,14 +1847,14 @@ 
        -fragsize <number>
        - Specify the sound fragment size to use. Linux/Mac seems to work + Specify the sound fragment size to use. Linux/Mac seems to work with 512, Windows usually needs 1024. 
        -freq <number>
        Set sound sample output frequency (11025, 22050, 31400, 44100, 48000) - Default is 31400. Do not change unless you experience sound + Default is 31400. Do not change unless you experience sound issues. @@ -1893,7 +1893,7 @@ 
        -tia.dbgcolors <roygbp>
        Assigns the colours (R)ed, (O)range, (Y)ellow, (G)reen, (B)lue and (P)urple - to each graphical register P0/M0/P1/M1/PF/BL, respectively. Currently, + to each graphical register P0/M0/P1/M1/PF/BL, respectively. Currently, these change be changed around to apply different colours to the respective register. @@ -1908,9 +1908,9 @@ 
        -tv.phosphor <always|byrom>
        - Determines how phosphor mode is enabled. If 'always', then the + Determines how phosphor mode is enabled. If 'always', then the ROM properties entry is ignored, and phosphor mode is always turned - on. Otherwise, the ROM properties determine whether phosphor mode + on. Otherwise, the ROM properties determine whether phosphor mode is used for each ROM. @@ -1918,7 +1918,7 @@ 
        -tv.phosblend <0 - 100>
        Enable default phosphor blending level; 0 implies no mixing, and 100 - is full mixing (not recommended). Note that this doesn't actually + is full mixing (not recommended). Note that this doesn't actually enable phosphor mode; that is done for each ROM in the ROM properties. Higher blend values will intensify the phosphor effect. Depending on your display and personal preferences, the optimal default for you may vary. @@ -2006,12 +2006,12 @@ 
        -loglevel <0|1|2>
        - Indicates level of logging to perform while the application is running. Zero completely disables logging (except for serious errors), while the remaining numbers show increasingly more detail. + Indicates level of logging to perform while the application is running. Zero completely disables logging (except for serious errors), while the remaining numbers show increasingly more detail. 
        -logtoconsole <1|0>
        - Indicates that logged output should be printed to the console/commandline as it's being collected. An internal log will still be kept, and the amount of logging is still controlled by 'loglevel'. + Indicates that logged output should be printed to the console/commandline as it's being collected. An internal log will still be kept, and the amount of logging is still controlled by 'loglevel'. @@ -2020,14 +2020,14 @@ All values within the deadzone are treated as zero-axis values, while only those values outside are registered as valid input. Accepts a number from 0 - 29, and uses the formula - 3200 + number * 1000. So the possible deadzone values + 3200 + number * 1000. So the possible deadzone values range from 3200 to 32200. 
        -joyallow4 <1|0>
        Allow all 4 directions on a joystick to be pressed - simultaneously. Bumper Bash ignores this setting, + simultaneously. Bumper Bash ignores this setting, and always allows all 4 directions. @@ -2079,8 +2079,8 @@ 
        -ctrlcombo <1|0>
        - Use control-x key combos. This is normally enabled, since the - 'Quit' command is tied to 'Control-q'. However, there are times when + Use control-x key combos. This is normally enabled, since the + 'Quit' command is tied to 'Control-q'. However, there are times when a 2-player game is using either the 'f' or 'r' keys for movement, and pressing Control (for Fire) will perform an unwanted action associated with Control-r or Control-f. @@ -2144,7 +2144,7 @@ 
        -listrominfo
        Prints relevant contents of the Stella ROM database, one ROM per line, - and then exit Stella. This can be used for external frontends. + and then exit Stella. This can be used for external frontends. @@ -2186,7 +2186,7 @@ 
        -listdelay <delay>
        Set the amount of time to wait between treating successive keypresses as a single word in list widgets (value can range - from 300-1000). Use '0' to disable list-skipping completely, + from 300-1000). Use '0' to disable list-skipping completely, @@ -2248,7 +2248,7 @@ -

        The following are useful to developers. Only use them if you know what +

        The following are useful to developers. Only use them if you know what you're doing! Note that in all cases, the values supplied to the arguments are not case sensitive.

        @@ -2261,7 +2261,7 @@ 
        -dis.resolve <1|0>
        Try to differentiate between code vs. data sections in the - disassembler. See the Debugger section for more information. + disassembler. See the Debugger section for more information. @@ -2304,34 +2304,34 @@ 
        -holdjoy0 <U,D,L,R,F>
        Start the emulator with the left joystick direction/button held down - (ie, use 'UF' for up and fire). After entering the emulation, you will + (ie, use 'UF' for up and fire). After entering the emulation, you will have to press and release the direction again to release the event. 
        -holdjoy1 <U,D,L,R,F>
        Start the emulator with the right joystick direction/button held down - (ie, use 'UF' for up and fire). After entering the emulation, you will + (ie, use 'UF' for up and fire). After entering the emulation, you will have to press and release the direction again to release the event. 
        -holdselect
        - Start the emulator with the Game Select switch held down. After entering + Start the emulator with the Game Select switch held down. After entering the emulation, you will have to press and release 'Select' to release the event. 
        -holdreset
        - Start the emulator with the Game Reset switch held down. After entering + Start the emulator with the Game Reset switch held down. After entering the emulation, you will have to press and release 'Reset' to release the event. 
        -bs <type>
        - Set "Cartridge.Type" property. See the Game Properties section + Set "Cartridge.Type" property. See the Game Properties section for valid types. @@ -2367,13 +2367,13 @@ 
        -lc <type>
        - Set "Controller.Left" property. See the Game Properties + Set "Controller.Left" property. See the Game Properties section for valid types. 
        -rc <type>
        - Set "Controller.Right" property. See the Game Properties + Set "Controller.Right" property. See the Game Properties section for valid types. @@ -2396,7 +2396,7 @@ 
        -format <format>
        - Set "Display.Format" property. See the Game Properties section + Set "Display.Format" property. See the Game Properties section for valid formats. @@ -2424,8 +2424,8 @@ 
        -thumb.trapfatal <1|0>
        The default of true allows the Thumb ARM emulation to - throw an exception and enter the debugger on fatal errors. When disabled, such - fatal errors are simply logged, and emulation continues. Do not use this + throw an exception and enter the debugger on fatal errors. When disabled, such + fatal errors are simply logged, and emulation continues. Do not use this unless you know exactly what you're doing, as it changes the behaviour as compared to real hardware. @@ -2701,11 +2701,11 @@ remapped).

        Note that there are currently two separate event modes in Stella; emulation - mode and user-interface (UI) mode. Each mode has separate mappings, so (for example) + mode and user-interface (UI) mode. Each mode has separate mappings, so (for example) while in emulation mode, the left arrow could mean 'joystick 0 left', while in UI - mode it could mean 'move cursor left'. Emulation mode occurs whenever you're - actually playing a game. UI mode occurs whenever a user interface is present - (ROM launcher, debugger, settings menu, etc.). Because of these different modes, + mode it could mean 'move cursor left'. Emulation mode occurs whenever you're + actually playing a game. UI mode occurs whenever a user interface is present + (ROM launcher, debugger, settings menu, etc.). Because of these different modes, there are two separate mapping areas.

        To remap an event: @@ -2715,7 +2715,7 @@ Otherwise, click the 'UI Events' tab for user interface events.

      • Select event you want to remap and click the 'Map' button.
      • Press a key or a joystick button, and that key/button will be bound - to the selected event. If nothing seems to happen, either Stella + to the selected event. If nothing seems to happen, either Stella can't see the input device, or the selected event doesn't support being remapped to the input device.
      • Cancel a remap in progress by clicking 'Cancel', erase a mapping by @@ -2768,7 +2768,7 @@

        4. ROM Launcher

        -

        Several options are configurable in the ROM launcher. The size of the +

        Several options are configurable in the ROM launcher. The size of the launcher and fonts, as well as the 'ROM info viewer' can be changed in UI Settings => Launcher dialog, as shown below:

        @@ -2776,21 +2776,21 @@ viewer', which is described below.

        Stella supports viewing snapshots and ROM properties of the currently - selected ROM in the ROM launcher. Support is automatic, as long as your - snapshot directory contains snapshots in the appropriate format. An + selected ROM in the ROM launcher. Support is automatic, as long as your + snapshot directory contains snapshots in the appropriate format. An archive of updated snapshots will be available on the Stella webpage. This archive may be updated periodically as new ROMs are found, and also - for each new release of Stella. Note that the snapshots can be any size + for each new release of Stella. Note that the snapshots can be any size generated by Stella; they will be resized accordingly.

        Currently, there are several restrictions for this feature:

        1. The ROM info viewer can be shown in 1x or 2x mode only.
        2. To view snapshots in 1x mode, the ROM launcher window must be sized at - least 640x480. If the launcher isn't large enough, the functionality + least 640x480. If the launcher isn't large enough, the functionality will be disabled.
        3. To view snapshots in 2x mode, the ROM launcher window must be sized at - least 1000x760. If the launcher isn't large enough, an attempt will + least 1000x760. If the launcher isn't large enough, an attempt will be made to use 1x mode.
        @@ -2807,25 +2807,25 @@

        The text box in the upper right corner can be used to narrow down the - results in the ROM listing. When this box is empty, all files are shown + results in the ROM listing. When this box is empty, all files are shown (subject to the restrictions from the filtering option, explained below). Typing characters here will show only those files that match that - pattern. For example, typing 'Activision' will show only files that - contain the word 'Activision' in their name. This is very useful for - quickly finding a group of related ROMs. Note that the search is not + pattern. For example, typing 'Activision' will show only files that + contain the word 'Activision' in their name. This is very useful for + quickly finding a group of related ROMs. Note that the search is not case sensitive, so you don't need to worry about capital or lower-case letters.

        The ROM launcher also contains a context menu, selected by clicking the - right mouse button anywhere in the current window. This context menu + right mouse button anywhere in the current window. This context menu contains the following items:

        1. Power-on options: Selecting this option shows a dialog whereby ROM properties can be temporarily overridden, and joystick/console buttons can be - temporarily held down. Selecting options from this dialog will cause all ROMs launched - after that to use those properties you specify. Clicking Defaults will disable - its functionality, and use ROM properties as defined by the ROM itself. The dialog is as + temporarily held down. Selecting options from this dialog will cause all ROMs launched + after that to use those properties you specify. Clicking Defaults will disable + its functionality, and use ROM properties as defined by the ROM itself. The dialog is as follows (See Advanced Configuration - Game Properties for more information concerning ROM properties):

          @@ -2852,13 +2852,13 @@

        2. Filter listing: Selecting this option shows a dialog whereby - one can filter the types of files shown in the listing. The dialog is as + one can filter the types of files shown in the listing. The dialog is as follows:

          Currently, the choices are as follows:

          • All files - self explanatory, show all files in the ROM - listing. This is the default, and emulates the behaviour of + listing. This is the default, and emulates the behaviour of all previous versions of Stella.
          • All roms - show only files with a valid ROM extension. Currently, this means extensions .a26, .bin, .rom, .gz, .zip.
            • @@ -2868,7 +2868,7 @@
          • Reload listing: Selecting this performs a reload of the - current listing. It is an alternative to pressing the Control-r + current listing. It is an alternative to pressing the Control-r key combo.

            • @@ -2877,29 +2877,29 @@

            Stella has the ability to rename all your ROMs according to the name - specified in the properties database. This is useful if you've downloaded + specified in the properties database. This is useful if you've downloaded ROMs in DOS 8.3 naming format, and wish the filenames to be more descriptive, or the current filenames are too large to see in the launcher.

            This feature is accessible from Options => Audit ROMs, and is only - available while in ROM launcher mode. The dialog box for this feature + available while in ROM launcher mode. The dialog box for this feature is as follows:

            Simply select the ROM path with the 'Audit path' button, and click the - 'Audit' button. The ROMs will then be renamed according to their internal - properties. When the operation is complete, the number of ROMs that were + 'Audit' button. The ROMs will then be renamed according to their internal + properties. When the operation is complete, the number of ROMs that were renamed (as well as ones that weren't) will be shown.

            There are several items to take note of:

              -
            • THIS OPERATION CANNOT BE UNDONE. I cannot stress this +
            • THIS OPERATION CANNOT BE UNDONE. I cannot stress this enough; if you aren't completely sure you want to rename your ROMs, - don't use this function. There is no undo feature, and one won't be + don't use this function. There is no undo feature, and one won't be added.
            • Only filenames that Stella considers to be valid ROMs will be - considered. Currently, this means files that end in '.a26', - '.bin', '.rom', '.gz' and '.zip'. Files which don't have these + considered. Currently, this means files that end in '.a26', + '.bin', '.rom', '.gz' and '.zip'. Files which don't have these extensions will be ignored.
            • If a valid ROM doesn't have a properties entry, it will be ignored.
              • @@ -2922,12 +2922,12 @@
              • The first device found will act as the left game port - on a real Atari. Depending on the device, Stella will detect it as + on a real Atari. Depending on the device, Stella will detect it as either the left joystick, paddles 0 & 1, the left driving controller, left keypad, etc.
              • The second device found will act as the right game port - on a real Atari. Depending on the device, Stella will detect it as + on a real Atari. Depending on the device, Stella will detect it as either the right joystick, paddles 2 & 3, the right driving controller, right keypad, etc.
                • @@ -2943,23 +2943,23 @@

                Stella supports a real AtariVox device for the speech/SpeakJet portion - of the controller. You will need a real AtariVox device + of the controller. You will need a real AtariVox device as well as some means of connecting it to your computer (some sort of - serial port/USB adaptor). There should be drivers for your serial convertor, + serial port/USB adaptor). There should be drivers for your serial convertor, which allow your particular operating system to 'see' the device (configuring - this is outside the scope of this document). Once your operating system + this is outside the scope of this document). Once your operating system properly detects the AtariVox, you will need to tell Stella which serial - port it is connected to. This is done by using the '-avoxport' commandline + port it is connected to. This is done by using the '-avoxport' commandline argument, or by setting it in the UI under the 'Devices & Ports' tab in Advanced Configuration - Input Devices.

                Note that you must use the entire name of the port as specified by - your operating system. For example, in Windows this would be COM1, + your operating system. For example, in Windows this would be COM1, COM2, etc.; Linux and MacOSX tend to use names similar to '/dev/xxxxxx'. For now, only Linux/UNIX, MacOSX, and Windows are supported.

                Support for the EEPROM portion of the AtariVox and SaveKey is currently - emulated. That is, a file will be created on your computer simulating the + emulated. That is, a file will be created on your computer simulating the EEPROM; the actual EEPROM hardware itself will not be accessed or modified. This is very useful in the testing stages of creating a new game, since writing to a real EEPROM many times will eventually wear it out.

                @@ -2995,9 +2995,9 @@

          3. Note that these EEPROM files will be created when necessary, and - initialized as a real EEPROM would be (containing all $FF). The + initialized as a real EEPROM would be (containing all $FF). The files can be manually deleted, which is very useful in testing - cases where a ROM is accessing the EEPROM for the first time. You can also + cases where a ROM is accessing the EEPROM for the first time. You can also reset the EEPROM to a clean state.

        @@ -3090,36 +3090,36 @@

        • Developer key-combo shortcuts, used to change TIA state dynamically - (ie, while the emulation is still running). See Keyboard Layout - + (ie, while the emulation is still running). See Keyboard Layout - Developer Keys in TIA mode for more information.
          • -
        • Commandline options influencing emulation state. See Using the Command Line - +
        • Commandline options influencing emulation state. See Using the Command Line - Developer Commands for more information.
          • -
        • Viewing TIA/console information overlaid on the TIA image. This option +
        • Viewing TIA/console information overlaid on the TIA image. This option can be enabled from the commandline or using the Alt-L key combo, and is extremely useful for viewing the current scanline count and associated - frames per second, bankswitch and display formats, etc. The following shows + frames per second, bankswitch and display formats, etc. The following shows an example of this information:

          The two lines of output describe the following:

          1. Number of scanlines in current frame, associated framerate, and - resulting display format. Note that the framerate shown is the + resulting display format. Note that the framerate shown is the internal, virtual framerate (it's calculated from the - number of scanlines). If the '*' character is present, it means - the display format was auto-detected as shown. For the given example, + number of scanlines). If the '*' character is present, it means + the display format was auto-detected as shown. For the given example, the format was auto-detected as 'NTSC'.
            2. -
          2. Cartridge information. If the '*' character is present, - it means the bankswitch format was auto-detected as shown. The item - in round brackets indicates ROM size. For the given example, +
          3. Cartridge information. If the '*' character is present, + it means the bankswitch format was auto-detected as shown. The item + in round brackets indicates ROM size. For the given example, the bankswitch type was auto-detected as 4K, and the file size was 4K (4096 bytes).

        -

        Finally, Stella contains an extensive, built-in debugger. Have a look at +

        Finally, Stella contains an extensive, built-in debugger. Have a look at this page for integrated debugger documentation.

        • @@ -3128,13 +3128,13 @@

        Stella will remember when you change a setting either at the command line or while the emulation is running, and use the settings the next time - you start the emulator. The settings are saved in a text file which can - be edited outside of Stella. This file can contain your default options, - and eliminates the need to specify them on the command line. Any + you start the emulator. The settings are saved in a text file which can + be edited outside of Stella. This file can contain your default options, + and eliminates the need to specify them on the command line. Any options specified on the command line will override those in the settings file.

        -

        The syntax for the settings file is very straightforward. Any line starting with - a ';' character is considered a comment and is ignored. Other lines must be of +

        The syntax for the settings file is very straightforward. Any line starting with + a ';' character is considered a comment and is ignored. Other lines must be of the form: command = value, where command is the same as that specified on the command line (without the '-' character), and value is dependent on the command.

        @@ -3202,7 +3202,7 @@ must be entered in hexadecimal format:

        • Per-frame RAM cheats:
          - Evaluated each frame, and apply to RAM only. Format as follows: + Evaluated each frame, and apply to RAM only. Format as follows: 

              4-digit code: c041
    c0 = address
@@ -3212,7 +3212,7 @@
 
     
        • Cheetah codes, which are explained in detail on
       Bob Colbert's web page,
-      along with a list of codes for various games.  Cheetah codes
+      along with a list of codes for various games. Cheetah codes
       don't support bankswitched ROMs, so they only work for 2K or 4K ROMs.
       Format as follows:
   
          @@ -3242,8 +3242,8 @@
     
          •
        -

        There's also the concept of one shot codes. These codes work - exactly the same as above, except they aren't saved. They are evaluated +

        There's also the concept of one shot codes. These codes work + exactly the same as above, except they aren't saved. They are evaluated once and immediately discarded.

        Here are a few cheat codes we've found:

        @@ -3262,7 +3262,7 @@ Ms Pac-Man (Stella extended codes):

        The name of the cheat database file is configurable through the '-cheatfile' commandline argument and within the application itself - (see Advanced Configuration - Config Paths). If the + (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:

        @@ -3292,10 +3292,10 @@ Ms Pac-Man (Stella extended codes):

        Stella maintains a log of its operations when the program first starts up, and - while it is running. In older releases, this information was only viewable from the - commandline. However, the current release allows - you to see this information from within the UI. This can be selected from the main - Options menu, where it is labelled "System Logs". Clicking on the button will show + while it is running. In older releases, this information was only viewable from the + commandline. However, the current release allows + you to see this information from within the UI. This can be selected from the main + Options menu, where it is labelled "System Logs". Clicking on the button will show a window similar to the following:

        @@ -3312,10 +3312,10 @@ Ms Pac-Man (Stella extended codes):
        -

        The log levels are self-explanatory (None, Basic, Verbose). The "Print to console" +

        The log levels are self-explanatory (None, Basic, Verbose). The "Print to console" option emulates the behaviour of older versions of Stella, whereby the logged output is also shown on the commandline from which Stella was launched (if it was launched - in that fashion). Finally, the current contents of the system log can be saved to your + in that fashion). Finally, the current contents of the system log can be saved to your home directory by clicking the "Save log to disk" button.

        @@ -3326,15 +3326,15 @@ Ms Pac-Man (Stella extended codes): game. As of version 2.2 of Stella, a default database of properties are built-in, but you may modify these through the use of a stella.pro file or within the corresponding Game Properties dialogs. - This file will contain all properties modified by the user. So this + This file will contain all properties modified by the user. So this means that when you upgrade Stella, your personal properties settings are preserved.

        Property File

        -

        A property file consists of some number of blocks. Each block in the file - contains the properties for a single game. For example the general format of +

        A property file consists of some number of blocks. Each block in the file + contains the properties for a single game. For example the general format of a property file is:

        @@ -3363,17 +3363,17 @@ Ms Pac-Man (Stella extended codes):

        Properties

        Each block in a property file consists of a set of properties for a single - game. Stella supports the properties described below:

        + game. Stella supports the properties described below:

        @@ -3390,7 +3390,7 @@ Ms Pac-Man (Stella extended codes): - @@ -3410,7 +3410,7 @@ Ms Pac-Man (Stella extended codes): + sound. The value must be Mono or Stereo. @@ -3418,7 +3418,7 @@ Ms Pac-Man (Stella extended codes):
        Cartridge.MD5: Indicates the MD5 checksum of the ROM image as a - string of hexadecimal digits. Stella uses this property while - attempting to match a game with its block of properties. If the + string of hexadecimal digits. Stella uses this property while + attempting to match a game with its block of properties. If the value of the property matches the MD5 checksum of the ROM image then - Stella uses that block of properties for the game. You can use the + Stella uses that block of properties for the game. You can use the GNU md5sum program, which is included with most Linux distributions, to calculate the MD5 checksum of a ROM image.
        Cartridge.Name:Indicates the actual name of the game. When you save snapshots, + Indicates the actual name of the game. When you save snapshots, load/save state files, or use the 'ROM Audit' functionality, this is the name that will be used for the respective file(s).
        Indicates if the game should use 1 or 2 channels for sound output. All original Atari 2600 machines supported 1 channel only, but some homebrew games have been written to take advantage of stereo - sound. The value must be Mono or Stereo.
        Indicates the bank-switching type for the game. The value of this property must be either Auto or one of the following (for more information about bank-switching see Kevin Horton's 2600 bankswitching - document or the documentation in each cartridges source code file). Types marked + document or the documentation in each cartridges source code file). Types marked as (¹) do not currently have reliable auto-detection, those marked as (²) are not fully supported in the debugger: @@ -3480,19 +3480,19 @@ Ms Pac-Man (Stella extended codes): + player. The value must be A or B. + right player. The value must be A or B. + game. The value must be Color or BW.
        Console.LeftDifficulty: Indicates the default difficulty setting for the left - player. The value must be A or B.
        Console.RightDifficulty: Indicates the default difficulty setting for the - right player. The value must be A or B.
        Console.TelevisionType: Indicates the default television setting for the - game. The value must be Color or BW.
        @@ -3501,7 +3501,7 @@ Ms Pac-Man (Stella extended codes):
        Controller.Left:
        Controller.Right:        		 Indicates what type of controller the left and right player - uses. The value must be one of the following types: + uses. The value must be one of the following types: @@ -3526,7 +3526,7 @@ Ms Pac-Man (Stella extended codes): @@ -3534,20 +3534,20 @@ Ms Pac-Man (Stella extended codes): + 'Console.SwapPorts'. The value must be Yes or No.
         Type Description
        Joystick Atari's famous black joystick that was originally included with the system.
        Console.SwapPorts: Indicates that the left and right ports should be - swapped internally. This is used for ROMs like 'Raiders' where the + swapped internally. This is used for ROMs like 'Raiders' where the Player 0 joystick is plugged into the right joystick port. The value must be Yes or No.
        Controller.SwapPaddles: Indicates that the left and right paddles in - a particular port should be swapped. This is used for ROMs like + a particular port should be swapped. This is used for ROMs like 'Demons to Diamonds' where the default paddle is paddle 1, not - paddle 0. Other ROMs such as 'Tac-Scan' default to paddle 3, + paddle 0. Other ROMs such as 'Tac-Scan' default to paddle 3, which can be set using both 'Controller.SwapPaddles' and - 'Console.SwapPorts'. The value must be Yes or No.
        Controller.MouseAxis: Indicates how the mouse should emulate virtual controllers. - In 'Auto' mode, the system decides how to best use the mouse. Otherwise, + In 'Auto' mode, the system decides how to best use the mouse. Otherwise, XY indicates how to use the X/Y axis (ie, 02 is paddle0/paddle2). Currently, the mouse X-axis and left button are tied together, as are the - Y-axis and right button. The value must be Auto or XY, as follows: + Y-axis and right button. The value must be Auto or XY, as follows: @@ -3574,7 +3574,7 @@ Ms Pac-Man (Stella extended codes):
         Id Controller
        0 Paddle 0
        - @@ -3602,8 +3602,8 @@ Ms Pac-Man (Stella extended codes): + phosphor effect. The value must be n such that 0 <= n + <= 100. The default value is whatever is specified for tv.phosblend.
        Display.Format:Indicates the television format the game was designed for. The value + Indicates the television format the game was designed for. The value must be Auto, NTSC, PAL, SECAM, NTSC50, PAL60 or SECAM60.
        Display.PPBlend: Indicates the amount of blending which will occur while using the - phosphor effect. The value must be n such that 0 <= n - <= 100. The default value is whatever is specified for tv.phosblend.

        The name of the properties file is configurable through the '-propsfile' commandline argument and within the application itself - (see Advanced Configuration - Config Paths). If the + (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:

        @@ -3663,21 +3663,21 @@ Ms Pac-Man (Stella extended codes):

        A user-defined palette has certain restrictions, further described as follows:

          -
        • The palette file must be at least 792 bytes long. Colours are stored +
        • The palette file must be at least 792 bytes long. Colours are stored in 24-bit RGB, with the first byte for red, the second for green, the third for blue, for a total of 3 bytes per colour.
        • The first 384 bytes of the file (128 * 3) will be used for the NTSC - palette. The next 384 bytes (128 * 3) will be for the PAL palette. + palette. The next 384 bytes (128 * 3) will be for the PAL palette. The next 24 bytes (8 * 3) will be for the SECAM palette, which - consists of eight distinct colours. Any extra data in the file + consists of eight distinct colours. Any extra data in the file will be ignored.
          • -
        • The PAL colour-loss effect is calculated within Stella. You do not +
        • The PAL colour-loss effect is calculated within Stella. You do not need to specify those colours in the palette file.

        The name of the palette file is configurable through the '-palettefile' commandline argument and within the application itself - (see Advanced Configuration - Config Paths). If the + (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:

        @@ -3702,7 +3702,7 @@ Ms Pac-Man (Stella extended codes):

        Note that to actually use the external palette, the palette file must exist and be valid, and the palette option should be set to user - (in Video Settings dialog). The current ROM will have to be reloaded + (in Video Settings dialog). The current ROM will have to be reloaded for changes to this file to take effect.

        @@ -3717,8 +3717,8 @@ Ms Pac-Man (Stella extended codes): Anthony has maintained the project since around 2004. Over the years, a number of people from around the world have contributed to the project. Some people have provided technical help while others have offered suggestions - and praise. The Stella Team is grateful for all the help and support it has - received over the years. A (likely incomplete) list of the people who have + and praise. The Stella Team is grateful for all the help and support it has + received over the years. A (likely incomplete) list of the people who have played a part in bringing Stella to you is available on the main Stella webpage Credits List. If we've missed someone, please let us know.

        @@ -3751,19 +3751,19 @@ of this license document, but changing it is not allowed.

        The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public +freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This +software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by +using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

        When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you +price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it @@ -3780,8 +3780,8 @@ distribute copies of the software, or if you modify it.

        For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their rights.

        @@ -3794,7 +3794,7 @@ distribute and/or modify the software.

        Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we +software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. @@ -3802,9 +3802,9 @@ authors' reputations.

        Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free +patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any +program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

        @@ -3823,17 +3823,17 @@ modification follow. 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, +under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in +language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

        Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of +covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). @@ -3884,16 +3884,16 @@ above, provided that you also meet all of these conditions: notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but + License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) -These requirements apply to the modified work as a whole. If +These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you +sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the @@ -3940,17 +3940,17 @@ Sections 1 and 2 above provided that you also do one of the following:

      • c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is + to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source +making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a +control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the @@ -3967,7 +3967,7 @@ compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt +except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under @@ -3978,9 +3978,9 @@ parties remain in full compliance. 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying @@ -3992,7 +3992,7 @@ the Program or works based on it. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further +these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. @@ -4004,10 +4004,10 @@ this License. infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot +excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent +may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to @@ -4024,7 +4024,7 @@ It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is -implemented by public license practices. Many people have made +implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing @@ -4043,23 +4043,23 @@ certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates +countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

        9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will +of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

        -Each version is given a distinguishing version number. If the Program +Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of +Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. @@ -4069,9 +4069,9 @@ Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free +to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals +make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. @@ -4083,12 +4083,12 @@ of promoting the sharing and reuse of software generally. 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.