summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/man/chdman.12
-rw-r--r--docs/source/commandline/commandline-all.rst116
-rw-r--r--docs/source/commandline/commandline-index.rst55
-rw-r--r--docs/source/commandline/sdlconfig.rst2
-rw-r--r--docs/source/conf.py6
-rw-r--r--docs/source/debugger/general.rst6
-rw-r--r--docs/source/debugger/index.rst32
-rw-r--r--docs/source/initialsetup/compilingmame.rst23
-rw-r--r--docs/source/license.rst2
-rw-r--r--docs/source/techspecs/layout_files.rst27
-rw-r--r--docs/source/techspecs/luareference.rst416
-rw-r--r--docs/source/techspecs/memory.rst4
-rw-r--r--docs/source/techspecs/object_finders.rst2
-rw-r--r--docs/source/usingmame/assetsearch.rst402
-rw-r--r--docs/source/usingmame/defaultkeys.rst10
-rw-r--r--docs/source/usingmame/index.rst1
-rw-r--r--docs/source/usingmame/usingmame.rst11
-rw-r--r--docs/source/whatis.rst2
18 files changed, 969 insertions, 150 deletions
diff --git a/docs/man/chdman.1 b/docs/man/chdman.1
index 34fd884eecd..57a1e4615c7 100644
--- a/docs/man/chdman.1
+++ b/docs/man/chdman.1
@@ -39,7 +39,7 @@ detailed list of the valid switches for the option.
Dump the header information from a drive image.
.TP
.B verify \
-\-i \fIfileiname\fR \
+\-i \fIfilename\fR \
[\fB\-ip \fIfilename\fR]
Validate the MD5/SHA1 on a drive image.
.TP
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index 3f008300f04..aa91bd6307c 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -1,4 +1,4 @@
-.. _universal-command-line:
+.. _mame-commandline-universal:
Universal Commandline Options
=============================
@@ -19,6 +19,8 @@ Verbs are actions to take upon something with the command (e.g.
**mame -validate pacman** has *mame* as a command and *-validate* as a verb)
+.. _mame-commandline-patterns:
+
Patterns
--------
@@ -80,6 +82,8 @@ Terminal window, set the working directory to the location of the script
(i.e. the folder containing MAME), and then start MAME.
+.. _mame-commandline-coreverbs:
+
Core Verbs
----------
@@ -136,6 +140,9 @@ Core Verbs
apple2_flop_orig.xml(137.3): mismatched tag
+
+.. _mame-commandline-configverbs:
+
Configuration Verbs
-------------------
@@ -175,6 +182,8 @@ Configuration Verbs
a sufficient description.
+.. _mame-commandline-fronendverbs:
+
Frontend Verbs
--------------
@@ -664,8 +673,8 @@ overwritten.
romset apple2_flop_orig:autobahn is good
...
-.. _osd-commandline-options:
+.. _mame-commandline-osdoptions:
OSD-related Options
-------------------
@@ -919,8 +928,10 @@ Example:
supporting both XInput and DirectInput controllers.
-OSD CLI Options
----------------
+.. _mame-commandline-cliverbs:
+
+OSD CLI Verbs
+-------------
.. _mame-commandline-listmidi:
@@ -961,6 +972,8 @@ OSD CLI Options
any network adapters.
+.. _mame-commandline-osdoutput:
+
OSD Output Options
------------------
@@ -987,6 +1000,8 @@ OSD Output Options
led0 = 0
+.. _mame-commandline-configoptions:
+
Configuration Options
---------------------
@@ -1025,6 +1040,8 @@ Configuration Options
mame apple2ee -noreadconfig -sl6 diskii -sl7 cffa2 -hard1 TotalReplay.2mg
+.. _mame-commandline-pathoptions:
+
Core Search Path Options
------------------------
@@ -1235,6 +1252,8 @@ Core Search Path Options
mame -swpath c:\mame\software;c:\emu\mydisks
+.. _mame-commandline-coreoutdir:
+
Core Output Directory Options
-----------------------------
@@ -1362,6 +1381,8 @@ Core Output Directory Options
mame -comment_directory c:\mame\comments
+.. _mame-commandline-savestate:
+
Core State/Playback Options
---------------------------
@@ -1706,6 +1727,8 @@ Core State/Playback Options
mame neogeo -burnin
+.. _mame-commandline-perf:
+
Core Performance Options
------------------------
@@ -1862,7 +1885,7 @@ Core Performance Options
.. _mame-commandline-lowlatency:
-**-lowlatency**
+**-[no]lowlatency**
This tells MAME to draw a new frame before throttling to reduce input
latency. This is particularly effective with VRR (Variable Refresh Rate)
@@ -1878,6 +1901,8 @@ Core Performance Options
mame bgaregga -lowlatency
+.. _mame-commandline-rotation:
+
Core Rotation Options
---------------------
@@ -1978,6 +2003,8 @@ Core Rotation Options
mame -flipy suprmrio
+.. _mame-commandline-videooptions:
+
Core Video Options
------------------
@@ -2232,6 +2259,8 @@ Core Video Options
mame dkong -nounevenstretch
+.. _mame-commandline-fullscreen:
+
Core Full Screen Options
------------------------
@@ -2257,6 +2286,8 @@ Core Full Screen Options
mame kof97 -video d3d -switchres -resolution 1280x1024
+.. _mame-commandline-windowoptions:
+
Core Per-Window Options
-----------------------
@@ -2422,6 +2453,8 @@ Core Per-Window Options
mame contra -view native
+.. _mame-commandline-artwork:
+
Core Artwork Options
--------------------
@@ -2475,6 +2508,8 @@ Core Artwork Options
mame galaga -override_artwork puckman
+.. _mame-commandline-screenoptions:
+
Core Screen Options
-------------------
@@ -2569,6 +2604,8 @@ Core Screen Options
mame pacman -effect scanlines
+.. _mame-commandline-vectoroptions:
+
Core Vector Options
-------------------
@@ -2649,12 +2686,14 @@ Core Vector Options
mame asteroid -flicker 0.15
-Core Video OpenGL Debugging Options
------------------------------------
+.. _mame-commandline-opengloptions:
+
+Core Video OpenGL Feature Options
+---------------------------------
These 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
+rendering artifacts you may be asked to try messing with them by the developers,
+but normally they should be left at their defaults which results in the best
possible video performance.
.. Tip:: Examples are not provided for these options as MAMEdev will provide
@@ -2693,16 +2732,18 @@ possible video performance.
The default is ON. (**-gl_pbo**)
+.. _mame-commandline-openglglsl:
+
Core Video OpenGL GLSL Options
------------------------------
.. _mame-commandline-glglsl:
-**-gl_glsl**
+**-[no]gl_glsl**
Enable OpenGL GLSL, if available.
- The default is OFF.
+ The default is OFF (**-nogl_glsl**).
Example:
.. code-block:: bash
@@ -2765,19 +2806,7 @@ Core Video OpenGL GLSL Options
mame suprmrio -gl_glsl -glsl_shader_screen0 gaussx -glsl_shader_screen1 gaussy -glsl_shader_screen2 CRT-geom-halation
-.. _mame-commandline-glglslvidattr:
-
-**-gl_glsl_vid_attr**
-
- Enable OpenGL GLSL handling of brightness and contrast.
- Better RGB system performance.
-
- Default is ``on``.
-
- Example:
- .. code-block:: bash
-
- mame pacman -gl_glsl -gl_glsl_vid_attr off
+.. _mame-commandline-soundoptions:
Core Sound Options
------------------
@@ -2904,7 +2933,7 @@ Core Sound Options
The default is ``1``.
- | For PortAudio, see the section on :ref:`-pa_latency <mame-commandline-pa-latency>`.
+ | For PortAudio, see the section on :ref:`-pa_latency <mame-commandline-palatency>`.
| XAudio2 calculates audio_latency as 10ms steps.
| DSound calculates audio_latency as 10ms steps.
| CoreAudio calculates audio_latency as 25ms steps.
@@ -2916,6 +2945,8 @@ Core Sound Options
mame galaga -audio_latency 1
+.. _mame-commandline-inputoptions:
+
Core Input Options
------------------
@@ -3256,7 +3287,7 @@ Core Input Options
.. _mame-commandline-natural:
-**\-natural**
+**\-[no]natural**
Allows user to specify whether or not to use a natural keyboard or not.
This allows you to start your system in a 'native' mode, depending on your
@@ -3290,7 +3321,7 @@ Core Input Options
.. _mame-commandline-joystickcontradictory:
-**-joystick_contradictory**
+**-[no]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.
@@ -3317,6 +3348,8 @@ Core Input Options
mame contra -coin_impulse 1
+.. _mame-commandline-inputenable:
+
Core Input Automatic Enable Options
-----------------------------------
@@ -3368,6 +3401,8 @@ Core Input Automatic Enable Options
**-[no]joystick**, etc.
+.. _mame-commandline-debugging:
+
Debugging Options
-----------------
@@ -3570,6 +3605,8 @@ Debugging Options
mame marble -debug -debugger_font "Comic Sans MS" -debugger_font_size 16
+.. _mame-commandline-commoptions:
+
Core Communication Options
--------------------------
@@ -3645,6 +3682,8 @@ Core Communication Options
mame arescue -comm_remotehost 192.168.1.3 -comm_remoteport 30100 -comm_framesync
+.. _mame-commandline-miscoptions:
+
Core Misc Options
-----------------
@@ -3663,7 +3702,7 @@ Core Misc Options
.. _mame-commandline-drcusec:
-**\-drc_use_c**
+**\-[no]drc_use_c**
Force DRC to use the C code backend.
@@ -3676,7 +3715,7 @@ Core Misc Options
.. _mame-commandline-drcloguml:
-**\-drc_log_uml**
+**\-[no]drc_log_uml**
Write DRC UML disassembly log.
@@ -3689,7 +3728,7 @@ Core Misc Options
.. _mame-commandline-drclognative:
-**\-drc_log_native**
+**\-[no]drc_log_native**
Write DRC native disassembly log.
@@ -3788,7 +3827,7 @@ Core Misc Options
.. _mame-commandline-confirmquit:
-**\-confirm_quit**
+**\-[no]confirm_quit**
Display a Confirm Quit dialog to screen on exit, requiring one extra step
to exit MAME.
@@ -3802,7 +3841,7 @@ Core Misc Options
.. _mame-commandline-uimouse:
-**\-ui_mouse**
+**\-[no]ui_mouse**
Displays a mouse cursor when using the built-in UI for MAME.
@@ -3841,6 +3880,8 @@ Core Misc Options
mame galaga88 -nonvram_save
+.. _mame-commandline-scripting:
+
Scripting Options
-----------------
@@ -3930,8 +3971,11 @@ Scripting Options
mame alcon -noplugin cheat
+.. _mame-commandline-webserver:
+
HTTP Server Options
-------------------
+
.. _mame-commandline-http:
**-[no]http**
@@ -3972,10 +4016,12 @@ HTTP Server Options
mame apple2 -http -http_port 6502 -http_root c:\users\me\appleweb\root
+.. _mame-commandline-portaudio:
+
PortAudio Options
-----------------
-.. _mame-commandline-pa-api:
+.. _mame-commandline-paapi:
**-pa_api** *API*
@@ -4031,7 +4077,7 @@ PortAudio Options
mame suprmrio -sound portaudio -pa_api "Windows WASAPI"
-.. _mame-commandline-pa-device:
+.. _mame-commandline-padevice:
**-pa_device** *device*
@@ -4045,7 +4091,7 @@ PortAudio Options
mame suprmrio -sound portaudio -pa_api "Windows WASAPI" -pa_device "NX-EDG27 (NVIDIA High Definition Audio)"
-.. _mame-commandline-pa-latency:
+.. _mame-commandline-palatency:
**-pa_latency** *latency*
diff --git a/docs/source/commandline/commandline-index.rst b/docs/source/commandline/commandline-index.rst
index b0cd9a51170..8698dcf7dc5 100644
--- a/docs/source/commandline/commandline-index.rst
+++ b/docs/source/commandline/commandline-index.rst
@@ -11,23 +11,23 @@ Universal Commandline Options
This section contains configuration options that are applicable to *all* MAME sub-builds (both SDL and Windows native).
-Core Commands
-~~~~~~~~~~~~~
+Core Verbs
+~~~~~~~~~~
| :ref:`help <mame-commandline-help>`
| :ref:`validate <mame-commandline-validate>`
-Configuration Commands
-~~~~~~~~~~~~~~~~~~~~~~
+Configuration Verbs
+~~~~~~~~~~~~~~~~~~~
| :ref:`createconfig <mame-commandline-createconfig>`
| :ref:`showconfig <mame-commandline-showconfig>`
| :ref:`showusage <mame-commandline-showusage>`
-Frontend Commands
-~~~~~~~~~~~~~~~~~
+Frontend Verbs
+~~~~~~~~~~~~~~
| :ref:`listxml <mame-commandline-listxml>`
| :ref:`listfull <mame-commandline-listfull>`
@@ -60,8 +60,8 @@ OSD-related Options
| :ref:`joystickprovider <mame-commandline-joystickprovider>`
-OSD CLI Options
-~~~~~~~~~~~~~~~
+OSD CLI Verbs
+~~~~~~~~~~~~~
| :ref:`listmidi <mame-commandline-listmidi>`
| :ref:`listnetwork <mame-commandline-listnetwork>`
@@ -117,9 +117,8 @@ Core State/Playback Options
| :ref:`state <mame-commandline-state>`
| :ref:`[no]autosave <mame-commandline-noautosave>`
| :ref:`playback <mame-commandline-playback>`
-| :ref:`exit_after_playback <mame-commandline-exitafterplayback>`
+| :ref:`[no]exit_after_playback <mame-commandline-exitafterplayback>`
| :ref:`record <mame-commandline-record>`
-| :ref:`record_timecode <mame-commandline-recordtimecode>`
| :ref:`mngwrite <mame-commandline-mngwrite>`
| :ref:`aviwrite <mame-commandline-aviwrite>`
| :ref:`wavwrite <mame-commandline-wavwrite>`
@@ -143,7 +142,7 @@ Core Performance Options
| :ref:`[no]refreshspeed <mame-commandline-norefreshspeed>`
| :ref:`numprocessors <mame-commandline-numprocessors>`
| :ref:`bench <mame-commandline-bench>`
-| :ref:`lowlatency <mame-commandline-lowlatency>`
+| :ref:`[no]lowlatency <mame-commandline-lowlatency>`
Core Rotation Options
@@ -212,6 +211,7 @@ Core Vector Options
| :ref:`beam_width_min <mame-commandline-beamwidthmin>`
| :ref:`beam_width_max <mame-commandline-beamwidthmax>`
| :ref:`beam_intensity_weight <mame-commandline-beamintensityweight>`
+| :ref:`beam_dot_size <mame-commandline-beamdotsize>`
| :ref:`flicker <mame-commandline-flicker>`
@@ -227,11 +227,10 @@ Core Video OpenGL Debugging Options
Core Video OpenGL GLSL Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-| :ref:`gl_glsl <mame-commandline-glglsl>`
+| :ref:`[no]gl_glsl <mame-commandline-glglsl>`
| :ref:`gl_glsl_filter <mame-commandline-glglslfilter>`
| :ref:`glsl_shader_mame[0-9] <mame-commandline-glslshadermame>`
| :ref:`glsl_shader_screen[0-9] <mame-commandline-glslshaderscreen>`
-| :ref:`gl_glsl_vid_attr <mame-commandline-glglslvidattr>`
Core Sound Options
@@ -261,8 +260,8 @@ Core Input Options
| :ref:`joystick_map <mame-commandline-joystickmap>`
| :ref:`joystick_deadzone <mame-commandline-joystickdeadzone>`
| :ref:`joystick_saturation <mame-commandline-joysticksaturation>`
-| :ref:`natural <mame-commandline-natural>`
-| :ref:`joystick_contradictory <mame-commandline-joystickcontradictory>`
+| :ref:`[no]natural <mame-commandline-natural>`
+| :ref:`[no]joystick_contradictory <mame-commandline-joystickcontradictory>`
| :ref:`coin_impulse <mame-commandline-coinimpulse>`
@@ -286,9 +285,11 @@ Core Debugging Options
| :ref:`[no]oslog <mame-commandline-oslog>`
| :ref:`[no]log <mame-commandline-log>`
| :ref:`[no]debug <mame-commandline-debug>`
+| :ref:`debugger <mame-commandline-debugger>`
| :ref:`debugscript <mame-commandline-debugscript>`
| :ref:`[no]update_in_pause <mame-commandline-updateinpause>`
| :ref:`watchdog <mame-commandline-watchdog>`
+| :ref:`debugger_port <mame-commandline-debuggerport>`
| :ref:`debugger_font <mame-commandline-debuggerfont>`
| :ref:`debugger_font_size <mame-commandline-debuggerfontsize>`
@@ -307,23 +308,23 @@ Core Misc Options
~~~~~~~~~~~~~~~~~
| :ref:`[no]drc <mame-commandline-drc>`
-| :ref:`drc_use_c <mame-commandline-drcusec>`
-| :ref:`drc_log_uml <mame-commandline-drcloguml>`
-| :ref:`drc_log_native <mame-commandline-drclognative>`
+| :ref:`[no]drc_use_c <mame-commandline-drcusec>`
+| :ref:`[no]drc_log_uml <mame-commandline-drcloguml>`
+| :ref:`[no]drc_log_native <mame-commandline-drclognative>`
| :ref:`bios <mame-commandline-bios>`
| :ref:`[no]cheat <mame-commandline-cheat>`
| :ref:`[no]skip_gameinfo <mame-commandline-skipgameinfo>`
| :ref:`uifont <mame-commandline-uifont>`
| :ref:`ui <mame-commandline-ui>`
| :ref:`ramsize <mame-commandline-ramsize>`
-| :ref:`confirm_quit <mame-commandline-confirmquit>`
-| :ref:`ui_mouse <mame-commandline-uimouse>`
+| :ref:`[no]confirm_quit <mame-commandline-confirmquit>`
+| :ref:`[no]ui_mouse <mame-commandline-uimouse>`
| :ref:`language <mame-commandline-language>`
| :ref:`[no]nvram_save <mame-commandline-nvramsave>`
Scripting Options
------------------
+~~~~~~~~~~~~~~~~~
| :ref:`autoboot_command <mame-commandline-autobootcommand>`
| :ref:`autoboot_delay <mame-commandline-autobootdelay>`
@@ -335,13 +336,21 @@ Scripting Options
HTTP Server Options
--------------------
+~~~~~~~~~~~~~~~~~~~
| :ref:`http <mame-commandline-http>`
| :ref:`http_port <mame-commandline-httpport>`
| :ref:`http_root <mame-commandline-httproot>`
+PortAudio Options
+~~~~~~~~~~~~~~~~~
+
+| :ref:`pa_api <mame-commandline-paapi>`
+| :ref:`pa_device <mame-commandline-padevice>`
+| :ref:`pa_latency <mame-commandline-palatency>`
+
+
Windows-Specific Commandline Options
------------------------------------
@@ -377,7 +386,7 @@ This section contains configuration options that are specific to any build suppo
SDL Performance Options
~~~~~~~~~~~~~~~~~~~~~~~
-| :ref:`sdlvideofps <mame-scommandline-sdlvideofps>`
+| :ref:`[no]sdlvideofps <mame-scommandline-sdlvideofps>`
SDL Video Options
diff --git a/docs/source/commandline/sdlconfig.rst b/docs/source/commandline/sdlconfig.rst
index 0da5f4c526e..e67835c8c21 100644
--- a/docs/source/commandline/sdlconfig.rst
+++ b/docs/source/commandline/sdlconfig.rst
@@ -11,7 +11,7 @@ Performance Options
.. _mame-scommandline-sdlvideofps:
-**-sdlvideofps**
+**-[no]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.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 95dc1d19bbf..e8277abefe4 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -56,16 +56,16 @@ master_doc = 'index'
# General information about the project.
project = u'MAME Documentation'
-copyright = u'1997-2021, MAMEdev and contributors'
+copyright = u'1997-2022, MAMEdev and contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.238'
+version = '0.243'
# The full version, including alpha/beta/rc tags.
-release = '0.238'
+release = '0.243'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst
index ffeb1379f3f..e7d82c3ad1c 100644
--- a/docs/source/debugger/general.rst
+++ b/docs/source/debugger/general.rst
@@ -41,6 +41,8 @@ General Debugger Commands
save a screen snapshot
:ref:`debugger-command-source`
read commands from file and executes them one by one
+:ref:`debugger-command-time`
+ prints the current machine time to the console
:ref:`debugger-command-quit`
exit the debugger and end the emulation session
@@ -78,8 +80,8 @@ do
The **do** command simply evaluates the supplied expression. This is
often used to set or modify device state variable (e.g. CPU registers),
-or to write to memory. See :ref:`debugger-expressions` for details
-about expression syntax.
+or to write to memory. See :ref:`debugger-express` for details about
+expression syntax.
Examples:
diff --git a/docs/source/debugger/index.rst b/docs/source/debugger/index.rst
index 18785e734e7..4b6cd02d2ba 100644
--- a/docs/source/debugger/index.rst
+++ b/docs/source/debugger/index.rst
@@ -163,7 +163,7 @@ debugger should take the most likely meaning for a device or address
space specification.
-.. _debugger-expressions:
+.. _debugger-express:
Debugger expression syntax
--------------------------
@@ -218,6 +218,8 @@ Major differences from C expression semantics:
always evaluated.
+.. _debugger-express-num:
+
Numbers
~~~~~~~
@@ -240,6 +242,8 @@ Examples:
* ``0b123`` is invalid
+.. _debugger-express-bool:
+
Boolean values
~~~~~~~~~~~~~~
@@ -253,6 +257,8 @@ debugger commands to use the default value, even when subsequent
parameters are specified.
+.. _debugger-express-mem:
+
Memory accesses
~~~~~~~~~~~~~~~
@@ -281,22 +287,22 @@ multiple effects of a write access. For example:
* Some registers need to be written in sequence to avoid race
conditions. The debugger can issue multiple writes at the same point
- in emulated time, so these race conditions cannot be avoided
- trivially. For example writing to the MC68HC05 output compare
- register high byte (OCRH) inhibits compare until the output compare
- register low byte (OCRL) is written to prevent race conditions.
- Since the debugger can write to both locations at the same instant
- from the emulated machine’s point of view, the race condition is not
- usually relevant. It’s more error-prone if you can accidentally set
- hidden state when all you really want to do is change the value, so
- writing to OCRH with side effects suppressed does not inhibit compare,
- it just changes the value in the output compare register.
+ in emulated time, so these race conditions can be avoided trivially.
+ For example writing to the MC68HC05 output compare register high byte
+ (OCRH) inhibits compare until the output compare register low byte
+ (OCRL) is written to prevent race conditions. Since the debugger can
+ write to both locations at the same instant from the emulated
+ machine’s point of view, the race condition is not usually relevant.
+ It’s more error-prone if you can accidentally set hidden state when
+ all you really want to do is change the value, so writing to OCRH with
+ side effects suppressed does not inhibit compare, it just changes the
+ value in the output compare register.
* Writing to some registers has multiple effects that may be useful to
separate for debugging purposes. Using the MC68HC05 as an example
again, writing to OCRL changes the value in the output compare
register, and also clears the output compare flag (OCF) and enables
compare if it was previously inhibited by writing to OCRH. Writing to
- OCRL with side effects disable just changes the value in the register
+ OCRL with side effects disabled just changes the value in the register
without clearing OCF or enabling compare, since it’s useful for
debugging purposes. Writing to OCRL with side effects enabled has the
additional effects.
@@ -390,6 +396,8 @@ Memory accesses can be used as both lvalues and rvalues, so you can write
``b@100 = ff`` to store a byte in memory.
+.. _debugger-express-func:
+
Functions
~~~~~~~~~
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index fdd0545db9f..3c8fddd26fc 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -72,7 +72,7 @@ building MAME on a 64-bit system. Instructions may need to be adjusted for
use the portable SDL (Simple DirectMedia Layer) interfaces instead, you can
add **OSD=sdl** to the make options. The main emulator binary will have an
``sdl`` prefix prepended (e.g. ``sdlmame.exe``). You
- will need to install the MSYS2 packages for SDL 2 version 2.0.3 or later.
+ will need to install the MSYS2 packages for SDL 2 version 2.0.6 or later.
* By default, MAME will include the native Windows debugger. To also include
the portable Qt debugger, add **USE_QTDEBUG=1** to the make options. You
will need to install the MSYS2 packages for Qt 5.
@@ -224,7 +224,7 @@ Fedora Linux
------------
You’ll need a few prerequisites from your Linux distribution. Make sure you get
-SDL2 2.0.4 or later as earlier versions are buggy::
+SDL2 2.0.6 or later as earlier versions lack required functionality::
sudo dnf install gcc gcc-c++ SDL2-devel SDL2_ttf-devel libXi-devel libXinerama-devel qt5-qtbase-devel qt5-qttools expat-devel fontconfig-devel alsa-lib-devel pulseaudio-libs-devel
@@ -246,7 +246,7 @@ Debian and Ubuntu (including Raspberry Pi and ODROID devices)
-------------------------------------------------------------
You’ll need a few prerequisites from your Linux distribution. Make sure you get
-SDL2 2.0.4 or later as earlier versions are buggy::
+SDL2 2.0.6 or later as earlier versions lack required functionality::
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qt5-default
@@ -274,8 +274,10 @@ Apple macOS
You’ll need a few prerequisites to get started. Make sure you’re on OS X 10.14
Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will
-need SDL2 2.0.4 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also
-need to install Python 3.
+need SDL2 2.0.6 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also
+need to install Python 3 – it’s currently included with the Xcode command line
+tools, but you can also install a stand-alone version or get it via the Homebrew
+package manager.
* Install **Xcode** from the Mac App Store or
`ADC <https://developer.apple.com/download/more/>`_ (AppleID required).
@@ -298,12 +300,13 @@ Next you’ll need to get SDL2 installed.
**SDL2.framework** folder from the SDL disk image into the **Frameworks**
folder. You will have to authenticate with your user password.
-Now get Python 3 set up:
+If you don’t already have it, get Python 3 set up:
-* Go to the `official Python site <https://www.python.org/>`_ and click the link
- to the download page for the current version (this was
- `Python 3.10.0 <https://www.python.org/downloads/release/python-3100/>`_ at
- the time of writing).
+* Go to the official Python site, navigate to the
+ `releases for macOS <https://www.python.org/downloads/macos/>`_, and click the
+ link to download the installer for the latest stable release (this was
+ `Python 3.10.4 <https://www.python.org/ftp/python/3.10.4/python-3.10.4-macos11.pkg>`_
+ at the time of writing).
* Scroll down to the “Files” section, and download the macOS version (called
“macOS 64-bit universal2 installer” or similar).
* Once the package downloads, open it and follow the standard installation
diff --git a/docs/source/license.rst b/docs/source/license.rst
index fd72712d9d8..d11b51b0f99 100644
--- a/docs/source/license.rst
+++ b/docs/source/license.rst
@@ -12,7 +12,7 @@ would encourage new contributors to distribute files under this license.
Please note that MAME is a registered trademark of Gregory Ember, and permission
is required to use the “MAME” name, logo, or wordmark.
- Copyright (C) 1997-2021 MAMEDev and contributors
+ Copyright (C) 1997-2022 MAMEDev and contributors
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index c43a7df8e1b..5dd1bba0758 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -517,21 +517,6 @@ text
be an integer, where 0 (zero) means centred, 1 (one) means left-aligned, and
2 (two) means right-aligned. If the ``align`` attribute is absent, the text
will be centred.
-dotmatrix
- Draws an eight-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrix5dot
- Draws a five-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrixdot
- Draws a single element of a dot matrix display as a circular pixels in the
- specified colour. The least significant bit of the element’s state
- determines whether the pixel is lit. An unlit pixel is drawn at low
- intensity (0x20/0xff).
led7seg
Draws a standard seven-segment (plus decimal point) digital LED/fluorescent
display in the specified colour. The low eight bits of the element’s state
@@ -539,14 +524,6 @@ led7seg
the bits correspond to the top segment, the upper right-hand segment,
continuing clockwise to the upper left segment, the middle bar, and the
decimal point. Unlit segments are drawn at low intensity (0x20/0xff).
-led8seg_gts1
- Draws an eight-segment digital fluorescent display of the type used in
- Gottlieb System 1 pinball machines (actually a Futaba part). Compared to
- standard seven-segment displays, these displays have no decimal point, the
- horizontal middle bar is broken in the centre, and there is a broken
- vertical middle bar controlled by the bit that would control the decimal
- point in a standard seven-segment display. Unlit segments are drawn at low
- intensity (0x20/0xff).
led14seg
Draws a standard fourteen-segment alphanumeric LED/fluorescent display in
the specified colour. The low fourteen bits of the element’s state control
@@ -1491,12 +1468,12 @@ internal layouts included in MAME.
This system uses lamps for key gameplay elements. Blending modes are used
for the translucent colour overlay placed over the monitor, and the lamps
reflected in front of the monitor. Also uses collections to allow parts of
- the layout to be disabled selectively. The shapes on the overlay are drawn
- using embedded SVG images.
+ the layout to be disabled selectively.
`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0235>`_
This game’s monitor is viewed directly through a translucent colour overlay
rather than being reflected from inside the cabinet. This means the overlay
reflects ambient light as well as affecting the colour of the video image.
+ The shapes on the overlay are drawn using embedded SVG images.
`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0235>`_
A multi-segment alphanumeric display and keypad. The keys are clickable,
and provide visual feedback when pressed.
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index 85c7ea8cb8a..e2e33b362f0 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -63,6 +63,29 @@ Core classes
Many of MAME’s core classes used to implement an emulation session are available
to Lua scripts.
+.. _luareference-core-notifiersub:
+
+Notifier subscription
+~~~~~~~~~~~~~~~~~~~~~
+
+Wraps MAME’s ``util::notifier_subscription`` class, which manages a subscription
+to a broadcast notification.
+
+Methods
+^^^^^^^
+
+subscription:unsubscribe()
+ Unsubscribes from notifications. The subscription will become inactive and
+ no future notifications will be received.
+
+Properties
+^^^^^^^^^^
+
+subscription.is_active (read-only)
+ A Boolean indicating whether the subscription is active. A subscription
+ becomes inactive after explicitly unsubscribing or if the underlying
+ notifier is destroyed.
+
.. _luareference-core-attotime:
Attotime
@@ -1363,6 +1386,34 @@ space:read_range(start, end, width, [step])
Reads a range of addresses as a binary string. The end address must be
greater than or equal to the start address. The width must be 8, 16, 30 or
64. If the step is provided, it must be a positive number of elements.
+space:add_change_notifier(callback)
+ Add a callback to receive notifications for handler changes in address
+ space. The callback function is passed a single string as an argument,
+ either ``r`` if read handlers have potentially changed, ``w`` if write
+ handlers have potentially changed, or ``rw`` if both read and write handlers
+ have potentially changed.
+
+ Returns a :ref:`notifier subscription <luareference-core-notifiersub>`.
+space:install_read_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luareference-mem-tap>` that will
+ receive notifications on reads from the specified range of addresses in the
+ address space. The start and end addresses are inclusive. The name must be
+ a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data read,
+ and the memory access mask. To modify the data being read, return the
+ modified value from the callback function as an integer. If the callback
+ does not return an integer, the data will not be modified.
+space:install_write_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luareference-mem-tap>` that will
+ receive notifications on write to the specified range of addresses in the
+ address space. The start and end addresses are inclusive. The name must be
+ a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data
+ written, and the memory access mask. To modify the data being written,
+ return the modified value from the callback function as an integer. If the
+ callback does not return an integer, the data will not be modified.
Properties
^^^^^^^^^^
@@ -1387,6 +1438,52 @@ space.map (read-only)
The configured :ref:`address map <luareference-mem-map>` for the space or
``nil``.
+.. _luareference-mem-tap:
+
+Pass-through handler
+~~~~~~~~~~~~~~~~~~~~
+
+Tracks a pass-through handler installed in an
+:ref:`address space <luareference-mem-space>`. A memory pass-through handler
+receives notifications on accesses to a specified range of addresses, and can
+modify the data that is read or written if desired.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on reads
+ from the specified range of addresses in an
+ :ref:`address space <luareference-mem-space>`.
+manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on writes to
+ the specified range of addresses in an
+ :ref:`address space <luareference-mem-space>`.
+
+Methods
+^^^^^^^
+
+passthrough:reinstall()
+ Reinstalls the pass-through handler in the address space. May be necessary
+ if the handler is removed due to other changes to handlers in the address
+ space.
+passthrough:remove()
+ Removes the pass-through handler from the address space. The associated
+ callback will not be called in response to future memory accesses.
+
+Properties
+^^^^^^^^^^
+
+passthrough.addrstart (read-only)
+ The inclusive start address of the address range monitored by the
+ pass-through handler (i.e. the lowest address that the handler will be
+ notified for).
+passthrough.addrend (read-only)
+ The inclusive end address of the address range monitored by the pass-through
+ handler (i.e. the highest address that the handler will be notified for).
+passthrough.name (read-only)
+ The display name for the pass-through handler.
+
.. _luareference-mem-map:
Address map
@@ -1648,9 +1745,12 @@ ioport:count_players()
Returns the number of player controllers in the system.
ioport:type_pressed(type, [player])
Returns a Boolean indicating whether the specified input is currently
- pressed. The input port type is an enumerated value. The player number is
- a zero-based index. If the player number is not supplied, it is assumed to
- be zero.
+ pressed. The input type may be an enumerated value or an
+ :ref:`input type <luareference-input-inputtype>` entry. If the input type
+ is an enumerated value, the player number may be supplied as a zero-based
+ index; if the player number is not supplied, it is assumed to be zero. If
+ the input type is an input type entry, the player number may not be supplied
+ separately.
ioport:type_name(type, [player])
Returns the display name for the specified input type and player number.
The input type is an enumerated value. The player number is a zero-based
@@ -1665,22 +1765,31 @@ ioport:type_group(type, player)
canonical grouping in an input configuration UI.
ioport:type_seq(type, [player], [seqtype])
Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. If the player
- number is not supplied, it is assumed to be zero. If the sequence type is
- supplied, it must be ``"standard"``, ``"increment"`` or ``"decrement"``; if
- it is not supplied, it is assumed to be ``"standard"``.
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luareference-input-inputtype>` entry. If the input type
+ is an enumerated value, the player number may be supplied as a zero-based
+ index; if the player number is not supplied, it is assumed to be zero. If
+ the input type is an input type entry, the player number may not be supplied
+ separately. If the sequence type is supplied, it must be ``"standard"``,
+ ``"increment"`` or ``"decrement"``; if it is not supplied, it is assumed to
+ be ``"standard"``.
This provides access to general input configuration.
-ioport:set_type_seq(type, player, seqtype, seq)
+ioport:set_type_seq(type, [player], seqtype, seq)
Set the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. The sequence
- type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luareference-input-inputtype>` entry. If the input type
+ is an enumerated value, the player number must be supplied as a zero-based
+ index. If the input type is an input type entry, the player number may not
+ be supplied separately. The sequence type must be ``"standard"``,
+ ``"increment"`` or ``"decrement"``.
This allows general input configuration to be set.
ioport:token_to_input_type(string)
- Returns the input type and player number for the specified input type token.
+ Returns the input type and player number for the specified input type token
+ string.
ioport:input_type_to_token(type, [player])
Returns the token string for the specified input type and player number. If
the player number is not supplied, it assumed to be zero.
@@ -1688,6 +1797,9 @@ ioport:input_type_to_token(type, [player])
Properties
^^^^^^^^^^
+ioport.types[] (read-only)
+ Gets the supported :ref:`input types <luareference-input-inputtype>`. Keys
+ are arbitrary indices. All supported operations have O(1) complexity.
ioport.ports[]
Gets the emulated :ref:`I/O ports <luareference-input-ioport>` in the
system. Keys are absolute tags. The ``at`` and ``index_of`` methods have
@@ -1850,7 +1962,7 @@ Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.
Instantiation
^^^^^^^^^^^^^
-manager.machine.ioport.ports[tag]:field[mask]
+manager.machine.ioport.ports[tag]:field(mask)
Gets a field for the given port by bit mask.
manager.machine.ioport.ports[tag].fields[name]
Gets a field for the given port by display name.
@@ -1862,6 +1974,9 @@ field:set_value(value)
Set the value of the I/O port field. For digital fields, the value is
compared to zero to determine whether the field should be active; for
analog fields, the value must be right-aligned and in the correct range.
+field:clear_value()
+ Clear programmatically overridden value and restore the field’s regular
+ behaviour.
field:set_input_seq(seqtype, seq)
Set the :ref:`input sequence <luareference-input-iptseq>` for the
specified sequence type. This is used to configure per-machine input
@@ -1906,9 +2021,13 @@ field.player (read-only)
field.mask (read-only)
Bits in the I/O port corresponding to this field.
field.defvalue (read-only)
- The field’s default value
+ The field’s default value.
+field.minvalue (read-only)
+ The minimum allowed value for analog fields, or ``nil`` for digital fields.
+field.maxvalue (read-only)
+ The maximum allowed value for analog fields, or ``nil`` for digital fields.
field.sensitivity (read-only)
- The sensitivity or gain for analog fields
+ The sensitivity or gain for analog fields, or ``nil`` for digital fields.
field.way (read-only)
The number of directions allowed by the restrictor plate/gate for a digital
joystick, or zero (0) for other inputs.
@@ -1985,6 +2104,41 @@ Properties
live.name
Display name for the field.
+.. _luareference-input-inputtype:
+
+Input type
+~~~~~~~~~~
+
+Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
+emulator UI input type. Input types are uniquely identified by the combination
+of their enumerated type value and player index.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager.machine.ioport.types[index]
+ Gets a supported input type.
+
+Properties
+^^^^^^^^^^
+
+type.type (read-only)
+ An enumerated value representing the type of input.
+type.group (read-only)
+ An integer giving the grouping for the input type. Should be used to
+ provide canonical grouping in an input configuration UI.
+type.player (read-only)
+ The zero-based player number, or zero for non-player controls.
+type.token (read-only)
+ The token string for the input type, used in configuration files.
+type.name (read-only)
+ The display name for the input type.
+type.is_analog (read-only)
+ A Boolean indicating whether the input type is analog or digital. Inputs
+ that only have on and off states are considered digital, while all other
+ inputs are considered analog, even if they can only represent discrete
+ values or positions.
+
.. _luareference-input-inputman:
Input manager
@@ -2745,10 +2899,12 @@ screens in the emulated system.
Instantiation
^^^^^^^^^^^^^
-Layout scripts generally
-
manager.machine.render.targets[index].current_view
Gets the currently selected view for a given render target.
+file.views[name]
+ Gets the view with the specified name from a
+ :ref:`layout file <luareference-render-layfile>`. This is how layout
+ scripts generally obtain views.
Methods
^^^^^^^
@@ -2982,9 +3138,221 @@ Debugger
--------
Some of MAME’s core debugging features can be controlled from Lua script. The
-debugger must be enabled to use the debugging features (usually by passing
+debugger must be enabled to use the debugger features (usually by passing
``-debug`` on the command line).
+.. _luareference-debug-symtable:
+
+Symbol table
+~~~~~~~~~~~~
+
+Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
+in expressions. Note that symbol tables can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+^^^^^^^^^^^^^
+
+emu.symbol_table(machine)
+ Creates a new symbol table in the context of the specified machine,
+emu.symbol_table(parent, [device])
+ Creates a new symbol table with the specified parent symbol table. If a
+ device is specified and it implements ``device_memory_interface``, it will
+ be used as the base for looking up address spaces and memory regions. Note
+ that if a device that does not implement ``device_memory_interface`` is
+ supplied, it will not be used (address spaces and memory regions will be
+ looked up relative to the root device).
+emu.symbol_table(device)
+ Creates a new symbol table in the context of the specified device. If the
+ device implements ``device_memory_interface``, it will be used as the base
+ for looking up address spaces and memory regions. Note that if a device
+ that does not implement ``device_memory_interface`` is supplied, it will
+ only be used to determine the machine context (address spaces and memory
+ regions will be looked up relative to the root device).
+
+Methods
+^^^^^^^
+
+symbols:set_memory_modified_func(cb)
+ Set a function to call when memory is modified via the symbol table. No
+ arguments are passed to the function and any return values are ignored.
+ Call with ``nil`` to remove the callback.
+symbols:add(name, [value])
+ Adds a named integer symbol. The name must be a string. If a value is
+ supplied, it must be an integer. If a value is supplied, a read-only symbol
+ is added with the supplied value. If no value is supplied, a read/write
+ symbol is created with and initial value of zero. If a symbol entry with
+ the specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
+symbols:add(name, getter, [setter], [format])
+ Adds a named integer symbol using getter and optional setter callbacks. The
+ name must be a string. The getter must be a function returning an integer
+ for the symbol value. If supplied, the setter must be a function that
+ accepts a single integer argument for the new value of the symbol. A format
+ string for displaying the symbol value may optionally be supplied. If a
+ symbol entry with the specified name already exists in the symbol table, it
+ will be replaced.
+
+ Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
+symbols:add(name, minparams, maxparams, execute)
+ Adds a named function symbol. The name must be a string. The minimum and
+ maximum numbers of parameters must be integers. If a symbol entry with the
+ specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
+symbols:find(name)
+ Returns the :ref:`symbol entry <luareference-debug-symentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table.
+symbols:find_deep(name)
+ Returns the :ref:`symbol entry <luareference-debug-symentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table or any of its parent symbol tables.
+symbols:value(name)
+ Returns the integer value of the symbol with the specified name, or zero if
+ there is no symbol with the specified name in the symbol table or any of its
+ parent symbol tables. Raises an error if the symbol with specified name is
+ a function symbol.
+symbols:set_value(name, value)
+ Sets the value of the symbol with the specified name. Raises an error if
+ the symbol with the specified name is a read-only integer symbol or if it is
+ a function symbol. Has no effect if there is no symbol with the specified
+ name in the symbol table or any of its parent symbol tables.
+symbols:memory_value(name, space, offset, size, disable_se)
+ Read a value from memory. Supply the name or tag of the address space or
+ memory region to read from, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:set_memory_value(name, space, offset, value, size, disable_se)
+ Write a value to memory. Supply the name or tag of the address space or
+ memory region to write to, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:read_memory(space, address, size, apply_translation)
+ Read a value from an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug read intention. Returns a value
+ of the requested size with all bits set if address translation fails.
+symbols:write_memory(space, address, data, size, apply_translation)
+ Write a value to an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug write intention. The symbol
+ table’s memory modified function will be called after the value is written.
+ The value will not be written and the symbol table’s memory modified
+ function will not be called if address translation fails.
+
+Properties
+^^^^^^^^^^
+
+symbols.entries[]
+ The :ref:`symbol entries <luareference-debug-symentry>` in the symbol table,
+ indexed by name. The ``at`` and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+symbols.parent (read-only)
+ The parent symbol table, or ``nil`` if the symbol table has no parent.
+
+.. _luareference-debug-expression:
+
+Parsed expression
+~~~~~~~~~~~~~~~~~
+
+Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
+expression. Note that parsed expressions can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+^^^^^^^^^^^^^
+
+emu.parsed_expression(symbols)
+ Creates an empty expression that will use the supplied
+ :ref:`symbol table <luareference-debug-symtable>` to look up symbols.
+emu.parsed_expression(symbols, string, [default_base])
+ Creates an expression by parsing the supplied string, looking up symbols in
+ the supplied :ref:`symbol table <luareference-debug-symtable>`. If the
+ default base for interpreting integer literals is not supplied, 16 is used
+ (hexadecimal). Raises an error if the string contains syntax errors or uses
+ undefined symbols.
+
+Methods
+^^^^^^^
+
+expression:set_default_base(base)
+ Set the default base for interpreting numeric literals. The base must be a
+ positive integer.
+expression:parse(string)
+ Parse a debugger expression string. Replaces the current contents of the
+ expression if it is not empty. Raises an error if the string contains
+ syntax errors or uses undefined symbols. The previous content of the
+ expression is not preserved when attempting to parse an invalid expression
+ string.
+expression:execute()
+ Evaluates the expression, returning an unsigned integer result. Raises an
+ error if the expression cannot be evaluated (e.g. calling a function with an
+ invalid number of arguments).
+
+Properties
+^^^^^^^^^^
+
+expression.is_empty (read-only)
+ A Boolean indicating whether the expression contains no tokens.
+expression.original_string (read-only)
+ The original string that was parsed to create the expression.
+expression.symbols (read/write)
+ The :ref:`symbol table <luareference-debug-symtable>` used for to look up
+ symbols in the expression.
+
+.. _luareference-debug-symentry:
+
+Symbol entry
+~~~~~~~~~~~~
+
+Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
+:ref:`symbol table <luareference-debug-symtable>`. Note that symbol entries
+must not be used after the symbol table they belong to is destroyed.
+
+Instantiation
+^^^^^^^^^^^^^
+
+symbols:add(name, [value])
+ Adds an integer symbol to a
+ :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
+ entry.
+symbols:add(name, getter, [setter], [format])
+ Adds an integer symbol to a
+ :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
+ entry.
+symbols:add(name, minparams, maxparams, execute)
+ Adds function symbol to a
+ :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
+ entry.
+
+Properties
+^^^^^^^^^^
+
+entry.name (read-only)
+ The name of the symbol entry.
+entry.format (read-only)
+ The format string used to convert the symbol entry to text for display.
+entry.is_function (read-only)
+ A Boolean indicating whether the symbol entry is a callable function.
+entry.is_lval (read-only)
+ A Boolean indicating whether the symbol entry is an integer symbol that can
+ be set (i.e. whether it can be used on the left-hand side of assignment
+ expressions).
+entry.value (read/write)
+ The integer value of the symbol entry. Attempting to set the value raises
+ an error if the symbol entry is read-only. Attempting to get or set the
+ value of a function symbol raises an error.
+
.. _luareference-debug-manager:
Debugger manager
@@ -3035,7 +3403,7 @@ emulated CPU device.
Instantiation
^^^^^^^^^^^^^
-manager.machine.devices[tag]:debug()
+manager.machine.devices[tag].debug
Returns the debugger interface for an emulated CPU device, or ``nil`` if the
device is not a CPU.
@@ -3120,7 +3488,7 @@ emulated CPU device.
Instantiation
^^^^^^^^^^^^^
-manager.machine.devices[tag]:debug():bplist()[bp]
+manager.machine.devices[tag].debug:bplist()[bp]
Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
breakpoint corresponds to the specified index.
@@ -3131,7 +3499,7 @@ breakpoint.index (read-only)
The breakpoint’s index. The can be used to enable, disable or clear the
breakpoint via the
:ref:`CPU debugger interface <luareference-debug-devdebug>`.
-breakpoint.enabled (read-only)
+breakpoint.enabled (read/write)
A Boolean indicating whether the breakpoint is currently enabled.
breakpoint.address (read-only)
The breakpoint’s address.
@@ -3154,7 +3522,7 @@ emulated CPU device.
Instantiation
^^^^^^^^^^^^^
-manager.machine.devices[tag]:debug():wplist(space)[wp]
+manager.machine.devices[tag].debug:wplist(space)[wp]
Gets the specified watchpoint for an address space of an emulated CPU
device, or ``nil`` if no watchpoint in the address space corresponds to the
specified index.
@@ -3166,7 +3534,7 @@ watchpoint.index (read-only)
The watchpoint’s index. The can be used to enable, disable or clear the
watchpoint via the
:ref:`CPU debugger interface <luareference-debug-devdebug>`.
-watchpoint.enabled (read-only)
+watchpoint.enabled (read/write)
A Boolean indicating whether the watchpoint is currently enabled.
watchpoint.type (read-only)
Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 5d18c4e1202..260e39e566e 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -180,7 +180,7 @@ retrieved by building one of these four finders.
[device constructor] m_bank(*this, "name"),
-A memory share can be created if it doesn’t exist in a memory map
+A memory bank can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved.
@@ -197,7 +197,7 @@ that the lookup can be expensive, prefer finders instead.
.. code-block:: C++
- class memory_bank {
+ class memory_region {
u8 *base();
u8 *end();
u32 bytes() const;
diff --git a/docs/source/techspecs/object_finders.rst b/docs/source/techspecs/object_finders.rst
index 2256d74b677..e05146c3167 100644
--- a/docs/source/techspecs/object_finders.rst
+++ b/docs/source/techspecs/object_finders.rst
@@ -239,7 +239,7 @@ the object finders in the device class (with all distractions removed):
}
sbus_device(machine_config const &mconfig, char const *tag, device_t *owner, u32 clock) :
- device_t(mconfig, type, tag, owner, clock),
+ device_t(mconfig, SBUS, tag, owner, clock),
device_memory_interface(mconfig, *this),
m_maincpu(*this, finder_base::DUMMY_TAG),
m_type1space(*this, finder_base::DUMMY_TAG, -1)
diff --git a/docs/source/usingmame/assetsearch.rst b/docs/source/usingmame/assetsearch.rst
new file mode 100644
index 00000000000..a8002db1c69
--- /dev/null
+++ b/docs/source/usingmame/assetsearch.rst
@@ -0,0 +1,402 @@
+.. _assetsearch:
+
+How does MAME look for files?
+=============================
+
+.. contents:: :local:
+
+Introduction
+------------
+
+Unlike typical desktop applications where you browse your disk and select a file
+to open or a location to save to, MAME has settings to tell it where to look for
+the files it needs. You can change these settings by starting MAME without
+specifying a system, selecting **Configure Options** from the system selection
+menu, and then selecting **Configure Directories** (remember to select **Save
+Configuration** if you want to keep your changes). You can also change settings
+by editing your mame.ini and ui.ini files directly, or specify settings on the
+command line. For information on available options for controlling where MAME
+searches for files, see :ref:`mame-commandline-pathoptions`.
+
+Terminology
+~~~~~~~~~~~
+
+It’s necessary to understand some MAME-specific terminology used in the
+explanations here:
+
+System
+ A system is a complete machine that can be emulated by MAME. Some systems
+ run fixed software, while others can load software from software list items
+ and/or media files.
+Device
+ An emulated component that can be used by multiple systems, or by other
+ devices. Some devices require ROM dumps, and some devices allow software
+ from additional software lists to be used with a system.
+Parent system
+ MAME uses so-called parent/clone relationships to group related systems.
+ One system in the group is chosen to be the *parent* and the others are
+ called *clones*. (The choice of the parent system is somewhat arbitrary.
+ It is not necessarily the original or definitive variant.)
+BIOS system
+ A system configured with no software. This is mostly applicable for arcade
+ systems that used interchangeable game cartridges or ROM boards. Note that
+ this is *not* the same as the BIOS selection settings that allow you to
+ select system boot ROMs or device firmware.
+Software item
+ A software package described in a software list. Software items may consist
+ of multiple *parts* that can be mounted independently. Due to the large
+ variety of media supported by MAME, software parts may use different
+ *loaders*. These include the *ROM loader*, typically used for cartridge
+ media, and the *image file loader*, used for software parts consisting of a
+ single media image (including floppy disk and cassette media).
+Parent software item
+ Related software items are grouped using parent/clone relationships, in a
+ similar way to related systems. This is usually used to group different
+ versions or releases of the same piece of software. If a software item has
+ a parent item, it will always be in the same software list.
+Short name
+ MAME uses *short names* to uniquely identify systems and devices, to
+ uniquely identify software lists, to uniquely identify software items within
+ a software list, and to uniquely identify software parts within a software
+ item.
+
+ You can see the short name for a system by highlighting it in the system
+ selection menu, ensuring the info panel is visible on the right, and
+ showing the **General Info** in the **Infos** tab. For example the short
+ name for the Nintendo Virtual Boy is ``vboy``. System and device short
+ names can also be seen in the output of various command line verbs,
+ including ``-listxml``, ``-listfull``, ``-listroms`` and ``-listcrc``.
+
+ You can see the short names for a software item and the software list it
+ belongs to by highlighting it in the software selection menu, ensuring the
+ info panel is visible on the right, and showing the **Software List Info**
+ in the **Infos** tab. For example the short name for Macintosh System
+ Software 6.0.3 is ``sys603`` and the short name of the software list it
+ belongs to is ``mac_flop``. Software list short names match their file
+ names (for example the Sega Mega Drive/Genesis cartridge software list is
+ called **megadriv.xml** and its short name is ``megadriv``). You can also
+ see the short names software lists, software items and parts by finding the
+ ``name`` attributes in the XML software list files.
+
+
+Search path options
+-------------------
+
+Most options for specifying locations to search allow multiple directories to be
+specified, separated by semicolon (``;``) characters. Environment variables are
+expanded, using CMD shell syntax on Windows, or Bourne shell syntax on UNIX-like
+systems.
+
+Relative paths are interpreted relative to the current working directory at the
+time of use. If you start MAME by double-clicking it in Windows Explorer, the
+working directory is set to the folder containing the MAME executable. If you
+start MAME by double-clicking it in the macOS Finder or from most Linux desktop
+environments, the working directory will be set to your home directory.
+
+
+Archive files
+-------------
+
+MAME can load files from PKZIP and 7-Zip archives (these must have ``.zip`` and
+``.7z`` file name extensions, respectively). A number of extensions to the
+PKZIP format are supported, including Zip64 for large archives, NTFS timestamps,
+and LZMA compression. Only ASCII or UTF-8 filenames are supported in PKZIP
+archives (7-Zip archives always use UTF-16 filenames).
+
+MAME *does not* load files from nested archives. MAME will not load files
+stored in a PKZIP or 7-Zip archive which is itself contained within a PKZIP or
+7-Zip archive. Multi-segment archives and encrypted archives are not supported.
+The legacy “implode” compression method in PKZIP archives is not supported.
+
+MAME may perform poorly with archives containing large numbers of files. Files
+compressed using the LZMA compression algorithm are inherently more
+CPU-intensive to decompress than files compressed using simpler algorithms.
+MAME does not take the archive layout into consideration when loading files from
+archives, so using “solid compression” often results in MAME decompressing the
+same data repeatedly when loading media.
+
+
+How does MAME search for media?
+-------------------------------
+
+Use the :ref:`rompath <mame-commandline-rompath>` option sets the folders where
+searches for ROM dumps, disk images, and other media. By default MAME looks for
+media in a folder called **roms** in the working directory. For the purpose of
+this discussion, floppy disk, cassette, paper tape and other media images that
+are not stored in CHD format are treated as ROM dumps.
+
+When searching for system, device and software ROM dumps, MAME treats folders
+and archives inside the folders configured in you ``rompath`` setting as
+equivalent, but remember the limitation that MAME cannot load files from an
+archive contained within another archive. MAME looks for a folder first, then a
+PKZIP archive, and finally a 7-Zip archive. When searching for a ROM dump in an
+archive, MAME first looks for a file with the expected name and CRC. If no
+matching file is found, MAME looks for a file with the expected CRC ignoring the
+name. If no matching file is found, MAME finally looks for a file with the
+expected name, ignoring the CRC.
+
+While MAME can load disk images in CHD format from inside archives, this is not
+recommended. CHD files contain compressed data stored in a format allowing
+random access. If a CHD format disk image is stored in a PKZIP or 7-Zip
+archive, MAME needs to load the entire file into memory in order to use it. For
+hard disk or LaserDisc images in particular, this will likely use an excessive
+amount of swap file space, hurting performance and possibly reducing the life
+expectancy of your disks or SSDs. It’s best to keep CHD format disk images in
+folders.
+
+System ROMs
+~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for system
+ROMs in the following locations:
+
+* A folder or archive matching the short name of the system itself.
+* A folder or archive matching the short name of the system’s parent system, if
+ applicable.
+* A folder or archive matching the short name of the corresponding BIOS system,
+ if applicable.
+
+Using Shiritsu Justice Gakuen as an example, MAME will search for system ROMs as
+follows:
+
+* The short name of the system is ``jgakuen``, so MAME will look for a folder
+ called **jgakuen**, a PKZIP archive called **jgakuen.zip**, or a 7-Zip archive
+ called **jgakuen.7z**.
+* The parent system is the European version of Rival Schools, which has the
+ short name ``rvschool``, so MAME will look for a folder called **rvschool**, a
+ PKZIP archive called **rvschool.zip**, or a 7-Zip archive called
+ **rvschool.7z**.
+* The corresponding BIOS system is the Capcom ZN2 board, which has the short
+ name ``coh3002c``, so MAME will look for a folder called **coh3002c**, a PKZIP
+ archive called **coh3002c.zip**, or a 7-Zip archive called **coh3002c.7z**.
+
+Device ROMs
+~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for device
+ROMs in the following locations:
+
+* A folder or archive matching the short name of the device.
+* A folder or archive matching the short name of the device’s parent ROM device,
+ if applicable.
+* A folder or archive matching the short name of the system.
+* A folder or archive matching the short name of the system’s parent system, if
+ applicable.
+* A folder or archive matching the short name of the corresponding BIOS system,
+ if applicable.
+
+Using a Unitron 1024 Macintosh clone with a French Macintosh Plus keyboard with
+integrated numeric keypad attached as an example, MAME will look for the
+keyboard microcontroller ROM as follows:
+
+* The short name of the French Macintosh Plus keyboard is ``mackbd_m0110a_f``,
+ so MAME will look for a folder called **mackbd_m0110a_f**, a PKZIP archive
+ called **mackbd_m0110a_f.zip**, or a 7-Zip archive called
+ **mackbd_m0110a_f.7z**.
+* The parent ROM device is the U.S. Macintosh Plus keyboard with integrated
+ numeric keypad, whcih has the short name ``mackbd_m0110a``, so MAME will look
+ for a folder called **mackbd_m0110a**, a PKZIP archive called
+ **mackbd_m0110a.zip**, or a 7-Zip archive called **mackbd_m0110a.7z**.
+* The short name of the Unitron 1024 system is ``utrn1024``, so MAME will look
+ for a folder called **utrn1024**, a PKZIP archive called **utrn1024.zip**, or
+ a 7-Zip archive called **utrn1024.7z**.
+* The parent system of the Unitron 1024 is the Macintosh Plus, which has the
+ short name ``macplus``, so MAME will look for a folder called **macplus**, a
+ PKZIP archive called **macplus.zip**, or a 7-Zip archive called
+ **macplus.7z**.
+* There is no corresponding BIOS system, so MAME will not search in any further
+ locations.
+
+Software Item ROMs
+~~~~~~~~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for software
+item ROMs in the following locations:
+
+* A folder or archive matching the short name of the software item inside a
+ folder matching the short name of the software list (or a folder matching the
+ short name of the software item inside an archive matching the name of the
+ software list).
+* A folder or archive matching the short name of the parent software item inside
+ a folder matching the short name of the software list, if applicable (or a
+ folder matching the short name of the parent software item in an archive
+ matching the name of the software list).
+* A folder or archive matching the short name of the software item. (This is
+ for convenience for software items that also run as stand-alone systems with
+ the same short name, such as Neo Geo games.)
+* A folder or archive matching the short name of the parent software item, if
+ applicable. (This is for convenience for software items that also run as
+ stand-alone systems with the same short name, such as Neo Geo games.)
+* Any folders and archives that would be searched for system or device ROMs for
+ the system or device that the software list belongs to. This is for
+ historical reasons due to the way software list support was originally added
+ to MESS and will be removed in a future version of MAME.
+
+If you load the German version of Dune II from the Mega Drive/Genesis cartridge
+software list in the PAL Mega Drive console, MAME will look for the cartridge
+ROM as follows:
+
+* The short name of the software item for the German version of Dune II is
+ ``dune2g`` and the short name of the Mega Drive/Genesis cartridge software
+ list is ``megadriv``, so MAME will look for a folder called **dune2g**, a
+ PKZIP archive called **dune2g.zip** or a 7-Zip archive called **dune2g.7z**
+ inside a folder called **megadriv** (or a folder called **dune2g** inside a
+ PKZIP archive called **megadriv.zip** or a 7-Zip archive called
+ **megadriv.7z**).
+* The parent software item is the general European PAL version of Dune II in the
+ same software list, which has the short name ``dune2``, so MAME will look for
+ a folder called **dune2**, a PKZIP archive called **dune2.zip** or a 7-Zip
+ archive called **dune2.7z** inside a folder called **megadriv** (or a folder
+ called **dune2** inside a PKZIP archive called **megadriv.zip** or a 7-Zip
+ archive called **megadriv.7z**).
+* Next MAME will ignore the short name of the software list and use the short
+ name of the software item only, looking for a folder called **dune2g**, a
+ PKZIP archive called **dune2g.zip** or a 7-Zip archive called **dune2g.7z**.
+* Still ignoring the short name of the software list, MAME will use the short
+ name of the parent software item only, looking for a folder called **dune2**,
+ a PKZIP archive called **dune2.zip** or a 7-Zip archive called **dune2.7z**.
+* The short name of the PAL Mega Drive system is ``megadriv``, so MAME will look
+ for a folder called **megadriv**, a PKZIP archive called **megadriv.zip**, or
+ a 7-Zip archive called **megadriv.7z**.
+* The parent system of the PAL Mega Drive is the North American Genesis system,
+ which has the short name ``genesis``, so MAME will look for a folder called
+ **genesis**, a PKZIP archive called **genesis.zip**, or a 7-Zip archive called
+ **genesis.7z**.
+
+CHD format disk images
+~~~~~~~~~~~~~~~~~~~~~~
+
+MAME searches for system, device and software item CHD format disk images in
+almost the same way it searches for ROMs, with just a few differences:
+
+* For systems and software items, MAME will check the parent system or software
+ item if applicable for alternate names for a disk image with the same content
+ digest. This allows you to keep a single copy of a CHD format disk image for
+ a parent system or software item and any clones that expect a disk image with
+ the same content, irrespective of the name the clones expect.
+* For software items, MAME will look for CHD format disk images in a folder
+ matching the short name of the software list. This is for convenience when
+ all items in a software list only contain a single CHD format disk image each.
+* We recommend that you *do not* store CHD format disk images inside PKZIP or
+ 7-Zip archives. However, if you do decide to do this, MAME will only find CHD
+ format disk images inside archives with an expected name. This is because
+ MAME uses the content digest from the CHD header, not the checksum of the CHD
+ file itself. The checksum of the CHD file itself can vary depending on
+ compression options.
+
+Loose software
+~~~~~~~~~~~~~~
+
+Many systems support loading media from a file by supplying the path on the
+command line for one of the media options. Relative paths are interpreted
+relative to the current working directory.
+
+You can specify a path to a file inside a PKZIP or 7-Zip archive similarly to
+specifying a path to a file in a folder (keep in mind that you can have at most
+a single archive file in a path, as MAME does not support loading files from
+archives contained within other archives). If you specify a path to a PKZIP or
+7-Zip archive, MAME will use the first file found in the archive (this depends
+on the order that files are stored in the archive – it’s most useful for
+archives containing a single file).
+
+Start the Nintendo Entertainment System/Famicom system with the file
+**amazon_diet_EN.nes** mounted in the cartridge slot:
+
+.. code-block:: bash
+
+ mame nes -cart amazon_diet_EN.nes
+
+Start the Osborne-1 system with the first file in the archive **os1xutls.zip**
+mounted in the first floppy disk drive:
+
+.. code-block:: bash
+
+ mame osborne1 -flop1 os1xutils.zip
+
+Start the Macintosh Plus system with the file **system tools.img** in the
+archive **sys603.zip** mounted in the first floppy disk drive:
+
+.. code-block:: bash
+
+ mame macplus -flop1 "sys603.zip/system tools.img"
+
+Diagnosing missing media
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When starting a system from MAME’s system selection menu or software selection
+menu, MAME will list any missing system or device ROM dumps or disk images, as
+long as at least one ROM dump or disk image for the system is present. For
+clone systems, at least one ROM dump or disk image *unique to the clone* must be
+present for MAME to list missing ROM dumps and disk images.
+
+If all system and device ROM dump and disk images are present and the system is
+being started with a software item, MAME will check that ROM dumps and disk
+images for the software item are present. If at least one ROM dump or disk
+image for the software item is present, MAME will list any missing ROM dumps or
+disk images.
+
+For example if you try to start the Macintosh Plus system and the keyboard
+microcontroller ROM dump is missing, MAME displays the following error message:
+
+ Required ROM/disk images for the selected system are missing or incorrect.
+ Please acquire the correct files or select a different system.
+
+ 341-0332-a.bin (mackbd_m0110a) - not found
+
+ Press any key to continue.
+
+The name of the missing ROM dump is shown (**341-0332-a.bin**), as well as the
+short name of the device it belongs to (``mackbd_m0110a``). When a missing ROM
+dump or disk image is not specific to the selected system, the short name of the
+system or device it belongs to is shown.
+
+If you start a system in MAME from a command prompt, MAME will show where it
+searched for any ROM dumps or disk images that were not found.
+
+Using the example of a Unitron 1024 Macintosh clone with a French keyboard
+connected, MAME will show the following error messages if no ROMs are present::
+
+ mame utrn1024 -kbd frp
+ 342-0341-a.u6d NOT FOUND (tried in utrn1024 macplus)
+ 342-0342-a.u8d NOT FOUND (tried in utrn1024 macplus)
+ 341-0332-a.bin NOT FOUND (tried in mackbd_m0110a_f mackbd_m0110a utrn1024 macplus)
+
+MAME used the system short name ``utrn1024`` and the parent system short name
+``macplus`` when searching for system ROMs. When searching for the keyboard
+microcontroller ROM, MAME used the device short name ``mackbd_m0110a_f``, the
+parent ROM device short name ``mackbd_m0110a``, the system short name
+``utrn1024``, and the parent system short name ``macplus``.
+
+Software parts that use the ROM loader (typically cartridge media) show similar
+messages when ROM dumps are not found. Using the example of the German version
+of Dune II on a PAL Mega Drive, MAME will show the following error messages if
+no ROMs are present::
+
+ mame megadriv dune2g
+ mpr-16838-f.u1 NOT FOUND (tried in megadriv\dune2g megadriv\dune2 dune2g dune2 megadriv genesis)
+ Fatal error: Required files are missing, the machine cannot be run.
+
+MAME searched for the cartridge ROM using:
+
+* The software list short name ``megadriv`` and the software item short name
+ ``dune2g``.
+* The software list short name ``megadriv`` and the parent software item short
+ name ``dune2``.
+* The software item short name ``dune2g`` only.
+* The parent software item short name ``dune2`` only.
+* The locations that would be searched for the PAL Mega Drive system (the system
+ short name ``megadriv`` and the parent system short name ``genesis``).
+
+Software parts that use the image file loader (including floppy disk and
+cassette media) only check for media after ROM images are loaded, and missing
+media files are shown differently. Using the example of Macintosh System 6.0.3,
+MAME will show these error messages if the software is missing::
+
+ mame macplus -flop1 sys603:flop1
+ :fdc:0:35dd: error opening image file system tools.img: No such file or directory (generic:2) (tried in mac_flop\sys603 sys603 macplus)
+ Fatal error: Device Apple/Sony 3.5 DD (400/800K GCR) load (-floppydisk1 sys603:flop1) failed: No such file or directory
+
+The error messages show where MAME searched for the image file in the same
+format. In this case, it used the software list short name ``mac_flop`` and the
+software short name ``sys603``, the software short name ``sys603`` only, and
+the locations that would be searched for system ROMs.
diff --git a/docs/source/usingmame/defaultkeys.rst b/docs/source/usingmame/defaultkeys.rst
index d66c6556a4a..08cf7b30184 100644
--- a/docs/source/usingmame/defaultkeys.rst
+++ b/docs/source/usingmame/defaultkeys.rst
@@ -35,8 +35,8 @@ and saving/loading save states.
If you are running with -debug, this key sends a ‘break’ in emulation.
- When the on-screen display is visible, you can use the following
- keys to control it:
+ When a slider control is visible, you can use the following keys to control
+ it:
* **Up** - select previous parameter to modify.
* **Down** - select next parameter to modify.
@@ -115,8 +115,10 @@ and saving/loading save states.
* **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.
- * **0** - restore the default number of tiles per row.
+ * **-**/**+** - increase/decrease the number of tiles per row (hold Shift to
+ restrict to integer scale factors).
+ * **0** - restore the default number of tiles per row (hold Shift to
+ restrict to integer scale factors).
* **Enter** - switch to tilemap viewer.
Tilemap mode:
diff --git a/docs/source/usingmame/index.rst b/docs/source/usingmame/index.rst
index e1a2ae8f5b1..615d3f34c4b 100644
--- a/docs/source/usingmame/index.rst
+++ b/docs/source/usingmame/index.rst
@@ -13,6 +13,7 @@ documentation for your platform of choice.
ui
defaultkeys
mamemenus
+ assetsearch
frontends
aboutromsets
commonissues
diff --git a/docs/source/usingmame/usingmame.rst b/docs/source/usingmame/usingmame.rst
index f808199cb52..9a66bc814c4 100644
--- a/docs/source/usingmame/usingmame.rst
+++ b/docs/source/usingmame/usingmame.rst
@@ -79,8 +79,8 @@ gives a basic summary of command line options for MAME, as explained above.
**mame.exe -showusage**
gives you the (quite long) list of available command line options for MAME.
-The main options are described, in the :ref:`universal-command-line` section of
-this manual.
+The main options are described, in the :ref:`mame-commandline-universal` section
+of this manual.
**mame.exe -showconfig**
@@ -88,9 +88,10 @@ this manual.
gives you a (quite long) list of available configuration options for MAME.
These optons can always be modified at command line, or by editing them in
mame.ini which is the main configuration file for MAME. You can find a
-description of some configuration options in the :ref:`universal-command-line`
-section of the manual (in most cases, each configuration option has a
-corresponding command line option to configure and modify it).
+description of some configuration options in the
+:ref:`mame-commandline-universal` section of the manual (in most cases, each
+configuration option has a corresponding command line option to configure and
+modify it).
**mame.exe -createconfig**
diff --git a/docs/source/whatis.rst b/docs/source/whatis.rst
index 6f6f772e480..ccc1643fa1c 100644
--- a/docs/source/whatis.rst
+++ b/docs/source/whatis.rst
@@ -19,7 +19,7 @@ that were its initial focus.
|
| **MAME®**
-| **Copyright © 1997-2021 Nicola Salmoria and the MAME team**
+| **Copyright © 1997-2022 Nicola Salmoria and the MAME team**
| **MAME is a registered trademark of Gregory Ember**
|