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 &sector_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
---------------------------------------