file_id.diz
Place artwork files here
This file describes general usage information about MAME. It is intended
to cover aspects of using and configuring the program that are common
across operating systems. For additional OS-specific options, please see
the separate documentation for your particular version of MAME.
Using the program
-----------------
The usual way to run MAME is by telling it to run a particular game:
mame <gamename> [options]
For example:
mame robby -sound none
...will run Robby Roto without sound. There are many, many options
available. All commonly supported options are listed below. Options that
are specific to one operating system or version of MAME will be listed
in a separate document.
An alternative way to run MAME is to give it a command:
mame <command> [parameters]
For example:
mame -listsource gridlee
...will print the name of the source file where the gridlee driver lives
to the screen. There are just a handful of these commands in MAME. They
are all listed below, just before the options list.
Default Keys
------------
All the keys below are fully configurable in the user interface. This list
shows the standard keyboard configuration.
Tab Toggles the configuration menu.
~ Toggles the On Screen Display. When the on-screen display is
visible, you can use the following keys to control it:
Up - select previous parameter to modify
Down - select next parameter to modify
Enter - reset parameter value to its default
Left - decrease the value of the selected parameter
Control+Left - decrease the value by 10x
Shift+Left - decrease the value by 0.1x
Alt+Left - decrease the value by the smallest amount
Right - increase the value of the selected parameter
Control+Right - increase the value by 10x
Shift+Right - increase the value by 0.1x
Alt+Right - increase the value by the smallest amount
If you are running with -debug, this key send a 'break'
in emulation.
P Pauses the game.
Shift+P While paused, advances to next frame.
F2 Service Mode for games that support it.
F3 Resets the game.
Shift+F3 Performs a "hard reset", which tears everything down and re-
creates it from scratch. This is a more thorough and complete
reset than an F3.
LCtrl+F3 [SDL ONLY]
Toggle Uneven stretch.
F4 Shows the game palette, decoded GFX, and any tilemaps. Use the
Enter key to switch between the three modes (palette, graphics,
and tilemaps). Press F4 again to turn off the display. The key
controls in each mode vary slightly:
* Palette/colortable mode:
[ ] - switch between palette and colortable modes
Up/Down - scroll up/down one line at a time
Page Up/Page Down - scroll up/down one page at a time
Home/End - move to top/bottom of list
-/+ - increase/decrease the number of colors per row
Enter - switch to graphics viewer
* Graphics mode:
[ ] - switch between different graphics sets
Up/Down - scroll up/down one line at a time
Page Up/Page Down - scroll up/down one page at a time
Home/End - move to top/bottom of list
Left/Right - change color displayed
R - rotate tiles 90 degrees clockwise
-/+ - increase/decrease the number of tiles per row
Enter - switch to tilemap viewer
* Tilemap mode:
[ ] - switch between different tilemaps
Up/Down/Left/Right - scroll 8 pixels at a time
Shift+Up/Down/Left/Right - scroll 1 pixel at a time
Control+Up/Down/Left/Right - scroll 64 pixels at a time
R - rotate tilemap view 90 degrees clockwise
-/+ - increase/decrease the zoom factor
Enter - switch to palette/colortable mode
Note: Not all games have decoded graphics and/or tilemaps.
LCtrl+F4 [SDL ONLY]
Toggle Keepaspect ratio.
LCtrl+F5 [SDL ONLY]
Toggle Filter.
Alt+Ctrl+F5 [WINDOWS ONLY. NON SDL]
Toggle HLSL Post-Processing.
F6 Toggle cheat mode (if started with "-cheat").
LCtrl+F6 Decrease Prescaling.
F7 Load a save state. You will be requested to press a key to
determine which save state you wish to load. Note that the save
state feature is not supported for a large number of drivers. If
support is not enabled for a given driver, you will receive a
warning when attempting to save or load.
LCtrl+F7 Increase Prescaling.
Shift+F7 Create a save state. Requires an additional keypress to identify
the state, similar to the load option above.
F8 Decrease frame skip on the fly.
F9 Increase frame skip on the fly.
F10 Toggle speed throttling.
F11 Toggles speed display.
Shift+F11 Toggles internal profiler display (if compiled in).
Alt+F11 Record HLSL Rendered Video.
F12 Saves a screen snapshot.
Alt+F12 Take HLSL Rendered Snapshot.
Insert [WINDOW ONLY, NON SDL]
Page DN [SDL ONLY]
Fast forward. While held, runs the game with throttling disabled
and with the maximum frameskip.
Alt+ENTER Toggles between full-screen and windowed mode.
Scroll Lock Default mapping for the uimodekey. This key allows user to
disable and enable the emulated keyboard in machines that require
it. All emulations which require emulated keyboards will start in
that mode and you can only access the internal UI (hitting TAB) by
first hitting this key. You can change the initial status of the
emulated keyboard is presented upon start by using -ui_active trigger
as detailed below.
Escape Exits emulator.
Core commands
-------------
-help / -h / -?
Displays current MAME version and copyright notice.
-validate / -valid
Performs internal validation on every driver in the system. Run this
before submitting changes to ensure that you haven't violated any of
the core system rules.
Configuration commands
----------------------
-createconfig / -cc
Creates the default mame.ini file. All the configuration options
(not commands) described below can be permanently changed by editing
this configuration file.
-showconfig / -sc
Displays the current configuration settings. If you route this to a
file, you can use it as an INI file. For example, the command:
mame -showconfig >mame.ini
is equivalent to -createconfig.
-showusage / -su
Displays a summary of all the command line options. For options that
are not mentioned here, the short summary given by "mame -showusage"
is usually sufficient.
Frontend commands
-----------------
Note: By default, all the '-list' commands below write info to the screen.
If you wish to write the info to a textfile instead, add this to the end
of your command:
> filename
...where 'filename' is the textfile's path and name
(e.g., c:\mame\list.txt).
-listxml / -lx [<gamename|wildcard>]
List comprehensive details for all of the supported games. The output
is quite long, so it is usually better to redirect this into a file.
The output is in XML format. By default all games are listed; however,
you can limit this list by specifying a driver name or wildcard after
the -listxml command.
-listfull / -ll [<gamename|wildcard>]
Displays a list of game driver names and descriptions. By default all
games are listed; however, you can limit this list by specifying a
driver name or wildcard after the -listfull command.
-listsource / -ls [<gamename|wildcard>]
Displays a list of drivers and the names of the source files their
game drivers live in. Useful for finding which driver a game runs on
in order to fix bugs. By default all games are listed; however, you
can limit this list by specifying a driver name or wildcard after
the -listsource command.
-listclones / -lc [<gamename|wildcard>]
Displays a list of clones. By default all clones are listed; however,
you can limit this list by specifying a driver name or wildcard after
the -listsource command.
-listbrothers / -lb [<gamename|wildcard>]
Displays a list of 'brothers', or rather, other sets which are located
in the same sourcefile as the gamename searched for.
-listcrc [<gamename|wildcard>]
Displays a full list of CRCs of all ROM images referenced by all
drivers within MAME.
-listroms [<gamename|wildcard>]
Displays a list of ROM images referenced by the specified game.
-listsamples [<gamename|wildcard>]
Displays a list of samples referenced by the specified game.
-verifyroms [<gamename|wildcard>]
Checks for invalid or missing ROM images. By default all drivers that
have valid ZIP files or directories in the rompath are verified;
however, you can limit this list by specifying a driver name or
wildcard after the -verifyroms command.
-verifysamples [<gamename|wildcard>]
Checks for invalid or missing samples. By default all drivers that
have valid ZIP files or directories in the samplepath are verified;
however, you can limit this list by specifying a driver name or
wildcard after the -verifyroms command.
-romident [path\to\romstocheck.zip]
Attempts to identify ROM files, if they are known to MAME, in the
specified .zip file or directory. This command can be used to try and
identify ROM sets taken from unknown boards. On exit, the errorlevel
is returned as one of the following:
0: means all files were identified
7: means all files were identified except for 1 or more "non-ROM"
files
8: means some files were identified
9: means no files were identified
-listdevices / -ld [<gamename|wildcard>]
Displays a list of all devices known to be hooked up to a game. The ":"
is considered the game itself with the devices list being attached to give
the user a better understanding of what the emulation is using.
-listslots [<gamename|wildcard>]
Show available slots and options for each slot (if available). Primarily
used for MESS to allow control over internal plug-in cards, much like PC's
needing video, sound and other cards.
-listmedia / -lm [<gamename|wildcard>]
List available media that the chosen game or system allows to be used. This
includes media types (cartridge, cassette, diskette and more) as well as
common file extentions which are supported.
-listsoftware [<gamename|wildcard>]
Posts to screen all software lists which can be used by the entered gamename
or system. Notice, this is simply a copy/paste of the .XML file which reside
in the HASH folder which are allowed to be used.
-verifysoftware [<gamename|wildcard>]
Checks for invalid or missing ROM images in your software lists. By default
all drivers that have valid ZIP files or directories in the rompath are verified;
however, you can limit this list by specifying a specific driver name or wildcard
after the -verifysoftware command.
-getsoftlist [<gamename|wildcard>]
Posts to screen a specific software list which matches with the gamename
provided.
-verifysoftlist [softwarelistname]
Checks a specified software list for missing ROM images if files exist for issued
softwarelistname. By default, all drivers that have valid ZIP files or directories
in the rompath are verified; however, you can limit this list by specifying a
specific softwarelistname (without .XML) after the -verifysoftlist command.
OSD related options
-------------------
-uimodekey [keystring]
Key used to toggle emulated keyboard on and off. Default setting is SCRLOCK.
-uifontprovider
Chooses provider for UI font: win, none or auto. The Default setting is AUTO.
OSD CLI options
---------------
-listmidi
Create a list of available MIDI I/O devices for use with emulation.
-listnetwork
Create a list of available Network Adapters for use with emulation.
Configuration options
---------------------
-[no]readconfig / -[no]rc
Enables or disables the reading of the config files. When enabled
(which is the default), MAME reads the following config files in order:
- mame.ini
- <mymame>.ini (i.e. if MAME was renamed mame060.exe, MAME
parses mame060.ini here)
- debug.ini (if the debugger is enabled)
- <driver>.ini (based on the source filename of the driver)
- vertical.ini (for games with vertical monitor orientation)
- horizont.ini (for games with horizontal monitor orientation)
- arcade.ini (for games in source added with GAME() macro)
- console.ini (for games in source added with CONS() macro)
- computer.ini (for games in source added with COMP() macro)
- othersys.ini (for games in source added with SYST() macro)
- vector.ini (for vector games only)
- <parent>.ini (for clones only, may be called recursively)
- <gamename>.ini
The settings in the later ini's override those in the earlier ini's.
So, for example, if you wanted to disable overlay effects in the
vector games, you can create a vector.ini with the "effect none" line
in it, and it will override whatever effect value you have in your
mame.ini. The default is ON (-readconfig).
Core search path options
------------------------
-rompath / -rp <path>
Specifies a list of paths within which to find ROM or hard disk images.
Multiple paths can be specified by separating them with semicolons.
The default is 'roms' (that is, a directory "roms" in the same directory
as the MAME executable).
-hashpath <path>
Specifies a list of paths within which to find Software List HASH files.
Multiple paths can be specified by separating them with semicolons.
The default is 'hash' (that is, a directory "roms" in the same directory
as the MAME executable).
-samplepath / -sp <path>
Specifies a list of paths within which to find sample files. Multiple
paths can be specified by separating them with semicolons. The default
is 'samples' (that is, a directory "samples" in the same directory as
the MAME executable).
-artpath <path> / -artwork_directory <path>
Specifies a list of paths within which to find artwork files. Multiple
paths can be specified by separating them with semicolons. The default
is 'artwork' (that is, a directory "artwork" in the same directory as
the MAME executable).
-ctrlrpath / -ctrlr_directory <path>
Specifies a list of paths within which to find controller-specific
configuration files. Multiple paths can be specified by separating
them with semicolons. The default is 'ctrlr' (that is, a directory
"ctrlr" in the same directory as the MAME executable).
-inipath <path>
Specifies a list of paths within which to find .INI files. Multiple
paths can be specified by separating them with semicolons. The default
is '.;ini' (that is, search in the current directory first, and then
in the directory "ini" in the same directory as the MAME executable).
-fontpath <path>
Specifies a list of paths within which to find .BDF font files. Multiple
paths can be specified by separating them with semicolons. The default
is '.' (that is, search in the same directory as the MAME executable).
-cheatpath <path>
Specifies a list of paths within which to find .XML cheat files.
Multiple paths can be specified by separating them with semicolons. The
default is 'cheat' (that is, a folder called 'cheat' located in the same
directory as the as the MAME executable).
-crosshairpath <path>
Specifies a list of paths within which to find crosshair files. Multiple
paths can be specified by separating them with semicolons. The default
is 'crsshair' (that is, a directory "crsshair" in the same directory as
the MAME executable). If the Crosshair is set to default in the menu,
MAME will look for gamename\cross#.png and then cross#.png in the
specified crsshairpath, where # is the player number. Failing that,
MAME will use built-in default crosshairs.
Core Output Directory Options
-----------------------------
-cfg_directory <path>
Specifies a single directory where configuration files are stored.
Configuration files store user configurable settings that are read at
startup and written when MAME exits. The default is 'cfg' (that is,
a directory "cfg" in the same directory as the MAME executable). If
this directory does not exist, it will be automatically created.
-nvram_directory <path>
Specifies a single directory where NVRAM files are stored. NVRAM files
store the contents of EEPROM and non-volatile RAM (NVRAM) for games
which used this type of hardware. This data is read at startup and
written when MAME exits. The default is 'nvram' (that is, a directory
"nvram" in the same directory as the MAME executable). If this
directory does not exist, it will be automatically created.
-input_directory <path>
Specifies a single directory where input recording files are stored.
Input recordings are created via the -record option and played back
via the -playback option. The default is 'inp' (that is, a directory
"inp" in the same directory as the MAME executable). If this directory
does not exist, it will be automatically created.
-state_directory <path>
Specifies a single directory where save state files are stored. Save
state files are read and written either upon user request, or when
using the -autosave option. The default is 'sta' (that is, a directory
"sta" in the same directory as the MAME executable). If this directory
does not exist, it will be automatically created.
-snapshot_directory <path>
Specifies a single directory where screen snapshots are stored, when
requested by the user. The default is 'snap' (that is, a directory
"snap" in the same directory as the MAME executable). If this
directory does not exist, it will be automatically created.
-diff_directory <path>
Specifies a single directory where hard drive differencing files are
stored. Hard drive differencing files store any data that is written
back to a hard disk image, in order to preserve the original image.
The differencing files are created at startup when a game with a hard
disk image. The default is 'diff' (that is, a directory "diff" in the
same directory as the MAME executable). If this directory does not
exist, it will be automatically created.
-comment_directory <path>
Specifies a single directory where debugger comment files are stored.
Debugger comment files are written by the debugger when comments are
added to the disassembly for a game. The default is 'comments' (that
is, a directory "comments" in the same directory as the MAME
executable). If this directory does not exist, it will be
automatically created.
Core state/playback options
---------------------------
-state <slot>
Immediately after starting the specified game, will cause the save
state in the specified <slot> to be loaded.
-[no]autosave
When enabled, automatically creates a save state file when exiting
MAME and automatically attempts to reload it when later starting MAME
with the same game. This only works for games that have explicitly
enabled save state support in their driver. The default is OFF
(-noautosave).
-playback / -pb <filename>
Specifies a file from which to play back a series of game inputs. This
feature does not work reliably for all games, but can be used to watch
a previously recorded game session from start to finish. In order to
make things consistent, you should only record and playback with all
configuration (.cfg), NVRAM (.nv), and memory card files deleted. The
default is NULL (no playback).
-record / -rec <filename>
Specifies a file to record all input from a game session. This can be
used to record a game session for later playback. This feature does
not work reliably for all games, but can be used to watch a previously
recorded game session from start to finish. In order to make things
consistent, you should only record and playback with all configuration
(.cfg), NVRAM (.nv), and memory card files deleted. The default is
NULL (no recording).
-mngwrite <filename>
Writes each video frame to the given <filename> in MNG format,
producing an animation of the game session. Note that -mngwrite only
writes video frames; it does not save any audio data. Use -wavwrite
for that, and reassemble the audio/video using offline tools. The
default is NULL (no recording).
-aviwrite <filename>
Stream video and sound data to the given <filename> in AVI format,
producing an animation of the game session complete with sound. The
default is NULL (no recording).
-wavwrite <filename>
Writes the final mixer output to the given <filename> in WAV format,
producing an audio recording of the game session. The default is
NULL (no recording).
-snapname <name>
Describes how MAME should name files for snapshots. <name> is a string
that provides a template that is used to generate a filename. Three
simple substitutions are provided: the / character represents the
path separator on any target platform (even Windows); the string %g
represents the driver name of the current game; and the string %i
represents an incrementing index. If %i is omitted, then each
snapshot taken will overwrite the previous one; otherwise, MAME will
find the next empty value for %i and use that for a filename. The
default is %g/%i, which creates a separate folder for each game,
and names the snapshots under it starting with 0000 and increasing
from there. In addition to the above, for drivers using different
media, like carts or floppy disks, you can also use the %d_[media]
indicator. Replace [media] with the media switch you want to use.
A few examples: if you use 'mame robby -snapname foo/%g%i' snapshots
will be saved as 'snaps\foo\robby0000.png' , 'snaps\foo\robby0001.png'
and so on ; if you use 'mess nes -cart robby -snapname %g/%d_cart'
snapshots will be saved as 'snaps\nes\robby.png' ; if you use
'mess c64 -flop1 robby -snapname %g/%d_flop1/%i' snapshots will be
saved as 'snaps\c64\robby\0000.png'.
-snapsize <width>x<height>
Hard-codes the size for snapshots and movie recording. By default,
MAME will create snapshots at the game's current resolution in raw
pixels, and will create movies at the game's starting resolution in
raw pixels. If you specify this option, then MAME will create both
snapshots and movies at the size specified, and will bilinear filter
the result. Note that this size does not automatically rotate if the
game is vertically oriented. The default is 'auto'.
-snapview <viewname>
Specifies the view to use when rendering snapshots and movies. By
default, both use a special 'internal' view, which renders a separate
snapshot per screen or renders movies only of the first screen. By
specifying this option, you can override this default behavior and
select a single view that will apply to all snapshots and movies.
Note that <viewname> does not need to be a perfect match; rather, it
will select the first view whose name matches all the characters
specified by <viewname>. For example, -snapview native will match the
"Native (15:14)" view even though it is not a perfect match.
<viewname> can also be 'auto', which selects the first view with all
screens present. The default value is 'internal'.
-[no]snapbilinear
Specify if the snapshot or movie should have bilinear filtering
applied. Shutting this off can make a difference in some performance
while recording video to a file. The default is ON (-snapbilinear).
-statename <name>
Describes how MAME should store save state files, relative to the
state_directory path. <name> is a string that provides a template that
is used to generate a relative path. Two simple substitutions are
provided: the / character represents the path separator on any target
platform (even Windows); the string %g represents the driver name of
the current game. The default is %g, which creates a separate folder for
each game. In addition to the above, for drivers using different
media, like carts or floppy disks, you can also use the %d_[media]
indicator. Replace [media] with the media switch you want to use.
A few examples: if you use 'mame robby -statename foo/%g' save states
will be stored inside 'sta\foo\robby\' ; if you use 'mess nes -cart
robby -statename %g/%d_cart' save states will be stored inside
'sta\nes\robby\' ; if you use 'mess c64 -flop1 robby -statename
%g/%d_flop1' save states will be stored inside 'sta\c64\robby\'.
-[no]burnin
Tracks brightness of the screen during play and at the end of
emulation generates a PNG that can be used to simulate burn-in
effects on other games. The resulting PNG is created such that the
least used-areas of the screen are fully white (since burned-in areas
are darker, all other areas of the screen must be lightened a touch).
The intention is that this PNG can be loaded via an artwork file with
a low alpha (e.g, 0.1-0.2 seems to work well) and blended over the
entire screen. The PNG files are saved in the snap directory under
the gamename/burnin-<screen.name>.png. The default is OFF (-noburnin).
Core performance options
------------------------
-[no]autoframeskip / -[no]afs
Automatically determines the frameskip level while you're playing the
game, adjusting it constantly in a frantic attempt to keep the game
running at full speed. Turning this on overrides the value you have
set for -frameskip below. The default is OFF (-noautoframeskip).
-frameskip / -fs <level>
Specifies the frameskip value. This is the number of frames out of
every 12 to drop when running. For example, if you say -frameskip 2,
then MAME will display 10 out of every 12 frames. By skipping those
frames, you may be able to get full speed in a game that requires more
horsepower than your computer has. The default value is -frameskip 0,
which skips no frames.
-seconds_to_run / -str <seconds>
This option can be used for benchmarking and automated testing. It tells
MAME to stop execution after a fixed number of seconds. By combining
this with a fixed set of other command line options, you can set up a
consistent environment for benchmarking MAME performance. In addition,
upon exit, the -str option will write a screenshot called final.png
to the game's snapshot directory.
-[no]throttle
Configures the default thottling setting. When throttling is on, MAME
attempts to keep the game running at the game's intended speed. When
throttling is off, MAME runs the game as fast as it can. Note that the
fastest speed is more often than not limited by your graphics card,
especially for older games. The default is ON (-throttle).
-[no]sleep
Allows MAME to give time back to the system when running with -throttle.
This allows other programs to have some CPU time, assuming that the
game isn't taxing 100% of your CPU resources. This option can
potentially cause hiccups in performance if other demanding programs
are running. The default is ON (-sleep).
-speed <factor>
Changes the way MAME throttles gameplay such that the game runs at some
multiplier of the original speed. A <factor> of 1.0 means to run the
game at its normal speed. A <factor> of 0.5 means run at half speed,
and a <factor> of 2.0 means run at 2x speed. Note that changing this
value affects sound playback as well, which will scale in pitch
accordingly. The internal resolution of the fraction is two decimal
places, so a value of 1.002 is the same as 1.0. The default is 1.0.
-[no]refreshspeed / -[no]rs
Allows MAME to dynamically adjust the gameplay speed such that it does
not exceed the slowest refresh rate for any targeted monitors in your
system. Thus, if you have a 60Hz monitor and run a game that is
actually designed to run at 60.6Hz, MAME will dynamically change the
speed down to 99% in order to prevent sound hiccups or other
undesirable side effects of running at a slower refresh rate. The
default is OFF (-norefreshspeed).
Core rotation options
---------------------
-[no]rotate
Rotate the game to match its normal state (horizontal/vertical). This
ensures that both vertically and horizontally oriented games show up
correctly without the need to rotate your monitor. If you want to keep
the game displaying 'raw' on the screen the way it would have in the
arcade, turn this option OFF. The default is ON (-rotate).
-[no]ror
-[no]rol
Rotate the game screen to the right (clockwise) or left (counter-
clockwise) relative to either its normal state (if -rotate is
specified) or its native state (if -norotate is specified). The
default for both of these options is OFF (-noror -norol).
-[no]autoror
-[no]autorol
These options are designed for use with pivoting screens that only
pivot in a single direction. If your screen only pivots clockwise,
use -autorol to ensure that the game will fill the screen either
horizontally or vertically in one of the directions you can handle.
If your screen only pivots counter-clockwise, use -autoror.
-[no]flipx
-[no]flipy
Flip (mirror) the game screen either horizontally (-flipx) or
vertically (-flipy). The flips are applied after the -rotate and
-ror/-rol options are applied. The default for both of these options
is OFF (-noflipx -noflipy).
Core artwork options
--------------------
-[no]artwork_crop / -[no]artcrop
Enable cropping of artwork to the game screen area only. This works
best with -video gdi or -video d3d, and means that vertically oriented
games running full screen can display their artwork to the left and
right sides of the screen. This does not work with -video ddraw
because of the way the game screens are rendered and scaled after the
fact. This option can also be controlled via the Video Options menu in
the user interface. The default is OFF (-noartwork_crop).
-[no]use_backdrops / -[no]backdrop
Enables/disables the display of backdrops. The default is ON
(-use_backdrops).
-[no]use_overlays / -[no]overlay
Enables/disables the display of overlays. The default is ON
(-use_overlays).
-[no]use_bezels / -[no]bezels
Enables/disables the display of bezels. The default is ON
(-use_bezels).
-[no]use_cpanels / -[no]cpanels
Enables/disables the display of control panels. The default is ON
(-use_cpanels).
-[no]use_marquees / -[no]marquees
Enables/disables the display of marquees. The default is ON
(-use_marquees).
Core screen options
-------------------
-brightness <value>
Controls the default brightness, or black level, of the game screens.
This option does not affect the artwork or other parts of the display.
Using the MAME UI, you can individually set the brightness for each
game screen; this option controls the initial value for all visible
game screens. The standard value is 1.0. Selecting lower values (down
to 0.1) will produce a darkened display, while selecting higher values
(up to 2.0) will give a brighter display. The default is 1.0.
-contrast <value>
Controls the contrast, or white level, of the game screens. This
option does not affect the artwork or other parts of the display.
Using the MAME UI, you can individually set the contrast for each
game screen; this option controls the initial value for all visible
game screens. The standard value is 1.0. Selecting lower values (down
to 0.1) will produce a dimmer display, while selecting higher values
(up to 2.0) will give a more saturated display. The default is 1.0.
-gamma <value>
Controls the gamma, which produces a potentially nonlinear black to
white ramp, for the game screens. This option does not affect the
artwork or other parts of the display. Using the MAME UI, you can
individually set the gamma for each game screen; this option controls
the initial value for all visible game screens. The standard value is
1.0, which gives a linear ramp from black to white. Selecting lower
values (down to 0.1) will increase the nonlinearity toward black,
while selecting higher values (up to 3.0) will push the nonlinearity
toward white. The default is 1.0.
-pause_brightness <value>
This controls the brightness level when MAME is paused. The default
value is 0.65.
-effect <filename>
Specifies a single PNG file that is used as an overlay over any game
screens in the video display. This PNG file is assumed to live in the
root of one of the artpath directories. The pattern in the PNG file is
repeated both horizontally and vertically to cover the entire game
screen areas (but not any external artwork), and is rendered at
the target resolution of the game image. For -video gdi and -video d3d
modes, this means that one pixel in the PNG will map to one pixel on
your output display. For -video ddraw, this means that one pixel in the
PNG will map to one pixel in the prescaled game screen. If you wish to
use an effect that requires mapping n PNG pixels to each game screen
pixel with -video ddraw, you need to specify a -prescale factor of n as
well. The RGB values of each pixel in the PNG are multiplied against the
RGB values of the target screen. The default is 'none', meaning no
effect.
Core vector options
-------------------
-[no]antialias / -[no]aa
Enables antialiased line rendering for vector games. The default is ON
(-antialias).
-beam <width>
Sets the width of the vectors. This is a scaling factor against the
standard vector width. A value of 1.0 will keep the default vector
line width. Smaller values will reduce the width, and larger values
will increase the width. The default is 1.0.
-flicker <value>
Simulates a vector "flicker" effect, similar to a vector monitor that
needs adjustment. This option requires a float argument in the range
of 0.00 - 100.00 (0=none, 100=maximum). The default is 0.
Core sound options
------------------
-samplerate <value> / -sr <value>
Sets the audio sample rate. Smaller values (e.g. 11025) cause lower
audio quality but faster emulation speed. Higher values (e.g. 48000)
cause higher audio quality but slower emulation speed. The default is
48000.
-[no]samples
Use samples if available. The default is ON (-samples).
-volume / -vol <value>
Sets the startup volume. It can later be changed with the user
interface (see Keys section). The volume is an attenuation in dB:
e.g., "-volume -12" will start with -12dB attenuation. The default
is 0.
Core input options
------------------
-[no]coin_lockout / -[no]coinlock
Enables simulation of the "coin lockout" feature that is implmeneted
on a number of game PCBs. It was up to the operator whether or not
the coin lockout outputs were actually connected to the coin
mechanisms. If this feature is enabled, then attempts to enter a coin
while the lockout is active will fail and will display a popup message
in the user interface (In debug mode). If this feature is disabled, the
coin lockout signal will be ignored. The default is ON (-coin_lockout).
-ctrlr <controller>
Enables support for special controllers. Configuration files are
loaded from the ctrlrpath. They are in the same format as the .cfg
files that are saved, but only control configuration data is read
from the file. The default is NULL (no controller file).
-[no]mouse
Controls whether or not MAME makes use of mouse controllers. When
this is enabled, you will likely be unable to use your mouse for other
purposes until you exit or pause the game. The default is OFF
(-nomouse).
-[no]joystick / -[no]joy
Controls whether or not MAME makes use of joystick/gamepad controllers.
When this is enabled, MAME will ask DirectInput about which
controllers are connected. The default is OFF (-nojoystick).
-[no]lightgun / -[no]gun
Controls whether or not MAME makes use of lightgun controllers.
Note that most lightguns map to the mouse, so using -lightgun and
-mouse together may produce strange results. The default is OFF
(-nolightgun).
-[no]multikeyboard / -[no]multikey
Determines whether MAME differentiates between multiple keyboards.
Some systems may report more than one keyboard; by default, the data
from all of these keyboards is combined so that it looks like a single
keyboard. Turning this option on will enable MAME to report keypresses
on different keyboards independently. The default is OFF
(-nomultikeyboard).
-[no]multimouse
Determines whether MAME differentiates between multiple mice. Some
systems may report more than one mouse device; by default, the data
from all of these mice is combined so that it looks like a single
mouse. Turning this option on will enable MAME to report mouse
movement and button presses on different mice independently. The
default is OFF (-nomultimouse).
-[no]steadykey / -[no]steady
Some games require two or more buttons to be pressed at exactly the
same time to make special moves. Due to limitations in the keyboard
hardware, it can be difficult or even impossible to accomplish that
using the standard keyboard handling. This option selects a different
handling that makes it easier to register simultaneous button presses,
but has the disadvantage of making controls less responsive. The
default is OFF (-nosteadykey)
-[no]ui_active
Enable user interface on top of emulated keyboard (if present). The
default if OFF (-noui_active)
-[no]offscreen_reload / -[no]reload
Controls whether or not MAME treats a second button input from a
lightgun as a reload signal. In this case, MAME will report the gun's
position as (0,MAX) with the trigger held, which is equivalent to an
offscreen reload. This is only needed for games that required you to
shoot offscreen to reload, and then only if your gun does not support
off screen reloads. The default is OFF (-nooffscreen_reload).
-joystick_map <map> / -joymap <map>
Controls how joystick values map to digital joystick controls. MAME
accepts all joystick input from the system as analog data. For true
analog joysticks, this needs to be mapped down to the usual 4-way or
8-way digital joystick values. To do this, MAME divides the analog
range into a 9x9 grid. It then takes the joystick axis position (for
X and Y axes only), maps it to this grid, and then looks up a
translation from a joystick map. This parameter allows you to specify
the map. The default is 'auto', which means that a standard 8-way,
4-way, or 4-way diagonal map is selected automatically based on the
input port configuration of the current game.
Maps are defined as a string of numbers and characters. Since the grid
is 9x9, there are a total of 81 characters necessary to define a
complete map. Below is an example map for an 8-way joystick:
777888999 Note that the numeric digits correspond to the keys
777888999 on a numeric keypad. So '7' maps to up+left, '4' maps
777888999 to left, '5' maps to neutral, etc. In addition to the
444555666 numeric values, you can specify the character 's',
444555666 which means "sticky". In this case, the value of the
444555666 map is the same as it was the last time a non-sticky
111222333 value was read.
111222333
111222333
To specify the map for this parameter, you can specify a string of
rows separated by a '.' (which indicates the end of a row), like so:
777888999.777888999.777888999.444555666.444555666.444555666.
111222333.111222333.111222333
However, this can be reduced using several shorthands supported by the
<map> parameter. If information about a row is missing, then it is
assumed that any missing data in columns 5-9 are left/right symmetric
with data in columns 0-4; and any missing data in colums 0-4 is
assumed to be copies of the previous data. The same logic applies to
missing rows, except that up/down symmetry is assumed.
By using these shorthands, the 81 character map can be simply
specified by this 11 character string: 7778...4445
Looking at the first row, 7778 is only 4 characters long. The 5th
entry can't use symmetry, so it is assumed to be equal to the previous
character '8'. The 6th character is left/right symmetric with the 4th
character, giving an '8'. The 7th character is left/right symmetric
with the 3rd character, giving a '9' (which is '7' with left/right
flipped). Eventually this gives the full 777888999 string of the row.
The second and third rows are missing, so they are assumed to be
identical to the first row. The fourth row decodes similarly to the
first row, producing 444555666. The fifth row is missing so it is
assumed to be the same as the fourth.
The remaining three rows are also missing, so they are assumed to be
the up/down mirrors of the first three rows, giving three final rows
of 111222333.
-joystick_deadzone <value> / -joy_deadzone <value> / -jdz <value>
If you play with an analog joystick, the center can drift a little.
joystick_deadzone tells how far along an axis you must move before the
axis starts to change. This option expects a float in the range of
0.0 to 1.0. Where 0 is the center of the joystick and 1 is the outer
limit. The default is 0.3.
-joystick_saturation <value> / joy_saturation <value> / -jsat <value>
If you play with an analog joystick, the ends can drift a little,
and may not match in the +/- directions. joystick_saturation tells how
far along an axis movement change will be accepted before it reaches
the maximum range. This option expects a float in the range of 0.0 to
1.0, where 0 is the center of the joystick and 1 is the outer limit.
The default is 0.85.
-natural
Allows user to specify whether or not to use a natural keyboard or not.
This allows you to start your game or system in a 'native' mode, depending
on your region, allowing compatability for non-"QWERTY" style keyboards.
The default is OFF (-nonatrual)
-joystick_contradictory
Enable contradictory direction digital joystick input at the same time
such as Left and Right or Up and Down at the same time. The default
is OFF (-nojoystick_contradictory)
-coin_impulse [n]
Set coin impulse time based on n (n<0 disable impulse, n==0 obey driver,
0<n set time n). Default is 0.
Core input automatic enable options
-----------------------------------
-paddle_device enable (none|keyboard|mouse|lightgun|joystick) if a paddle control is present
-adstick_device enable (none|keyboard|mouse|lightgun|joystick) if an analog joystick control is present
-pedal_device enable (none|keyboard|mouse|lightgun|joystick) if a pedal control is present
-dial_device enable (none|keyboard|mouse|lightgun|joystick) if a dial control is present
-trackball_device enable (none|keyboard|mouse|lightgun|joystick) if a trackball control is present
-lightgun_device enable (none|keyboard|mouse|lightgun|joystick) if a lightgun control is present
-positional_device enable (none|keyboard|mouse|lightgun|joystick) if a positional control is present
-mouse_device enable (none|keyboard|mouse|lightgun|joystick) if a mouse control is present
Each of these options controls autoenabling the mouse, joystick, or
lightgun depending on the presence of a particular class of analog
control for a particular game. For example, if you specify the option
-paddle mouse, then any game that has a paddle control will
automatically enable mouse controls just as if you had explicitly
specified -mouse. Note that these controls override the values of
-[no]mouse, -[no]joystick, etc.
Debugging options
-----------------
-[no]verbose / -[no]v
Displays internal diagnostic information. This information is very
useful for debugging problems with your configuration. IMPORTANT: when
reporting bugs, please run with mame -verbose and include the
resulting information. The default is OFF (-noverbose).
-[no]oslog
Output error.log data to the system debugger. The default is OFF
(-nooslog).
-[no]log
Creates a file called error.log which contains all of the internal
log messages generated by the MAME core and game drivers. The default
is OFF (-nolog).
-[no]debug
Activates the integrated debugger. By default, the debugger is entered
by pressing the tilde (~) key during emulation. It is also entered
immediately at startup. The default is OFF (-nodebug).
-debugscript <filename>
Specifies a file that contains a list of debugger commands to execute
immediately upon startup. The default is NULL (no commands).
-[no]update_in_pause
Enables updating of the main screen bitmap while the game is paused.
This means that the VIDEO_UPDATE callback will be called repeatedly
during pause, which can be useful for debugging. The default is OFF
(-noupdate_in_pause).
Core communication options
--------------------------
-comm_localhost <string>
Local address to bind to. This can be a traditional xxx.xxx.xxx.xxx
address or a string containing a resolvable hostname. The default is
value is "0.0.0.0"
-comm_localport <string>
Local port to bind to. This can be any traditional communications port
as an unsigned 16-bit integer (0-65535). The default value is "15122".
-comm_remotehost <string>
Remote address to connect to. This can be a traditional xxx.xxx.xxx.xxx
address or a string containing a resolvable hostname. The default is
value is "0.0.0.0"
-comm_remoteport <string>
Remote port to connect to. This can be any traditional communications port
as an unsigned 16-bit integer (0-65535). The default value is "15122".
Core misc options
-----------------
-[no]drc
Enable DRC cpu core if available. The default is ON (-drc).
-drc_use_c
Force DRC use the C code backend. The default is OFF
(-nodrc_use_c).
-drc_log_uml
Write DRC UML disassembly log. The default is OFF
(-nodrc_log_uml).
-drc_log_native
write DRC native disassembly log. The default is OFF
(-nodrc_log_native).
-bios <biosname>
Specifies the specific BIOS to use with the current game, for game
systems that make use of a BIOS. The -listxml output will list all of
the possible BIOS names for a game. The default is 'default'.
-[no]cheat / -[no]c
Enables the reading of the cheat database, if present, and the Cheat
menu in the user interface. The default is OFF (-nocheat).
-[no]skip_gameinfo
Forces MAME to skip displaying the game info screen. The default is
OFF (-noskip_gameinfo).
-uifont <fontname>
Specifies the name of a font file to use for the UI font. If this font
cannot be found or cannot be loaded, the system will fall back to its
built-in UI font. On some platforms 'fontname' can be a system font
name (TTF) instead of a (BDF) font file. The default is 'default' (use
the OSD-determined default font).
-ramsize [n]
Allows you to change the default RAM size (if supported by driver).
-confirm_quit
Display a Confirm Quit dialong to screen on exit, requiring one extra
step to exit MAME. The default is OFF (-noconfirm_quit).
-ui_mouse
Displays a mouse cursor when using the built-in UI for MAME. The default
is (-noui_mouse).
-autoboot_command "<command>"
Command string to execute after machine boot (in quotes " "). To issue
a quote to the emulation, use """ in the string. Using \n will issue a
create a new line, issuing what was typed prior as a command.
Example: -autoboot_command "load """$""",8,1\n"
-autoboot_delay [n]
Timer delay (in seconds) to trigger command execution on autoboot.
-autoboot_script / -script [filename.lua]
File containing scripting to execute after machine boot.
The new floppy subsystem
------------------------
1. Introduction
The new floppy subsystem aims at emulating the behaviour of floppies
and floppy controllers at a level low enough that protections work as
a matter of course. It reaches its goal by following the real
hardware configuration:
- a floppy image class keeps in memory the magnetic state of the
floppy surface and its physical characteristics
- an image handler class talks with the floppy image class to simulate
the floppy drive, providing all the signals you have on a floppy drive
connector
- floppy controller devices talk with the image handler and provide
the register interfaces to the host we all know and love
- format handling classes are given the task of statelessly converting
to and from an on-disk image format to the in-memory magnetic state
format the floppy image class manages
2. Floppy storage 101
2.1. Floppy disk
A floppy disk is a disc that stores magnetic orientations on their
surface disposed in a series on concentric circles called tracks or
cylinders[1]. Its main characteristics are its size (goes from a
diameter of around 2.8" to 8") , its number of writable sides (1 or 2)
and its magnetic resistivity. The magnetic resistivity indicates how
close magnetic orientation changes can happen and the information
kept. That's one third of what defines the term "density" that is so
often used for floppies (the other two are floppy drive head size and
bit-level encoding).
The magnetic orientations are always binary, e.g. they're one way or
the opposite, there's no intermediate state. Their direction can
either be tengentially to the track, e.g in the direction or opposite
to the rotation, or in the case of perpendicular recording the
direction is perpendicular to the disc surface (hence the name).
Perpendicular recording allows for closer orientation changes by
writing the magnetic information more deeply, but arrived late in the
technology lifetime. 2.88Mb disks and the floppy children (Zip
drives, etc) used perpendicular recording. For simulation purposes
the direction is not important, only the fact that only two
orientations are possible is. Two more states are possible though: a
portion of a track can be demagnetized (no orientation) or damaged (no
orientation and can't be written to).
A specific position in the disk rotation triggers an index pulse.
That position can be detected through a hole in the surface (very
visible in 5.25" and 3" floppies for instance) or through a specific
position of the rotating center (3.5" floppies, perhaps others). This
index pulse is used to designate the beginning of the track, but is
not used by every system. Older 8" floppies have multiple index holes
used to mark the beginning of sectors (called hard sectoring) but one
of them is positioned differently to be recognized as the track start,
and the others are at fixed positions relative to the origin one.
2.2 Floppy drive
A floppy drive is what reads and writes a floppy disk. It includes an
assembly capable of rotating the disk at a fixed speed and one or two
magnetic heads tied to a positioning motor to access the tracks.
The head width and positioning motor step size decides how many tracks
are written on the floppy. Total number of tracks goes from 32 to 84
depending on the floppy and drive, with the track 0 being the most
exterior (longer) one of the concentric circles, and the highest
numbered the smallest interior circle. As a result the tracks with
the lowest numbers have the lowest physical magnetic orientation
density, hence the best reliability. Which is why important and/or
often changed structures like the boot block or the fat allocation
table are at track 0. That is also where the terminology "stepping
in" to increase the track number and "stepping out" to decrease it
comes from. The number of tracks available is the second part of what
is usually behind the term "density".
A sensor detects when the head is on track 0 and the controller is not
supposed to try to go past it. In addition physical blocks prevent
the head from going out of the correct track range. Some systems
(Apple II, some C64) do not take the track 0 sensor into account and
just wham the head against the track 0 physical block, giving a
well-known crash noise and eventually damaging the head alignment.
Also, some systems (Apple II and C64 again) have direct access to the
phases of the head positioning motor, allowing to trick the head into
going between tracks, in middle or even quarter positions. That was
not usable to write more tracks, since the head width did not change,
but since reliable reading was only possible with the correct position
it was used for some copy protection systems.
The disk rotates at a fixed speed for a given track. The most usual
speed is 300 rpm for every track, with 360 rpm found for HD 5.25"
floppies and most 8" ones, and a number of different values like 90 rpm
for the earlier floppies or 150 rpm for an HD floppy in an Amiga.
Having a fixed rotational speed for the whole disk is called Constant
Angular Velocity (CAV, almost everybody) or Zoned Constant Angular
Velocity (ZCAV, C64) depending on whether the read/write bitrate is
constant or track-dependant. Some systems (Apple II, Mac) vary the
rotational speed depending on the track (something like 394 rpm up to
590 rpm) to end up with a Constant Linear Velocity (CLV). The idea
behind ZCAV/CLV is to get more bits out of the media by keeping the
minimal spacing between magnetic orientation transitions close to the
best the support can do. It seems that the complexity was not deemed
worth it since almost no system does it.
Finally, after the disc rotates and the head is over the proper track
reading happens. The reading is done through an inductive head, which
gives it the interesting characteristic of not reading the magnetic
orientation directly but instead of being sensitive to orientation
inversions, called flux transitions. This detection is weak and
somewhat uncalibrated, so an amplifier with Automatic Gain Calibration
(AGC) and a peak detector are put behind the head to deliver clean
pulses. The AGC slowly increases the amplification level until a
signal goes over the threshold, then modulates its gain so that said
signal is at a fixed position over the threshold. Afterwards the
increase happens again. This makes the amplifier calibrate itself to
the signals read from the floppy as long as flux transitions happen
often enough. Too long and the amplification level will reach a point
where the random noise the head picks from the environment is
amplified over the threshold, creating a pulse where none should be.
Too long in our case happens to be around 16-20us with no transitions.
That means a long enough zone with a fixed magnetic orientation or no
orientation at all (demagnetized or damaged) is going to be read as a
series of random pulses after a brief delay. This is used by
protections and is known as "weak bits", which read differently each
time they're accessed.
A second level of filtering happens after the peak detector. When two
transitions are a little close (but still over the media threshold) a
bouncing effect happens between them giving two very close pulses in
the middle in addition to the two normal pulses. The floppy drive
detects when pulses are too close and filter them out, leaving the
normal ones. As a result, if one writes a train of high-frequency
pulses to the floppy they will be read back as a train of too close
pulses (weak because they're over the media tolerance, but picked up
by the AGC anyway, only somewhat unreliably) they will be all filtered
out, giving a large amount of time without any pulse in the output
signal. This is used by some protections since it's not writable with
a normally clocked controller.
Writing is symmetrical, with a series of pulses sent which make the
write head invert the magnetic field orientation each time a pulse is
received.
So, in conclusion, the floppy drive provides inputs to control disk
rotation and head position (and choice when double-sided), and the
data goes both way as a train of pulses representing magnetic
orientation inversions. The absolute value of the orientation itself
is never known.
2.3 Floppy controller
The task of the floppy controller is to turn the signals to/from the
floppy drive into something the main CPU can digest. The level of
support actually done by the controller is extremely variable from one
device to the other, from pretty much nothing (Apple II, C64) through
minimal (Amiga) to complete (Western Digital chips, uPD765 family).
Usual functions include drive selection, motor control, track seeking
and of course reading and writing data. Of these only the last two
need to be described, the rest is obvious.
The data is structured at two levels: how individual bits (or nibbles,
or bytes) are encoded on the surface, and how these are grouped in
individually-addressable sectors. Two standards exist for these,
called FM and MFM, and in addition a number of systems use their
home-grown variants. Moreover, some systems such as the Amiga use a
standard bit-level encoding (MFM) but a homegrown sector-level
organisation.
2.3.1 Bit-level encodings
2.3.1.1 Cell organization
All floppy controllers, even the wonkiest like the Apple II one, start
by dividing the track in equally-sized cells. They're angular
sections in the middle of which a magnetic orientation inversion may
be present. From a hardware point of view the cells are seen as
durations, which combined with the floppy rotation give the section.
For instance the standard MFM cell size for a 3" double-density floppy
is 2us, which combined with the also standard 300 rpm rotational speed
gives an angular size of 1/100000th of a turn. Another way of saying
it is that there are 100K cells in a 3" DD track.
In every cell there may or may not be a magnetic orientation
transition, e.g. a pulse coming from (reading) or going to (writing)
the floppy drive. A cell with a pulse is traditionally noted '1', and
one without '0'. Two constraints apply to the cell contents though.
First, pulses must not be too close together or they'll blur
each-other and/or be filtered out. The limit is slightly better than
1/50000th of a turn for single and double density floppies, half that
for HD floppys, and half that again for ED floppies with perpendicular
recording. Second, they must not be too away from each other or
either the AGC is going to get wonky and introduce phantom pulses or
the controller is going to lose sync and get a wrong timing on the
cells on reading. Conservative rule of thumb is not to have more than
three consecutive '0' cells.
Of course protections play with that to make formats not reproducible
by the system controller, either breaking the three-zeroes rule or
playing with the cells durations/sizes.
Bit endocing is then the art of transforming raw data into a cell 0/1
configuration that respects the two constraints.
2.3.1.2 FM encoding
The very first encoding method developed for floppies is called
Frequency Modulation, or FM. The cell size is set at slighly over the
physical limit, e.g. 4us. That means it is possible to reliably have
consecutive '1' cells. Each bit is encoded on two cells:
- the first cell, called the clock bit, is '1'
- the second cell, called data bit, is the bit
Since every other cell at least is '1' there is no risk of going over
three zeroes.
The name Frequency Modulation simply derives from the fact that a 0 is
encoded with one period of a 125Khz pulse train while a 1 is two
periods of a 250Khz pulse train.
2.3.1.3 MFM encoding
The FM encoding has been superseded by the Modified Frequency
Modulation encoding, which can cram exactly twice as much data on the
same surface, hence its other name of "double density". The cell size
is set at slightly over half the physical limit, e.g. 2us usually.
The constraint means that two '1' cells must be separated by at least
one '0' cell. Each bit is once again encoded on two cells:
- the first cell, called the clock bit, is '1' if both the previous
and current data bits are 0, '0' otherwise
- the second cell, called data bit, is the bit
The minimum space rule is respected since a '1' clock bit is by
definition surrounded by two '0' data bits, and a '1' data bit is
surrounded by two '0' clock bits. The longest '0'-cell string
possible is when encoding 101 which gives x10001, respecting the
maximum of three zeroes.
2.3.1.4 GCR encodings
Group Coded Recording, or GCR, encodings are a class of encodings
where strings of bits at least nibble-size are encoded into a given
cell stream given by a table. It has been used in particular by the
Apple II, the Mac and the C64, and each system has its own table, or
tables.
2.3.1.5 Other encodings
Other encodings exist, like M2FM, but they're very rare and
system-specific.
2.3.1.6 Reading back encoded data
Writing encoded data is easy, you only need a clock at the appropriate
frequency and send or not a pulse on the clock edges. Reading back
the data is where the fun is. Cells are a logical construct and not a
physical measurable entity. Rotational speeds very around the defined
one (+/- 2% is not rare) and local perturbations (air turbulence,
surface distance...) make the instant speed very variable in general.
So to extract the cell values stream the controller must dynamically
synchronize with the pulse train that the floppy head picks up. The
principle is simple: a cell-sized duration window is build within
which the presence of at least one pulse indicates the cell is a '1',
and the absence of any a '0'. After reaching the end of the window
the starting time is moved appropriately to try to keep the observed
pulse at the exact middle of the window. This allows to correct the
phase on every '1' cell, making the synchronization work if the
rotational speed is not too off. Subsequent generations of
controllers used a Phase-Locked Loop (PLL) which vary both phase and
window duration to adapt better to wrong rotational speeds, with
usually a tolerance of +/- 15%.
Once the cell data stream is extracted decoding depends on the
encoding. In the FM and MFM case the only question is to recognize
data bits from clock bits, while in GCR the start position of the
first group should be found. That second level of synchronization is
handled at a higher level using patterns not found in a normal stream.
2.3.2 Sector-level organization
Floppies have been designed for read/write random access to reasonably
sized blocks of data. Track selection allows for a first level of
random access and sizing, but the ~6K of a double density track would
be too big a block to handle. 256/512 bytes are considered a more
appropriate value. To that end data on a track is organized as a
series of (sector header, sector data) pairs where the sector header
indicates important information like the sector number and size, and
the sector data contains the data. Sectors have to be broken in two
parts because while reading is easy, read the header then read the
data if you want it, writing requires reading the header to find the
correct place then once that is done switching on the writing head for
the data. Starting writing is not instantaneous and will not be
perfectly phase-aligned with the read header, so space for
synchronization is required between header and data.
In addition somewhere in the sector header and in the sector data are
pretty much always added some kind of checksum allowing to know
whether the data was damaged or not.
FM and MFM have (not always used) standard sector layout methods.
2.3.2.1 FM sector layout
The standard "PC" track/sector layout for FM is as such:
- A number of FM-encoded 0xff (usually 40)
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111011101111010 (f77a, clock 0xd7, data 0xfc)
- A number of FM-encoded 0xff (usually 26, very variable)
Then for each sector:
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111010101111110 (f57e, clock 0xc7, data 0xfe)
- Sector header, e.g. FM encoded track, head, sector, size code and two bytes of crc
- 11 FM-encoded 0xff
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111010101101111 (f56f, clock 0xc7, data 0xfb)
- FM-encoded sector data followed by two bytes of crc
- A number of FM-encoded 0xff (usually 48, very variable)
The track is finished with a stream of '1' cells.
The 125KHz pulse trains are used to lock the PLL to the signal
correctly. The specific 16-cells streams allow to distinguish between
clock and data bits by providing a pattern that is not supposed to
happen in normal FM-encoded data. In the sector header track numbers
start at 0, heads are 0/1 depending on the size, sector numbers
usually start at 1 and size code is 0 for 128 bytes, 1 for 256, 2 for
512, etc.
The crc is a cyclic redundancy check of the data bits starting with
the mark just after the pulse train using polynom 0x11021.
The Western Digital-based controllers usually get rid of everything
but some 0xff before the first sector and allow a better use of space
as a result.
2.3.2.2 MFM sector layout
The standard "PC" track/sector layout for MFM is as such:
- A number of MFM-encoded 0x4e (usually 80)
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0101001000100100 (5224, clock 0x14, data 0xc2)
- The MFM-encoded value 0xfc
- A number of MFM-encoded 0x4e (usually 50, very variable)
Then for each sector:
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
- Sector header, e.g. MFM-encoded 0xfe, track, head, sector, size code and two bytes of crc
- 22 MFM-encoded 0x4e
- 12 MFM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
- MFM-encoded 0xfb, sector data followed by two bytes of crc
- A number of MFM-encoded 0x4e (usually 84, very variable)
The track is finished with a stream of MFM-encoded 0x4e.
The 250KHz pulse trains are used to lock the PLL to the signal
correctly. The cell pattern 4489 does not appear in normal
MFM-encoded data and is used for clock/data separation.
As for FM, the Western Digital-based controllers usually get rid of
everything but some 0x4e before the first sector and allow a better
use of space as a result.
2.3.2.3 Formatting and write splices
To be usable, a floppy must have the sector headers and default sector
data written on every track before using it. The controller starts
writing at a given place, often the index pulse but on some systems
whenever the command is sent, and writes until a complete turn is
done. That's called formatting the floppy. At the point where the
writing stops there is a synchronization loss since there is no chance
the cell stream clock warps around perfectly. This brutal phase
change is called a write splice, specifically the track write splice.
It is the point where writing should start if one wants to raw copy
the track to a new floppy.
Similarly two write splices are created when a sector is written at
the start and end of the data block part. They're not supposed to
happen on a mastered disk though, even if there are some rare
exceptions.
3 The new implementation
3.1 Floppy disk representation
Th floppy disk contents are represented by the class floppy_image. It
contains information of the media type and a representation of the
magnetic state of the surface.
The media type is divided in two parts. The first half
indicates the physical form factor, i.e. all medias with that
form factor can be physically inserted in a reader that handles
it. The second half indicates the variants which are usually
detectable by the reader, such as density and number of sides.
Track data consists of a series of 32-bits lsb-first values
representing magnetic cells. Bits 0-27 indicate the absolute
position of the start of the cell (not the size), and bits
28-31 the type. Type can be:
- 0, MG_A -> Magnetic orientation A
- 1, MG_B -> Magnetic orientation B
- 2, MG_N -> Non-magnetized zone (neutral)
- 3, MG_D -> Damaged zone, reads as neutral but cannot be changed by writing
The position is in angular units of 1/200,000,000th of a turn. It
corresponds to one nanosecond when the drive rotates at 300 rpm.
The last cell implicit end position is of course 200,000,000.
Unformatted tracks are encoded as zero-size.
The "track splice" information indicates where to start writing
if you try to rewrite a physical disk with the data. Some
preservation formats encode that information, it is guessed for
others. The write track function of fdcs should set it. The
representation is the angular position relative to the index.
3.2 Converting to and from the internal representation
3.2.1 Class and interface
We need to be able to convert on-disk formats of the floppy data to
and from the internal representation. This is done through classes
derived from floppy_image_format_t. The interface to be implemented
includes:
- name() gives the short name of the on-disk format
- description() gives a short description of the format
- extensions() gives a comma-separated list of file name extensions
found for that format
- supports_save() returns true is converting to that external format
is supported
- identify(file, form factor) gives a 0-100 score for the file to be
of that format:
- 0 = not that format
- 100 = certainly that format
- 50 = format identified from file size only
- load(file, form factor, floppy_image) loads an image and converts it
into the internal representation
- save(file, floppy_image) (if implemented) converts from the internal
representation and saves an image
All these methods are supposed to be stateless.
3.2.2 Conversion helper methods
A number of methods are provided to simplify writing the converter
classes.
3.2.2.1 Load-oriented conversion methods
generate_track_from_bitstream(track number,
head number,
UINT8 *cell stream,
int cell count,
floppy image)
Takes a stream of cell types (0/1), MSB-first, converts it to the
internal format and stores it at the given track and head in the
given image.
generate_track_from_levels(track number,
head number,
UINT32 *cell levels,
int cell count,
splice position,
floppy image)
Takes a variant of the internal format where each value represents a
cell, the position part of the values is the size of the cell and
the level part is MG_0, MG_1 for normal cell types, MG_N, MG_D for
unformatted/damaged cells, and MG_W for Dungeon-Master style weak
bits. Converts it into the internal format. The sizes are
normalized so that they total to a full turn.
normalize_times(UINT32 *levels,
int level_count)
Takes an internal-format buffer where the position part represents
angle until the next change and turns it into a normal positional
stream, first ensuring that the total size is normalized to a full
turn.
3.2.2.2 Save-oriented conversion methods
generate_bitstream_from_track(track number,
head number,
base cell size,
UINT8 *cell stream,
int &cell_stream_size,
floppy image)
Extract a cell 0/1 stream from the internal format using a PLL setup
with an initial cell size set to 'base cell size' and a +/- 25%
tolerance.
struct desc_xs { int track, head, size; const UINT8 *data }
extract_sectors_from_bitstream_mfm_pc(...)
extract_sectors_from_bitstream_fm_pc(const UINT8 *cell stream,
int cell_stream_size,
desc_xs *sectors,
UINT8 *sectdata,
int sectdata_size)
Extract standard mfm or fm sectors from a regenerated
cell stream. Sectors must point to an array of 256 desc_xs.
An existing sector is recognizable by having ->data non-null.
Sector data is written in sectdata up to sectdata_size bytes.
get_geometry_mfm_pc(...)
get_geometry_fm_pc(floppy image,
base cell size,
int &track_count,
int &head_count,
int §or_count)
Extract the geometry (heads, tracks, sectors) from a pc-ish floppy
image by checking track 20.
get_track_data_mfm_pc(...)
get_track_data_fm_pc(track number,
head number,
floppy image,
base cell size,
sector size,
sector count,
UINT8 *sector data)
Extract what you'd get by reading in order 'sector size'-sized
sectors from number 1 to sector count and put the result in sector
data.
3.3 Floppy drive
The class floppy_image_interface simulates the floppy drive. That
includes a number of control signals, reading, and writing. Control
signal changes must be synchronized, e.g. fired off a timer to ensure
the current time is the same for all devices.
3.3.1 Control signals
Due to the way they're usually connected to CPUs (e.g. directly on an
I/O port), the control signals work with physical instead of logical
values. Which means than in general 0 means active, 1 means inactive.
Some signals also have a callback associated called when they change.
mon_w(state) / mon_r()
Motor on signal, rotates on 0.
idx_r() / setup_index_pulse_cb(cb)
Index signal, goes 0 at start of track for about 2ms. Callback is
synchronized. Only happens when a disk is in and the motor is
running.
ready_r() / setup_ready_cb(cb)
Ready signal, goes to 1 when the disk is removed or the motor
stopped. Goes to 0 after two index pulses.
wpt_r() / setup_wpt_cb(cb)
Write protect signal (1 = readonly). Callback is unsynchronized.
dskchg_r()
Disk change signal, goes to 1 when a disk is change, goes to 0 on
track change.
dir_w(dir)
Selects track stepping direction (1 = out = decrease track number).
stp_w(state)
Step signal, moves by one track on 1->0 transistion.
trk00_r()
Track 0 sensor, returns 0 when on track 0.
ss_w(ss) / ss_r()
Side select
3.3.2 Read/write interface
The read/write interface is designed to work asynchronously,
e.g. somewhat independently of the current time.
[1] Cylinder is a hard-drive term somewhat improperly used for
floppies. It comes from the fact that hard-drives are similar to
floppies but include a series of stacked disks with a read/write head
on each. The heads are physically linked and all point to the same
circle on every disk at a given time, making the accessed area look
like a cylinder. Hence the name.
HLSL-Related Enable Switches
----------------------------
Name Values Description
hlsl_enable 0/1 Enables HLSL post-processing in Direct3D 9 modes.
yiq_enable 0/1 Enables YIQ-colorspace post-processing. Causes a
performance drop but gives a much more authentic
NTSC TV appearance on TV-based systems when configured
properly.
hlslpath [path] Path to the .fx files that are in use. (default: hlsl)
hlsl_prescale_x [horizontal] HLSL pre-scale override factor for X. (0 for auto)
hlsl_prescale_y [vertical] HLSL pre-scale override factor for Y. (0 for auto)
hlsl_preset -1 through 3 HLSL preset to use. (default: -1)
hlsl_write [filename] Enable HLSL AVI writing. (huge disk bandwidth suggested)
hlsl_snap_width [width] HLSL upscaled-snapshot width. (default: 2048)
hlsl_snap_height [height] HLSL upscaled-snapshot height. (default: 1536)
Surface/Color Processing Parameters
-----------------------------------
Name Values Description
shadow_mask_alpha 0.0 to 1.0 The ovearll darkness of each shadow mask pixel.
shadow_mask_texture [filename] A PNG that defines the shadow mask for each pixel.
shadow_mask_x_count 1+ The count of shadow mask elements, X (usually 640-ish).
shadow_mask_y_count 1+ The count of shadow mask elements, Y (usually 480-ish).
shadow_mask_usize 0.0 to 1.0 These parameters define the *in-use* pixel count on the
shadow_mask_vsize 0.0 to 1.0 X and Y axes of the shadow mask texture.
curvature 0.0 to 1.0 Screen curvature. Affects borders and shadow mask.
pincushion 0.0 to 1.0 Image curvature. Affects the source image only.
scanline_alpha 0.0 to 1.0 The overall darkness of each scanline furrow.
scanline_size 0.0 to 4.0 The overall height of each scanline.
scanline_height [height] Individual height scaling value for scanlines.
scanline_bright_scale 0.0 to 2.0 The overall brightness multiplier for each scanline.
scanline_bright_offset 0.0 to 1.0 The overall brightness additive value for each scanline.
scanline_jitter 0.0 to 2.0 The relative scanline movement per field.
defocus [xval,yval] This defines the overall defocus radius for the three
post-converged beams. Values allowed range from 0.0 to
32.0.
converge_x [r,g,b] Convergence in screen-relative X direction.
converge_y [r,g,b] Convergence in screen-relative Y direction.
radial_converge_x [r,g,b] Radial convergence in screen-relative X direction.
radial_converge_y [r,g,b] Radial convergence in screen-relative Y direction.
Allowed values for convergence: -150 to 150 for each color.
red_ratio [r,g,b] These parameters define a 3x3 matrix which is multiplied
grn_ratio [r,g,b] by the incoming RGB signal. This can be used for any
blu_ratio [r,g,b] standard matrix convolution, including H/S/V or simply
affecting the TV-style tint.
saturation 0.0 to 4.0 This parameter defines the amount each color channel is
raised above said channel's baseline grayscale value.
A value of 0.0 gives a gamma-correct grayscale image,
whereas 1.0 is full saturation, with each channel being
oversaturated equally beyond that.
offset [r,g,b] These parameters define a value for each color channel
that is added to said channel after scaling and after
matrix convolution. (-2.0 to 2.0)
scale [r,g,b] These parameters define a value for each color channel
that is multiplied with said channel after matrix
convolution. (-2.0 to 2.0)
power [r,g,b] These parameters define the exponent for each color
channel that is applied after scaling, offsetting,
saturation and matrix convolution. (-4.0 to 4.0)
floor [r,g,b] These parameters define the lower limit of each final
color channel value; 0.05, for example, raises the
minimum to 0.05 but re-scales to leave the max at 1.0.
phosphor_life [r,g,b] These parameters define the phosphor lifetime for each
channel, with 0.0 representing no phosphorescence and
1.0 leaving the channel on indefinitely. Values allowed
range from 0.0 to 1.0.
NTSC Processing Parameters
--------------------------
Name Default Values Description
yiq_cc 3.59754545 Color Carrier frequency for NTSC signal processing.
yiq_a 0.5 A value for NTSC signal processing.
yiq_b 0.5 B value for NTSC signal processing.
yiq_o 0.0 Outgoing Color Carrier phase offset for NTSC signal processing.
yiq_p 1.0 Incoming Pixel Clock scaling value for NTSC signal processing.
yiq_n 1.0 Y filter notch width for NTSC signal processing.
yiq_y 6.0 Y filter cutoff frequency for NTSC signal processing.
yiq_i 1.2 I filter cutoff frequency for NTSC signal processing.
yiq_q 0.6 Q filter cutoff frequency for NTSC signal processing.
yiq_scan_time 52.6 Horizontal scanline duration for NTSC signal processing. (usec)
yiq_phase_count 2 Phase Count value for NTSC signal processing. (3 for NES, else 2)
Vector Post-Processing Options
------------------------------
Name Default Values Description
vector_length_scale 0.8 How much length affects vector fade. (0.00-1.00)
vector_length_ratio 500.0 Vector fade length (4.0 - vectors fade the most at and above 4
pixels, etc.) (0.000 - 1000.000)
Bloom Post-Processing Options
-----------------------------
Name Default Values Description
vector_bloom_scale 0.300 Intensity factor for vector bloom. (0.000-1.000)
raster_bloom_scale 0.225 Intensity factor for raster bloom. (0.000-1.000)
bloom_lvl0_weight 1.00 Bloom level 0 (full-size target) weight. (0.00-1.00)
bloom_lvl1_weight 0.21 Bloom level 1 (half-size target) weight. (0.00-1.00)
bloom_lvl2_weight 0.19 Bloom level 2 (quarter-size target) weight. (0.00-1.00)
bloom_lvl3_weight 0.17 Bloom level 3 (.) weight. (0.00-1.00)
bloom_lvl4_weight 0.14 Bloom level 4 (.) weight. (0.00-1.00)
bloom_lvl5_weight 0.14 Bloom level 5 (.) weight. (0.00-1.00)
bloom_lvl6_weight 0.13 Bloom level 6 (.) weight. (0.00-1.00)
bloom_lvl7_weight 0.12 Bloom level 7 (.) weight. (0.00-1.00)
bloom_lvl8_weight 0.11 Bloom level 8 (.) weight. (0.00-1.00)
bloom_lvl9_weight 0.10 Bloom level 9 (.) weight. (0.00-1.00)
bloom_lvl10_weight 0.09 Bloom level 10 (1x1 target) weight. (0.00-1.00)
Imgtool - A generic image manipulation tool for MESS
Imgtool is a tool for the maintenance and manipulation of disk and other types
of images that MESS users need to deal with. Functions include retrieving and
storing files and CRC checking/validation.
Imgtool is part of the MESS project. It shares large portions of code with
MESS/MAME, and its existence would not be if it were not for MESS. As such,
the distribution terms are the same as MESS. Please read mess.txt thoroughly.
Some portions in Imgtool is Copyright (c) 1989, 1993 The Regents of the
University of California. All rights reserved.
Using Imgtool
=============
Imgtool is a command line program that contains several "subcommands" that
actually do all of the work. Most commands are invoked in a manner along the
lines of this:
imgtool <subcommand> <format> <image> ...
<subcommand> is the name of the subcommand
<format> is the format of the image
<image> is the filename of the image
Further details vary with each subcommand. Also note that not all subcommands
are applicable or supported for different image formats.
Certain Imgtool subcommands (info, crc, good) make use of the CRC files, so if
you use these commands, make sure that your CRC directory is set up.
Imgtool Subcommands
===================
create Creates an image
dir Lists the contents of an image
get Gets a single file from an image
put Puts a single file on an image (wildcards supported)
getall Gets all files off an image
del Deletes a file on an image
info Retrieves info about an image (by reading CRC files)
crc Retrieves info about an image in the same format used by the
CRC files
good CRC checks a set of images and for matching images, copy into
a new directory
listformats Lists all image file formats supported by imgtool
listfilters Lists all filters supported by imgtool
listdriveroptions Lists all format-specific options for the 'put' and 'create'
commands
Filters
=======
Filters are a means to process data being written into or read out of an image
in a certain way. Filters can be specified on the get, put, and getall
commands by specifying --filter=xxxx on the command line. Currently, only
three filters are supported:
ascii Translates end-of-lines to the appropriate format
cocobas Processes tokenized CoCo BASIC programs
dragonbas Processes tokenized Dragon BASIC programs
Format Info
===========
rsdos CoCo Disks
----------------
Fully implemented. This format supports two format-specific options on the put
command:
--ftype=(basic|data|binary|assembler) Specifies the file type
--ascii=(ascii|binary) Specifies the ASCII flag
cococas CoCo Cassettes
----------------------
Both .cas and .wav supported, but read only.
lnx Commodore 64 Lynx Archive
-----------------------------
only for early revisions of lynx archivs
only extraction supported
not heavily tested
Lynx archivs could and should be handled in a c64 emulation
with the native lynx tool
t64 Commodore 64/C64S Archive for Tapes
---------------------------------------
not heavily tested
further creation/use of these archivs discouraged
c64crt/crt Commodore 64 Cartridge
---------------------------------
for professional use only (cartridge dumper)
not heavily tested
d64 Commodore SX64/VC1541/1551/2031 Diskette
x64 VICE variant of the above
d71 Commodore 128D/1571 Diskette
d81 Commodore 65/1565/1581 Diskette
-----------------------------------
not heavily tested
x64: further creation/use discouraged
msdos/fat Microsoft DOS Diskette
--------------------------------
directories not finished
not heavily tested
Formatting (low and high level) must be done with the msdos utility format!
Boot structures must be installed on these disks with the msdos utility sys!
standard parameter for common disk formats:
type 0: 5 1/4 inch, double density, single sided, 160kb: sectors 8, heads 1, tracks 40
type 1: 5 1/4 inch, DD, SS, 180kb: sectors 9, heads 1, tracks 40
type 2: 5 1/4 inch, DD, double sided, 320kb: sectors 8, heads 2, tracks 40
type 3: 5 1/4 inch, DD, DS, 360kb: sectors 9, heads 2, tracks 40
type 4: 3 1/2 inch, DD, DS, 720kb: sectors 9, heads 2, tracks 80
at disk controller necessary for high density
type 5: 5 1/4 inch, high density, DS, 1.2mb: sectors 15, heads 2, tracks 80
3 1/2 inch, HD, DS, 1.2mb: sectors 15, heads 2, tracks 80
type 6: 3 1/2 inch, HD, DS, 1.44mb: sectors 18, heads 2, tracks 80
special disk controller necessary for enhanced density
type 7: 3 1/2 inch, enhanced density, DS, 2.88mb: sectors 36, heads 2, tracks 80
unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((9*2*40))
to generate standard blank 360kb image
msdoshd/fat Microsoft DOS Harddisk/PC Partition Table
-----------------------------------------------------
not finished and not working
(see also unter msdos/fat)
No low level format necessary with image files
Partitioning must be done with the msdos utility fdisk
Then you can format each partition with msdos utility format
standard parameter for common disk formats:
type 0: 20mb standard pc/xt harddisk: 17 sectors, 4 heads, 615 cylinders
unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((17*4*615))
to generate standard blank 20mb pc xt harddisk image
Virtual MSX tape archive
------------------------
Converts .tap files from Virtual MSX 1.x to .cas files. It is not
fault-tolerant.
Virtual MSX Game Master 2 SRAM file
-----------------------------------
Very simple, not overly useful but some might want it. Virtual MSX stored the
SRAM of Konami's Game Master 2 in "gmaster2.ram". To convert this to something
useful with MESS and other MSX emulators, go:
imgtool getall vmsx_gm2 gmaster2.ram
You'll get a file called gmaster2.mem, which must place in the correct directory
of mess to use (MESS\MEMCARD\GameMaster2 if your Game Master 2 .rom file is
called GameMaster2.rom). It's ~/.xmess/memcard/GameMaster2.mem for xmess.
fMSX style .cas file
--------------------
Converts .cas files to .wav files. The MSX driver can use .cas files directly
so you don't have to convert them. You can use it to export files to a real
MSX. Connect the MSX to the line out of your computer. Give the apropriate
command on the MSX (BLOAD "CAS:",R for example) and then play the .wav file
on your computer.
imgtool dir fmsx_cas file.cas
imgtool getall fmsx_cas file.cas
imgtool get fmsx_cas file.cas file.wav newfile.wav
XelaSoft Archive (.xsa)
-----------------------
The XelaSoft Archive is a compressed file. It can only contain one
file. Although it can contain any file, it's always used for MSX disk
images. The were programs written by XelaSoft which made a dump
of a disk, and compressing them at the same time. Very useful to store
a disk dump on another disk. zip/gzip offer much better compression and
are mainstream, so let's stick with that.
imgtool uses XSA code developed by Alex Wulms/XelaSoft.
http://web.inter.nl.net/users/A.P.Wulms/
Various bogus MSX disk images (img/ddi/msx/multidisks)
------------------------------------------------------
These are formats you might come across, which have no actual added value
whatsoever. The only format MESS will support, like most other MSX
emulators, is .dsk (a plain dump without any header information). This
filetype converts them all to .dsk format.
msx_img are disk images with an extra byte at the beginning. It' 1 (0x01)
for single-sided images and 2 (0x02) for double-side images. These
files are at: ftp://ftp.funet.fi/pub/msx/. The extension is .img
msx_ddi are DiskDupe 5.12 disk images. There is a 0x1800 bytes header
at the beginning. The CompuJunkS MSX emulator used these files. The header
often contain garbage so it's simply stripped. The extension is .ddi
msx_msx are disk images with a weird sector order. You can find them
at: ftp://jazz.snu.ac.kr/pub/msx/. The extension is .msx
msx_mul are "multi disk" images, used by fmsx-dos 1.6. It is simply
more than one .dsk image appended to one another. The extension is
still .dsk, but the file is larger than 720kB (actually always a
multiple of 720kB.
rom16 16 bit wide rom image
---------------------------
allows easy access to even and odd parts
file even: even bytes
file odd: odd bytes
Amstrad NC100/NC150/NC200 PCMCIA Ram Card Images (crd/card)
-----------------------------------------------------------
The card filesystem is similar to FAT, but not identical.
The maximum card size is 1mb, and maximum file size is 64k.
(Files will be cut at 64k if they are larger - e.g. when putting a large file)
As far as I know there is no directory system, however there is always a
system "NC100" directory which points to the root directory. (Like the DOS "."
directory).
Using imgtool, you can put, get and delete files.
At this time only ascii file type is supported. These files can be loaded
into the internal wordprocessor,or,if the file is a BASIC listing, it can
be loaded into basic with "*EXEC <filename>" at the ">" prompt.
From BASIC you can get a directory listing of the card filesystem with "*."
at the ">" prompt.
The file date information is not supported at this time.
The card filesystem reading/writing in imgtool has not been heavily tested.
TI99 floppy disk images (v9t9/pc99fm/pc99mfm/ti99_old)
------------------------------------------------------
These modules enable you to create and catalog ti99 images, to delete
individual files and directories, and to get and put files in TIFILE format.
Note that you cannot create images in pc99 format.
The v9t9 module supports the v9t9 disk images that is used by MESS, the pc99fm
module supports FM-encoded pc99 images, and the pc99mfm supports MFM-encoded
pc99 images, and the ti99_old module supports the now obsolete image format
that was used by MESS versions prior to .69. The MESS ti99 drivers supports
the v9t9 disk image format only. (Note that the old MESS format was identical
to the V9T9 format for single-sided disks, but that the track order was
completely different for double-sided disks, which caused the two formats to be
incompatible for double-sided disk images. I have changed the format to v9t9
as this format is used by most other TI99 utilities and emulators.)
The TIFILE format is a file format that is supported by many ti99 utilities: it
encodes a TI99 file as a flat stream of bytes, which enables to store it on
file systems that do not support the TI99 file structure and to transmit it
through networks. This format uses a data format similar to the one used on
ti99 floppies (i.e. logical records are grouped in physical records of 256
bytes), with a custom 128-byte header.
Legal characters for volume and file names are upper case ASCII characters,
except period ('.') and space (' '). Lower case characters are not recommended
because they are not supported by TI99/4. You had better avoid control
characters and non-ASCII characters, too. (Additionally, the NULL character is
forbidden in file names, but I think nobody in his right sense would even try
to enter a NULL character in a file name.) The restriction on the period ('.')
character may sound strange to users of other OSes, but this character is used
as a path separator by TI systems. (As a matter of fact, no TI99 floppy disk
DSR (except the HFDC DSR) implements disk directories, but other TI systems
implement this convention extensively.) Since period is used as the path
separator, TI99 users often use the slash ('/') or dash ('-') characters as
file extension separators; note, however, that the use of file extensions is
never systematic in TI99: you may use file extensions if you find them useful,
just like you may use any other file naming scheme, but no program enforce or
require filename extensions as it is often the case in the DOS/windows world.
Parameters for create:
--label=...: an optional string of up to 10 characters.
--sides=[1|2]: 1 for single-sided, 2 for double-sided.
--tracks=[1-80]: number of track per side. Should be 40 for a 40-track disk,
and 80 for an 80-track disk.
--sectors=[1-36]: number of sectors per track. Should be 9 in single density
(FM), 18 in double density (MFM), and 36 in high density (MFM).
--protection=[0|1]: when set to 1, the disk will be protected and some (but not
all) TI99 programs won't overwrite the disk.
--density=[Auto|SD|DD|HD]: you should probably leave this parameter to Auto, so
that imgtool picks the correct value automatically (according to the number
of sectors per track). If you really need to, SD forces single density
(FM), DD forces double density (MFM), and HD forces high density (MFM).
Supported geometries for create:
description |sides|tracks|sectors| size | FDC Compatibility (1)
| | | | |
SSSD 48TPI 5"1/4 | 1 | 40 | 9 | 90K | All
| | | | |
DSSD 48TPI 5"1/4 | 2 | 40 | 9 | 180K | All
| | | | |
DSDD 48TPI 5"1/4 | 2 | 40 | 18 | 360K | SNUG BwG, Myarc HFDC
| | | | |
DSDD 96TPI 5"1/4 | 2 | 80 | 18 | 720K | Myarc HFDC (2)
or DSDD 3"1/2 | | | | |
| | | | |
DSHD 3"1/2 | 2 | 80 | 36 |1.44M | Myarc HFDC (Geneve Only) (3)
(1) Only emulated controllers are listed in this table
(2) SNUG BwG can read such images, but it will corrupt them when writing new
data to them
(3) You cannot boot from such images (this is because the Geneve MDOS operating
system needs to replaces the incomplete HFDC DSR with a better DSR to
support HD: since MDOS is not loaded yet at boot time, you cannot boot from
a HD disk).
Examples:
List the catalog of image test.dsk:
imgtool dir v9t9 test.dsk
Extract file FILE1 located on image test.dsk:
imgtool get v9t9 test.dsk FILE1
Extract file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
imgtool get v9t9 test.dsk SUBDIR1.FILE1
Write file FILE1 on image test.dsk:
imgtool put v9t9 test.dsk FILE1
(Note that file FILE1 must not exist before the command is run. Use the delete
command first if you need to overwrite an existing file.)
Delete file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
imgtool delete v9t9 test.dsk SUBDIR1.FILE1
Delete subdirectory SUBDIR1 on image test.dsk:
imgtool delete v9t9 test.dsk SUBDIR1
(Subdirectory SUBDIR1 must be empty.)
Create a SSSD image compatible with all controllers:
imgtool create v9t9 test.dsk --sides=1 --tracks=40 --sectors=9
Create a DSSD image compatible with all controllers:
imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=9
Create a DSDD image compatible with BwG and HFDC controllers:
imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=18
Create a 80-track DSDD image compatible with the HFDC controller:
imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=18
Create a DSHD image compatible with the Geneve with a HFDC controller:
imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=36
TI99 hard disk images (ti99hd)
------------------------------
This module can catalog ti99 hard disk images, delete individual files and
directories, and get and put files in TIFILE format. Only images in HFDC
format are supported for now (no SCSI format).
TI990 disk images (ti990hd)
---------------------------
This module supports disk images in DNOS format (which appears to be virtually
identical to DX10 3.x format). Although the module is named ti990hd, this
module will work fine with floppy images as well as hard disk images: just make
sure that the disks are formatted in the proper format, as neither DX10 2.x nor
TX990 formats are supported.
Parameters for create:
The most interesting command is create, as you cannot create new images within
emulation.
--cylinders: number of cylinders
--heads: number of heads
--sectors: number of sectors per track
--seclen: bytes per sector
Known restrictions on geometry:
256 < bytes per sector < 512 (arbitrary restriction, actual TI990s might
accept values out of this range)
bytes per sector must be even
3 < # cylinders < 2047
1 < # heads < 31
1 < sectors per track < 256
(sectors per track) * (bytes per sector) < 2^17 = 131072 (which implies
(sectors per track) < 255 if sectors are 512-byte long)
(There are probably other restrictions, so you had better stick to values
similar to the ones used by actual disk units... Also note that according to
the Spectra 126-Plus manual, ADU size limitations prevent most operating
systems from supporting units larger than 500MBytes.)
Known drive geometries:
(Sources: 946250-9703 p. 3-14, 2270512-9701 p. 11-3, 945250-9701 pp. 5-20
through 5-28, 946250-9701B pp. 2-1 through 2-3, 2540219A-0001 pp. 4-2 and 4-3,
2306140-9701 p. 1-15, 223439B-9701 pp. 3-14 and 3-28. See also "Spectra
126-Plus Product Reference Manual" by Cipher P/N 8500055 revision A4 page 2-8.)
Disk Type Units Size (MB) Cylinders Heads Sectors/Track Bytes/Sector
FD800 (min) 1 .244 77 1 26 128
FD800 (max) 1 .978??? 77 2??? 26??? 256???
FD1000 1 1.15 77 2 26 288
DS31/DS32 1 2.81 203 2 24 288
DS10 2 4.70 408 2(*2) 20 288
DS25 1 22.3 408 5 38 288
DS50 1 44.6 815 5 38 288
DS200 1 169.5 815 19 38 288
CD1400-32 2 13.5 821(h) 1 64 256
CD1400-64 (rem) 1 13.5 821(h) 1 64 256
CD1400-64 (fix) 1 38.5 821(h) 3 64 256
CD1400-96 (rem) 1 13.5 821(h) 1 64 256
CD1400-96 (fix) 1 67.3 821(h) 5 64 256
DS80 1 62.7 803(g) 5 61 256
DS300 1 238.3 803(c) 19 61 256
WD800-18 1 18.5 651(b) 3 37 256
WD800-43 1 43.2 651(b) 7 37 256
WD800A/38 1 38.5 911(d) 5 33 256
WD800A/69 1 69.3 911(d) 9 33 256
WD800A/114 1 114.6 904(d) 15 33 256
WD500 1 4.92 150(a) 4 32 256
WD500A 1 17.1 694(a) 3 32 256
WD900-138 1 138.1 805(e) 10 67 256
WD900-138/2 2 69.0 805(e) 5(*2) 67 256
WD900-425 1 425.8 693(e) 24 100 256
WD900-425/2 2 212.9 693(e) 12(*2) 100 256
MSU II 1 158.8 957(f) 9 36 512
MSU IIA 1 332.9 1204(f) 15 36 512
a) some extra cylinders are reserved for diagnostics
b) 6 extra cylinders are reserved for storage system use (including 2 for
diagnostics)
c) some extra cylinders are reserved for diagnostics, and 10 extra cylinders
are reserved to replace bad tracks
d) 4 extra cylinders are reserved for storage system use (including 2 for
diagnostics), and 10 extra cylinders are reserved to replace bad tracks
e) 16 extra cylinders are reserved for bad track relocation
f) there are extra cylinders, and the way logical addresses relates to physical
address is so complex I don't even want to talk about it
g) 2 extra cylinders are reserved for diagnostics, and 10 extra cylinders are
reserved to replace bad tracks
h) 2 extra cylinders are reserved for diagnostics
Note that 2270512-9701 and 946250-9703 describe more disk units (namely CMD 16,
CMD 80, WD800A-43 and WD800A-100 for the former, and WD500-10 for the later).
Since there are no other references anywhere and DX-10 does not seem to know
about them, I assume that these models were uncommon.
FD800 is a 8" floppy disc unit that is not emulated, and it is only cited for
completeness. (The FD800 controller is connected to the CRU bus instead of the
TILINE bus, and it is the only disc controller that is supported by non-TILINE
systems).
FD1000 is a 8" floppy disc unit.
DS31/DS32 was the first hard disk unit for ti990. The only difference between
DS31 and DS32 is that DS32 does not require a screwdriver to change the disc
cartridge.
DS10 has one 5-mb fixed platter and one 5mb disk cartridge.
CD1400-32 and CD1400-96 have a one-platter 16-mb removable unit, and a fixed
unit (16 mb for CD1400-32 and 80 mb for CD1400-96).
WDxxx units are Winchester drives that connect to a proprietary PBUS bus
interface. This bus is a built-in interface in BS300 and BS300A systems, and
the TPBI card enables any TILINE 990 system to support it. WD800s are 8"
drives with integrated tape backup, WD500s are 5"1/4 drives with integrated
FD1000 backup, and WD900s are 9" drives. The WD900 controller can optionally
partition the disc into two partitions: the set-up with no partitioning is
listed as WD900-138 and WD900-425, whereas the set-up with partitioning is
listed as WD900-138/2 and WD900-425/2.
MSU II and MSU IIa are SCSI units to be connected to the 990/SCSI controller
board.
Macintosh floppy disk images (mac)
----------------------------------
This module supports MFS (Macintosh File System) and HFS (Hierarchical File
System) floppy disk images, either in diskcopy 4.2 or raw image format (the raw
image format is partially compatible with diskcopy 6 format).
This module can catalog images, and get files in MacBinary format. You can put
files on MFS-formatted images, too, but not on HFS-formatted images.
The module does not support folders in MFS format, because MFS folders are not
documented by Apple.
Extracted files are in MacBinary III format (which is fully compatible with
MacBinary I and II). The MacBinary III format joins both macintosh file forks,
the comment field, and most file info in one single file: it is supported by
several Macintosh utilities.
Texas Instruments calculators variable files
--------------------------------------------
+--------+------------------------------------------+-----------+
| Format | Description | Extension |
+--------+------------------------------------------+-----------+
| ti85p | TI-85 program file | 85p |
| ti85s | TI-85 string file (also ZShell programs) | 85s |
| ti85i | TI-85 picture file (85-image) | 85i |
| ti85n | TI-85 real number file | 85n |
| ti85c | TI-85 complex number file | 85c |
| ti85l | TI-85 list (real or complex) | 85l |
| ti85k | TI-85 constant file | 85k |
| ti85m | TI-85 matrix (real or complex) file | 85m |
| ti85v | TI-85 vector (real or complex) file | 85v |
| ti85d | TI-85 graphics database file | 85d |
| ti85e | TI-85 equation file | 85e |
| ti85r | TI-85 range settings file | 85r |
| ti85g | TI-85 grouped file | 85g |
| ti85 | TI-85 generic file | 85? |
| ti86p | TI-86 program file | 86p |
| ti86s | TI-86 string file | 86s |
| ti86i | TI-86 picture file (85-image) | 86i |
| ti86n | TI-86 real number file | 86n |
| ti86c | TI-86 complex number file | 86c |
| ti86l | TI-86 list (real or complex) file | 86l |
| ti86k | TI-86 constant file | 86k |
| ti86m | TI-86 matrix (real or complex) file | 86m |
| ti86v | TI-86 vector (real or complex) file | 86v |
| ti86d | TI-86 graphics database file | 86d |
| ti86e | TI-86 equation file | 86e |
| ti86r | TI-86 range settings file | 86r |
| ti86g | TI-86 grouped file | 86g |
| ti86 | TI-86 generic file | 86? |
+--------+------------------------------------------+-----------+
Grouped formats (ti85g and ti86g) can keep more than one variable.
Generic formats (ti85 and ti86) can be used for all types of variable files.
For all types of variable files dir, create, put, get and delete commands are
supported.
Texas Instruments calculators memory backup files
-------------------------------------------------
+--------+------------------------------------------+-----------+
| Format | Description | Extension |
+--------+------------------------------------------+-----------+
| ti85b | TI-85 memory backup file | 85b |
+--------+------------------------------------------+-----------+
For TI memory backup files only dir command is supported.
The new 6502 family implementation
----------------------------------
1. Introduction
The new 6502 family implementation has been created to reach
sub-instruction accuracy in observable behaviour. It is designed with
3 goals in mind:
- every bus cycle must happen at the exact time it would happen in a
real cpu, and every access the real cpu does is done
- instructions can be interrupted at any time in the middle then
restarted at that point transparently
- instructions can be interrupted even from within a memory handler
for bus contention/wait states emulation purposes
Point 1 has been ensured through bisimulation with the gate-level
simulation perfect6502. Point 2 has been ensured structurally through
a code generator which will be explained in section 8. Point 3 is not
done yet due to lack of support on the memory subsystem side, but
section 9 shows how it will be handled.
2. The 6502 family
The MOS 6502 family has been large and productive. A large number of
variants exist, varying on bus sizes, i/o, and even opcodes. Some
offshots (g65c816, hu6280) even exist that live elsewhere in the mame
tree. The final class hierarchy is this:
6502
|
+------+--------+--+--+-------+-------+
| | | | | |
6510 deco16 6504 6509 n2a03 65c02
| |
+-----+-----+ r65c02
| | | |
6510t 7501 8502 +---+---+
| |
65ce02 65sc02
|
4510
The 6510 adds an up to 8 bits i/o port, with the 6510t, 7501 and 8502
being software-identical variants with different pin count (hence i/o
count), die process (nmos, hnmos, etc) and clock support.
The deco16 is a Deco variant with a small number of not really understood
additional instructions and some i/o.
The 6504 is a pin and address-bus reduced version.
The 6509 adds internal support for paging.
The n2a03 is the nes variant with the D flag disabled and sound
functionality integrated.
The 65c02 is the very first cmos variant with some additional
instructions, some fixes, and most of the undocumented instructions
turned into nops. The R (rockwell, but eventually produced by wdc too
among others) variant adds a number of bitwise instructions and also
stp and wai. The sc variant, used by the Lynx portable console, looks
identical to the R variant. The 's' probably indicates a
static-ram-cell process allowing full dc-to-max clock control.
The 65ce02 is the final evolution of the ISA in this hierarchy, with
additional instructions, registers, and removals of a lot of dummy
accesses that slowed the original 6502 down by at least 25%. The 4510
is a 65ce02 with integrated mmu and gpio support.
3. Usage of the classes
All the cpus are standard modern cpu devices, with all the normal
interaction with the device infrastructure. To include one of these
cpu in your driver you need to include "cpu/m6502/<cpu>.h" and then do
a MCFG_CPU_ADD("tag", <CPU>, clock).
6510 variants port i/o callbacks are setup through:
MCFG_<CPU>_PORT_CALLBACKS(READ8(type, read_method), WRITE8(type, write_method))
And the pullup and floating lines mask is given through:
MCFG_<CPU>_PORT_PULLS(pullups, floating)
In order to see all bus accesses on the memory handlers it is possible
to disable accesses through the direct map (at a cpu cost, of course)
with:
MCFG_M6502_DISABLE_DIRECT()
In that case, transparent decryption support is also disabled,
everything goes through normal memory-map read/write calls. The state
of the sync line is given by the cpu method get_sync(), making
implementing the decryption in the handler possible.
Also, as for every executable device, the cpu method total_cycles()
gives the current time in cycles since the start of the machine from
the point of view of the cpu. Or, in other words, what is usually
called the cycle number for the cpu when somebody talks about bus
contention or wait states. The call is designed to be fast (no
system-wide sync, no call to machine.time()) and is precise. Cycle
number for every access is exact at the sub-instruction level.
The 4510 special nomap line is accessible through get_nomap().
Other than these specifics, these are perfectly normal cpu classes.
4. General structure of the emulations
Each variant is emulated through up to 4 files:
- <cpu>.h = header for the cpu class
- <cpu>.c = implementation of most of the cpu class
- d<cpu>.lst = dispatch table for the cpu
- o<cpu>.lst = opcode implementation code for the cpu
The last two are optional. They're used to generate a <cpu>.inc file
in the object directory which is included by the .c file.
At a minimum, the class must include a constructor and an enum picking
up the correct input line ids. See m65sc02 for a minimalist example.
The header can also include specific configuration macros (see m8502)
and also the class can include specific memory accessors (more on
these later, simple example in m6504).
If the cpu has its own dispatch table, the class must also include the
declaration (but not definition) of disasm_entries, do_exec_full and
do_exec_partial, the declaration and definition of disasm_disassemble
(identical for all classes but refers to the class-specific
disasm_entries array) and include the .inc file (which provides the
missing definitions). Support for the generation must also be added
to cpu.mak.
If the cpu has in addition its own opcodes, their declaration must be
done through a macro, see f.i. m65c02. The .inc file will provide the
definitions.
5. Dispatch tables
Each d<cpu>.lst is the dispatch table for the cpu. Lines starting
with '#' are comments. The file must include 257 entries, the first
256 being opcodes and the 257th what the cpu should do on reset. In
the 6502 irq and nmi actually magically call the "brk" opcode, hence
the lack of specific description for them.
Entries 0 to 255, i.e. the opcodes, must have one of these two
structures:
- opcode_addressing-mode
- opcode_middle_addressing-mode
Opcode is traditionally a three-character value. Addressing mode must
be a 3-letter value corresponding to one of the DASM_* macros in
m6502.h. Opcode and addressing mode are used to generate the
disassembly table. The full entry text is used in the opcode
description file and the dispatching methods, allowing for per-cpu
variants for identical-looking opcodes.
An entry of "." was usable for unimplemented/unknown opcodes,
generating "???" in the disassembly, but is not a good idea at this
point since it will infloop in execute() if encountered.
6. Opcode descriptions
Each o<cpu>.lst file includes the cpu-specific opcodes descriptions.
An opcode description is a series of lines starting by an opcode entry
by itself and followed by a series of indented lines with code
executing the opcode.
For instance the asl <absolute address> opcode looks like this:
asl_aba
TMP = read_pc();
TMP = set_h(TMP, read_pc());
TMP2 = read(TMP);
write(TMP, TMP2);
TMP2 = do_asl(TMP2);
write(TMP, TMP2);
prefetch();
First the low part of the address is read, then the high part (read_pc
is auto-incrementing). Then, now that the address is available the
value to shift is read, then re-written (yes, the 6502 does that),
shifted then the final result is written (do_asl takes care of the
flags). The instruction finishes with a prefetch of the next
instruction, as all non-cpu-crashing instructions do.
Available bus-accessing functions are:
- read(adr) - standard read
- read_direct(adr) - read from program space
- read_pc() - read at the PC address and increment it
- read_pc_noinc() - read at the PC address
- read_9() - 6509 indexed-y banked read
- write(adr, val) - standard write
- prefetch() - instruction prefetch
- prefetch_noirq() - instruction prefetch without irq check
Cycle counting is done by the code generator which detects (through
string matching) the accesses and generates the appropriate code. In
addition to the bus-accessing functions a special line can be used to
wait for the next event (irq or whatever). "eat-all-cycles;" on a
line will do that wait then continue. It is used by wai_imp and
stp_imp for the m65c02.
Due to the constraints of the code generation, some rules have to be
followed:
- in general, stay with one instruction/expression per line
- there must be no side effects in the parameters of a bus-accessing
function
- local variables lifetime must not go past a bus access. In general,
it's better to leave them to helper methods (like do_asl) which do not
do bus accesses. Note that "TMP" and "TMP2" are not local variables,
they're variables of the class.
- single-line then or else constructs must have braces around them if
they're calling a bus-accessing function
The per-opcode generated code are methods of the cpu class. As such
they have complete access to other methods of the class, variables of
the class, everything.
7. Memory interface
For better opcode reuse with the mmu/banking variants, a memory access
subclass has been created. It's called memory_interface, declared in
m6502_device, and provides the following accessors:
- UINT8 read(UINT16 adr) - normal read
- UINT8 read_sync(UINT16 adr) - opcode read with sync active (first byte of opcode)
- UINT8 read_arg(UINT16 adr) - opcode read with sync inactive (rest of opcode)
- void write(UINT16 adr, UINT8 val) - normal write
- UINT8 read_9(UINT16 adr) - special y-indexed 6509 read, defaults to read()
- void write_9(UINT16 adr, UINT8 val); - special y-indexed 6509 write, defaults to write()
Two implementations are given by default, one usual,
mi_default_normal, one disabling direct access, mi_default_nd. A cpu
that wants its own interface (see 6504 or 6509 for instance) must
override device_start, intialize mintf there then call init().
8. The generated code
A code generator is used to support interrupting and restarting an
instruction in the middle. This is done through a two-level state
machine with updates only at the boundaries. More precisely,
inst_state tells you which main state you're in. It's equal to the
opcode byte when 0-255, and 0xff00 means reset. It's always valid and
used by instructions like rmb. inst_substate indicates at which step
we are in an instruction, but it set only when an instruction has been
interrupted. Let's go back to the asl <abs> code:
asl_aba
TMP = read_pc();
TMP = set_h(TMP, read_pc());
TMP2 = read(TMP);
write(TMP, TMP2);
TMP2 = do_asl(TMP2);
write(TMP, TMP2);
prefetch();
The complete generated code is:
void m6502_device::asl_aba_partial()
{
switch(inst_substate) {
case 0:
if(icount == 0) { inst_substate = 1; return; }
case 1:
TMP = read_pc();
icount--;
if(icount == 0) { inst_substate = 2; return; }
case 2:
TMP = set_h(TMP, read_pc());
icount--;
if(icount == 0) { inst_substate = 3; return; }
case 3:
TMP2 = read(TMP);
icount--;
if(icount == 0) { inst_substate = 4; return; }
case 4:
write(TMP, TMP2);
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
case 5:
write(TMP, TMP2);
icount--;
if(icount == 0) { inst_substate = 6; return; }
case 6:
prefetch();
icount--;
}
inst_substate = 0;
}
One can see that the initial switch() restarts the instruction at the
appropriate substate, that icount is updated after each access, and
upon reaching 0 the instruction is interrupted and the substate
updated. Since most instructions are started from the beginning a
specific variant is generated for when inst_substate is known to be 0:
void m6502_device::asl_aba_full()
{
if(icount == 0) { inst_substate = 1; return; }
TMP = read_pc();
icount--;
if(icount == 0) { inst_substate = 2; return; }
TMP = set_h(TMP, read_pc());
icount--;
if(icount == 0) { inst_substate = 3; return; }
TMP2 = read(TMP);
icount--;
if(icount == 0) { inst_substate = 4; return; }
write(TMP, TMP2);
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
write(TMP, TMP2);
icount--;
if(icount == 0) { inst_substate = 6; return; }
prefetch();
icount--;
}
That variant removes the switch, avoiding a costly computed branch and
also an inst_substate write. There is in addition a fair chance that
the decrement-test with zero pair is compiled into something
efficient.
All these opcode functions are called through two virtual methods,
do_exec_full and do_exec_partial, which are generated into a 257-entry
switch statement. Pointers-to-methods being expensive to call, a
virtual function implementing a switch has a fair chance of being
better.
The execute main call ends up very simple:
void m6502_device::execute_run()
{
if(inst_substate)
do_exec_partial();
while(icount > 0) {
if(inst_state < 0x100) {
PPC = NPC;
inst_state = IR;
if(machine().debug_flags & DEBUG_FLAG_ENABLED)
debugger_instruction_hook(this, NPC);
}
do_exec_full();
}
}
If an instruction was partially executed finish it (icount will then
be zero if it still doesn't finish). Then try to run complete
instructions. The NPC/IR dance is due to the fact that the 6502 does
instruction prefetching, so the instruction PC and opcode come from
the prefetch results.
9. Future bus contention/delay slot support
Supporting bus contention and delay slots in the context of the code
generator only requires being able to abort a bus access when not
enough cycles are available into icount, and restart it when cycles
have become available again. The implementation plan is to:
- Have a delay() method on the cpu that removes cycles from icount.
If icount becomes zero or less, having it throw a suspend() exception.
- Change the code generator to generate this:
void m6502_device::asl_aba_partial()
{
switch(inst_substate) {
case 0:
if(icount == 0) { inst_substate = 1; return; }
case 1:
try {
TMP = read_pc();
} catch(suspend) { inst_substate = 1; return; }
icount--;
if(icount == 0) { inst_substate = 2; return; }
case 2:
try {
TMP = set_h(TMP, read_pc());
} catch(suspend) { inst_substate = 2; return; }
icount--;
if(icount == 0) { inst_substate = 3; return; }
case 3:
try {
TMP2 = read(TMP);
} catch(suspend) { inst_substate = 3; return; }
icount--;
if(icount == 0) { inst_substate = 4; return; }
case 4:
try {
write(TMP, TMP2);
} catch(suspend) { inst_substate = 4; return; }
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
case 5:
try {
write(TMP, TMP2);
} catch(suspend) { inst_substate = 5; return; }
icount--;
if(icount == 0) { inst_substate = 6; return; }
case 6:
try {
prefetch();
} catch(suspend) { inst_substate = 6; return; }
icount--;
}
inst_substate = 0;
}
A modern try/catch costs nothing if an exception is not thrown. Using
this the control will go back to the main loop, which will then look
like this:
void m6502_device::execute_run()
{
if(waiting_cycles) {
icount -= waiting_cycles;
waiting_cycles = 0;
}
if(icount > 0 && inst_substate)
do_exec_partial();
while(icount > 0) {
if(inst_state < 0x100) {
PPC = NPC;
inst_state = IR;
if(machine().debug_flags & DEBUG_FLAG_ENABLED)
debugger_instruction_hook(this, NPC);
}
do_exec_full();
}
waiting_cycles = -icount;
icount = 0;
}
A negative icount means that the cpu won't be able to do anything for
some time in the future, because it's either waiting for the bus to be
free or for a peripheral to answer. These cycles will be counted
until elapsed and then normal processing will go on. It's important
to note that the exception path only happens when the contention/wait
state goes further than the scheduling slice of the cpu. That should
not usually be the case, so the cost should be minimal.
10. Multi-dispatch variants
Some variants currently in the process of being supported change
instruction set depending on an internal flag, either switching to a
16-bits mode or changing some register accesses to memory accesses.
This is handled by having multiple dispatch tables for the cpu, the
d<cpu>.lst not being 257 entries anymore but 256*n+1. The variable
inst_state_base must select which instruction table to use at a given
time. It must be a multiple of 256, and is in fact simply or-ed to
the first instruction byte to get the dispatch table index (aka
inst_state).
11. Current TODO
- Implement the bus contention/wait states stuff, but that requires
support on the memory map side first.
- Integrate the i/o subsystems in the 4510
- Possibly integrate the sound subsytem in the n2a03
- Add decent hookups for the apple 3 madness
MAME(tm), the Multiple Arcade Machine Emulator
Copyright (c) 1997-2013 by Nicola Salmoria and the MAME team
MAME is a trademark owned by Nicola Salmoria
----------
I. Purpose
----------
MAME is strictly a non-profit project. Its main purpose is to be a
reference to the inner workings of the emulated arcade machines. This is
done both for educational purposes and for preservation purposes, in
order to prevent many historical games from disappearing forever once the
hardware they run on stops working. Of course, in order to preserve the
games and demonstrate that the emulated behavior matches the original,
you must also be able to actually play the games. This is considered a
nice side effect, and is not MAME's primary focus.
It is not our intention to infringe on any copyrights or patents on the
original games. All of MAME's source code is either our own or freely
available. To operate, the emulator requires images of the original ROMs,
CDs, or hard disks from the arcade machines, which must be provided by
the user. No portions of the original game code are included in the
executable.
--------
II. Cost
--------
MAME is free. Its source code is free. Selling either is not allowed.
----------------
III. Image Files
----------------
ROM, CD, and hard disk images are all copyrighted material. They cannot
be distributed without the explicit permission of the copyright owner.
They are not "abandonware", nor have any of the games supported by MAME
passed out of copyright.
MAME is not intended to be used as a tool for mass copyright
infringement. Therefore, it is strongly against the authors' wishes to
sell, advertise, or link to resources that provide illegal copies of ROM,
CD, or hard disk images.
--------------------
IV. Derivative Works
--------------------
Derivative works are allowed under the MAME license. However, you are
discouraged from providing specific functionality that goes against the
philosophy of the MAME team. Specifically:
* Do not add games which are more recent than 3 years old, or which are
still being sold new by the company that produced them. MAME is not
intended to be a platform that competes with arcade games that are still
being actively sold.
* Do not provide a means of generating a list of games that specifically
identifies those games for which the user does not have image files. This
only encourages users to seek out sources for illegal ROM, CD, and hard
disk images in order to "complete" their collection.
* Do not remove the startup screen that contains information about why
certain non-working games don't work. This only serves to generate a
bunch of useless email traffic to the developers asking why the games
don't work.
Because the name MAME is trademarked, you must abide by the rules of the
trademark usage if you wish to use "MAME" as part of the name your
derivative work. In general, this means you must request permission,
which requires that you follow the guidelines above.
The version number of any derivative work should reflect the version
number of the MAME release it was derived from.
-------------------------------
V. Official Contact Information
-------------------------------
For questions regarding the MAME license, trademark, or other usage, go
to http://www.mamedev.org/
The MAME project, as a whole, is currently released under the following
license, known as the MAME License.
Most code in MAME is under a more permissive license, or dual-licensed.
This is noted in per-file headers which specify the alternate license.
The text of the MAME License follows.
Copyright Nicola Salmoria and the MAME team
All rights reserved.
Redistribution and use of this code or any derivative works are permitted
provided that the following conditions are met:
* Redistributions may not be sold, nor may they be used in a commercial
product or activity.
* Redistributions that are modified from the original source must include the
complete source code, including the source code for all components used by a
binary built from the modified sources. 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 operating system on which the executable runs, unless that
component itself accompanies the executable.
* Redistributions must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This article originally appeared in a slightly different form at
http://aarongiles.com. You should read this if you are used to how
MAME's video system worked prior to 0.107 and you want to understand
how you should configure MAME with the new rendering system in place.
The New Video Landscape
Since its inception 9 years ago, MAME's video system has defaulted to
a mode where it tries to change resolutions on you. And since the
first port of the core to Windows 5 years ago, it has defaulted to
using your graphics card to stretch the video to that resolution.
I'm sure a lot of you out there have taken a lot of time to tweak the
current set of video options to make them work the way you like. But
every once in a while, you need to take a step back and re-evaluate
the situation. The current video system has been in place for 5 years
now without much substantial change. And with the recent rewrite,
you're almost certainly going to want to rethink the way you have
things configured.
At the highest level, there are really three different ways you can
configure the new system. Placing yourself into one of these three
categories will help you get the initial settings right. From there,
you can tweak with the settings to figure out what works best.
Category 1: Bells and whistles. People who fall into this category
would include anyone with a modern system and a decent video card
(decent in this context means at least 16MB of VRAM and built in the
last 5 years or so -- we're not talking cutting edge here). Any decent
video card will be able to render the simple MAME graphics at pretty
much any resolution without breaking a sweat. Configure your desktop
to the video mode you want (preferably something high like 1024x768
or greater with a high refresh rate, unless you are running on a
fixed-mode LCD, in which case just match what your LCD panel is),
and tell MAME to leave the resolution alone. In this day and age,
there is little reason to switch resolutions at all, unless you
fall into Category 3, below. In this mode, you will have full access
to artwork options, and you'll get your artwork scaled to full
resolution and with full alpha blending effects. Vector games will
look crisp, you can use decent fonts, and you can see a whole lot
more of the world when using the graphics/tilemap viewer. This mode
uses Direct3D, so you should configure yourself like this:
-video d3d -noswitchres [-triplebuffer] [-nofilter]
The -noswitchres option tells MAME to just run at the current
resolution. Although you can let MAME pick a resolution for you, it
doesn't really make much sense in D3D mode, and in fact I may even
remove that feature altogether. To avoid tearing artifacts, I
recommend using the -triplebuffer option as well. Just make sure your
monitor's refresh rate is higher than the game you are running. If
you dislike the blurry look of the graphics, you can specify the
-nofilter option to disable bilinear filtering, though that will
produce blocky artifacts. Alternatively, you can use the -prescale
option which is described at the end of this article.
Category 2: Like the old days. I really didn't even want to support
this mode at all, but certain vocal MAMEdevs would have skinned me
alive otherwise. People who fall into this category include those who
have weak systems that worked fine with previous versions of MAME,
but who don't run well with Direct3D rendering. (Note that just
because Space Invaders runs unthrottled at 2000fps with DirectDraw
and 1000fps with Direct3D doesn't mean that Direct3D is going to be
a serious issue when playing at a regular 60fps, so if you're unsure,
give the Direct3D route a try for a while.) In this mode, MAME will
draw the game screen and artwork at the game's resolution, just like
it did in MAME 0.106 and earlier; however, some artwork options,
such as -artcrop, won't work as you might expect, and some alpha
blending artwork modes (specifically overlays) will operate with a
performance penality. MAME will then use your video card to stretch
the video to the proper aspect ratio.
-video ddraw -hwstretch [-switchres] [-triplebuffer]
The -switchres is optional here. If your video card is really ancient
and struggles expanding the screen to fit your desktop resolution,
you might want to turn it on. Again, to avoid tearing artifacts, I
recommend using the -triplebuffer option as well, but make sure your
monitor's refresh rate is higher than the game you are running
(-switchres will do that for you if you use it). If your video card
produces blurry pixels which you don't like, try the -prescale option
described at the end of this article.
Category 3: Anal video mode types. These are the guys who have
generally built their own cabinets and set them up with a CRT display
where they have several dozen carefully hand-tweaked video modes that
approximate the original video modes the games ran at. They want MAME
to pick that hand-tweaked mode and use it, drawing one pixel on the
screen for each pixel in the original game. They don't give a whit
about artwork or anything other than the raw pixels going to the
right place. Fortunately, you can still configure MAME for this case
as well:
-video ddraw -nohwstretch -switchres [-triplebuffer]
Obviously in this case, the -switchres is required. You also want to
disable hardware stretching, otherwise you won't get that "perfect"
1:1 pixel mapping. Triple buffering may or may not help.
So, I recommend starting with these initial options and then tweaking
from there. One additional option you might want to try in
combination with the above is the -prescale option. -prescale takes
an integer parameter from 1 to 3, and specifies a magnification
amount by which the screen pixels are expanded before they are drawn
to the screen. Why is this useful? And how much of a performance
impact does it have? Well, that depends on the mode you are running
in.
If you are running in Category 1 (-video d3d), then -prescale will
use your video card to scale the game graphics up before rendering
them to the screen. Depending on the video card, this is usually a
small performance hit, but not too significant. The benefit is that
each prescale factor reduces the blurriness of the pixels.
-prescale 1 is the default, which does no scaling. -prescale 2 will
double each pixel, and -prescale 3 will triple each pixel. For my
money, -prescale 2 is sufficient, but people with super high
resolution displays claim that larger -prescale factors work even
better.
If you are running in Category 2 (-video ddraw -hwstretch), then
-prescale will cause MAME to compose the screen graphics at the
specified scale factor. This is unfortunately done in software, but
carries the benefit that artwork, fonts, and the graphics viewer can
take advantage of the additional resolution to produce nicer results.
The end effect is that you will get less blurry pixels, just like the
Category 1 case, plus higher quality artwork, fonts, and more visible
area in the graphics viewer.
If you are running in Category 3 (-video ddraw -nohwstretch), then
-prescale will cause MAME to pick a video mode that is the prescale
factor times the raw screen resolution, and then MAME will, in
software, compose the screen graphics at the specified scale factor.
This has all the advantages of the Category 2 case, except that since
there wasn't any pixel blurring to begin with, there is no additional
crispness that comes about as a result.
Finally, you may be wondering about effects (and yes, scanlines are
an "effect"). Effects are no longer hard-coded into the system.
Rather, you can provide a PNG file in the artwork directory that will
be loaded and overlaid on top of screen bitmaps. See the description
of -effect in windows.txt for more details.
The new SCSI subsystem
----------------------
1. Introduction
The nscsi subsystem was created to allow an implementation to be
closer to the physical reality, making it easier (hopefully) to
implement new controller chips from the documentations.
2. Global structure
Parallel SCSI is built around a symmetric bus to which a number of
devices are connected. The bus is composed of 9 control lines (for
now, later scsi versions may have more) and up to 32 data lines (but
currently implemented chips only handle 8). All the lines are open
collector, which means that either one or multiple chip connect the
line to ground and the line, of course, goes to ground, or no chip
drives anything and the line stays at Vcc. Also, the bus uses
inverted logic, where ground means 1. SCSI chips traditionally work
in logical and not physical levels, so the nscsi subsystem also works
in logical levels and does a logical-or of all the outputs of the
devices.
Structurally, the implementation is done around two main classes:
nscsi_bus_devices represents the bus, and nscsi_device represents an
individual device. A device only communicate with the bus, and the
bus takes care of transparently handling the device discovery and
communication. In addition the nscsi_full_device class proposes a
scsi device with the scsi protocol implemented making building generic
scsi devices like harddrives or cdrom readers easier.
3. Plugging in a scsi bus in a driver
The nscsi subsystem leverages the slot interfaces and the device
naming to allow for a configurable yet simple bus implementation.
First you need to create a list of acceptable devices to plug on the
bus. This usually comprises of cdrom, harddisk and the controller
chip. For instance:
static SLOT_INTERFACE_START( next_scsi_devices )
SLOT_INTERFACE("cdrom", NSCSI_CDROM)
SLOT_INTERFACE("harddisk", NSCSI_HARDDISK)
SLOT_INTERFACE_INTERNAL("ncr5390", NCR5390)
SLOT_INTERFACE_END
The _INTERNAL interface indicates a device that is not
user-selectable, which is useful for the controller.
Then in the machine config (or in a fragment config) you need to first
add the bus, and then the (potential) devices as subdevices of the bus
with the scsi id as the name. For instance you can use:
MCFG_NSCSI_BUS_ADD("scsibus")
MCFG_NSCSI_ADD("scsibus:0", next_scsi_devices, "cdrom", 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:1", next_scsi_devices, "harddisk", 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:2", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:3", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:4", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:5", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:6", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:7", next_scsi_devices, "ncr5390", 0, &next_ncr5390_interface, 10000000, true)
That configuration puts as default a cdrom reader on scsi id 0 and a
hard drive on scsi id 1, and forces the controller on id 7. The
parameters of add are:
- device tag, comprised of bus-tag:scsi-id
- the list of acceptable devices
- the device name as per the list, if one is to be there by default
- the device input config, if any (and there usually isn't one)
- the device configuration structure, usually for the controller only
- the frequency, usually for the controller only
- "false" for a user-modifyable slot, "true" for a fixed slot
The full device name, for mapping purposes, will be
bus-tag:scsi-id:device-type, i.e. "scsibus:7:ncr5390" for our
controller here.
4. Creating a new scsi device using nscsi_device
The base class "nscsi_device" is to be used for down-to-the-metal
devices, i.e. scsi controller chips. The class provides three
variables and one method. The first variable, scsi_bus, is a pointer
to the nscsi_bus_device. The second, scsi_refid, is an opaque
reference to pass to the bus on some operations. Finally, scsi_id
gives the scsi id as per the device tag. It's written once at startup
and never written or read afterwards, the device can do whatever it
wants with the value or the variable.
The virtual method scsi_ctrl_changed is called when watched-for
control lines change. Which lines are watched is defined through the
bus.
The bus proposes five methods to access the lines. The read methods
are ctrl_r() and data_r(). The meaning of the control bits are
defined in the S_* enum of nscsi_device. The bottom three bits (INP,
CTL and MSG) are setup so that masking with 7 (S_PHASE_MASK) gives the
traditional numbers for the phases, which are also available with the
S_PHASE_* enum.
Writing the data lines is done with data_w(scsi_refid, value).
Writing the control lines is done with ctrl_w(scsi_refid, value,
mask-of-lines-to-change). To change all control lines in one call use
S_ALL as the mask.
Of course, what is read is the logical-or of all of what is driven by
all devices.
Finally, the method ctrl_wait_w(scsi_id, value,
mask-of-wait-lines-to-change) allows to select which control lines are
watched. The watch mask is per-device, and the device method
scsi_ctrl_changed is called whenever a control line in the mask
changes due to an action of another device (not itself, to avoid an
annoying and somewhat useless recursion).
Implementing the controller is then just a matter of following the
state machines descriptions, at least if they're available. The only
part often not described is the arbitration/selection, which is
documented in the scsi standard though. For an initiator (which is
what the controller essentially always is), it goes like this:
- wait for the bus to be idle
- assert the data line which number is your scsi_id (1 << scsi_id)
- assert the busy line
- wait the arbitration time
- check that the of the active data lines the one with the highest number is yours
- if no, the arbitration was lost, stop driving anything and restart at the beginning
- assert the select line (at that point, the bus is yours)
- wait a short while
- keep your data line asserted, assert the data line which number is the scsi id of the target
- wait a short while
- assert the atn line if needed, deassert busy
- wait for busy to be asserted or timeout
- timeout means nobody is answering at that id, deassert everything and stop
- wait a short while for deskewing
- deassert the data bus and the select line
- wait a short while
and then you're done, you're connected with the target until the
target deasserts the busy line, either because you asked it to or just
to annoy you. The deassert is called a disconnect.
The ncr5390 is an example of how to use a two-level state machine to
handle all the events.
5. Creating a new scsi device using nscsi_full_device
The base class "nscsi_full_device" is used to create HLE-d scsi
devices intended for generic uses, like hard drives, cdroms, perhaps
scanners, etc. The class provides the scsi protocol handling, leaving
only the command handling and (optionally) the message handling to the
implementation.
The class currently only support target devices.
The first method to implement is scsi_command(). That method is
called when a command has fully arrived. The command is available in
scsi_cmdbuf[], and its length is in scsi_cmdsize (but the length is
generally useless, the command first byte giving it). The 4096-bytes
scsi_cmdbuf array is then freely modifiable.
In scsi_command(), the device can either handle the command or pass it
up with nscsi_full_device::scsi_command().
To handle the command, a number of methods are available:
- get_lun(lua-set-in-command) will give you the lun to work on (the
in-command one can be overriden by a message-level one).
- bad_lun() replies to the host that the specific lun is unsupported.
- scsi_data_in(buffer-id, size) sends size bytes from buffer buffer-id
- scsi_data_out(buffer-id, size) recieves size bytes into buffer buffer-id
- scsi_status_complete(status) ends the command with a given status.
- sense(deferred, key) prepares the sense buffer for a subsequent
request-sense command, which is useful when returning a
check-condition status.
The scsi_data_* and scsi_status_complete commands are queued, the
command handler should call them all without waiting.
buffer-id identifies a buffer. 0, aka SBUF_MAIN, targets the
scsi_cmdbuf buffer. Other acceptable values are 2 or more. 2+ ids
are handled through the scsi_get_data method for read and
scsi_put_data for write.
UINT8 device::scsi_get_data(int id, int pos) must return byte pos of
buffer id, upcalling in nscsi_full_device for id < 2.
void device::scsi_put_data(int id, int pos, UINT8 data) must write
byte pos in buffer id, upcalling in nscsi_full_device for id < 2.
scsi_get_data and scsi_put_data should do the external reads/writes
when needed.
The device can also override scsi_message to handle scsi messages
other than the ones generically handled, and it can also override some
of the timings (but a lot of them aren't used, beware).
A number of enums are defined to make things easier. The SS_* enum
gives status returns (with SS_GOOD for all's well). The SC_* enum
gives the scsi commands. The SM_* enum gives the scsi messages, with
the exception of identify (which is 80-ff, doesn't really fit in an
enum).
6. What's missing
6.1. What's missing in scsi_full_device
Initiator support - we have no initiator device to HLE at that point.
Delays - a scsi_delay command would help giving more realistic timings
to the cdrom reader in particular.
Disconnected operation - would first require delays and in addition an
emulated OS that can handle it.
16-bits wide operation - needs an OS and an initiator that can handle
it.
6.2. What's missing in the ncr5390 (and probably future other controllers)
Bus free detection. Right now the bus is considered free if the
controllers isn't using it, which is true. This may change once
disconnected operation is in.
Target commands, we don't emulate (vs. HLE) any target yet.
This file describes SDL-specific usage information about MAME. It is
intended to cover aspects of using and configuring the program that are
specific to running MAME from the command line on any system which is
supported by SDL (including Windows).
In addition to the keys described in config.txt, the following additional
keys are defined for SDL-specific versions of MAME:
Debugging options
-----------------
-[no]oslog
Outputs the error.log data to the stderr TTY channel (usually the
command line window MAME was started in). This can be used at
the same time as -log to output the log data to both targets as well.
Default is OFF (-nooslog).
-watchdog <duration> / -wdog <duration>
Enables an internal watchdog timer that will automatically kill the MAME
process if more than <duration> seconds passes without a frame update.
Keep in mind that some games sit for a while during load time without
updating the screen, so <duration> should be long enough to cover that.
10-30 seconds on a modern system should be plenty in general. By default
there is no watchdog.
Performance options
-------------------
-[no]multithreading / -[no]mt
Enables multithreading for the final drawing operation. This can help
performance on multicore/hyperthreaded systems with slow video cards,
but may cause undesired behavior in some games.
Note that some drivers in MAME and MESS will use multiple threads even
when this is set to OFF, assuming -numprocessors allows it.
The default is OFF (-nomultithreading).
-numprocessors <auto|value> / -np <auto|value>
Specify the number of processors to use for work queues. Specifying
"auto" will use the value reported by the system or environment
variable OSDPROCESSORS. To avoid abuse, this value is internally limited
to 4 times the number of processors reported by the system.
The default is "auto".
-sdlvideofps
Enable output of benchmark data on the SDL video subsystem, including
your system's video driver, X server (if applicable), and OpenGL stack
in -video opengl mode.
-bench [n]
Benchmark for [n] number of emulated seconds; implies the command string:
-str [n] -video none -sound none -nothrottle. Default is OFF (-nobench)
Video options
-------------
-video <soft|opengl|none>
Specifies which video subsystem to use for drawing. The default for
Mac OS X is 'opengl' because OS X is guaranteed to have a compliant
OpenGL stack. The default on all other systems is 'soft'.
-numscreens <count>
Tells MAME how many output windows to create. For most games, a single
output window is all you need, but some games originally used multiple
screens. Each screen (up to 4) has its own independent settings for
physical monitor, aspect ratio, resolution, and view, which can be
set using the options below. The default is 1. SDL currently has a
limit of 1 with the expectation of increasing this when SDL 2.0 is
released.
-[no]window / -[no]w
Run MAME in either a window or full screen. The default is OFF
(-nowindow).
-[no]maximize / -[no]max
Controls initial window size in windowed mode. If it is set on, the
window will initially be set to the maximum supported size when you
start MAME. If it is turned off, the window will start out at the
smallest supported size. This option only has an effect when the
-window option is used. The default is ON (-maximize).
-[no]keepaspect / -[no]ka
Enables aspect ratio enforcement. When this option is on, the game's
proper aspect ratio (generally 4:3 or 3:4) is enforced, so you get the
game looking like it should. When running in a window with this option
on, you can only resize the window to the proper aspect ratio, unless
you are holding down the CONTROL key. By turning the option off, the
aspect ratio is allowed to float. In full screen mode, this means that
all games will stretch to the full screen size (even vertical games).
In window mode, it means that you can freely resize the window without
any constraints. The default is ON (-keepaspect).
-[no]unevenstretch
Allow non-integer stretch factors allowing for great window sizing
flexability. The default is ON. (-unevenstretch)
-[no]centerh
Center horizontally within the view area. Default is ON (-centerh).
-[no]centerv
Center vertically within the view area. Default is ON (-centerv).
-[no]waitvsync
Waits for the refresh period on your computer's monitor to finish
before starting to draw video to your screen. If this option is off,
MAME will just draw to the screen at any old time, even in the middle
of a refresh cycle. This can cause "tearing" artifacts, where the top
portion of the screen is out of sync with the bottom portion. Tearing
is not noticeable on all games, and some people hate it more than
others. However, if you turn this option on, you will waste more of
your CPU cycles waiting for the proper time to draw, so you will see a
performance hit. You should only need to turn this on in windowed mode.
In full screen mode, it is only needed if -triplebuffer does not
remove the tearing, in which case you should use -notriplebuffer
-waitvsync. Note that support for this option depends entirely on your
operating system and video drivers; in general it will not work in
windowed mode so -video opengl and fullscreen give the greatest chance
of success.
The default is OFF (-nowaitvsync).
-[no]syncrefresh
Enables speed throttling only to the refresh of your monitor. This
means that the game's actual refresh rate is ignored; however, the
sound code still attempts to keep up with the game's original refresh
rate, so you may encounter sound problems. This option is intended
mainly for those who have tweaked their video card's settings to
provide carefully matched refresh rate options. Note that this option
does not work with -video gdi mode.The default is OFF (-nosyncrefresh).
Video soft-specific options
---------------------------
-scalemode
Scale mode: none, async, yv12, yuy2, yv12x2, yuy2x2 (-video soft only)
Default is 'none'.
Video OpenGL-specific options
-----------------------------
-[no]filter / -[no]flt
Enable bilinear filtering on the game screen graphics. When disabled,
point filtering is applied, which is crisper but leads to scaling
artifacts. If you don't like the filtered look, you are probably better
off increasing the -prescale value rather than turning off filtering
altogether. The default is ON (-filter).
-prescale <amount>
Controls the size of the screen images when they are passed off to the
graphics system for scaling. At the minimum setting of 1, the screen
is rendered at its original resolution before being scaled. At higher
settings, the screen is expanded by a factor of <amount> before being
scaled. This produces a less blurry image at the expense of some speed
and also increases the effective resolution of non-screen elements such
as artwork and fonts. The default is 1.
-[no]gl_forcepow2texture Always use only power-of-2 sized textures (default off)
-[no]gl_notexturerect Don't use OpenGL GL_ARB_texture_rectangle (default on)
-[no]gl_vbo Enable OpenGL VBO, if available (default on)
-[no]gl_pbo Enable OpenGL PBO, if available (default on)
These 4 options are for compatibility in -video opengl. If you report
rendering artifacts you may be asked to try messing with them by the
devs, but normally they should be left at their defaults which results
in the best possible video performance.
-gl_glsl Enable OpenGL GLSL, if available (default off)
-gl_glsl_filter Enable OpenGL GLSL filtering instead of FF filtering 0-plain,
1-bilinear (default)
-glsl_shader_mame0 Custom OpenGL GLSL shader set mame bitmap 0
-glsl_shader_mame1 Custom OpenGL GLSL shader set mame bitmap 1
-glsl_shader_mame2 Custom OpenGL GLSL shader set mame bitmap 2
-glsl_shader_mame3 Custom OpenGL GLSL shader set mame bitmap 3
-glsl_shader_mame4 Custom OpenGL GLSL shader set mame bitmap 4
-glsl_shader_mame5 Custom OpenGL GLSL shader set mame bitmap 5
-glsl_shader_mame6 Custom OpenGL GLSL shader set mame bitmap 6
-glsl_shader_mame7 Custom OpenGL GLSL shader set mame bitmap 7
-glsl_shader_mame8 Custom OpenGL GLSL shader set mame bitmap 8
-glsl_shader_mame9 Custom OpenGL GLSL shader set mame bitmap 9
-glsl_shader_screen0 Custom OpenGL GLSL shader screen bitmap 0
-glsl_shader_screen1 Custom OpenGL GLSL shader screen bitmap 1
-glsl_shader_screen2 Custom OpenGL GLSL shader screen bitmap 2
-glsl_shader_screen3 Custom OpenGL GLSL shader screen bitmap 3
-glsl_shader_screen4 Custom OpenGL GLSL shader screen bitmap 4
-glsl_shader_screen5 Custom OpenGL GLSL shader screen bitmap 5
-glsl_shader_screen6 Custom OpenGL GLSL shader screen bitmap 6
-glsl_shader_screen7 Custom OpenGL GLSL shader screen bitmap 7
-glsl_shader_screen8 Custom OpenGL GLSL shader screen bitmap 8
-glsl_shader_screen9 Custom OpenGL GLSL shader screen bitmap 9
-gl_glsl_vid_attr Enable OpenGL GLSL handling of brightness and contrast.
Better RGB game performance. Default is on.
Per-window options
------------------
NOTE: Multiple Screens are limited to 1 until SDL 2.0 is released.
-screen <display>
-screen0 <display>
-screen1 <display>
-screen2 <display>
-screen3 <display>
Specifies which physical monitor on your system you wish to have each
window use by default. In order to use multiple windows, you must have
increased the value of the -numscreens option. The name of each
display in your system can be determined by running MAME with the
-verbose option. The display names are typically in the format of:
\\.\DISPLAYn, where 'n' is a number from 1 to the number of connected
monitors. The default value for these options is 'auto', which means
that the first window is placed on the first display, the second
window on the second display, etc.
The -screen0, -screen1, -screen2, -screen3 parameters apply to the
specific window. The -screen parameter applies to all windows. The
window-specific options override values from the all window option.
-aspect <width:height> / -screen_aspect <num:den>
-aspect0 <width:height>
-aspect1 <width:height>
-aspect2 <width:height>
-aspect3 <width:height>
Specifies the physical aspect ratio of the physical monitor for each
window. In order to use multiple windows, you must have increased the
value of the -numscreens option. The physical aspect ratio can be
determined by measuring the width and height of the visible screen
image and specifying them separated by a colon. The default value for
these options is 'auto', which means that MAME assumes the aspect
ratio is proportional to the number of pixels in the desktop video
mode for each monitor.
The -aspect0, -aspect1, -aspect2, -aspect3 parameters apply to the
specific window. The -aspect parameter applies to all windows. The
window-specific options override values from the all window option.
-resolution <widthxheight[@refresh]> / -r <widthxheight[@refresh]>
-resolution0 <widthxheight[@refresh]> / -r0 <widthxheight[@refresh]>
-resolution1 <widthxheight[@refresh]> / -r1 <widthxheight[@refresh]>
-resolution2 <widthxheight[@refresh]> / -r2 <widthxheight[@refresh]>
-resolution3 <widthxheight[@refresh]> / -r3 <widthxheight[@refresh]>
Specifies an exact resolution to run in. In full screen mode, MAME
will try to use the specific resolution you request. The width and
height are required; the refresh rate is optional. If omitted or
set to 0, MAME will determine the mode auomatically. For example,
-resolution 640x480 will force 640x480 resolution, but MAME is free to
choose the refresh rate. Similarly, -resolution 0x0@60 will force a
60Hz refresh rate, but allows MAME to choose the resolution. The
string "auto" is also supported, and is equivalent to 0x0@0. In window
mode, this resolution is used as a maximum size for the window. This
option requires the -switchres option as well in order to actually
Enable resolution switching.
The -resolution0, -resolution1, -resolution2, -resolution3 parameters
apply to the specific window. The -resolution parameter applies to all
windows. The window-specific options override values from the all
window option.
-view <viewname>
-view0 <viewname>
-view1 <viewname>
-view2 <viewname>
-view3 <viewname>
Specifies the initial view setting for each window. The <viewname>
does not need to be a perfect match; rather, it will select the first
view whose name matches all the characters specified by <viewname>.
For example, -view native will match the "Native (15:14)" view even
though it is not a perfect match. The value 'auto' is also supported,
and requests that MAME perform a default selection. The default value
for these options is 'auto'.
The -view0, -view1, -view2, -view3 parameters apply to the
specific window. The -view parameter applies to all windows. The
window-specific options override values from the all window option.
Full screen options
-------------------
-[no]switchres
Enables resolution switching. This option is required for the
-resolution* options to switch resolutions in full screen mode. On
modern video cards, there is little reason to switch resolutions unless
you are trying to achieve the "exact" pixel resolutions of the original
games, which requires significant tweaking. This option is also useful
on LCD displays, since they run with a fixed resolution and switching
resolutions on them is just silly.
The default is OFF (-noswitchres).
Sound options
-------------
-sound <sdl|none>
Specifies which sound subsystem to use. 'none' disables sound altogether.
The default is sdl.
-audio_latency <value>
This controls the amount of latency built into the audio streaming. By
default MAME tries to keep the audio buffer between 1/5 and 2/5 full.
On some systems, this is pushing it too close to the edge, and you get
poor sound sometimes. The latency parameter controls the lower threshold.
The default is 2 (meaning lower=2/5 and upper=3/5). Set it to 3
(-audio_latency 3) to keep the sound buffer between 3/5 and 4/5 full.
If you crank it up to 4, you can definitely notice the lag.
SDL Keyboard Mapping
--------------------
-keymap Enable keymap. Default is OFF (-nokeymap)
-keymap_file Keymap Filename. Default is 'keymap.dat'.
-uimodekey Key to toggle keyboard mode. Default is 'SCRLOCK'
SDL Joystick Mapping
--------------------
-joy_idx1 Name of joystick mapped to joystick #1, default is auto.
-joy_idx2 Name of joystick mapped to joystick #2, default is auto.
-joy_idx3 Name of joystick mapped to joystick #3, default is auto.
-joy_idx4 Name of joystick mapped to joystick #4, default is auto.
-joy_idx5 Name of joystick mapped to joystick #5, default is auto.
-joy_idx6 Name of joystick mapped to joystick #6, default is auto.
-joy_idx7 Name of joystick mapped to joystick #7, default is auto.
-joy_idx8 Name of joystick mapped to joystick #8, default is auto.
-sixaxis Use special handling for PS3 Sixaxis controllers.
Default is OFF (-nosixaxis)
SDL Lowlevel driver options
---------------------------
-videodriver SDL video driver to use ('x11', 'directfb', ... or 'auto' for SDL default
-audiodriver SDL audio driver to use ('alsa', 'arts', ... or 'auto' for SDL default
-gl_lib Alternative libGL.so to use; 'auto' for system default
This file describes Windows-specific usage information about MAME. It is
intended to cover aspects of using and configuring the program that are
specific to running MAME from the command line on a Windows-based system.
For common options that apply to all systems, please see config.txt.
In addition to the keys described in config.txt, the following additional
keys are defined for Windows versions of MAME:
Windows debugging options
-------------------------
-[no]oslog
Outputs the error.log data to the Windows debugger. This can be used at
the same time as -log to output the log data to both targets as well.
Default is OFF (-nooslog).
-watchdog <duration> / -wdog <duration>
Enables an internal watchdog timer that will automatically kill the MAME
process if more than <duration> seconds passes without a frame update.
Keep in mind that some games sit for a while during load time without
updating the screen, so <duration> should be long enough to cover that.
10-30 seconds on a modern system should be plenty in general. By default
there is no watchdog.
-debugger_font <fontname> / -dfont <fontname>
Specifies the name of the font to use for debugger windows. By default,
the font is Lucida Console.
-debugger_font_size <points> / -dfontsize <points>
Specifies the size of the font to use for debugger windows, in points.
By default, this is set to 9pt.
Windows performance options
---------------------------
-priority <priority>
Sets the thread priority for the MAME threads. By default the priority
is left alone to guarantee proper cooperation with other applications.
The valid range is -15 to 1, with 1 being the highest priority. The
default is 0 (NORMAL priority).
-[no]multithreading / -[no]mt
Enables multithreading within MAME. At the moment, this causes the
window and all DirectDraw/Direct3D code to execute on a second thread,
which can improve performance on hyperthreaded and multicore systems.
The default is OFF (-nomultithreading).
-numprocessors <auto|value> / -np <auto|value>
Specify the number of processors to use for work queues. Specifying
"auto" will use the value reported by the system or environment
variable OSDPROCESSORS. To avoid abuse, this value is internally limited
to 4 times the number of processors reported by the system.
The default is "auto".
-profile [n]
Enables profiling, specifying the stack depth of [n] to track.
-bench [n]
Benchmark for [n] number of emulated seconds; implies the command string:
-str [n] -video none -sound none -nothrottle
Windows video options
---------------------
-video <gdi|ddraw|d3d|none>
Specifies which video subsystem to use for drawing. By specifying 'gdi'
here, you tell MAME to render video using standard Windows graphics
drawing calls. This is the slowest but most compatible option.
Specifying 'ddraw' instructs MAME to use DirectDraw for rendering.
This causes MAME to render everything at a lower resolution and then
upscale the results at the end. This produces high performance,
especially on older or low-power video cards, but has a noticeably
lower output quality. Specifying 'd3d' tells MAME to use Direct3D for
rendering. This produces the highest quality output and enables all
rendering options. It is recommended if you have a recent (2002+)
video card. The final option 'none' displays no windows and does no
drawing. This is primarily present for doing CPU benchmarks without
the overhead of the video system. The default is d3d.
-numscreens <count>
Tells MAME how many output windows to create. For most games, a single
output window is all you need, but some games originally used multiple
screens. Each screen (up to 4) has its own independent settings for
physical monitor, aspect ratio, resolution, and view, which can be
set using the options below. The default is 1.
-[no]window / -[no]w
Run MAME in either a window or full screen. The default is OFF
(-nowindow).
-[no]maximize / -[no]max
Controls initial window size in windowed mode. If it is set on, the
window will initially be set to the maximum supported size when you
start MAME. If it is turned off, the window will start out at the
smallest supported size. This option only has an effect when the
-window option is used. The default is ON (-maximize).
-[no]keepaspect / -[no]ka
Enables aspect ratio enforcement. When this option is on, the game's
proper aspect ratio (generally 4:3 or 3:4) is enforced, so you get the
game looking like it should. When running in a window with this option
on, you can only resize the window to the proper aspect ratio, unless
you are holding down the CONTROL key. By turning the option off, the
aspect ratio is allowed to float. In full screen mode, this means that
all games will stretch to the full screen size (even vertical games).
In window mode, it means that you can freely resize the window without
any constraints. The default is ON (-keepaspect).
-prescale <amount>
Controls the size of the screen images when they are passed off to the
graphics system for scaling. At the minimum setting of 1, the screen
is rendered at its original resolution before being scaled. At higher
settings, the screen is expanded by a factor of <amount> before being
scaled. With -video ddraw or -video d3d, this produces a less blurry
image at the expense of some speed. In -video ddraw mode, this also
increases the effective resolution of non-screen elements such as
artwork and fonts. The default is 1.
-[no]waitvsync
Waits for the refresh period on your computer's monitor to finish
before starting to draw video to your screen. If this option is off,
MAME will just draw to the screen at any old time, even in the middle
of a refresh cycle. This can cause "tearing" artifacts, where the top
portion of the screen is out of sync with the bottom portion. Tearing
is not noticeable on all games, and some people hate it more than
others. However, if you turn this option on, you will waste more of
your CPU cycles waiting for the proper time to draw, so you will see a
performance hit. You should only need to turn this on in windowed mode.
In full screen mode, it is only needed if -triplebuffer does not
remove the tearing, in which case you should use -notriplebuffer
-waitvsync. Note that this option does not work with -video gdi mode.
The default is OFF (-nowaitvsync).
-[no]syncrefresh
Enables speed throttling only to the refresh of your monitor. This
means that the game's actual refresh rate is ignored; however, the
sound code still attempts to keep up with the game's original refresh
rate, so you may encounter sound problems. This option is intended
mainly for those who have tweaked their video card's settings to
provide carefully matched refresh rate options. Note that this option
does not work with -video gdi mode.The default is OFF (-nosyncrefresh).
DirectDraw-specific options
---------------------------
-[no]hwstretch / -[no]hws
When enabled, MAME uses the hardware stretching abilities of your
video card to scale the game image and associated artwork to the
target resolution. Depending on the quality of your graphic card and
its drivers, this may be a fractional, antialiased scaling (nice) or
an integer, blocky scaling (not so nice), in which case you might want
to disable this option. In addition, if you have configured specific
arcade-like video modes for MAME and don't want MAME to perform any
non-integral scaling of the image, you should also disable this option.
The default is ON (-hwstretch).
Direct3D-specific options
-------------------------
-[no]filter / -[no]d3dfilter / -[no]flt
Enable bilinear filtering on the game screen graphics. When disabled,
point filtering is applied, which is crisper but leads to scaling
artifacts. If you don't like the filtered look, you are probably better
off increasing the -prescale value rather than turning off filtering
altogether. The default is ON (-filter).
Per-window options
------------------
-screen <display>
-screen0 <display>
-screen1 <display>
-screen2 <display>
-screen3 <display>
Specifies which physical monitor on your system you wish to have each
window use by default. In order to use multiple windows, you must have
increased the value of the -numscreens option. The name of each
display in your system can be determined by running MAME with the
-verbose option. The display names are typically in the format of:
\\.\DISPLAYn, where 'n' is a number from 1 to the number of connected
monitors. The default value for these options is 'auto', which means
that the first window is placed on the first display, the second
window on the second display, etc.
The -screen0, -screen1, -screen2, -screen3 parameters apply to the
specific window. The -screen parameter applies to all windows. The
window-specific options override values from the all window option.
-aspect <width:height> / -screen_aspect <num:den>
-aspect0 <width:height>
-aspect1 <width:height>
-aspect2 <width:height>
-aspect3 <width:height>
Specifies the physical aspect ratio of the physical monitor for each
window. In order to use multiple windows, you must have increased the
value of the -numscreens option. The physical aspect ratio can be
determined by measuring the width and height of the visible screen
image and specifying them separated by a colon. The default value for
these options is 'auto', which means that MAME assumes the aspect
ratio is proportional to the number of pixels in the desktop video
mode for each monitor.
The -aspect0, -aspect1, -aspect2, -aspect3 parameters apply to the
specific window. The -aspect parameter applies to all windows. The
window-specific options override values from the all window option.
-resolution <widthxheight[@refresh]> / -r <widthxheight[@refresh]>
-resolution0 <widthxheight[@refresh]> / -r0 <widthxheight[@refresh]>
-resolution1 <widthxheight[@refresh]> / -r1 <widthxheight[@refresh]>
-resolution2 <widthxheight[@refresh]> / -r2 <widthxheight[@refresh]>
-resolution3 <widthxheight[@refresh]> / -r3 <widthxheight[@refresh]>
Specifies an exact resolution to run in. In full screen mode, MAME
will try to use the specific resolution you request. The width and
height are required; the refresh rate is optional. If omitted or
set to 0, MAME will determine the mode auomatically. For example,
-resolution 640x480 will force 640x480 resolution, but MAME is free to
choose the refresh rate. Similarly, -resolution 0x0@60 will force a
60Hz refresh rate, but allows MAME to choose the resolution. The
string "auto" is also supported, and is equivalent to 0x0@0. In window
mode, this resolution is used as a maximum size for the window. This
option requires the -switchres option as well in order to actually
enable resolution switching with -video ddraw or -video d3d. The
default value for these options is 'auto'.
The -resolution0, -resolution1, -resolution2, -resolution3 parameters
apply to the specific window. The -resolution parameter applies to all
windows. The window-specific options override values from the all
window option.
-view <viewname>
-view0 <viewname>
-view1 <viewname>
-view2 <viewname>
-view3 <viewname>
Specifies the initial view setting for each window. The <viewname>
does not need to be a perfect match; rather, it will select the first
view whose name matches all the characters specified by <viewname>.
For example, -view native will match the "Native (15:14)" view even
though it is not a perfect match. The value 'auto' is also supported,
and requests that MAME perform a default selection. The default value
for these options is 'auto'.
The -view0, -view1, -view2, -view3 parameters apply to the
specific window. The -view parameter applies to all windows. The
window-specific options override values from the all window option.
Full screen options
-------------------
-[no]triplebuffer / -[no]tb
Enables or disables "triple buffering". Normally, MAME just draws
directly to the screen, without any fancy buffering. But with this
option enabled, MAME creates three buffers to draw to, and cycles
between them in order. It attempts to keep things flowing such that one
buffer is currently displayed, the second buffer is waiting to be
displayed, and the third buffer is being drawn to. -triplebuffer will
override -waitvsync, if the buffer is sucessfully created. This option
does not work with -video gdi. The default is OFF (-notriplebuffer).
-[no]switchres
Enables resolution switching. This option is required for the
-resolution* options to switch resolutions in full screen mode. On
modern video cards, there is little reason to switch resolutions unless
you are trying to achieve the "exact" pixel resolutions of the original
games, which requires significant tweaking. This option is also useful
on LCD displays, since they run with a fixed resolution and switching
resolutions on them is just silly. This option does not work with
-video gdi. The default is OFF (-noswitchres).
-full_screen_brightness / -fsb <value>
Controls the brightness, or black level, of the entire display. The
standard value is 1.0. Selecting lower values (down to 0.1) will produce
a darkened display, while selecting higher values (up to 2.0) will
give a brighter display. Note that not all video cards have hardware to
support this option. This option does not work with -video gdi. The
default is 1.0.
-full_screen_contrast / -fsc <value>
Controls the contrast, or white level, of the entire display. The
standard value is 1.0. Selecting lower values (down to 0.1) will produce
a dimmer display, while selecting higher values (up to 2.0) will
give a more saturated display. Note that not all video cards have
hardware to support this option. This option does not work with
-video gdi. The default is 1.0.
-full_screen_gamma / -fsg <value>
Controls the gamma, which produces a potentially nonlinear black to
white ramp, for the entire display. The standard value is 1.0, which
gives a linear ramp from black to white. Selecting lower values (down
to 0.1) will increase the nonlinearity toward black, while selecting
higher values (up to 3.0) will push the nonlinearity toward white. Note
that not all video cards have hardware to support this option. This
option does not work with -video gdi. The default is 1.0.
Windows sound options
---------------------
-sound <dsound|sdl|none>
Specifies which sound subsystem to use. 'none' disables sound altogether.
The default is dsound.
-audio_latency <value>
This controls the amount of latency built into the audio streaming. By
default MAME tries to keep the DirectSound audio buffer between 1/5 and
2/5 full. On some systems, this is pushing it too close to the edge,
and you get poor sound sometimes. The latency parameter controls the
lower threshold. The default is 1 (meaning lower=1/5 and upper=2/5).
Set it to 2 (-audio_latency 2) to keep the sound buffer between 2/5 and
3/5 full. If you crank it up to 4, you can definitely notice the lag.
Input device options
--------------------
-[no]dual_lightgun / -[no]dual
Controls whether or not MAME attempts to track two lightguns connected
at the same time. This option requires -lightgun. This option is a hack
for supporting older dual lightgun setups. If you have multiple
lightguns connected, you will probably just need to enable -mouse and
configure each lightgun independently. The default is OFF
(-nodual_lightgun).
Place samples directories here
0.167
-------
MAMETesters Bugs Fixed
----------------------
- 00100: [Sound] (galdrvr.c) froggermc: After starting a game, the sound cuts off. (Osso)
- 05596: [Color/Palette] (thunderj.c) thunderj & clones: palette problem in the briefing (hap)
- 06049: [Gameplay] (ibmpcjr.c) ibmpcjr [kingqst, mouser, pitfall2, scubavnt] : some
softlist games are broken (crazyc)
Source Changes
--------------
-piggypas.c: fixed CPU type, added layout and some inputs. [Sandro Ronco]
-firebeat: add proper dongle dumps for kbm3rd, pop4 and popn5 [Guru, Ville Linde]
-Fix reversion for PI. PI transfers round length up, not down. Add [Happy]
field for VI interlaced modes. Display of interlaced video still
needs work.
-adding ROM dump of Commodore MPS-1000 dot matrix printer [Felipe Sanches]
-dvk_ksm: update memory map, rom checksums. [shattered]
-ec1840, ec1841: clean up memory options [shattered]
-Victor 9000 Keyboard: Added two key labels I realized I'd forgotten.
Updated comments to be more clear about keys with multiple contacts
underneath but only one metal contact on the key. Noted in comments
that the symbolic and mode keys on the numeric keypad (except for
decimal point) are beige, not white. [Lord Nightmare]
-DEC LA120: Make the status leds and 7seg displays a popmessage(), for
now. [Lord Nightmare]
-Votrax TNT: fixed the memory map mirroring based on schematic.
[Lord Nightmare, Kevtris]
-added correct sprite rom dumps to Led Storm Rally 2011 (US) [Guru]
-adjusted the rom loading / gfxdecoding in the driver to accommodate
the correct ROMs for Led Storm Rally 2011 [David Haywood]
-z80scc rework [Joakim Larsson]
* z80scc_channel class rebased on device_t instead of z80sio_channel
* Improved LOG printouts
* Interrupt support started
* Made register pointer bits shared bewtween A and B channel as per
spec
* Variant type keeping moved from channel class to device class where
it belongs
* Clocks are blocked until Rx/Tx enabled by ROM code
* Improved logging
* Started variant handling
-tiki100: Added 8088 expansion ROMs. [Person]
-tiki100: Used PROM for memory mapping. [Curt Coder]
-tiki100: Added expansion bus and skeleton for 8088 card. [Curt Coder]
-tiki100: Connected the I/O space to the expansion bus, and added the
360KB floppy format for MS-DOS. [Curt Coder]
-tiki100: Added raw screen parameters. [Curt Coder]
-tiki100: Added DART speed select jumper. [Curt Coder]
-tiki100: Added skeleton for Winchester controller. [Curt Coder]
-tiki100: Added the expansion bus slots to the Z80 daisy chain.
[Curt Coder]
-tiki100: Added BUSRQ, BUSAK, and EXIN to the expansion bus.
[Curt Coder]
-PTY support for u*x OSes [F.Ulivi]
-Fix to allow mips3 exceptions to detect branch delay slots for setting
EPC. Minor cleanup/correction for n64.c [Happy]
-Added Siemens Sicomp PC16-05 BIOS ROM (Multitech MPF-PC/700 mainboard) [rfka01]
-Split cat.c into separate drivers for canon cat and iai swyft. [Lord Nightmare]
-PSX GPU: Fix the 24bit rendering of video sequences on games such as
GranTurismo and Digimon World 3 [Felipe Sanches]
-ETI-660 fixed and working [Robbbert]
-Camputers Lynx 48k, 96k, 128k fixed and working. [Robbbert]
-Game-A-Tron gambling hardware changes [Roberto Fresca]:
* Added siren/alarm input to Pull Tabs, and beeps/alarm input to Four
In One Poker. All these are present in the Test Mode. However,
their functions aren't clear.
* Switched the PSG to SN76489, since it's present in the Bingo PCB.
* Added technical notes and more documentation.
-Pinball, Bally early solid state (by17.c by35.c) [Quench]
* Add mockup playfield layouts for Playboy, PowerPlay and Matahari
that includes input/output devices
* Add sound to first gen -35 games
* Various fixes based on schematics and measurements.
-TMS52xx: Fix a bug where if the FIFO contained exactly 0 bytes and a
SPEAK (VSM) command was issued, the command would instantly terminate
due to the FIFO being empty even though the chip wasn't in SPEAK
EXTERNAL mode. Fixes speech in TI Extended Basic [Lord Nightmare]
-wackygtr: added inputs and internal layout. [Sandro Ronco]
-Aristocrat MKV driver: Added the undumped PLD devices to Adonis
(parent) ROM_LOAD since is running in the same hardware than the
recent added clon. [Roberto Fresca]
-Aristocrat MKV driver: Added PCB ASCII layout and components
description. Added extra documentation and some notes. [Roberto
Fresca]
-Aristocrat MKV driver improvements [Roberto Fresca]
Added the undumped ST93C46 serial EEPROMS to Adonisa, and added a placeholder to
the parent set for the same devices, flagged as NO_DUMP. Added master
crystal via #define, and derived the CPU clock. Added some technical
notes.
-saa5050: graphics generator and character rounding [Nigel Barnes]
* implemented graphics generator, no longer read from fake ROM
* added character rounding
* improved control code handling
* added ROMs for variants saa5051, saa5053, saa5054, saa5055,
saa5056, saa5057
-osborne1: add SCREEN-PAC support [Vas Crabb]
* implement 104-column and pseudo-80-column modes
* correct scrolling in 52-column mode according to schematics
* approximate scrolling in 104-column and pseudo-80-column modes
* rework Osborne 1 memory and I/O maps to match schematics
-bbc: floppy formats and rom updates [Nigel Barnes]
* improved ssd, dsd handling
* added Acorn DOS and CPM formats
* added known good rom configuration for acw443 (Cambridge
Workstation)
* removed some BAD_DUMP flags
-bbc: various softlists [Nigel Barnes]
* bbca_cass - new titles and additional info added
* bbcb_cass - new titles and additional info added
* bbcb_flop - preliminary list containing test cases
* bbcm_flop - preliminary list
* bbc_32016_flop - requires additional hardware emulated
* bbc_65c102_flop - requires additional hardware emulated
* bbc_80186_flop - requires additional hardware emulated
* bbc_arm_flop - requires additional hardware emulated
* bbc_z80_flop - requires additional hardware emulated
* pro128s_flop - all known available dumps
-bbc: fdc intrq/drq causes nmi [Nigel Barnes]
-HLSL changes [ImJezze]
* Unified HLSL render pipline for raster and vector graphics
* simplified draw call of render pass functions
* reduced number of used render targets from 7 to 4 (2 native and 2
pre-scaled)
* made render pass functions (nearly) independent from each other
* unified render pipeline for raster and vector graphics, which means
that all effects are now also available for vector graphics
(except scan-lines)
* removed/replaced simple.fx by primary.fx
* removed CU_PHOSPHOR_IGNORE uniform, which was only used in phosphor
pass function and is now directly set
* added CU_TARGET_DIMS uniform based on the current render target
* added CU_QUAD_DIMS uniform based on the current full screen polygon
quad
* removed pre-scale knowledge from shaders
* fixed DX9 related half pixel offset in most shaders
* reduced shadow mask color bleeding
* fixed defocus strength with different pre-scales
* added slight noise to bloom effect to reduce the color banding of
lower bloom levels
* fixed position of reflection effect when screen is rotated or
flipped
* fixed roundness and size of rounded corners in any aspect ratio
* added distortion pass, which is applied after the bloom pass and
moved curvature, vignetting, rounded corners and reflection effect
to this pass
* fixed bloom stair-step artifacts when screen is curved
* added smooth border effect and option, its amount is limited by the
amount of rounded corners
* added bloom overdrive effect and options, this effect allows to
overdrive pure colors like red, green and blue to become more
brighter
* merged vector and raster bloom options, use vector.ini or
raster.ini to distinguish
* added raster.ini and lcd.ini to parse_standard_inis()
* added bounds() and screen_bounds() getter to layout_view
* added current_view() getter to render_target
* many other small changes and refactoring
* fixed vector intensity
* fixed vector flicker
* replace beam width by beam width min. and beam width max. width, this
makes it possible to create a linear dynamic beam width by the amount
of intensity of the beam
* added beam intensity weight, this adds an exponential factor to the
dynamic beam width (values greater than 0 will push larger intensities
more than smaller intensities)
* fixed ratio of "vector points" (zero-length lines)
-psxcd: Declaring ROM images for the CDROM controller MCU. [Felipe Sanches]
-Apollo changes: [Hans Ostermeyer]
* fixed the Apollo floppy disk emulation
* added the media option -node_id resp. -ni to set the node ID from a
node ID rom image file
* fixed the unmapped ISA Bus access to return 0xff instead of 0x00
* removed excessive log entries from unmapped ISA Bus access
* fixed date (and some other issues) in mc146818 (new in MAME 0166)
-Fix for imds2 driver after i8271 modernization [F.Ulivi]
-namcos23: fix the polynew conversion [O. Galibert]
-namcos23: Go back to z-sorting [O. Galibert]
-deorphaned the software lists for cd32, 3do_m2 and pippin so that they get
parsed by the validity checker etc. [Shideravan]
-amstrad: added Draysoft Doubler expansion [Barry Rodewald]
-Changed the qotna set to run in a US-Export hardware.
Even when is NSW/ACT, the program seems to run in that hardware.
Added more documentation. [Roberto Fresca]
-apple2: fixed "The Mill" 6809 card so OS9 can boot. [robj, R. Belmont]
-Changed the vpoker set description to Videotronics Draw Poker,
since the game is "Draw Poker". Two companies sold it with
different name. Documented the legal issues and added links.
[Roberto Fresca]
-Update VMX/Altivec RGB implementation (fixes PowerPC) [Vas Crabb]
New machines added or promoted from NOT_WORKING status
------------------------------------------------------
Attack Pla Rail (Japan, AP1/VER.A) [Guru, R. Belmont]
Led Storm Rally 2011 (US) [Guru, David Haywood]
Player's Edge Plus (X002287P+XP000057) Pay the Aces NO Faces Bonus Poker [BrianT]
Exidy Sorcerer II [Robbbert]
Unisonic Champion 2711 [David Viens]
SegaSonic Popcorn Shop (Rev B) [ShouTime, The Dumping Union - insert full credit list here]
New clones added or promoted from NOT_WORKING status
----------------------------------------------------
Final Fight (USA 900424) [Bonky0013]
Lightning Swords [System11, The Dumping Union]
Air Duel (World, M82) [system11, The Dumping Union]
Ken-Go (set 2) [caius]
Master Boy (Italian, PCB Rev A, set 2) [Any, The Dumping Union]
WEC Le Mans 24 (v1.26) [Any, The Dumping Union]
Wonder Stick (set 2, censored) [Any, The Dumping Union]
Sliver (set 2) [Any, The Dumping Union]
Joe & Mac Returns (Japan, Version 1.2, 1994.06.06) [rtw, The Dumping Union]
Led Storm Rally 2011 (World) [system11]
Player's Edge Plus (KE0004) Keno [Badbaud, BrianT]
Player's Edge Plus (KE1006) Keno [Badbaud, BrianT]
Player's Edge Plus (KE1013) Keno (set 2) [Badbaud, BrianT]
Player's Edge Plus (PP0042) 10's or Better (set 2) [Badbaud, BrianT]
Player's Edge Plus (PP0045) 10's or Better (Gambler Downtown Reno) [Badbaud, BrianT]
Player's Edge Plus (PP0045) 10's or Better (Par-A-Dice Riverboat Casino) [Badbaud, BrianT]
Player's Edge Plus (PP0045) 10's or Better (Annie Oakely's Central City) [Badbaud, BrianT]
Player's Edge Plus (PP0055) Deuces Wild Poker (set 2, Skyline Casino) [Badbaud, BrianT]
Player's Edge Plus (PP0158) 4 of a Kind Bonus Poker (set 2, Skyline Casino) [Badbaud, BrianT]
Player's Edge Plus (PP0430) Deuces Joker Wild Poker [Badbaud, BrianT]
Player's Edge Plus (PP0459) Joker Poker [Badbaud, BrianT]
Player's Edge Plus (PP0515) Double Bonus Poker (set 4) [Badbaud, BrianT]
Player's Edge Plus (X000055P+XP000038) Deuces Wild Poker (Sunset Station Hotel-Casino)
[Badbaud, BrianT]
Player's Edge Plus (X000426P+XP000038) Joker Poker [Badbaud, BrianT]
Player's Edge Plus (X002179P+XP000119) Double Bonus Poker [BrianT]
Player's Edge Plus (XM00006P+XMP00002) Multi-Poker (The Orleans) [Badbaud, BrianT]
New machines marked as NOT_WORKING
----------------------------------
Micral 80-22G [Robbbert]
Data RD100 [Robbbert]
Proteus III [Robbbert]
Neo Print (Japan) (T2d) [Bonky0013]
Cuckoo (MV4104, Export) [Roberto Fresca]
Mine, Mine, Mine (Export) [Roberto Fresca]
Party Gras (MV4115/6, Export) [Roberto Fresca]
Penguin Pays (Export) [Roberto Fresca]
Wild Cougar (Export) [Roberto Fresca]
Boot Scootin' (Export, 92.767%) [Roberto Fresca]
Bumble Bugs (Export, 92.691%) [Roberto Fresca]
Cash Chameleon (Export) [Roberto Fresca]
Sub Hunter [Piero Andreini]
The Chariot Challenge (04J00714, NSW/ACT) [Roberto Fresca]
Eagle 1600 [SomeGuy]
New clones marked as NOT_WORKING
--------------------------------
Dolphin Treasure (Export) [Roberto Fresca]
Magic Mask (MV4115, Export, set 2) [Roberto Fresca]
Adonis (MV4124/1, Export) [Roberto Fresca]
Mega-CD with 32X (Japan, NTSC) [Shideravan]
Mega-CD with 32X (Europe, PAL) [Shideravan]
Adonis (0100751V, NSW/ACT) [Roberto Fresca]
Dolphin Treasure (Export) [Roberto Fresca]
Queen of the Nile (MV4091, NSW/ACT) [Roberto Fresca]
New WORKING software list additions
-----------------------------------
a2600.xml: Atari 2600 cartridges
- Stella's Stocking 2008 [The Dumping Union]
megadriv.xml:
- Putty Squad (prototype) [?]
New NOT_WORKING software list additions
---------------------------------------
