mirror of
https://github.com/holub/mame
synced 2025-06-14 08:26:57 +03:00
remove old doc content (nw)
This commit is contained in:
parent
bade8ef9a9
commit
a86a53fb64
116
docs/LICENSE
116
docs/LICENSE
@ -1,116 +0,0 @@
|
|||||||
CC0 1.0 Universal
|
|
||||||
|
|
||||||
Statement of Purpose
|
|
||||||
|
|
||||||
The laws of most jurisdictions throughout the world automatically confer
|
|
||||||
exclusive Copyright and Related Rights (defined below) upon the creator and
|
|
||||||
subsequent owner(s) (each and all, an "owner") of an original work of
|
|
||||||
authorship and/or a database (each, a "Work").
|
|
||||||
|
|
||||||
Certain owners wish to permanently relinquish those rights to a Work for the
|
|
||||||
purpose of contributing to a commons of creative, cultural and scientific
|
|
||||||
works ("Commons") that the public can reliably and without fear of later
|
|
||||||
claims of infringement build upon, modify, incorporate in other works, reuse
|
|
||||||
and redistribute as freely as possible in any form whatsoever and for any
|
|
||||||
purposes, including without limitation commercial purposes. These owners may
|
|
||||||
contribute to the Commons to promote the ideal of a free culture and the
|
|
||||||
further production of creative, cultural and scientific works, or to gain
|
|
||||||
reputation or greater distribution for their Work in part through the use and
|
|
||||||
efforts of others.
|
|
||||||
|
|
||||||
For these and/or other purposes and motivations, and without any expectation
|
|
||||||
of additional consideration or compensation, the person associating CC0 with a
|
|
||||||
Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
|
|
||||||
and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
|
|
||||||
and publicly distribute the Work under its terms, with knowledge of his or her
|
|
||||||
Copyright and Related Rights in the Work and the meaning and intended legal
|
|
||||||
effect of CC0 on those rights.
|
|
||||||
|
|
||||||
1. Copyright and Related Rights. A Work made available under CC0 may be
|
|
||||||
protected by copyright and related or neighboring rights ("Copyright and
|
|
||||||
Related Rights"). Copyright and Related Rights include, but are not limited
|
|
||||||
to, the following:
|
|
||||||
|
|
||||||
i. the right to reproduce, adapt, distribute, perform, display, communicate,
|
|
||||||
and translate a Work;
|
|
||||||
|
|
||||||
ii. moral rights retained by the original author(s) and/or performer(s);
|
|
||||||
|
|
||||||
iii. publicity and privacy rights pertaining to a person's image or likeness
|
|
||||||
depicted in a Work;
|
|
||||||
|
|
||||||
iv. rights protecting against unfair competition in regards to a Work,
|
|
||||||
subject to the limitations in paragraph 4(a), below;
|
|
||||||
|
|
||||||
v. rights protecting the extraction, dissemination, use and reuse of data in
|
|
||||||
a Work;
|
|
||||||
|
|
||||||
vi. database rights (such as those arising under Directive 96/9/EC of the
|
|
||||||
European Parliament and of the Council of 11 March 1996 on the legal
|
|
||||||
protection of databases, and under any national implementation thereof,
|
|
||||||
including any amended or successor version of such directive); and
|
|
||||||
|
|
||||||
vii. other similar, equivalent or corresponding rights throughout the world
|
|
||||||
based on applicable law or treaty, and any national implementations thereof.
|
|
||||||
|
|
||||||
2. Waiver. To the greatest extent permitted by, but not in contravention of,
|
|
||||||
applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
|
|
||||||
unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
|
|
||||||
and Related Rights and associated claims and causes of action, whether now
|
|
||||||
known or unknown (including existing as well as future claims and causes of
|
|
||||||
action), in the Work (i) in all territories worldwide, (ii) for the maximum
|
|
||||||
duration provided by applicable law or treaty (including future time
|
|
||||||
extensions), (iii) in any current or future medium and for any number of
|
|
||||||
copies, and (iv) for any purpose whatsoever, including without limitation
|
|
||||||
commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
|
|
||||||
the Waiver for the benefit of each member of the public at large and to the
|
|
||||||
detriment of Affirmer's heirs and successors, fully intending that such Waiver
|
|
||||||
shall not be subject to revocation, rescission, cancellation, termination, or
|
|
||||||
any other legal or equitable action to disrupt the quiet enjoyment of the Work
|
|
||||||
by the public as contemplated by Affirmer's express Statement of Purpose.
|
|
||||||
|
|
||||||
3. Public License Fallback. Should any part of the Waiver for any reason be
|
|
||||||
judged legally invalid or ineffective under applicable law, then the Waiver
|
|
||||||
shall be preserved to the maximum extent permitted taking into account
|
|
||||||
Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
|
|
||||||
is so judged Affirmer hereby grants to each affected person a royalty-free,
|
|
||||||
non transferable, non sublicensable, non exclusive, irrevocable and
|
|
||||||
unconditional license to exercise Affirmer's Copyright and Related Rights in
|
|
||||||
the Work (i) in all territories worldwide, (ii) for the maximum duration
|
|
||||||
provided by applicable law or treaty (including future time extensions), (iii)
|
|
||||||
in any current or future medium and for any number of copies, and (iv) for any
|
|
||||||
purpose whatsoever, including without limitation commercial, advertising or
|
|
||||||
promotional purposes (the "License"). The License shall be deemed effective as
|
|
||||||
of the date CC0 was applied by Affirmer to the Work. Should any part of the
|
|
||||||
License for any reason be judged legally invalid or ineffective under
|
|
||||||
applicable law, such partial invalidity or ineffectiveness shall not
|
|
||||||
invalidate the remainder of the License, and in such case Affirmer hereby
|
|
||||||
affirms that he or she will not (i) exercise any of his or her remaining
|
|
||||||
Copyright and Related Rights in the Work or (ii) assert any associated claims
|
|
||||||
and causes of action with respect to the Work, in either case contrary to
|
|
||||||
Affirmer's express Statement of Purpose.
|
|
||||||
|
|
||||||
4. Limitations and Disclaimers.
|
|
||||||
|
|
||||||
a. No trademark or patent rights held by Affirmer are waived, abandoned,
|
|
||||||
surrendered, licensed or otherwise affected by this document.
|
|
||||||
|
|
||||||
b. Affirmer offers the Work as-is and makes no representations or warranties
|
|
||||||
of any kind concerning the Work, express, implied, statutory or otherwise,
|
|
||||||
including without limitation warranties of title, merchantability, fitness
|
|
||||||
for a particular purpose, non infringement, or the absence of latent or
|
|
||||||
other defects, accuracy, or the present or absence of errors, whether or not
|
|
||||||
discoverable, all to the greatest extent permissible under applicable law.
|
|
||||||
|
|
||||||
c. Affirmer disclaims responsibility for clearing rights of other persons
|
|
||||||
that may apply to the Work or any use thereof, including without limitation
|
|
||||||
any person's Copyright and Related Rights in the Work. Further, Affirmer
|
|
||||||
disclaims responsibility for obtaining any necessary consents, permissions
|
|
||||||
or other rights required for any use of the Work.
|
|
||||||
|
|
||||||
d. Affirmer understands and acknowledges that Creative Commons is not a
|
|
||||||
party to this document and has no duty or obligation with respect to this
|
|
||||||
CC0 or use of the Work.
|
|
||||||
|
|
||||||
For more information, please see
|
|
||||||
<http://creativecommons.org/publicdomain/zero/1.0/>
|
|
@ -1,5 +0,0 @@
|
|||||||
# **Docs** #
|
|
||||||
|
|
||||||
Documentation of MAME is work of many different contributors, and contain information about usage and internals of MAME.
|
|
||||||
|
|
||||||
Licensed under [CC0 1.0 Universal (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/)
|
|
376
docs/SDL.txt
376
docs/SDL.txt
@ -1,376 +0,0 @@
|
|||||||
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
|
|
||||||
|
|
1264
docs/config.txt
1264
docs/config.txt
File diff suppressed because it is too large
Load Diff
@ -1,60 +0,0 @@
|
|||||||
Compiling MAME to JavaScript via Emscripten
|
|
||||||
===========================================
|
|
||||||
|
|
||||||
First, download and install Emscripten by following the instructions at the
|
|
||||||
official site:
|
|
||||||
|
|
||||||
https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html
|
|
||||||
|
|
||||||
Once Emscripten has been installed, it should be possible to compile MAME
|
|
||||||
out-of-the-box using Emscripten's 'emmake' tool. Because a full MAME compile is
|
|
||||||
too large to load into a web browser at once, you will want to use the SOURCES
|
|
||||||
parameter to compile only a subset of the project, e.g. (in the mame directory):
|
|
||||||
|
|
||||||
emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp
|
|
||||||
|
|
||||||
The SOURCES parameter should have the path to at least one driver .cpp file.
|
|
||||||
The make process will attempt to locate and include all dependencies necessary
|
|
||||||
to produce a complete build including the specified driver(s). However,
|
|
||||||
sometimes it is necessary to manually specify additional files (using commas) if
|
|
||||||
this process misses something. E.g.:
|
|
||||||
|
|
||||||
emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp
|
|
||||||
|
|
||||||
The value of the SUBTARGET parameter serves only to differentiate multiple
|
|
||||||
builds and need not be set to any specific value.
|
|
||||||
|
|
||||||
Other make parameters can also be used, e.g. -j for multithreaded compilation.
|
|
||||||
|
|
||||||
When the compilation reaches the emcc phase, you may see a number of "unresolved
|
|
||||||
symbol" warnings. At the moment, this is expected for OpenGL-related functions
|
|
||||||
such as glPointSize. Any others may indicate that an additional dependency file
|
|
||||||
needs to be specified in the SOURCES list. Unfortunately this process is not
|
|
||||||
automated and you will need to search the source tree to locate the files
|
|
||||||
supplying the missing symbols. You may also be able to get away with ignoring
|
|
||||||
the warnings if the code path referencing them is not used at run-time.
|
|
||||||
|
|
||||||
If all goes well, a .js file will be output to the current directory. This file
|
|
||||||
cannot be run by itself, but requires an HTML loader to provide it with a canvas
|
|
||||||
to output to and pass in command-line parameters. The Emularity project provides
|
|
||||||
such a loader:
|
|
||||||
|
|
||||||
https://github.com/db48x/emularity
|
|
||||||
|
|
||||||
There are example .html files in that repository which can be edited to point
|
|
||||||
to your newly compiled MAME js filename and pass in whatever parameters you
|
|
||||||
desire. You will then need to place all of the following on a web server:
|
|
||||||
|
|
||||||
* The compiled MAME .js file
|
|
||||||
* The .js files from the Emularity package (loader.js, browserfs.js, etc.)
|
|
||||||
* A .zip file with the ROMs for the MAME driver you would like to run (if any)
|
|
||||||
* Any software files you would like to run with the MAME driver
|
|
||||||
* An Emularity loader .html modified to point to all of the above
|
|
||||||
|
|
||||||
You need to use a web server instead of opening the local files directly due to
|
|
||||||
security restrictions in modern web browsers.
|
|
||||||
|
|
||||||
If the result fails to run, you can open the Web Console in your browser to see
|
|
||||||
any error output which may have been produced (e.g. missing or incorrect ROM
|
|
||||||
files). A "ReferenceError: foo is not defined" error most likely indicates that
|
|
||||||
a needed source file was omitted from the SOURCES list.
|
|
633
docs/floppy.txt
633
docs/floppy.txt
@ -1,633 +0,0 @@
|
|||||||
The new floppy subsystem
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
1. Introduction
|
|
||||||
|
|
||||||
The new floppy subsystem aims at emulating the behaviour of floppies
|
|
||||||
and floppy controllers at a level low enough that protections work as
|
|
||||||
a matter of course. It reaches its goal by following the real
|
|
||||||
hardware configuration:
|
|
||||||
|
|
||||||
- a floppy image class keeps in memory the magnetic state of the
|
|
||||||
floppy surface and its physical characteristics
|
|
||||||
|
|
||||||
- an image handler class talks with the floppy image class to simulate
|
|
||||||
the floppy drive, providing all the signals you have on a floppy drive
|
|
||||||
connector
|
|
||||||
|
|
||||||
- floppy controller devices talk with the image handler and provide
|
|
||||||
the register interfaces to the host we all know and love
|
|
||||||
|
|
||||||
- format handling classes are given the task of statelessly converting
|
|
||||||
to and from an on-disk image format to the in-memory magnetic state
|
|
||||||
format the floppy image class manages
|
|
||||||
|
|
||||||
|
|
||||||
2. Floppy storage 101
|
|
||||||
2.1. Floppy disk
|
|
||||||
|
|
||||||
A floppy disk is a disc that stores magnetic orientations on their
|
|
||||||
surface disposed in a series on concentric circles called tracks or
|
|
||||||
cylinders[1]. Its main characteristics are its size (goes from a
|
|
||||||
diameter of around 2.8" to 8") , its number of writable sides (1 or 2)
|
|
||||||
and its magnetic resistivity. The magnetic resistivity indicates how
|
|
||||||
close magnetic orientation changes can happen and the information
|
|
||||||
kept. That's one third of what defines the term "density" that is so
|
|
||||||
often used for floppies (the other two are floppy drive head size and
|
|
||||||
bit-level encoding).
|
|
||||||
|
|
||||||
The magnetic orientations are always binary, e.g. they're one way or
|
|
||||||
the opposite, there's no intermediate state. Their direction can
|
|
||||||
either be tengentially to the track, e.g in the direction or opposite
|
|
||||||
to the rotation, or in the case of perpendicular recording the
|
|
||||||
direction is perpendicular to the disc surface (hence the name).
|
|
||||||
Perpendicular recording allows for closer orientation changes by
|
|
||||||
writing the magnetic information more deeply, but arrived late in the
|
|
||||||
technology lifetime. 2.88Mb disks and the floppy children (Zip
|
|
||||||
drives, etc) used perpendicular recording. For simulation purposes
|
|
||||||
the direction is not important, only the fact that only two
|
|
||||||
orientations are possible is. Two more states are possible though: a
|
|
||||||
portion of a track can be demagnetized (no orientation) or damaged (no
|
|
||||||
orientation and can't be written to).
|
|
||||||
|
|
||||||
A specific position in the disk rotation triggers an index pulse.
|
|
||||||
That position can be detected through a hole in the surface (very
|
|
||||||
visible in 5.25" and 3" floppies for instance) or through a specific
|
|
||||||
position of the rotating center (3.5" floppies, perhaps others). This
|
|
||||||
index pulse is used to designate the beginning of the track, but is
|
|
||||||
not used by every system. Older 8" floppies have multiple index holes
|
|
||||||
used to mark the beginning of sectors (called hard sectoring) but one
|
|
||||||
of them is positioned differently to be recognized as the track start,
|
|
||||||
and the others are at fixed positions relative to the origin one.
|
|
||||||
|
|
||||||
|
|
||||||
2.2 Floppy drive
|
|
||||||
|
|
||||||
A floppy drive is what reads and writes a floppy disk. It includes an
|
|
||||||
assembly capable of rotating the disk at a fixed speed and one or two
|
|
||||||
magnetic heads tied to a positioning motor to access the tracks.
|
|
||||||
|
|
||||||
The head width and positioning motor step size decides how many tracks
|
|
||||||
are written on the floppy. Total number of tracks goes from 32 to 84
|
|
||||||
depending on the floppy and drive, with the track 0 being the most
|
|
||||||
exterior (longer) one of the concentric circles, and the highest
|
|
||||||
numbered the smallest interior circle. As a result the tracks with
|
|
||||||
the lowest numbers have the lowest physical magnetic orientation
|
|
||||||
density, hence the best reliability. Which is why important and/or
|
|
||||||
often changed structures like the boot block or the fat allocation
|
|
||||||
table are at track 0. That is also where the terminology "stepping
|
|
||||||
in" to increase the track number and "stepping out" to decrease it
|
|
||||||
comes from. The number of tracks available is the second part of what
|
|
||||||
is usually behind the term "density".
|
|
||||||
|
|
||||||
A sensor detects when the head is on track 0 and the controller is not
|
|
||||||
supposed to try to go past it. In addition physical blocks prevent
|
|
||||||
the head from going out of the correct track range. Some systems
|
|
||||||
(Apple II, some C64) do not take the track 0 sensor into account and
|
|
||||||
just wham the head against the track 0 physical block, giving a
|
|
||||||
well-known crash noise and eventually damaging the head alignment.
|
|
||||||
|
|
||||||
Also, some systems (Apple II and C64 again) have direct access to the
|
|
||||||
phases of the head positioning motor, allowing to trick the head into
|
|
||||||
going between tracks, in middle or even quarter positions. That was
|
|
||||||
not usable to write more tracks, since the head width did not change,
|
|
||||||
but since reliable reading was only possible with the correct position
|
|
||||||
it was used for some copy protection systems.
|
|
||||||
|
|
||||||
The disk rotates at a fixed speed for a given track. The most usual
|
|
||||||
speed is 300 rpm for every track, with 360 rpm found for HD 5.25"
|
|
||||||
floppies and most 8" ones, and a number of different values like 90 rpm
|
|
||||||
for the earlier floppies or 150 rpm for an HD floppy in an Amiga.
|
|
||||||
Having a fixed rotational speed for the whole disk is called Constant
|
|
||||||
Angular Velocity (CAV, almost everybody) or Zoned Constant Angular
|
|
||||||
Velocity (ZCAV, C64) depending on whether the read/write bitrate is
|
|
||||||
constant or track-dependant. Some systems (Apple II, Mac) vary the
|
|
||||||
rotational speed depending on the track (something like 394 rpm up to
|
|
||||||
590 rpm) to end up with a Constant Linear Velocity (CLV). The idea
|
|
||||||
behind ZCAV/CLV is to get more bits out of the media by keeping the
|
|
||||||
minimal spacing between magnetic orientation transitions close to the
|
|
||||||
best the support can do. It seems that the complexity was not deemed
|
|
||||||
worth it since almost no system does it.
|
|
||||||
|
|
||||||
Finally, after the disc rotates and the head is over the proper track
|
|
||||||
reading happens. The reading is done through an inductive head, which
|
|
||||||
gives it the interesting characteristic of not reading the magnetic
|
|
||||||
orientation directly but instead of being sensitive to orientation
|
|
||||||
inversions, called flux transitions. This detection is weak and
|
|
||||||
somewhat uncalibrated, so an amplifier with Automatic Gain Calibration
|
|
||||||
(AGC) and a peak detector are put behind the head to deliver clean
|
|
||||||
pulses. The AGC slowly increases the amplification level until a
|
|
||||||
signal goes over the threshold, then modulates its gain so that said
|
|
||||||
signal is at a fixed position over the threshold. Afterwards the
|
|
||||||
increase happens again. This makes the amplifier calibrate itself to
|
|
||||||
the signals read from the floppy as long as flux transitions happen
|
|
||||||
often enough. Too long and the amplification level will reach a point
|
|
||||||
where the random noise the head picks from the environment is
|
|
||||||
amplified over the threshold, creating a pulse where none should be.
|
|
||||||
Too long in our case happens to be around 16-20us with no transitions.
|
|
||||||
That means a long enough zone with a fixed magnetic orientation or no
|
|
||||||
orientation at all (demagnetized or damaged) is going to be read as a
|
|
||||||
series of random pulses after a brief delay. This is used by
|
|
||||||
protections and is known as "weak bits", which read differently each
|
|
||||||
time they're accessed.
|
|
||||||
|
|
||||||
A second level of filtering happens after the peak detector. When two
|
|
||||||
transitions are a little close (but still over the media threshold) a
|
|
||||||
bouncing effect happens between them giving two very close pulses in
|
|
||||||
the middle in addition to the two normal pulses. The floppy drive
|
|
||||||
detects when pulses are too close and filter them out, leaving the
|
|
||||||
normal ones. As a result, if one writes a train of high-frequency
|
|
||||||
pulses to the floppy they will be read back as a train of too close
|
|
||||||
pulses (weak because they're over the media tolerance, but picked up
|
|
||||||
by the AGC anyway, only somewhat unreliably) they will be all filtered
|
|
||||||
out, giving a large amount of time without any pulse in the output
|
|
||||||
signal. This is used by some protections since it's not writable with
|
|
||||||
a normally clocked controller.
|
|
||||||
|
|
||||||
Writing is symmetrical, with a series of pulses sent which make the
|
|
||||||
write head invert the magnetic field orientation each time a pulse is
|
|
||||||
received.
|
|
||||||
|
|
||||||
So, in conclusion, the floppy drive provides inputs to control disk
|
|
||||||
rotation and head position (and choice when double-sided), and the
|
|
||||||
data goes both way as a train of pulses representing magnetic
|
|
||||||
orientation inversions. The absolute value of the orientation itself
|
|
||||||
is never known.
|
|
||||||
|
|
||||||
|
|
||||||
2.3 Floppy controller
|
|
||||||
|
|
||||||
The task of the floppy controller is to turn the signals to/from the
|
|
||||||
floppy drive into something the main CPU can digest. The level of
|
|
||||||
support actually done by the controller is extremely variable from one
|
|
||||||
device to the other, from pretty much nothing (Apple II, C64) through
|
|
||||||
minimal (Amiga) to complete (Western Digital chips, uPD765 family).
|
|
||||||
Usual functions include drive selection, motor control, track seeking
|
|
||||||
and of course reading and writing data. Of these only the last two
|
|
||||||
need to be described, the rest is obvious.
|
|
||||||
|
|
||||||
The data is structured at two levels: how individual bits (or nibbles,
|
|
||||||
or bytes) are encoded on the surface, and how these are grouped in
|
|
||||||
individually-addressable sectors. Two standards exist for these,
|
|
||||||
called FM and MFM, and in addition a number of systems use their
|
|
||||||
home-grown variants. Moreover, some systems such as the Amiga use a
|
|
||||||
standard bit-level encoding (MFM) but a homegrown sector-level
|
|
||||||
organisation.
|
|
||||||
|
|
||||||
|
|
||||||
2.3.1 Bit-level encodings
|
|
||||||
2.3.1.1 Cell organization
|
|
||||||
|
|
||||||
All floppy controllers, even the wonkiest like the Apple II one, start
|
|
||||||
by dividing the track in equally-sized cells. They're angular
|
|
||||||
sections in the middle of which a magnetic orientation inversion may
|
|
||||||
be present. From a hardware point of view the cells are seen as
|
|
||||||
durations, which combined with the floppy rotation give the section.
|
|
||||||
For instance the standard MFM cell size for a 3" double-density floppy
|
|
||||||
is 2us, which combined with the also standard 300 rpm rotational speed
|
|
||||||
gives an angular size of 1/100000th of a turn. Another way of saying
|
|
||||||
it is that there are 100K cells in a 3" DD track.
|
|
||||||
|
|
||||||
In every cell there may or may not be a magnetic orientation
|
|
||||||
transition, e.g. a pulse coming from (reading) or going to (writing)
|
|
||||||
the floppy drive. A cell with a pulse is traditionally noted '1', and
|
|
||||||
one without '0'. Two constraints apply to the cell contents though.
|
|
||||||
First, pulses must not be too close together or they'll blur
|
|
||||||
each-other and/or be filtered out. The limit is slightly better than
|
|
||||||
1/50000th of a turn for single and double density floppies, half that
|
|
||||||
for HD floppys, and half that again for ED floppies with perpendicular
|
|
||||||
recording. Second, they must not be too away from each other or
|
|
||||||
either the AGC is going to get wonky and introduce phantom pulses or
|
|
||||||
the controller is going to lose sync and get a wrong timing on the
|
|
||||||
cells on reading. Conservative rule of thumb is not to have more than
|
|
||||||
three consecutive '0' cells.
|
|
||||||
|
|
||||||
Of course protections play with that to make formats not reproducible
|
|
||||||
by the system controller, either breaking the three-zeroes rule or
|
|
||||||
playing with the cells durations/sizes.
|
|
||||||
|
|
||||||
Bit endocing is then the art of transforming raw data into a cell 0/1
|
|
||||||
configuration that respects the two constraints.
|
|
||||||
|
|
||||||
2.3.1.2 FM encoding
|
|
||||||
|
|
||||||
The very first encoding method developed for floppies is called
|
|
||||||
Frequency Modulation, or FM. The cell size is set at slighly over the
|
|
||||||
physical limit, e.g. 4us. That means it is possible to reliably have
|
|
||||||
consecutive '1' cells. Each bit is encoded on two cells:
|
|
||||||
|
|
||||||
- the first cell, called the clock bit, is '1'
|
|
||||||
|
|
||||||
- the second cell, called data bit, is the bit
|
|
||||||
|
|
||||||
Since every other cell at least is '1' there is no risk of going over
|
|
||||||
three zeroes.
|
|
||||||
|
|
||||||
The name Frequency Modulation simply derives from the fact that a 0 is
|
|
||||||
encoded with one period of a 125Khz pulse train while a 1 is two
|
|
||||||
periods of a 250Khz pulse train.
|
|
||||||
|
|
||||||
2.3.1.3 MFM encoding
|
|
||||||
|
|
||||||
The FM encoding has been superseded by the Modified Frequency
|
|
||||||
Modulation encoding, which can cram exactly twice as much data on the
|
|
||||||
same surface, hence its other name of "double density". The cell size
|
|
||||||
is set at slightly over half the physical limit, e.g. 2us usually.
|
|
||||||
The constraint means that two '1' cells must be separated by at least
|
|
||||||
one '0' cell. Each bit is once again encoded on two cells:
|
|
||||||
|
|
||||||
- the first cell, called the clock bit, is '1' if both the previous
|
|
||||||
and current data bits are 0, '0' otherwise
|
|
||||||
|
|
||||||
- the second cell, called data bit, is the bit
|
|
||||||
|
|
||||||
The minimum space rule is respected since a '1' clock bit is by
|
|
||||||
definition surrounded by two '0' data bits, and a '1' data bit is
|
|
||||||
surrounded by two '0' clock bits. The longest '0'-cell string
|
|
||||||
possible is when encoding 101 which gives x10001, respecting the
|
|
||||||
maximum of three zeroes.
|
|
||||||
|
|
||||||
2.3.1.4 GCR encodings
|
|
||||||
|
|
||||||
Group Coded Recording, or GCR, encodings are a class of encodings
|
|
||||||
where strings of bits at least nibble-size are encoded into a given
|
|
||||||
cell stream given by a table. It has been used in particular by the
|
|
||||||
Apple II, the Mac and the C64, and each system has its own table, or
|
|
||||||
tables.
|
|
||||||
|
|
||||||
2.3.1.5 Other encodings
|
|
||||||
|
|
||||||
Other encodings exist, like M2FM, but they're very rare and
|
|
||||||
system-specific.
|
|
||||||
|
|
||||||
2.3.1.6 Reading back encoded data
|
|
||||||
|
|
||||||
Writing encoded data is easy, you only need a clock at the appropriate
|
|
||||||
frequency and send or not a pulse on the clock edges. Reading back
|
|
||||||
the data is where the fun is. Cells are a logical construct and not a
|
|
||||||
physical measurable entity. Rotational speeds very around the defined
|
|
||||||
one (+/- 2% is not rare) and local perturbations (air turbulence,
|
|
||||||
surface distance...) make the instant speed very variable in general.
|
|
||||||
So to extract the cell values stream the controller must dynamically
|
|
||||||
synchronize with the pulse train that the floppy head picks up. The
|
|
||||||
principle is simple: a cell-sized duration window is build within
|
|
||||||
which the presence of at least one pulse indicates the cell is a '1',
|
|
||||||
and the absence of any a '0'. After reaching the end of the window
|
|
||||||
the starting time is moved appropriately to try to keep the observed
|
|
||||||
pulse at the exact middle of the window. This allows to correct the
|
|
||||||
phase on every '1' cell, making the synchronization work if the
|
|
||||||
rotational speed is not too off. Subsequent generations of
|
|
||||||
controllers used a Phase-Locked Loop (PLL) which vary both phase and
|
|
||||||
window duration to adapt better to wrong rotational speeds, with
|
|
||||||
usually a tolerance of +/- 15%.
|
|
||||||
|
|
||||||
Once the cell data stream is extracted decoding depends on the
|
|
||||||
encoding. In the FM and MFM case the only question is to recognize
|
|
||||||
data bits from clock bits, while in GCR the start position of the
|
|
||||||
first group should be found. That second level of synchronization is
|
|
||||||
handled at a higher level using patterns not found in a normal stream.
|
|
||||||
|
|
||||||
|
|
||||||
2.3.2 Sector-level organization
|
|
||||||
|
|
||||||
Floppies have been designed for read/write random access to reasonably
|
|
||||||
sized blocks of data. Track selection allows for a first level of
|
|
||||||
random access and sizing, but the ~6K of a double density track would
|
|
||||||
be too big a block to handle. 256/512 bytes are considered a more
|
|
||||||
appropriate value. To that end data on a track is organized as a
|
|
||||||
series of (sector header, sector data) pairs where the sector header
|
|
||||||
indicates important information like the sector number and size, and
|
|
||||||
the sector data contains the data. Sectors have to be broken in two
|
|
||||||
parts because while reading is easy, read the header then read the
|
|
||||||
data if you want it, writing requires reading the header to find the
|
|
||||||
correct place then once that is done switching on the writing head for
|
|
||||||
the data. Starting writing is not instantaneous and will not be
|
|
||||||
perfectly phase-aligned with the read header, so space for
|
|
||||||
synchronization is required between header and data.
|
|
||||||
|
|
||||||
In addition somewhere in the sector header and in the sector data are
|
|
||||||
pretty much always added some kind of checksum allowing to know
|
|
||||||
whether the data was damaged or not.
|
|
||||||
|
|
||||||
FM and MFM have (not always used) standard sector layout methods.
|
|
||||||
|
|
||||||
2.3.2.1 FM sector layout
|
|
||||||
|
|
||||||
The standard "PC" track/sector layout for FM is as such:
|
|
||||||
- A number of FM-encoded 0xff (usually 40)
|
|
||||||
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
|
|
||||||
- The 16-cell stream 1111011101111010 (f77a, clock 0xd7, data 0xfc)
|
|
||||||
- A number of FM-encoded 0xff (usually 26, very variable)
|
|
||||||
|
|
||||||
Then for each sector:
|
|
||||||
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
|
|
||||||
- The 16-cell stream 1111010101111110 (f57e, clock 0xc7, data 0xfe)
|
|
||||||
- Sector header, e.g. FM encoded track, head, sector, size code and two bytes of crc
|
|
||||||
- 11 FM-encoded 0xff
|
|
||||||
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
|
|
||||||
- The 16-cell stream 1111010101101111 (f56f, clock 0xc7, data 0xfb)
|
|
||||||
- FM-encoded sector data followed by two bytes of crc
|
|
||||||
- A number of FM-encoded 0xff (usually 48, very variable)
|
|
||||||
|
|
||||||
The track is finished with a stream of '1' cells.
|
|
||||||
|
|
||||||
The 125KHz pulse trains are used to lock the PLL to the signal
|
|
||||||
correctly. The specific 16-cells streams allow to distinguish between
|
|
||||||
clock and data bits by providing a pattern that is not supposed to
|
|
||||||
happen in normal FM-encoded data. In the sector header track numbers
|
|
||||||
start at 0, heads are 0/1 depending on the size, sector numbers
|
|
||||||
usually start at 1 and size code is 0 for 128 bytes, 1 for 256, 2 for
|
|
||||||
512, etc.
|
|
||||||
|
|
||||||
The crc is a cyclic redundancy check of the data bits starting with
|
|
||||||
the mark just after the pulse train using polynom 0x11021.
|
|
||||||
|
|
||||||
The Western Digital-based controllers usually get rid of everything
|
|
||||||
but some 0xff before the first sector and allow a better use of space
|
|
||||||
as a result.
|
|
||||||
|
|
||||||
2.3.2.2 MFM sector layout
|
|
||||||
|
|
||||||
The standard "PC" track/sector layout for MFM is as such:
|
|
||||||
- A number of MFM-encoded 0x4e (usually 80)
|
|
||||||
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
|
|
||||||
- 3 times the 16-cell stream 0101001000100100 (5224, clock 0x14, data 0xc2)
|
|
||||||
- The MFM-encoded value 0xfc
|
|
||||||
- A number of MFM-encoded 0x4e (usually 50, very variable)
|
|
||||||
|
|
||||||
Then for each sector:
|
|
||||||
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
|
|
||||||
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
|
|
||||||
- Sector header, e.g. MFM-encoded 0xfe, track, head, sector, size code and two bytes of crc
|
|
||||||
- 22 MFM-encoded 0x4e
|
|
||||||
- 12 MFM-encoded 0x00 (giving a steady 250KHz pulse train)
|
|
||||||
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
|
|
||||||
- MFM-encoded 0xfb, sector data followed by two bytes of crc
|
|
||||||
- A number of MFM-encoded 0x4e (usually 84, very variable)
|
|
||||||
|
|
||||||
The track is finished with a stream of MFM-encoded 0x4e.
|
|
||||||
|
|
||||||
The 250KHz pulse trains are used to lock the PLL to the signal
|
|
||||||
correctly. The cell pattern 4489 does not appear in normal
|
|
||||||
MFM-encoded data and is used for clock/data separation.
|
|
||||||
|
|
||||||
As for FM, the Western Digital-based controllers usually get rid of
|
|
||||||
everything but some 0x4e before the first sector and allow a better
|
|
||||||
use of space as a result.
|
|
||||||
|
|
||||||
2.3.2.3 Formatting and write splices
|
|
||||||
|
|
||||||
To be usable, a floppy must have the sector headers and default sector
|
|
||||||
data written on every track before using it. The controller starts
|
|
||||||
writing at a given place, often the index pulse but on some systems
|
|
||||||
whenever the command is sent, and writes until a complete turn is
|
|
||||||
done. That's called formatting the floppy. At the point where the
|
|
||||||
writing stops there is a synchronization loss since there is no chance
|
|
||||||
the cell stream clock warps around perfectly. This brutal phase
|
|
||||||
change is called a write splice, specifically the track write splice.
|
|
||||||
It is the point where writing should start if one wants to raw copy
|
|
||||||
the track to a new floppy.
|
|
||||||
|
|
||||||
Similarly two write splices are created when a sector is written at
|
|
||||||
the start and end of the data block part. They're not supposed to
|
|
||||||
happen on a mastered disk though, even if there are some rare
|
|
||||||
exceptions.
|
|
||||||
|
|
||||||
|
|
||||||
3 The new implementation
|
|
||||||
3.1 Floppy disk representation
|
|
||||||
|
|
||||||
Th floppy disk contents are represented by the class floppy_image. It
|
|
||||||
contains information of the media type and a representation of the
|
|
||||||
magnetic state of the surface.
|
|
||||||
|
|
||||||
The media type is divided in two parts. The first half
|
|
||||||
indicates the physical form factor, i.e. all medias with that
|
|
||||||
form factor can be physically inserted in a reader that handles
|
|
||||||
it. The second half indicates the variants which are usually
|
|
||||||
detectable by the reader, such as density and number of sides.
|
|
||||||
|
|
||||||
Track data consists of a series of 32-bits lsb-first values
|
|
||||||
representing magnetic cells. Bits 0-27 indicate the absolute
|
|
||||||
position of the start of the cell (not the size), and bits
|
|
||||||
28-31 the type. Type can be:
|
|
||||||
- 0, MG_A -> Magnetic orientation A
|
|
||||||
- 1, MG_B -> Magnetic orientation B
|
|
||||||
- 2, MG_N -> Non-magnetized zone (neutral)
|
|
||||||
- 3, MG_D -> Damaged zone, reads as neutral but cannot be changed by writing
|
|
||||||
|
|
||||||
The position is in angular units of 1/200,000,000th of a turn. It
|
|
||||||
corresponds to one nanosecond when the drive rotates at 300 rpm.
|
|
||||||
|
|
||||||
The last cell implicit end position is of course 200,000,000.
|
|
||||||
|
|
||||||
Unformatted tracks are encoded as zero-size.
|
|
||||||
|
|
||||||
The "track splice" information indicates where to start writing
|
|
||||||
if you try to rewrite a physical disk with the data. Some
|
|
||||||
preservation formats encode that information, it is guessed for
|
|
||||||
others. The write track function of fdcs should set it. The
|
|
||||||
representation is the angular position relative to the index.
|
|
||||||
|
|
||||||
3.2 Converting to and from the internal representation
|
|
||||||
3.2.1 Class and interface
|
|
||||||
|
|
||||||
We need to be able to convert on-disk formats of the floppy data to
|
|
||||||
and from the internal representation. This is done through classes
|
|
||||||
derived from floppy_image_format_t. The interface to be implemented
|
|
||||||
includes:
|
|
||||||
- name() gives the short name of the on-disk format
|
|
||||||
|
|
||||||
- description() gives a short description of the format
|
|
||||||
|
|
||||||
- extensions() gives a comma-separated list of file name extensions
|
|
||||||
found for that format
|
|
||||||
|
|
||||||
- supports_save() returns true is converting to that external format
|
|
||||||
is supported
|
|
||||||
|
|
||||||
- identify(file, form factor) gives a 0-100 score for the file to be
|
|
||||||
of that format:
|
|
||||||
- 0 = not that format
|
|
||||||
- 100 = certainly that format
|
|
||||||
- 50 = format identified from file size only
|
|
||||||
|
|
||||||
- load(file, form factor, floppy_image) loads an image and converts it
|
|
||||||
into the internal representation
|
|
||||||
|
|
||||||
- save(file, floppy_image) (if implemented) converts from the internal
|
|
||||||
representation and saves an image
|
|
||||||
|
|
||||||
All these methods are supposed to be stateless.
|
|
||||||
|
|
||||||
3.2.2 Conversion helper methods
|
|
||||||
|
|
||||||
A number of methods are provided to simplify writing the converter
|
|
||||||
classes.
|
|
||||||
|
|
||||||
3.2.2.1 Load-oriented conversion methods
|
|
||||||
|
|
||||||
generate_track_from_bitstream(track number,
|
|
||||||
head number,
|
|
||||||
UINT8 *cell stream,
|
|
||||||
int cell count,
|
|
||||||
floppy image)
|
|
||||||
|
|
||||||
Takes a stream of cell types (0/1), MSB-first, converts it to the
|
|
||||||
internal format and stores it at the given track and head in the
|
|
||||||
given image.
|
|
||||||
|
|
||||||
generate_track_from_levels(track number,
|
|
||||||
head number,
|
|
||||||
UINT32 *cell levels,
|
|
||||||
int cell count,
|
|
||||||
splice position,
|
|
||||||
floppy image)
|
|
||||||
|
|
||||||
Takes a variant of the internal format where each value represents a
|
|
||||||
cell, the position part of the values is the size of the cell and
|
|
||||||
the level part is MG_0, MG_1 for normal cell types, MG_N, MG_D for
|
|
||||||
unformatted/damaged cells, and MG_W for Dungeon-Master style weak
|
|
||||||
bits. Converts it into the internal format. The sizes are
|
|
||||||
normalized so that they total to a full turn.
|
|
||||||
|
|
||||||
normalize_times(UINT32 *levels,
|
|
||||||
int level_count)
|
|
||||||
|
|
||||||
Takes an internal-format buffer where the position part represents
|
|
||||||
angle until the next change and turns it into a normal positional
|
|
||||||
stream, first ensuring that the total size is normalized to a full
|
|
||||||
turn.
|
|
||||||
|
|
||||||
|
|
||||||
3.2.2.2 Save-oriented conversion methods
|
|
||||||
|
|
||||||
generate_bitstream_from_track(track number,
|
|
||||||
head number,
|
|
||||||
base cell size,
|
|
||||||
UINT8 *cell stream,
|
|
||||||
int &cell_stream_size,
|
|
||||||
floppy image)
|
|
||||||
|
|
||||||
Extract a cell 0/1 stream from the internal format using a PLL setup
|
|
||||||
with an initial cell size set to 'base cell size' and a +/- 25%
|
|
||||||
tolerance.
|
|
||||||
|
|
||||||
|
|
||||||
struct desc_xs { int track, head, size; const UINT8 *data }
|
|
||||||
extract_sectors_from_bitstream_mfm_pc(...)
|
|
||||||
extract_sectors_from_bitstream_fm_pc(const UINT8 *cell stream,
|
|
||||||
int cell_stream_size,
|
|
||||||
desc_xs *sectors,
|
|
||||||
UINT8 *sectdata,
|
|
||||||
int sectdata_size)
|
|
||||||
|
|
||||||
Extract standard mfm or fm sectors from a regenerated
|
|
||||||
cell stream. Sectors must point to an array of 256 desc_xs.
|
|
||||||
|
|
||||||
An existing sector is recognizable by having ->data non-null.
|
|
||||||
Sector data is written in sectdata up to sectdata_size bytes.
|
|
||||||
|
|
||||||
|
|
||||||
get_geometry_mfm_pc(...)
|
|
||||||
get_geometry_fm_pc(floppy image,
|
|
||||||
base cell size,
|
|
||||||
int &track_count,
|
|
||||||
int &head_count,
|
|
||||||
int §or_count)
|
|
||||||
|
|
||||||
Extract the geometry (heads, tracks, sectors) from a pc-ish floppy
|
|
||||||
image by checking track 20.
|
|
||||||
|
|
||||||
|
|
||||||
get_track_data_mfm_pc(...)
|
|
||||||
get_track_data_fm_pc(track number,
|
|
||||||
head number,
|
|
||||||
floppy image,
|
|
||||||
base cell size,
|
|
||||||
sector size,
|
|
||||||
sector count,
|
|
||||||
UINT8 *sector data)
|
|
||||||
|
|
||||||
Extract what you'd get by reading in order 'sector size'-sized
|
|
||||||
sectors from number 1 to sector count and put the result in sector
|
|
||||||
data.
|
|
||||||
|
|
||||||
|
|
||||||
3.3 Floppy drive
|
|
||||||
|
|
||||||
The class floppy_image_interface simulates the floppy drive. That
|
|
||||||
includes a number of control signals, reading, and writing. Control
|
|
||||||
signal changes must be synchronized, e.g. fired off a timer to ensure
|
|
||||||
the current time is the same for all devices.
|
|
||||||
|
|
||||||
3.3.1 Control signals
|
|
||||||
|
|
||||||
Due to the way they're usually connected to CPUs (e.g. directly on an
|
|
||||||
I/O port), the control signals work with physical instead of logical
|
|
||||||
values. Which means than in general 0 means active, 1 means inactive.
|
|
||||||
Some signals also have a callback associated called when they change.
|
|
||||||
|
|
||||||
mon_w(state) / mon_r()
|
|
||||||
|
|
||||||
Motor on signal, rotates on 0.
|
|
||||||
|
|
||||||
|
|
||||||
idx_r() / setup_index_pulse_cb(cb)
|
|
||||||
|
|
||||||
Index signal, goes 0 at start of track for about 2ms. Callback is
|
|
||||||
synchronized. Only happens when a disk is in and the motor is
|
|
||||||
running.
|
|
||||||
|
|
||||||
|
|
||||||
ready_r() / setup_ready_cb(cb)
|
|
||||||
|
|
||||||
Ready signal, goes to 1 when the disk is removed or the motor
|
|
||||||
stopped. Goes to 0 after two index pulses.
|
|
||||||
|
|
||||||
|
|
||||||
wpt_r() / setup_wpt_cb(cb)
|
|
||||||
|
|
||||||
Write protect signal (1 = readonly). Callback is unsynchronized.
|
|
||||||
|
|
||||||
|
|
||||||
dskchg_r()
|
|
||||||
|
|
||||||
Disk change signal, goes to 1 when a disk is change, goes to 0 on
|
|
||||||
track change.
|
|
||||||
|
|
||||||
|
|
||||||
dir_w(dir)
|
|
||||||
|
|
||||||
Selects track stepping direction (1 = out = decrease track number).
|
|
||||||
|
|
||||||
|
|
||||||
stp_w(state)
|
|
||||||
|
|
||||||
Step signal, moves by one track on 1->0 transistion.
|
|
||||||
|
|
||||||
|
|
||||||
trk00_r()
|
|
||||||
|
|
||||||
Track 0 sensor, returns 0 when on track 0.
|
|
||||||
|
|
||||||
|
|
||||||
ss_w(ss) / ss_r()
|
|
||||||
|
|
||||||
Side select
|
|
||||||
|
|
||||||
|
|
||||||
3.3.2 Read/write interface
|
|
||||||
|
|
||||||
The read/write interface is designed to work asynchronously,
|
|
||||||
e.g. somewhat independently of the current time.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[1] Cylinder is a hard-drive term somewhat improperly used for
|
|
||||||
floppies. It comes from the fact that hard-drives are similar to
|
|
||||||
floppies but include a series of stacked disks with a read/write head
|
|
||||||
on each. The heads are physically linked and all point to the same
|
|
||||||
circle on every disk at a given time, making the accessed area look
|
|
||||||
like a cylinder. Hence the name.
|
|
131
docs/hlsl.txt
131
docs/hlsl.txt
@ -1,131 +0,0 @@
|
|||||||
HLSL-Related Enable Switches
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Name Values Description
|
|
||||||
hlsl_enable 0 or 1 Enables HLSL post-processing in Direct3D 9 modes.
|
|
||||||
hlsl_oversampling 0 or 1 Enables HLSL oversampling.
|
|
||||||
yiq_enable 0 or 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_write [filename] Enables 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_tile_mode 0 or 1 0 for screen based tile mode or 1 for source based tile mode.
|
|
||||||
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 number of pixels one shadow mask tile uses on screen.
|
|
||||||
shadow_mask_y_count 1+ This stretches the shadow mask tiles on X and Y axis.
|
|
||||||
shadow_mask_usize 0.0 to 1.0 The size of one shadow mask tile in U/V coordinate.
|
|
||||||
shadow_mask_vsize 0.0 to 1.0 The shadow mask textures always has a size of power-of-two.
|
|
||||||
shadow_mask_voffset -1.0 to 1.0 The offset of the shadow mask texture in U/V coordinates.
|
|
||||||
shadow_mask_voffset -1.0 to 1.0 An offset of 1.0 repressents one pixel on screen.
|
|
||||||
distortion -1.0 to 1.0 Distortion amount of the screen.
|
|
||||||
cubic_distortion -1.0 to 1.0 Cubic Distortion amount of the screen.
|
|
||||||
distort_corner 0.0 to 1.0 Distorted corners amount of the screen.
|
|
||||||
round_corner 0.0 to 1.0 Rounded corners amount of the screen.
|
|
||||||
smooth_border 0.0 to 1.0 Smooth borders amount of the screen.
|
|
||||||
reflection 0.0 to 1.0 Refelection amount of the screen highlight.
|
|
||||||
vignetting 0.0 to 1.0 Vignetting amount of the image.
|
|
||||||
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 1.0 The relative scanline movement per field.
|
|
||||||
hum_bar_alpha 0.0 to 1.0 The maximum darkness of the hum bar gradient.
|
|
||||||
defocus [xval,yval] This defines the overall defocus radius for the three
|
|
||||||
post-converged beams. Values allowed range from 0.0 to
|
|
||||||
10.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: -10.0 to 10.0 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_jitter 0.0 Jitter for the NTSC signal processing. (0.0 to 1.0)
|
|
||||||
yiq_cc 3.57954545 Color Carrier frequency for NTSC signal processing. (0.0 to 6.0)
|
|
||||||
yiq_a 0.5 A value for NTSC signal processing. (-1.0 to 1.0)
|
|
||||||
yiq_b 0.5 B value for NTSC signal processing. (-1.0 to 1.0)
|
|
||||||
yiq_o 0.0 Outgoing Color Carrier phase offset for NTSC signal processing. (-3.0 to 3.0)
|
|
||||||
yiq_p 1.0 Incoming Pixel Clock scaling value for NTSC signal processing. (-3.0 to 3.0)
|
|
||||||
yiq_n 1.0 Y filter notch width for NTSC signal processing. (0.0 to 6.0)
|
|
||||||
yiq_y 6.0 Y filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
|
|
||||||
yiq_i 1.2 I filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
|
|
||||||
yiq_q 0.6 Q filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
|
|
||||||
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_beam_smooth 0.0 The vector beam smoothness. (0.00 to 1.00)
|
|
||||||
vector_length_scale 0.5 The maximum vector attenuation. (0.00 to 1.00)
|
|
||||||
vector_length_ratio 0.5 The minimum vector length (vector length to screen size ratio)
|
|
||||||
that is affected by the attenuation (0.000 to 1.000)
|
|
||||||
|
|
||||||
|
|
||||||
Bloom Post-Processing Options
|
|
||||||
-----------------------------
|
|
||||||
Name Default Values Description
|
|
||||||
bloom_blend_mode 0 or 1 0 for brighten blend mode or 1 for darken blend mode.
|
|
||||||
bloom_scale 0.0 Bloom intensity factor. (0.000 to 2.000)
|
|
||||||
bloom_overdrive 0.0,0.0,0.0 Bloom overdrive factor to bright full saturated colors. (0.000 to 2.000)
|
|
||||||
bloom_lvl0_weight 1.00 Bloom level 0 weight. (full-size target) (0.00 to 1.00)
|
|
||||||
bloom_lvl1_weight 0.64 Bloom level 1 weight. (1/4 smaller that level 0 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl2_weight 0.32 Bloom level 2 weight. (1/4 smaller that level 1 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl3_weight 0.16 Bloom level 3 weight. (1/4 smaller that level 2 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl4_weight 0.08 Bloom level 4 weight. (1/4 smaller that level 3 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl5_weight 0.06 Bloom level 5 weight. (1/4 smaller that level 4 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl6_weight 0.04 Bloom level 6 weight. (1/4 smaller that level 5 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl7_weight 0.02 Bloom level 7 weight. (1/4 smaller that level 6 target) (0.00 to 1.00)
|
|
||||||
bloom_lvl8_weight 0.01 Bloom level 8 weight. (1/4 smaller that level 7 target) (0.00 to 1.00)
|
|
||||||
|
|
||||||
|
|
||||||
Presets
|
|
||||||
-------
|
|
||||||
../ini/presets/raster.ini for raster screens
|
|
||||||
../ini/presets/vector.ini for color vector screens
|
|
||||||
../ini/presets/vector-mono.ini for monochrome vector screens (rename to vector.ini or <system>.ini)
|
|
||||||
../ini/presets/lcd.ini for screens with TFT color LCD
|
|
||||||
../ini/presets/lcd-matrix.ini for screens with STN LCD matrix (rename to lcd.ini or <system>.ini)
|
|
||||||
../ini/presets/gameboy.ini for Game Boy screen (same as lcd-matrix.ini with greenish color transformation)
|
|
||||||
../ini/presets/gba.ini for Game Boy Advance screen (same as lcd.ini)
|
|
577
docs/imgtool.txt
577
docs/imgtool.txt
@ -1,577 +0,0 @@
|
|||||||
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.
|
|
||||||
|
|
@ -1,190 +0,0 @@
|
|||||||
# Scripting MAME via LUA
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
It is now possible to externally drive MAME via LUA scripts.
|
|
||||||
This feature initially appeared in version 0.148, when a minimal `luaengine`
|
|
||||||
was implemented. Nowadays, the LUA interface is rich enough
|
|
||||||
to let you inspect and manipulate devices state, access CPU
|
|
||||||
registers, read and write memory, and draw a custom HUD on screen.
|
|
||||||
|
|
||||||
Internally, MAME makes extensive use of `luabridge` to implement
|
|
||||||
this feature: the idea is to transparently expose as many of
|
|
||||||
the useful internals as possible.
|
|
||||||
|
|
||||||
Finally, a warning: LUA API is not yet declared stable and may
|
|
||||||
suddenly change without prior notice.
|
|
||||||
However, we expose methods to let you know at runtime which API
|
|
||||||
version you are running against, and you can introspect most of the
|
|
||||||
objects at runtime.
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
The API is not yet complete, but this is a partial list of capabilities
|
|
||||||
currently available to LUA scripts:
|
|
||||||
|
|
||||||
* machine metadata (app version, current rom, rom details)
|
|
||||||
* machine control (starting, pausing, resetting, stopping)
|
|
||||||
* machine hooks (on frame painting and on user events)
|
|
||||||
* machine options (hard reset required for options to take affect)
|
|
||||||
* devices introspection (device tree listing, memory and register enumeration)
|
|
||||||
* screens introspection (screens listing, screen details, frames counting)
|
|
||||||
* screen snaps and HUD drawing (text, lines, boxes on multiple screens)
|
|
||||||
* memory read/write (8/16/32/64 bits, signed and unsigned)
|
|
||||||
* registers and states control (states enumeration, get and set)
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
MAME supports external scripting via LUA (>= 5.3) scripts, either
|
|
||||||
written on the interactive console or loaded as a file.
|
|
||||||
To reach the console, just run MAME with `-console`; you will be
|
|
||||||
greeted by a naked `>` prompt where you can input your script.
|
|
||||||
|
|
||||||
To load a whole script at once, store it in a plaintext file and
|
|
||||||
pass it via the `-autoboot_script`. Please note that script
|
|
||||||
loading may be delayed (few seconds by default), but you can
|
|
||||||
override the default with the `-autoboot_delay` argument.
|
|
||||||
|
|
||||||
To control the execution of your code, you can use a loop-based or
|
|
||||||
an event-based approach. The former is not encouraged as it is
|
|
||||||
resource-intensive and makes control flow unnecessarily complex.
|
|
||||||
Instead, we suggest to register custom hooks to be invoked on specific
|
|
||||||
events (eg. at each frame rendering).
|
|
||||||
|
|
||||||
## Walktrough
|
|
||||||
|
|
||||||
Let's first run MAME in a terminal to reach the LUA console:
|
|
||||||
```
|
|
||||||
$ mame -console YOUR_ROM
|
|
||||||
M.A.M.E. v0.158 (Feb 5 2015) - Multiple Arcade Machine Emulator
|
|
||||||
Copyright Nicola Salmoria and the MAME team
|
|
||||||
Lua 5.3.0 Copyright (C) 1994-2015 Lua.org, PUC-Rio
|
|
||||||
|
|
||||||
>
|
|
||||||
```
|
|
||||||
|
|
||||||
At this point, your game is probably running in demo mode, let's pause it:
|
|
||||||
```
|
|
||||||
> emu.pause()
|
|
||||||
>
|
|
||||||
```
|
|
||||||
Even without textual feedback on the console, you'll notice the game is now paused.
|
|
||||||
In general, commands are quiet and only print back error messages.
|
|
||||||
|
|
||||||
You can check at runtime which version of MAME you are running, with:
|
|
||||||
```
|
|
||||||
> print(emu.app_name() .. " " .. emu.app_version())
|
|
||||||
mame 0.158
|
|
||||||
```
|
|
||||||
|
|
||||||
We now start exploring screen related methods. First, let's enumerate available screens:
|
|
||||||
```
|
|
||||||
> for i,v in pairs(manager:machine().screens) do print(i) end
|
|
||||||
:screen
|
|
||||||
```
|
|
||||||
|
|
||||||
`manager:machine()` is the root object of your currently running machine:
|
|
||||||
we will be using this often. `screens` is a table with all available screens;
|
|
||||||
most machines only have one main screen.
|
|
||||||
In our case, the main and only screen is tagged as `:screen`, and we can further
|
|
||||||
inspect it:
|
|
||||||
```
|
|
||||||
> -- let's define a shorthand for the main screen
|
|
||||||
> s = manager:machine().screens[":screen"]
|
|
||||||
> print(s:width() .. "x" .. s:height())
|
|
||||||
320x224
|
|
||||||
```
|
|
||||||
|
|
||||||
We have several methods to draw on the screen a HUD composed of lines, boxes and text:
|
|
||||||
```
|
|
||||||
> -- we define a HUD-drawing function, and then call it
|
|
||||||
> function draw_hud()
|
|
||||||
>> s:draw_text(40, 40, "foo"); -- (x0, y0, msg)
|
|
||||||
>> s:draw_box(20, 20, 80, 80, 0, 0xff00ffff); -- (x0, y0, x1, y1, fill-color, line-color)
|
|
||||||
>> s:draw_line(20, 20, 80, 80, 0xff00ffff); -- (x0, y0, x1, y1, line-color)
|
|
||||||
>> end
|
|
||||||
> draw_hud();
|
|
||||||
```
|
|
||||||
|
|
||||||
This will draw some useless art on the screen. However, when unpausing the game, your HUD
|
|
||||||
needs to be refreshed otherwise it will just disappear. In order to do this, you have to register
|
|
||||||
your hook to be called on every frame repaint:
|
|
||||||
```
|
|
||||||
> emu.sethook(draw_hud, "frame")
|
|
||||||
```
|
|
||||||
|
|
||||||
All colors are expected in ARGB format (32b unsigned), while screen origin (0,0)
|
|
||||||
normally corresponds to the top-left corner.
|
|
||||||
|
|
||||||
Similarly to screens, you can inspect all the devices attached to a
|
|
||||||
machine:
|
|
||||||
```
|
|
||||||
> for k,v in pairs(manager:machine().devices) do print(k) end
|
|
||||||
:audiocpu
|
|
||||||
:maincpu
|
|
||||||
:saveram
|
|
||||||
:screen
|
|
||||||
:palette
|
|
||||||
[...]
|
|
||||||
```
|
|
||||||
|
|
||||||
On some of them, you can also inspect and manipulate memory and state:
|
|
||||||
```
|
|
||||||
> cpu = manager:machine().devices[":maincpu"]
|
|
||||||
> -- enumerate, read and write state registers
|
|
||||||
> for k,v in pairs(cpu.state) do print(k) end
|
|
||||||
D5
|
|
||||||
SP
|
|
||||||
A4
|
|
||||||
A3
|
|
||||||
D0
|
|
||||||
PC
|
|
||||||
[...]
|
|
||||||
> print(cpu.state["D0"].value)
|
|
||||||
303
|
|
||||||
> cpu.state["D0"].value = 255
|
|
||||||
> print(cpu.state["D0"].value)
|
|
||||||
255
|
|
||||||
```
|
|
||||||
|
|
||||||
```
|
|
||||||
> -- inspect memory
|
|
||||||
> for k,v in pairs(cpu.spaces) do print(k) end
|
|
||||||
program
|
|
||||||
> mem = cpu.spaces["program"]
|
|
||||||
> print(mem:read_i8(0xC000))
|
|
||||||
41
|
|
||||||
```
|
|
||||||
|
|
||||||
manager:options()
|
|
||||||
manager:machine():options()
|
|
||||||
manager:machine():ui():options()
|
|
||||||
```
|
|
||||||
> opts = manager:machine():options()
|
|
||||||
> for k, entry in pairs(opts.entries) do print(string.format("%10s: %s\n%11s %s", k, entry:value(), "", entry:description())) end
|
|
||||||
diff_directory: diff
|
|
||||||
directory to save hard drive image differeVnce files
|
|
||||||
joystick_contradictory: false
|
|
||||||
enable contradictory direction digital joystick input at the same time
|
|
||||||
scalemode: none
|
|
||||||
Scale mode: none, hwblit, hwbest, yv12, yuy2, yv12x2, yuy2x2 (-video soft only)
|
|
||||||
oslog: false
|
|
||||||
output error.log data to the system debugger
|
|
||||||
[...]
|
|
||||||
> print(opts.entries["sleep"]:value())
|
|
||||||
true
|
|
||||||
> print(opts.entries["sleep"]:value("invalid"))
|
|
||||||
Illegal boolean value for sleep: "invalid"; reverting to 1
|
|
||||||
true
|
|
||||||
> print(opts.entries["sleep"]:value(false))
|
|
||||||
false
|
|
||||||
```
|
|
||||||
|
|
||||||
individual screen snapshots
|
|
||||||
```
|
|
||||||
> local screen = manager:machine().screens[":screen"]
|
|
||||||
> screen:snapshot()
|
|
||||||
saved snap/gridlee/0000.png
|
|
||||||
> screen:snapshot('%g.png')
|
|
||||||
saved snap/gridlee.png
|
|
||||||
```
|
|
482
docs/m6502.txt
482
docs/m6502.txt
@ -1,482 +0,0 @@
|
|||||||
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
|
|
@ -1,65 +0,0 @@
|
|||||||
MAME(r)
|
|
||||||
Copyright (c) 1997-2016 by MAMEdev and contributors
|
|
||||||
MAME is a registered trademark of Nicola Salmoria
|
|
||||||
|
|
||||||
|
|
||||||
----------
|
|
||||||
I. Purpose
|
|
||||||
----------
|
|
||||||
MAME main purpose is to be a reference to the inner workings of the
|
|
||||||
emulated machines. This is done both for educational purposes and for
|
|
||||||
preservation purposes, in order to prevent historical software from
|
|
||||||
disappearing forever once the hardware it runs on stops working. Of
|
|
||||||
course, in order to preserve the software and demonstrate that the
|
|
||||||
emulated behavior matches the original, one must also be able to
|
|
||||||
actually use the software. 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, hard disks or other media from the 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. The project as whole is
|
|
||||||
distributed under the GNU General Public License, version 2 or later
|
|
||||||
(GPL-2.0+), but most of code (including core functionality) is also
|
|
||||||
available under the 3-clause BSD license (BSD-3-clause).
|
|
||||||
|
|
||||||
|
|
||||||
-------------------------
|
|
||||||
III. Software Image Files
|
|
||||||
-------------------------
|
|
||||||
ROM, CD, hard disk and other media images are all copyrighted material.
|
|
||||||
They cannot be distributed without the explicit permission of the
|
|
||||||
copyright holder(s). They are not "abandonware", nor has any of the
|
|
||||||
software 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, hard disk or other media images.
|
|
||||||
|
|
||||||
|
|
||||||
--------------------
|
|
||||||
IV. Derivative Works
|
|
||||||
--------------------
|
|
||||||
Because the name MAME is trademarked, you must abide by the rules set
|
|
||||||
out for 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 from which it was was derived.
|
|
||||||
|
|
||||||
|
|
||||||
-------------------------------
|
|
||||||
V. Official Contact Information
|
|
||||||
-------------------------------
|
|
||||||
For questions regarding the MAME license, trademark, or other usage, go
|
|
||||||
to http://www.mamedev.org/
|
|
@ -1,146 +0,0 @@
|
|||||||
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.
|
|
234
docs/nscsi.txt
234
docs/nscsi.txt
@ -1,234 +0,0 @@
|
|||||||
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.
|
|
370
docs/windows.txt
370
docs/windows.txt
@ -1,370 +0,0 @@
|
|||||||
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).
|
|
Loading…
Reference in New Issue
Block a user