MAME Documentation Release 0.227 MAMEdev Team Apr 11, 2021 CONTENTS 1 What is MAME 3 1.1 I. Purpose ................................................. 3 1.2 II. Cost .................................................. 4 1.3 III. Software Image Files ......................................... 4 1.4 IV. Derivative Works ........................................... 4 1.5 V. Official Contact Information ..................................... 4 2 Health Warnings 5 2.1 Epilepsy Warning ............................................ 5 3 Getting MAME prepared 7 3.1 An Introduction to MAME ........................................ 7 3.2 Purpose of MAME ............................................ 7 3.3 Systems Emulated by MAME ...................................... 7 3.4 Supported OS ............................................... 8 3.5 System Requirements .......................................... 8 3.6 Installing MAME ............................................. 9 3.7 Compiling MAME ............................................ 9 4 Basic MAME Usage and Configuration 21 4.1 Using MAME .............................................. 21 4.2 Default Keyboard Controls ........................................ 22 4.3 MAME Menus .............................................. 32 4.4 Frontends ................................................. 33 4.5 About ROMs and Sets .......................................... 33 4.6 Common Issues and Questions (FAQ) .................................. 36 5 MAME Commandline Usage and OS-Specific Configuration 43 5.1 Universal Commandline Options .................................... 43 5.2 Windows-Specific Commandline Options ................................ 94 5.3 SDL-Specific Commandline Options .................................. 95 5.4 Commandline Index ........................................... 96 6 Advanced configuration 107 6.1 Multiple Configuration Files ....................................... 107 6.2 MAME Path Handling .......................................... 109 6.3 Shifter Toggle Disable .......................................... 110 6.4 BGFX Effects for (nearly) Everyone ................................... 111 6.5 HLSL Effects for Windows ....................................... 114 6.6 GLSL Effects for *nix, OS X, and Windows .............................. 122 6.7 Stable Controller IDs ........................................... 124 i 6.8 Linux Lightguns ............................................. 126 7 MAME Debugger 129 7.1 General Debugger Commands ...................................... 129 7.2 Memory Debugger Commands ..................................... 137 7.3 Execution Debugger Commands ..................................... 141 7.4 Breakpoint Debugger Commands .................................... 149 7.5 Watchpoint Debugger Commands .................................... 152 7.6 Registerpoints Debugger Commands .................................. 155 7.7 Code Annotation Debugger Commands ................................. 158 7.8 Cheat Debugger Commands ....................................... 160 7.9 Image Debugger Commands ....................................... 166 7.10 Debugger Expressions Guide ...................................... 167 8 MAME External Tools 169 8.1 Imgtool - A generic image manipulation tool for MAME . 169 8.2 Using Imgtool .............................................. 169 8.3 Imgtool Subcommands .......................................... 170 8.4 Imgtool Filters .............................................. 171 8.5 Imgtool Format Info ........................................... 172 8.6 Castool - A generic cassette image manipulation tool for MAME . 194 8.7 Using Castool .............................................. 194 8.8 Castool Formats ............................................. 194 8.9 Floptool - A generic floppy image manipulation tool for MAME . 199 8.10 Using Floptool .............................................. 199 8.11 Floptool Formats ............................................. 199 8.12 Other tools included with MAME .................................... 202 8.13 Developer-focused tools included with MAME ............................. 202 9 Technical Specifications 205 9.1 MAME Naming Conventions ...................................... 205 9.2 MAME Layout Files ........................................... 207 9.3 MAME Layout Scripting ......................................... 227 9.4 Object Finders .............................................. 237 9.5 The device_memory_interface ...................................... 253 9.6 The device_rom_interface ........................................ 256 9.7 The device_disasm_interface and the disassemblers . 258 9.8 Emulated system memory and address spaces management . 261 9.9 The new floppy subsystem ........................................ 273 9.10 The new SCSI subsystem ........................................ 283 9.11 Scripting MAME via Lua ........................................ 286 9.12 MAME Lua Class Reference ....................................... 290 9.13 The new 6502 family implementation .................................. 333 10 MAME and security concerns 343 11 The MAME License 345 12 Contribute 347 ii MAME Documentation, Release 0.227 Note: This documentation is a work in progress. You can track the status of these topics through MAME's issue tracker. Learn how you can contribute on GitHub. CONTENTS 1 MAME Documentation, Release 0.227 2 CONTENTS CHAPTER ONE WHAT IS MAME MAME is a multi-purpose emulation framework. MAME's purpose is to preserve decades of software history. As electronic technology continues to rush forward, MAME prevents this important "vintage" software from being lost and forgotten. This is achieved by documenting the hardware and how it functions. The source code to MAME serves as this documentation. The fact that the software is usable serves primarily to validate the accuracy of the documentation (how else can you prove that you have recreated the hardware faithfully?). Over time, MAME (originally stood for Multiple Arcade Machine Emulator) absorbed the sister-project MESS (Multi Emulator Super System), so MAME now documents a wide variety of (mostly vintage) computers, video game consoles and calculators, in addition to the arcade video games that were its initial focus. MAME® Copyright © 1997-2021 by Nicola Salmoria and the MAME team MAME is a registered trademark owned by Gregory Ember 1.1 I. Purpose MAME's 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. 3 MAME Documentation, Release 0.227 1.2 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). 1.3 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. 1.4 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. 1.5 V. Official Contact Information For questions regarding the MAME license, trademark, or other usage, go to http://www.mamedev.org/ 4 Chapter 1. What is MAME CHAPTER TWO HEALTH WARNINGS 2.1 Epilepsy Warning A very small percentage of individuals may experience epileptic seizures when exposed to certain light patterns or flashing lights. Exposure to certain patterns or backgrounds on a television screen or computer monitor, or while playing video games may induce an epileptic seizure in these individuals. Certain conditions may induce previously undetected epileptic symptoms even in persons who have no history of prior seizures or epilepsy. These conditions can include emulation accuracy or inaccuracy, computer performance at the time of running MAME, video card drivers, your monitor, and a lot of other factors. If you, or anyone in your family, has an epileptic condition, consult your physician prior to using MAME. If you experience any of the following while using MAME, IMMEDIATELY discontinue