diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/LICENSE | 116 | ||||
-rw-r--r-- | docs/README.md | 5 | ||||
-rw-r--r-- | docs/SDL.txt | 376 | ||||
-rw-r--r-- | docs/config.txt | 1264 | ||||
-rw-r--r-- | docs/emscripten.txt | 60 | ||||
-rw-r--r-- | docs/floppy.txt | 633 | ||||
-rw-r--r-- | docs/hlsl.txt | 131 | ||||
-rw-r--r-- | docs/imgtool.txt | 577 | ||||
-rw-r--r-- | docs/luaengine.md | 190 | ||||
-rw-r--r-- | docs/m6502.txt | 482 | ||||
-rw-r--r-- | docs/mame.txt | 65 | ||||
-rw-r--r-- | docs/newvideo.txt | 146 | ||||
-rw-r--r-- | docs/nscsi.txt | 234 | ||||
-rw-r--r-- | docs/windows.txt | 370 |
14 files changed, 0 insertions, 4649 deletions
diff --git a/docs/LICENSE b/docs/LICENSE deleted file mode 100644 index 670154e3538..00000000000 --- a/docs/LICENSE +++ /dev/null @@ -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/> diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 669c251a923..00000000000 --- a/docs/README.md +++ /dev/null @@ -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/)
\ No newline at end of file diff --git a/docs/SDL.txt b/docs/SDL.txt deleted file mode 100644 index 5361c7e4e39..00000000000 --- a/docs/SDL.txt +++ /dev/null @@ -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 - diff --git a/docs/config.txt b/docs/config.txt deleted file mode 100644 index 25ba9844386..00000000000 --- a/docs/config.txt +++ /dev/null @@ -1,1264 +0,0 @@ -This file describes general usage information about MAME. It is intended -to cover aspects of using and configuring the program that are common -across operating systems. For additional OS-specific options, please see -the separate documentation for your particular version of MAME. - - - -Using the program ------------------ - -The usual way to run MAME is by telling it to run a particular game: - - mame <gamename> [options] - -For example: - - mame robby -sound none - -...will run Robby Roto without sound. There are many, many options -available. All commonly supported options are listed below. Options that -are specific to one operating system or version of MAME will be listed -in a separate document. - -An alternative way to run MAME is to give it a command: - - mame <command> [parameters] - -For example: - - mame -listsource gridlee - -...will print the name of the source file where the gridlee driver lives -to the screen. There are just a handful of these commands in MAME. They -are all listed below, just before the options list. - - - -Default Keys ------------- - -All the keys below are fully configurable in the user interface. This list -shows the standard keyboard configuration. - -Tab Toggles the configuration menu. - -~ Toggles the On Screen Display. When the on-screen display is - visible, you can use the following keys to control it: - - Up - select previous parameter to modify - Down - select next parameter to modify - Enter - reset parameter value to its default - - Left - decrease the value of the selected parameter - Control+Left - decrease the value by 10x - Shift+Left - decrease the value by 0.1x - Alt+Left - decrease the value by the smallest amount - - Right - increase the value of the selected parameter - Control+Right - increase the value by 10x - Shift+Right - increase the value by 0.1x - Alt+Right - increase the value by the smallest amount - - If you are running with -debug, this key send a 'break' - in emulation. - -P Pauses the game. - -Shift+P While paused, advances to next frame. - -F2 Service Mode for games that support it. - -F3 Resets the game. - -Shift+F3 Performs a "hard reset", which tears everything down and re- - creates it from scratch. This is a more thorough and complete - reset than an F3. - -LCtrl+F3 [SDL ONLY] - Toggle Uneven stretch. - -F4 Shows the game palette, decoded GFX, and any tilemaps. Use the - Enter key to switch between the three modes (palette, graphics, - and tilemaps). Press F4 again to turn off the display. The key - controls in each mode vary slightly: - - * Palette/colortable mode: - [ ] - switch between palette and colortable modes - Up/Down - scroll up/down one line at a time - Page Up/Page Down - scroll up/down one page at a time - Home/End - move to top/bottom of list - -/+ - increase/decrease the number of colors per row - Enter - switch to graphics viewer - - * Graphics mode: - [ ] - switch between different graphics sets - Up/Down - scroll up/down one line at a time - Page Up/Page Down - scroll up/down one page at a time - Home/End - move to top/bottom of list - Left/Right - change color displayed - R - rotate tiles 90 degrees clockwise - -/+ - increase/decrease the number of tiles per row - Enter - switch to tilemap viewer - - * Tilemap mode: - [ ] - switch between different tilemaps - Up/Down/Left/Right - scroll 8 pixels at a time - Shift+Up/Down/Left/Right - scroll 1 pixel at a time - Control+Up/Down/Left/Right - scroll 64 pixels at a time - R - rotate tilemap view 90 degrees clockwise - -/+ - increase/decrease the zoom factor - Enter - switch to palette/colortable mode - - Note: Not all games have decoded graphics and/or tilemaps. - -LCtrl+F4 [SDL ONLY] - Toggle Keepaspect ratio. - -LCtrl+F5 [SDL ONLY] - Toggle Filter. - -Alt+Ctrl+F5 [WINDOWS ONLY. NON SDL] - Toggle HLSL Post-Processing. - -F6 Toggle cheat mode (if started with "-cheat"). - -LCtrl+F6 Decrease Prescaling. - -F7 Load a save state. You will be requested to press a key to - determine which save state you wish to load. Note that the save - state feature is not supported for a large number of drivers. If - support is not enabled for a given driver, you will receive a - warning when attempting to save or load. - -LCtrl+F7 Increase Prescaling. - -Shift+F7 Create a save state. Requires an additional keypress to identify - the state, similar to the load option above. - -F8 Decrease frame skip on the fly. - -F9 Increase frame skip on the fly. - -F10 Toggle speed throttling. - -F11 Toggles speed display. - -Shift+F11 Toggles internal profiler display (if compiled in). - -Alt+F11 Record HLSL Rendered Video. - -F12 Saves a screen snapshot. - -Alt+F12 Take HLSL Rendered Snapshot. - -Insert [WINDOW ONLY, NON SDL] -Page DN [SDL ONLY] - Fast forward. While held, runs the game with throttling disabled - and with the maximum frameskip. - -Alt+ENTER Toggles between full-screen and windowed mode. - -Scroll Lock Default mapping for the uimodekey. This key allows user to - disable and enable the emulated keyboard in machines that require - it. All emulations which require emulated keyboards will start in - that mode and you can only access the internal UI (hitting TAB) by - first hitting this key. You can change the initial status of the - emulated keyboard is presented upon start by using -ui_active trigger - as detailed below. - -Escape Exits emulator. - - - -Core commands -------------- - --help / -h / -? - - Displays current MAME version and copyright notice. - --validate / -valid - - Performs internal validation on every driver in the system. Run this - before submitting changes to ensure that you haven't violated any of - the core system rules. - - - -Configuration commands ----------------------- - --createconfig / -cc - - Creates the default mame.ini file. All the configuration options - (not commands) described below can be permanently changed by editing - this configuration file. - --showconfig / -sc - - Displays the current configuration settings. If you route this to a - file, you can use it as an INI file. For example, the command: - - mame -showconfig >mame.ini - - is equivalent to -createconfig. - --showusage / -su - - Displays a summary of all the command line options. For options that - are not mentioned here, the short summary given by "mame -showusage" - is usually sufficient. - - - -Frontend commands ------------------ - -Note: By default, all the '-list' commands below write info to the screen. -If you wish to write the info to a textfile instead, add this to the end -of your command: - - > filename - -...where 'filename' is the textfile's path and name -(e.g., c:\mame\list.txt). - --listxml / -lx [<gamename|wildcard>] - - List comprehensive details for all of the supported games. The output - is quite long, so it is usually better to redirect this into a file. - The output is in XML format. By default all games are listed; however, - you can limit this list by specifying a driver name or wildcard after - the -listxml command. - --listfull / -ll [<gamename|wildcard>] - - Displays a list of game driver names and descriptions. By default all - games are listed; however, you can limit this list by specifying a - driver name or wildcard after the -listfull command. - --listsource / -ls [<gamename|wildcard>] - - Displays a list of drivers and the names of the source files their - game drivers live in. Useful for finding which driver a game runs on - in order to fix bugs. By default all games are listed; however, you - can limit this list by specifying a driver name or wildcard after - the -listsource command. - --listclones / -lc [<gamename|wildcard>] - - Displays a list of clones. By default all clones are listed; however, - you can limit this list by specifying a driver name or wildcard after - the -listsource command. - --listbrothers / -lb [<gamename|wildcard>] - - Displays a list of 'brothers', or rather, other sets which are located - in the same sourcefile as the gamename searched for. - --listcrc [<gamename|wildcard>] - - Displays a full list of CRCs of all ROM images referenced by all - drivers within MAME. - --listroms [<gamename|wildcard>] - - Displays a list of ROM images referenced by the specified game. - --listsamples [<gamename|wildcard>] - - Displays a list of samples referenced by the specified game. - --verifyroms [<gamename|wildcard>] - - Checks for invalid or missing ROM images. By default all drivers that - have valid ZIP files or directories in the rompath are verified; - however, you can limit this list by specifying a driver name or - wildcard after the -verifyroms command. - --verifysamples [<gamename|wildcard>] - - Checks for invalid or missing samples. By default all drivers that - have valid ZIP files or directories in the samplepath are verified; - however, you can limit this list by specifying a driver name or - wildcard after the -verifyroms command. - --romident [path\to\romstocheck.zip] - - Attempts to identify ROM files, if they are known to MAME, in the - specified .zip file or directory. This command can be used to try and - identify ROM sets taken from unknown boards. On exit, the errorlevel - is returned as one of the following: - - 0: means all files were identified - 7: means all files were identified except for 1 or more "non-ROM" - files - 8: means some files were identified - 9: means no files were identified - --listdevices / -ld [<gamename|wildcard>] - - Displays a list of all devices known to be hooked up to a game. The ":" - is considered the game itself with the devices list being attached to give - the user a better understanding of what the emulation is using. - --listslots [<gamename|wildcard>] - - Show available slots and options for each slot (if available). Primarily - used for MESS to allow control over internal plug-in cards, much like PC's - needing video, sound and other cards. - --listmedia / -lm [<gamename|wildcard>] - - List available media that the chosen game or system allows to be used. This - includes media types (cartridge, cassette, diskette and more) as well as - common file extentions which are supported. - --listsoftware [<gamename|wildcard>] - - Posts to screen all software lists which can be used by the entered gamename - or system. Notice, this is simply a copy/paste of the .XML file which reside - in the HASH folder which are allowed to be used. - --verifysoftware [<gamename|wildcard>] - - Checks for invalid or missing ROM images in your software lists. By default - all drivers that have valid ZIP files or directories in the rompath are verified; - however, you can limit this list by specifying a specific driver name or wildcard - after the -verifysoftware command. - --getsoftlist [<gamename|wildcard>] - - Posts to screen a specific software list which matches with the gamename - provided. - --verifysoftlist [softwarelistname] - - Checks a specified software list for missing ROM images if files exist for issued - softwarelistname. By default, all drivers that have valid ZIP files or directories - in the rompath are verified; however, you can limit this list by specifying a - specific softwarelistname (without .XML) after the -verifysoftlist command. - - -OSD related options -------------------- - --uimodekey [keystring] - - Key used to toggle emulated keyboard on and off. Default setting is SCRLOCK. - --uifontprovider - - Chooses provider for UI font: win, none or auto. The Default setting is AUTO. - - -OSD CLI options ---------------- - --listmidi - - Create a list of available MIDI I/O devices for use with emulation. - --listnetwork - - Create a list of available Network Adapters for use with emulation. - - - -Configuration options ---------------------- - --[no]readconfig / -[no]rc - - Enables or disables the reading of the config files. When enabled - (which is the default), MAME reads the following config files in order: - - - mame.ini - - <mymame>.ini (i.e. if MAME was renamed mame060.exe, MAME - parses mame060.ini here) - - debug.ini (if the debugger is enabled) - - <driver>.ini (based on the source filename of the driver) - - vertical.ini (for games with vertical monitor orientation) - - horizont.ini (for games with horizontal monitor orientation) - - arcade.ini (for games in source added with GAME() macro) - - console.ini (for games in source added with CONS() macro) - - computer.ini (for games in source added with COMP() macro) - - othersys.ini (for games in source added with SYST() macro) - - vector.ini (for vector games only) - - <parent>.ini (for clones only, may be called recursively) - - <gamename>.ini - - - The settings in the later ini's override those in the earlier ini's. - So, for example, if you wanted to disable overlay effects in the - vector games, you can create a vector.ini with the "effect none" line - in it, and it will override whatever effect value you have in your - mame.ini. The default is ON (-readconfig). - - - -Core search path options ------------------------- - --rompath / -rp <path> - - Specifies a list of paths within which to find ROM or hard disk images. - Multiple paths can be specified by separating them with semicolons. - The default is 'roms' (that is, a directory "roms" in the same directory - as the MAME executable). - --hashpath <path> - - Specifies a list of paths within which to find Software List HASH files. - Multiple paths can be specified by separating them with semicolons. - The default is 'hash' (that is, a directory "roms" in the same directory - as the MAME executable). - --samplepath / -sp <path> - - Specifies a list of paths within which to find sample files. Multiple - paths can be specified by separating them with semicolons. The default - is 'samples' (that is, a directory "samples" in the same directory as - the MAME executable). - --artpath <path> / -artwork_directory <path> - - Specifies a list of paths within which to find artwork files. Multiple - paths can be specified by separating them with semicolons. The default - is 'artwork' (that is, a directory "artwork" in the same directory as - the MAME executable). - --ctrlrpath / -ctrlr_directory <path> - - Specifies a list of paths within which to find controller-specific - configuration files. Multiple paths can be specified by separating - them with semicolons. The default is 'ctrlr' (that is, a directory - "ctrlr" in the same directory as the MAME executable). - --inipath <path> - - Specifies a list of paths within which to find .INI files. Multiple - paths can be specified by separating them with semicolons. The default - is '.;ini' (that is, search in the current directory first, and then - in the directory "ini" in the same directory as the MAME executable). - --fontpath <path> - - Specifies a list of paths within which to find .BDF font files. Multiple - paths can be specified by separating them with semicolons. The default - is '.' (that is, search in the same directory as the MAME executable). - --cheatpath <path> - - Specifies a list of paths within which to find .XML cheat files. - Multiple paths can be specified by separating them with semicolons. The - default is 'cheat' (that is, a folder called 'cheat' located in the same - directory as the as the MAME executable). - --crosshairpath <path> - - Specifies a list of paths within which to find crosshair files. Multiple - paths can be specified by separating them with semicolons. The default - is 'crsshair' (that is, a directory "crsshair" in the same directory as - the MAME executable). If the Crosshair is set to default in the menu, - MAME will look for gamename\cross#.png and then cross#.png in the - specified crsshairpath, where # is the player number. Failing that, - MAME will use built-in default crosshairs. - - - -Core Output Directory Options ------------------------------ - --cfg_directory <path> - - Specifies a single directory where configuration files are stored. - Configuration files store user configurable settings that are read at - startup and written when MAME exits. The default is 'cfg' (that is, - a directory "cfg" in the same directory as the MAME executable). If - this directory does not exist, it will be automatically created. - --nvram_directory <path> - - Specifies a single directory where NVRAM files are stored. NVRAM files - store the contents of EEPROM and non-volatile RAM (NVRAM) for games - which used this type of hardware. This data is read at startup and - written when MAME exits. The default is 'nvram' (that is, a directory - "nvram" in the same directory as the MAME executable). If this - directory does not exist, it will be automatically created. - --input_directory <path> - - Specifies a single directory where input recording files are stored. - Input recordings are created via the -record option and played back - via the -playback option. The default is 'inp' (that is, a directory - "inp" in the same directory as the MAME executable). If this directory - does not exist, it will be automatically created. - --state_directory <path> - - Specifies a single directory where save state files are stored. Save - state files are read and written either upon user request, or when - using the -autosave option. The default is 'sta' (that is, a directory - "sta" in the same directory as the MAME executable). If this directory - does not exist, it will be automatically created. - --snapshot_directory <path> - - Specifies a single directory where screen snapshots are stored, when - requested by the user. The default is 'snap' (that is, a directory - "snap" in the same directory as the MAME executable). If this - directory does not exist, it will be automatically created. - --diff_directory <path> - - Specifies a single directory where hard drive differencing files are - stored. Hard drive differencing files store any data that is written - back to a hard disk image, in order to preserve the original image. - The differencing files are created at startup when a game with a hard - disk image. The default is 'diff' (that is, a directory "diff" in the - same directory as the MAME executable). If this directory does not - exist, it will be automatically created. - --comment_directory <path> - - Specifies a single directory where debugger comment files are stored. - Debugger comment files are written by the debugger when comments are - added to the disassembly for a game. The default is 'comments' (that - is, a directory "comments" in the same directory as the MAME - executable). If this directory does not exist, it will be - automatically created. - - - -Core state/playback options ---------------------------- - --state <slot> - - Immediately after starting the specified game, will cause the save - state in the specified <slot> to be loaded. - --[no]autosave - - When enabled, automatically creates a save state file when exiting - MAME and automatically attempts to reload it when later starting MAME - with the same game. This only works for games that have explicitly - enabled save state support in their driver. The default is OFF - (-noautosave). - --playback / -pb <filename> - - Specifies a file from which to play back a series of game inputs. This - feature does not work reliably for all games, but can be used to watch - a previously recorded game session from start to finish. In order to - make things consistent, you should only record and playback with all - configuration (.cfg), NVRAM (.nv), and memory card files deleted. The - default is NULL (no playback). - --record / -rec <filename> - - Specifies a file to record all input from a game session. This can be - used to record a game session for later playback. This feature does - not work reliably for all games, but can be used to watch a previously - recorded game session from start to finish. In order to make things - consistent, you should only record and playback with all configuration - (.cfg), NVRAM (.nv), and memory card files deleted. The default is - NULL (no recording). - --mngwrite <filename> - - Writes each video frame to the given <filename> in MNG format, - producing an animation of the game session. Note that -mngwrite only - writes video frames; it does not save any audio data. Use -wavwrite - for that, and reassemble the audio/video using offline tools. The - default is NULL (no recording). - --aviwrite <filename> - - Stream video and sound data to the given <filename> in AVI format, - producing an animation of the game session complete with sound. The - default is NULL (no recording). - --wavwrite <filename> - - Writes the final mixer output to the given <filename> in WAV format, - producing an audio recording of the game session. The default is - NULL (no recording). - --snapname <name> - - Describes how MAME should name files for snapshots. <name> is a string - that provides a template that is used to generate a filename. Three - simple substitutions are provided: the / character represents the - path separator on any target platform (even Windows); the string %g - represents the driver name of the current game; and the string %i - represents an incrementing index. If %i is omitted, then each - snapshot taken will overwrite the previous one; otherwise, MAME will - find the next empty value for %i and use that for a filename. The - default is %g/%i, which creates a separate folder for each game, - and names the snapshots under it starting with 0000 and increasing - from there. In addition to the above, for drivers using different - media, like carts or floppy disks, you can also use the %d_[media] - indicator. Replace [media] with the media switch you want to use. - A few examples: if you use 'mame robby -snapname foo/%g%i' snapshots - will be saved as 'snaps\foo\robby0000.png' , 'snaps\foo\robby0001.png' - and so on ; if you use 'mess nes -cart robby -snapname %g/%d_cart' - snapshots will be saved as 'snaps\nes\robby.png' ; if you use - 'mess c64 -flop1 robby -snapname %g/%d_flop1/%i' snapshots will be - saved as 'snaps\c64\robby\0000.png'. - --snapsize <width>x<height> - - Hard-codes the size for snapshots and movie recording. By default, - MAME will create snapshots at the game's current resolution in raw - pixels, and will create movies at the game's starting resolution in - raw pixels. If you specify this option, then MAME will create both - snapshots and movies at the size specified, and will bilinear filter - the result. Note that this size does not automatically rotate if the - game is vertically oriented. The default is 'auto'. - --snapview <viewname> - - Specifies the view to use when rendering snapshots and movies. By - default, both use a special 'internal' view, which renders a separate - snapshot per screen or renders movies only of the first screen. By - specifying this option, you can override this default behavior and - select a single view that will apply to all snapshots and movies. - Note that <viewname> does not need to be a perfect match; rather, it - will select the first view whose name matches all the characters - specified by <viewname>. For example, -snapview native will match the - "Native (15:14)" view even though it is not a perfect match. - <viewname> can also be 'auto', which selects the first view with all - screens present. The default value is 'internal'. - --[no]snapbilinear - - Specify if the snapshot or movie should have bilinear filtering - applied. Shutting this off can make a difference in some performance - while recording video to a file. The default is ON (-snapbilinear). - --statename <name> - - Describes how MAME should store save state files, relative to the - state_directory path. <name> is a string that provides a template that - is used to generate a relative path. Two simple substitutions are - provided: the / character represents the path separator on any target - platform (even Windows); the string %g represents the driver name of - the current game. The default is %g, which creates a separate folder for - each game. In addition to the above, for drivers using different - media, like carts or floppy disks, you can also use the %d_[media] - indicator. Replace [media] with the media switch you want to use. - A few examples: if you use 'mame robby -statename foo/%g' save states - will be stored inside 'sta\foo\robby\' ; if you use 'mess nes -cart - robby -statename %g/%d_cart' save states will be stored inside - 'sta\nes\robby\' ; if you use 'mess c64 -flop1 robby -statename - %g/%d_flop1' save states will be stored inside 'sta\c64\robby\'. - --[no]burnin - - Tracks brightness of the screen during play and at the end of - emulation generates a PNG that can be used to simulate burn-in - effects on other games. The resulting PNG is created such that the - least used-areas of the screen are fully white (since burned-in areas - are darker, all other areas of the screen must be lightened a touch). - The intention is that this PNG can be loaded via an artwork file with - a low alpha (e.g, 0.1-0.2 seems to work well) and blended over the - entire screen. The PNG files are saved in the snap directory under - the gamename/burnin-<screen.name>.png. The default is OFF (-noburnin). - - - -Core performance options ------------------------- - --[no]autoframeskip / -[no]afs - - Automatically determines the frameskip level while you're playing the - game, adjusting it constantly in a frantic attempt to keep the game - running at full speed. Turning this on overrides the value you have - set for -frameskip below. The default is OFF (-noautoframeskip). - --frameskip / -fs <level> - - Specifies the frameskip value. This is the number of frames out of - every 12 to drop when running. For example, if you say -frameskip 2, - then MAME will display 10 out of every 12 frames. By skipping those - frames, you may be able to get full speed in a game that requires more - horsepower than your computer has. The default value is -frameskip 0, - which skips no frames. - --seconds_to_run / -str <seconds> - - This option can be used for benchmarking and automated testing. It tells - MAME to stop execution after a fixed number of seconds. By combining - this with a fixed set of other command line options, you can set up a - consistent environment for benchmarking MAME performance. In addition, - upon exit, the -str option will write a screenshot called final.png - to the game's snapshot directory. - --[no]throttle - - Configures the default thottling setting. When throttling is on, MAME - attempts to keep the game running at the game's intended speed. When - throttling is off, MAME runs the game as fast as it can. Note that the - fastest speed is more often than not limited by your graphics card, - especially for older games. The default is ON (-throttle). - --[no]sleep - - Allows MAME to give time back to the system when running with -throttle. - This allows other programs to have some CPU time, assuming that the - game isn't taxing 100% of your CPU resources. This option can - potentially cause hiccups in performance if other demanding programs - are running. The default is ON (-sleep). - --speed <factor> - - Changes the way MAME throttles gameplay such that the game runs at some - multiplier of the original speed. A <factor> of 1.0 means to run the - game at its normal speed. A <factor> of 0.5 means run at half speed, - and a <factor> of 2.0 means run at 2x speed. Note that changing this - value affects sound playback as well, which will scale in pitch - accordingly. The internal resolution of the fraction is two decimal - places, so a value of 1.002 is the same as 1.0. The default is 1.0. - --[no]refreshspeed / -[no]rs - - Allows MAME to dynamically adjust the gameplay speed such that it does - not exceed the slowest refresh rate for any targeted monitors in your - system. Thus, if you have a 60Hz monitor and run a game that is - actually designed to run at 60.6Hz, MAME will dynamically change the - speed down to 99% in order to prevent sound hiccups or other - undesirable side effects of running at a slower refresh rate. The - default is OFF (-norefreshspeed). - - - -Core rotation options ---------------------- - --[no]rotate - - Rotate the game to match its normal state (horizontal/vertical). This - ensures that both vertically and horizontally oriented games show up - correctly without the need to rotate your monitor. If you want to keep - the game displaying 'raw' on the screen the way it would have in the - arcade, turn this option OFF. The default is ON (-rotate). - --[no]ror --[no]rol - - Rotate the game screen to the right (clockwise) or left (counter- - clockwise) relative to either its normal state (if -rotate is - specified) or its native state (if -norotate is specified). The - default for both of these options is OFF (-noror -norol). - --[no]autoror --[no]autorol - - These options are designed for use with pivoting screens that only - pivot in a single direction. If your screen only pivots clockwise, - use -autorol to ensure that the game will fill the screen either - horizontally or vertically in one of the directions you can handle. - If your screen only pivots counter-clockwise, use -autoror. - --[no]flipx --[no]flipy - - Flip (mirror) the game screen either horizontally (-flipx) or - vertically (-flipy). The flips are applied after the -rotate and - -ror/-rol options are applied. The default for both of these options - is OFF (-noflipx -noflipy). - - - -Core artwork options --------------------- - --[no]artwork_crop / -[no]artcrop - - Enable cropping of artwork to the game screen area only. This works - best with -video gdi or -video d3d, and means that vertically oriented - games running full screen can display their artwork to the left and - right sides of the screen. This does not work with -video ddraw - because of the way the game screens are rendered and scaled after the - fact. This option can also be controlled via the Video Options menu in - the user interface. The default is OFF (-noartwork_crop). - --[no]use_backdrops / -[no]backdrop - - Enables/disables the display of backdrops. The default is ON - (-use_backdrops). - --[no]use_overlays / -[no]overlay - - Enables/disables the display of overlays. The default is ON - (-use_overlays). - --[no]use_bezels / -[no]bezels - - Enables/disables the display of bezels. The default is ON - (-use_bezels). - --[no]use_cpanels / -[no]cpanels - - Enables/disables the display of control panels. The default is ON - (-use_cpanels). - --[no]use_marquees / -[no]marquees - - Enables/disables the display of marquees. The default is ON - (-use_marquees). - - - -Core screen options -------------------- - --brightness <value> - - Controls the default brightness, or black level, of the game screens. - This option does not affect the artwork or other parts of the display. - Using the MAME UI, you can individually set the brightness for each - game screen; this option controls the initial value for all visible - game screens. The standard value is 1.0. Selecting lower values (down - to 0.1) will produce a darkened display, while selecting higher values - (up to 2.0) will give a brighter display. The default is 1.0. - --contrast <value> - - Controls the contrast, or white level, of the game screens. This - option does not affect the artwork or other parts of the display. - Using the MAME UI, you can individually set the contrast for each - game screen; this option controls the initial value for all visible - game screens. The standard value is 1.0. Selecting lower values (down - to 0.1) will produce a dimmer display, while selecting higher values - (up to 2.0) will give a more saturated display. The default is 1.0. - --gamma <value> - - Controls the gamma, which produces a potentially nonlinear black to - white ramp, for the game screens. This option does not affect the - artwork or other parts of the display. Using the MAME UI, you can - individually set the gamma for each game screen; this option controls - the initial value for all visible game screens. The standard value is - 1.0, which gives a linear ramp from black to white. Selecting lower - values (down to 0.1) will increase the nonlinearity toward black, - while selecting higher values (up to 3.0) will push the nonlinearity - toward white. The default is 1.0. - --pause_brightness <value> - - This controls the brightness level when MAME is paused. The default - value is 0.65. - --effect <filename> - - Specifies a single PNG file that is used as an overlay over any game - screens in the video display. This PNG file is assumed to live in the - root of one of the artpath directories. The pattern in the PNG file is - repeated both horizontally and vertically to cover the entire game - screen areas (but not any external artwork), and is rendered at - the target resolution of the game image. For -video gdi and -video d3d - modes, this means that one pixel in the PNG will map to one pixel on - your output display. For -video ddraw, this means that one pixel in the - PNG will map to one pixel in the prescaled game screen. If you wish to - use an effect that requires mapping n PNG pixels to each game screen - pixel with -video ddraw, you need to specify a -prescale factor of n as - well. The RGB values of each pixel in the PNG are multiplied against the - RGB values of the target screen. The default is 'none', meaning no - effect. - - - -Core vector options -------------------- - --beam_width_min <value> --beam_width_max <value> - - Sets the minimum and maximum width of the vectors. This is a scaling factor - against the standard vector width, which is interpolated between minimum and - maximum according to the beam's intensity. A value of 1.0 will keep the default - vector line width. Smaller values will reduce the width, and larger values - will increase the width. The default is 1.0. - --beam_intensity_weight <value> - - Applies an exponential weight to the minimum and maximum beam width. For positive - values the interpolated scaling factor will affect lines with higher intensity - more than lines with lower intensity. The default is 0.0. - --flicker <value> - - Simulates a vector "flicker" effect, similar to a vector monitor that - needs adjustment. This option requires a float argument in the range - of 0.00 - 100.00 (0=none, 100=maximum). The default is 0. - - - -Core sound options ------------------- - --samplerate <value> / -sr <value> - - Sets the audio sample rate. Smaller values (e.g. 11025) cause lower - audio quality but faster emulation speed. Higher values (e.g. 48000) - cause higher audio quality but slower emulation speed. The default is - 48000. - --[no]samples - - Use samples if available. The default is ON (-samples). - --volume / -vol <value> - - Sets the startup volume. It can later be changed with the user - interface (see Keys section). The volume is an attenuation in dB: - e.g., "-volume -12" will start with -12dB attenuation. The default - is 0. - - - -Core input options ------------------- - --[no]coin_lockout / -[no]coinlock - - Enables simulation of the "coin lockout" feature that is implmeneted - on a number of game PCBs. It was up to the operator whether or not - the coin lockout outputs were actually connected to the coin - mechanisms. If this feature is enabled, then attempts to enter a coin - while the lockout is active will fail and will display a popup message - in the user interface (In debug mode). If this feature is disabled, the - coin lockout signal will be ignored. The default is ON (-coin_lockout). - --ctrlr <controller> - - Enables support for special controllers. Configuration files are - loaded from the ctrlrpath. They are in the same format as the .cfg - files that are saved, but only control configuration data is read - from the file. The default is NULL (no controller file). - --[no]mouse - - Controls whether or not MAME makes use of mouse controllers. When - this is enabled, you will likely be unable to use your mouse for other - purposes until you exit or pause the game. The default is OFF - (-nomouse). - --[no]joystick / -[no]joy - - Controls whether or not MAME makes use of joystick/gamepad controllers. - When this is enabled, MAME will ask DirectInput about which - controllers are connected. The default is OFF (-nojoystick). - --[no]lightgun / -[no]gun - - Controls whether or not MAME makes use of lightgun controllers. - Note that most lightguns map to the mouse, so using -lightgun and - -mouse together may produce strange results. The default is OFF - (-nolightgun). - --[no]multikeyboard / -[no]multikey - - Determines whether MAME differentiates between multiple keyboards. - Some systems may report more than one keyboard; by default, the data - from all of these keyboards is combined so that it looks like a single - keyboard. Turning this option on will enable MAME to report keypresses - on different keyboards independently. The default is OFF - (-nomultikeyboard). - --[no]multimouse - - Determines whether MAME differentiates between multiple mice. Some - systems may report more than one mouse device; by default, the data - from all of these mice is combined so that it looks like a single - mouse. Turning this option on will enable MAME to report mouse - movement and button presses on different mice independently. The - default is OFF (-nomultimouse). - --[no]steadykey / -[no]steady - - Some games require two or more buttons to be pressed at exactly the - same time to make special moves. Due to limitations in the keyboard - hardware, it can be difficult or even impossible to accomplish that - using the standard keyboard handling. This option selects a different - handling that makes it easier to register simultaneous button presses, - but has the disadvantage of making controls less responsive. The - default is OFF (-nosteadykey) - --[no]ui_active - - Enable user interface on top of emulated keyboard (if present). The - default if OFF (-noui_active) - --[no]offscreen_reload / -[no]reload - - Controls whether or not MAME treats a second button input from a - lightgun as a reload signal. In this case, MAME will report the gun's - position as (0,MAX) with the trigger held, which is equivalent to an - offscreen reload. This is only needed for games that required you to - shoot offscreen to reload, and then only if your gun does not support - off screen reloads. The default is OFF (-nooffscreen_reload). - --joystick_map <map> / -joymap <map> - - Controls how joystick values map to digital joystick controls. MAME - accepts all joystick input from the system as analog data. For true - analog joysticks, this needs to be mapped down to the usual 4-way or - 8-way digital joystick values. To do this, MAME divides the analog - range into a 9x9 grid. It then takes the joystick axis position (for - X and Y axes only), maps it to this grid, and then looks up a - translation from a joystick map. This parameter allows you to specify - the map. The default is 'auto', which means that a standard 8-way, - 4-way, or 4-way diagonal map is selected automatically based on the - input port configuration of the current game. - - Maps are defined as a string of numbers and characters. Since the grid - is 9x9, there are a total of 81 characters necessary to define a - complete map. Below is an example map for an 8-way joystick: - - 777888999 Note that the numeric digits correspond to the keys - 777888999 on a numeric keypad. So '7' maps to up+left, '4' maps - 777888999 to left, '5' maps to neutral, etc. In addition to the - 444555666 numeric values, you can specify the character 's', - 444555666 which means "sticky". In this case, the value of the - 444555666 map is the same as it was the last time a non-sticky - 111222333 value was read. - 111222333 - 111222333 - - To specify the map for this parameter, you can specify a string of - rows separated by a '.' (which indicates the end of a row), like so: - - 777888999.777888999.777888999.444555666.444555666.444555666. - 111222333.111222333.111222333 - - However, this can be reduced using several shorthands supported by the - <map> parameter. If information about a row is missing, then it is - assumed that any missing data in columns 5-9 are left/right symmetric - with data in columns 0-4; and any missing data in colums 0-4 is - assumed to be copies of the previous data. The same logic applies to - missing rows, except that up/down symmetry is assumed. - - By using these shorthands, the 81 character map can be simply - specified by this 11 character string: 7778...4445 - - Looking at the first row, 7778 is only 4 characters long. The 5th - entry can't use symmetry, so it is assumed to be equal to the previous - character '8'. The 6th character is left/right symmetric with the 4th - character, giving an '8'. The 7th character is left/right symmetric - with the 3rd character, giving a '9' (which is '7' with left/right - flipped). Eventually this gives the full 777888999 string of the row. - - The second and third rows are missing, so they are assumed to be - identical to the first row. The fourth row decodes similarly to the - first row, producing 444555666. The fifth row is missing so it is - assumed to be the same as the fourth. - - The remaining three rows are also missing, so they are assumed to be - the up/down mirrors of the first three rows, giving three final rows - of 111222333. - --joystick_deadzone <value> / -joy_deadzone <value> / -jdz <value> - - If you play with an analog joystick, the center can drift a little. - joystick_deadzone tells how far along an axis you must move before the - axis starts to change. This option expects a float in the range of - 0.0 to 1.0. Where 0 is the center of the joystick and 1 is the outer - limit. The default is 0.3. - --joystick_saturation <value> / joy_saturation <value> / -jsat <value> - - If you play with an analog joystick, the ends can drift a little, - and may not match in the +/- directions. joystick_saturation tells how - far along an axis movement change will be accepted before it reaches - the maximum range. This option expects a float in the range of 0.0 to - 1.0, where 0 is the center of the joystick and 1 is the outer limit. - The default is 0.85. - --natural - - Allows user to specify whether or not to use a natural keyboard or not. - This allows you to start your game or system in a 'native' mode, depending - on your region, allowing compatability for non-"QWERTY" style keyboards. - The default is OFF (-nonatrual) - --joystick_contradictory - - Enable contradictory direction digital joystick input at the same time - such as Left and Right or Up and Down at the same time. The default - is OFF (-nojoystick_contradictory) - --coin_impulse [n] - - Set coin impulse time based on n (n<0 disable impulse, n==0 obey driver, - 0<n set time n). Default is 0. - - - -Core input automatic enable options ------------------------------------ - --paddle_device enable (none|keyboard|mouse|lightgun|joystick) if a paddle control is present --adstick_device enable (none|keyboard|mouse|lightgun|joystick) if an analog joystick control is present --pedal_device enable (none|keyboard|mouse|lightgun|joystick) if a pedal control is present --dial_device enable (none|keyboard|mouse|lightgun|joystick) if a dial control is present --trackball_device enable (none|keyboard|mouse|lightgun|joystick) if a trackball control is present --lightgun_device enable (none|keyboard|mouse|lightgun|joystick) if a lightgun control is present --positional_device enable (none|keyboard|mouse|lightgun|joystick) if a positional control is present --mouse_device enable (none|keyboard|mouse|lightgun|joystick) if a mouse control is present - - Each of these options controls autoenabling the mouse, joystick, or - lightgun depending on the presence of a particular class of analog - control for a particular game. For example, if you specify the option - -paddle mouse, then any game that has a paddle control will - automatically enable mouse controls just as if you had explicitly - specified -mouse. Note that these controls override the values of - -[no]mouse, -[no]joystick, etc. - - - -Debugging options ------------------ - --[no]verbose / -[no]v - - Displays internal diagnostic information. This information is very - useful for debugging problems with your configuration. IMPORTANT: when - reporting bugs, please run with mame -verbose and include the - resulting information. The default is OFF (-noverbose). - --[no]oslog - - Output error.log data to the system debugger. The default is OFF - (-nooslog). - --[no]log - - Creates a file called error.log which contains all of the internal - log messages generated by the MAME core and game drivers. The default - is OFF (-nolog). - --[no]debug - - Activates the integrated debugger. By default, the debugger is entered - by pressing the tilde (~) key during emulation. It is also entered - immediately at startup. The default is OFF (-nodebug). - --debugscript <filename> - - Specifies a file that contains a list of debugger commands to execute - immediately upon startup. The default is NULL (no commands). - --[no]update_in_pause - - Enables updating of the main screen bitmap while the game is paused. - This means that the VIDEO_UPDATE callback will be called repeatedly - during pause, which can be useful for debugging. The default is OFF - (-noupdate_in_pause). - - -Core communication options --------------------------- - --comm_localhost <string> - - Local address to bind to. This can be a traditional xxx.xxx.xxx.xxx - address or a string containing a resolvable hostname. The default is - value is "0.0.0.0" - --comm_localport <string> - - Local port to bind to. This can be any traditional communications port - as an unsigned 16-bit integer (0-65535). The default value is "15122". - --comm_remotehost <string> - - Remote address to connect to. This can be a traditional xxx.xxx.xxx.xxx - address or a string containing a resolvable hostname. The default is - value is "0.0.0.0" - --comm_remoteport <string> - - Remote port to connect to. This can be any traditional communications port - as an unsigned 16-bit integer (0-65535). The default value is "15122". - - - -Core misc options ------------------ - --[no]drc - Enable DRC cpu core if available. The default is ON (-drc). - --drc_use_c - - Force DRC use the C code backend. The default is OFF - (-nodrc_use_c). - --drc_log_uml - - Write DRC UML disassembly log. The default is OFF - (-nodrc_log_uml). - --drc_log_native - - write DRC native disassembly log. The default is OFF - (-nodrc_log_native). - --bios <biosname> - - Specifies the specific BIOS to use with the current game, for game - systems that make use of a BIOS. The -listxml output will list all of - the possible BIOS names for a game. The default is 'default'. - --[no]cheat / -[no]c - - Enables the reading of the cheat database, if present, and the Cheat - menu in the user interface. The default is OFF (-nocheat). - --[no]skip_gameinfo - - Forces MAME to skip displaying the game info screen. The default is - OFF (-noskip_gameinfo). - --uifont <fontname> - - Specifies the name of a font file to use for the UI font. If this font - cannot be found or cannot be loaded, the system will fall back to its - built-in UI font. On some platforms 'fontname' can be a system font - name (TTF) instead of a (BDF) font file. The default is 'default' (use - the OSD-determined default font). - --ramsize [n] - - Allows you to change the default RAM size (if supported by driver). - --confirm_quit - - Display a Confirm Quit dialong to screen on exit, requiring one extra - step to exit MAME. The default is OFF (-noconfirm_quit). - --ui_mouse - - Displays a mouse cursor when using the built-in UI for MAME. The default - is (-noui_mouse). - --autoboot_command "<command>" - - Command string to execute after machine boot (in quotes " "). To issue - a quote to the emulation, use """ in the string. Using \n will issue a - create a new line, issuing what was typed prior as a command. - Example: -autoboot_command "load """$""",8,1\n" - --autoboot_delay [n] - - Timer delay (in seconds) to trigger command execution on autoboot. - --autoboot_script / -script [filename.lua] - - File containing scripting to execute after machine boot. diff --git a/docs/emscripten.txt b/docs/emscripten.txt deleted file mode 100644 index dbc8bd5ad48..00000000000 --- a/docs/emscripten.txt +++ /dev/null @@ -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. diff --git a/docs/floppy.txt b/docs/floppy.txt deleted file mode 100644 index 7fc2331d4f6..00000000000 --- a/docs/floppy.txt +++ /dev/null @@ -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. diff --git a/docs/hlsl.txt b/docs/hlsl.txt deleted file mode 100644 index 00facb0649a..00000000000 --- a/docs/hlsl.txt +++ /dev/null @@ -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) diff --git a/docs/imgtool.txt b/docs/imgtool.txt deleted file mode 100644 index c9ac101d514..00000000000 --- a/docs/imgtool.txt +++ /dev/null @@ -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. - diff --git a/docs/luaengine.md b/docs/luaengine.md deleted file mode 100644 index 223a421cc27..00000000000 --- a/docs/luaengine.md +++ /dev/null @@ -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 -``` diff --git a/docs/m6502.txt b/docs/m6502.txt deleted file mode 100644 index d09954719bd..00000000000 --- a/docs/m6502.txt +++ /dev/null @@ -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 diff --git a/docs/mame.txt b/docs/mame.txt deleted file mode 100644 index 154ebcbc2db..00000000000 --- a/docs/mame.txt +++ /dev/null @@ -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/ diff --git a/docs/newvideo.txt b/docs/newvideo.txt deleted file mode 100644 index 10c752bf2b0..00000000000 --- a/docs/newvideo.txt +++ /dev/null @@ -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. diff --git a/docs/nscsi.txt b/docs/nscsi.txt deleted file mode 100644 index 3eea1576344..00000000000 --- a/docs/nscsi.txt +++ /dev/null @@ -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. diff --git a/docs/windows.txt b/docs/windows.txt deleted file mode 100644 index bbd14a19359..00000000000 --- a/docs/windows.txt +++ /dev/null @@ -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). |