summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/_templates/versions.html13
-rw-r--r--docs/source/advanced/ctrlr_config.rst64
-rw-r--r--docs/source/commandline/commandline-all.rst101
-rw-r--r--docs/source/commandline/commandline-index.rst7
-rw-r--r--docs/source/commandline/sdlconfig.rst29
-rw-r--r--docs/source/conf.py6
-rw-r--r--docs/source/contributing/index.rst19
-rw-r--r--docs/source/debugger/exceptionpoint.rst74
-rw-r--r--docs/source/debugger/general.rst21
-rw-r--r--docs/source/initialsetup/compilingmame.rst162
-rw-r--r--docs/source/license.rst2
-rw-r--r--docs/source/luascript/ref-common.rst6
-rw-r--r--docs/source/luascript/ref-core.rst8
-rw-r--r--docs/source/luascript/ref-devices.rst49
-rw-r--r--docs/source/luascript/ref-input.rst10
-rw-r--r--docs/source/luascript/ref-render.rst75
-rw-r--r--docs/source/techspecs/audio_effects.rst147
-rw-r--r--docs/source/techspecs/cpu_device.rst229
-rw-r--r--docs/source/techspecs/device_sound_interface.rst318
-rw-r--r--docs/source/techspecs/index.rst5
-rw-r--r--docs/source/techspecs/layout_files.rst18
-rw-r--r--docs/source/techspecs/layout_script.rst97
-rw-r--r--docs/source/techspecs/m6502.rst4
-rw-r--r--docs/source/techspecs/memory.rst156
-rw-r--r--docs/source/techspecs/osd_audio.rst348
-rw-r--r--docs/source/techspecs/uml_instructions.rst1582
-rw-r--r--docs/source/tools/castool.rst4
-rw-r--r--docs/source/tools/chdman.rst457
-rw-r--r--docs/source/tools/floptool.rst4
-rw-r--r--docs/source/tools/imgtool.rst6
-rw-r--r--docs/source/tools/index.rst16
-rw-r--r--docs/source/tools/othertools.rst16
-rw-r--r--docs/source/usingmame/defaultkeys.rst57
-rw-r--r--docs/source/usingmame/mamemenus.rst120
-rw-r--r--docs/source/usingmame/ui.rst30
-rw-r--r--docs/source/whatis.rst2
36 files changed, 3991 insertions, 271 deletions
diff --git a/docs/source/_templates/versions.html b/docs/source/_templates/versions.html
index 3e5e6a020af..e4d2ae4731a 100644
--- a/docs/source/_templates/versions.html
+++ b/docs/source/_templates/versions.html
@@ -1,14 +1,7 @@
{% if mamedev_site %}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Downloads') }}">
- <span class="rst-current-version" data-toggle="rst-current-version">
- <span class="fa fa-book">Downloads</span>
- <span class="fa fa-caret-down"></span>
- </span>
- <div class="rst-other-versions">
- <dl>
- <dd><a href="https://docs.mamedev.org/_files/MAME.pdf">PDF</a></dd>
- <dd><a href="https://docs.mamedev.org/_files/MAME.epub">EPUB</a></dd>
- </dl>
- </div>
+ <span class="rst-current-version" data-toggle="rst-current-version">
+ Download documentation as <a href="https://docs.mamedev.org/_files/MAME.pdf">PDF</a> or <a href="https://docs.mamedev.org/_files/MAME.epub">EPUB</a>
+ </span>
</div>
{% endif %}
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst
index 7fb531b604c..13ffa34b050 100644
--- a/docs/source/advanced/ctrlr_config.rst
+++ b/docs/source/advanced/ctrlr_config.rst
@@ -20,18 +20,20 @@ arcade-style controllers.
Controller configuration files are an XML application, using the ``.cfg``
filename extension. MAME searches for controller configuration files in the
-directories specified using the ``ctrlrpath`` option. A controller
-configuration file is selected by setting the ``ctrlr`` option to its filename,
-excluding the ``.cfg`` extension (e.g. set the ``ctrlr`` option to
-``scorpionxg`` to use **scorpionxg.cfg**). It is an error if the specified
-controller configuration file does not exist, or if it contains no sections
-applicable to the emulated system.
+directories specified using the :ref:`ctrlrpath <mame-commandline-ctrlrpath>`
+option. A controller configuration file is selected by setting the ``ctrlr``
+option to its filename, excluding the ``.cfg`` extension (e.g. set the ``ctrlr``
+option to ``scorpionxg`` to use **scorpionxg.cfg**). It is an error if the
+specified controller configuration file does not exist, or if it contains no
+sections applicable to the emulated system.
Controller configuration files use implementation-dependent input tokens. The
values available and their precise meanings depend on the exact version of MAME
used, the input devices connected, the selected input provider modules
-(``keyboardprovider``, ``mouseprovider``, ``lightgunprovider`` and
-``joystickprovider`` options), and possibly other settings.
+(:ref:`keyboardprovider <mame-commandline-keyboardprovider>`,
+:ref:`mouseprovider <mame-commandline-mouseprovider>`, :ref:`lightgunprovider
+<mame-commandline-lightgunprovider>` and :ref:`joystickprovider
+<mame-commandline-joystickprovider>` options), and possibly other settings.
.. _ctrlrcfg-structure:
@@ -71,8 +73,10 @@ with a ``version`` attribute specifying the configuration format version
(currently ``10`` – MAME will not load a file using a different version). The
``mameconfig`` element contains one or more ``system`` elements, each of which
has a ``name`` attribute specifying the system(s) it applies to. Each
-``system`` element contains an ``input`` element which holds the actual
+``system`` element may contain an ``input`` element which holds the actual
``remap`` and ``port`` configuration elements, which will be described later.
+Each ``system`` element may also contain a ``pointer_input`` element to set
+pointer input options for systems with interactive artwork.
When launching an emulated system, MAME will apply configuration from ``system``
elements where the value of the ``name`` attribute meets one of the following
@@ -261,3 +265,45 @@ MAME applies ``mapdevice`` elements found inside the first applicable ``system``
element only. To avoid confusion, it’s simplest to place the ``system`` element
applying to all systems (``name`` attribute set to ``default``) first in the
file, and use it to assign input device numbers.
+
+
+.. _ctrlrcfg-pointers:
+
+Setting pointer input options
+-----------------------------
+
+A ``pointer_input`` element may contain ``target`` elements to set pointer input
+options for each output screen or window. Each ``target`` element must have an
+``index`` attribute containing the zero-based index of the screen to which it
+applies.
+
+Each ``target`` element may have an ``activity_timeout`` attribute to set the
+time after which a mouse pointer that has not moved and has no buttons pressed
+will be considered inactive. The value is specified in seconds, and must be in
+the range of 0.1 seconds to 10 seconds, inclusive.
+
+Each ``target`` element may have a ``hide_inactive`` element to set whether
+inactive pointers may be hidden. If the value is ``0`` (zero), inactive
+pointers will not be hidden. If the value is ``1``, inactive pointers may be
+hidden, but layout views can still specify that inactive pointers should not be
+hidden.
+
+Here’s an example demonstrating the use of this feature:
+
+.. code-block:: XML
+
+ <system name="default">
+ <pointer_input>
+ <target index="0" activity_timeout="1.5" />
+ </pointer_input>
+ </system>
+ <system name="intellec4.cpp">
+ <pointer_input>
+ <target index="0" hide_inactive="0" />
+ </pointer_input>
+ </system>
+
+For all systems, pointers over the first output screen or window will be
+considered inactive after not moving for 1.5 seconds with no buttons pressed.
+For systems defined in ``intellec4.cpp``, inactive pointers over the first
+window will not be hidden.
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index b2cd5ad2c64..9f058e10dff 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -775,24 +775,24 @@ OSD-related Options
* - **Microsoft Windows**
- win
- dwrite
- - none
- auto
-
- - sdl [#UIFPSDLWindows]_.
+ - sdl [#UIFPSDLWindows]_
+ - none
* - **macOS**
-
-
- - none
- auto
- osx
- sdl
+ - none
* - **Linux**
-
-
- - none
- auto
-
- sdl
+ - none
.. rubric:: Footnotes
@@ -816,26 +816,19 @@ Example:
:stub-columns: 0
* - **Microsoft Windows**
- - auto [#KBIPAutoWindows]_.
+ - auto [#KBIPAutoWindows]_
- rawinput
- dinput
- win32
+ - sdl [#KBIPSDLWindows]_
- none
- - sdl [#KBIPSDLWindows]_.
* - **SDL (macOS and Linux)**
- - auto [#KBIPAutoSDL]_.
+ - auto [#KBIPAutoSDL]_
-
-
-
- - none
- sdl
- * - **Linux**
- - auto [#KBIPAutoSDL]_.
- -
- -
- -
- none
- - sdl
.. rubric:: Footnotes
@@ -868,26 +861,19 @@ Example:
:stub-columns: 0
* - **Microsoft Windows**
- - auto [#MIPAutoWindows]_.
+ - auto [#MIPAutoWindows]_
- rawinput
- dinput
- win32
+ - sdl [#MIPSDLWindows]_
- none
- - sdl [#MIPSDLWindows]_.
* - **SDL (macOS and Linux)**
- - auto [#MIPAutoSDL]_.
+ - auto [#MIPAutoSDL]_
-
-
-
- - none
- sdl
- * - **Linux**
- - auto [#MIPAutoSDL]_.
- -
- -
- -
- none
- - sdl
.. rubric:: Footnotes
@@ -916,36 +902,37 @@ Example:
:stub-columns: 0
* - **Microsoft Windows**
- - auto [#LGIPAutoWindows]_.
+ - auto [#LGIPAutoWindows]_
- rawinput
- win32
- - none
- -
+ - sdl [#LGIPSDLWindows]_
-
+ - none
* - **macOS**
- - auto [#LGIPAutoSDL]_.
- -
+ - auto [#LGIPAutoSDL]_
-
- - none
-
+ - sdl
-
+ - none
* - **Linux**
- - auto [#LGIPAutoLinux]_.
+ - auto [#LGIPAutoSDL]_
-
-
- - none
- -
+ - sdl
- x11
+ - none
.. rubric:: Footnotes
.. [#LGIPAutoWindows] On Windows, auto will try ``rawinput`` with fallback to
``win32``, or ``none`` if it doesn't find any.
-.. [#LGIPAutoSDL] On non-Linux SDL, ``auto`` will default to ``none``.
+.. [#LGIPSDLWindows] SDL support on Windows requires that you compile MAME with
+ the support in. By default SDL is not included in Windows
+ builds of MAME.
-.. [#LGIPAutoLinux] On SDL/Linux, ``auto`` will default to ``x11``, or ``none``
- if it doesn't find any.
+.. [#LGIPAutoSDL] On SDL, ``auto`` will default to ``sdl``.
Example:
.. code-block:: bash
@@ -964,15 +951,15 @@ Example:
:stub-columns: 0
* - **Microsoft Windows**
- - auto [#JIPAutoWindows]_.
+ - auto [#JIPAutoWindows]_
- winhybrid
- dinput
- xinput
- - sdlgame
- - sdljoy
+ - sdlgame [#JIPSDLWindows]_
+ - sdljoy [#JIPSDLWindows]_
- none
* - **SDL**
- - auto [#JIPAutoSDL]_.
+ - auto [#JIPAutoSDL]_
-
-
-
@@ -984,6 +971,10 @@ Example:
.. [#JIPAutoWindows] On Windows native, auto will default to ``winhybrid``.
+.. [#JIPSDLWindows] SDL support on Windows requires that you compile MAME with
+ the support in. By default SDL is not included in Windows
+ builds of MAME.
+
.. [#JIPAutoSDL] On SDL, auto will default to ``sdlgame``.
winhybrid
@@ -2978,7 +2969,7 @@ Core Sound Options
**-volume** / **-vol** *<value>*
Sets the initial sound volume. It can be changed later with the user
- interface (see Keys section). The volume is an attenuation in decibels:
+ interface (see Keys section). The volume is in decibels:
e.g. "**-volume -12**" will start with -12 dB attenuation. Note that if the
volume is changed in the user interface it will be saved to the
configuration file for the system. The value from the configuration file
@@ -3686,8 +3677,9 @@ Debugging Options
Acts as a remote debugging server for the GNU debugger (GDB). Only a
small subset of the CPUs emulated by MAME are supported. Use the
:ref:`debugger_port <mame-commandline-debuggerport>` option to set the
- listening port on the loopback interface. Supported on all platforms
- with TCP socket support.
+ listening port and the
+ :ref:`debugger_host <mame-commandline-debuggerhost>` option to set the
+ address to bind to. Supported on all platforms with TCP socket support.
Example:
.. code-block:: bash
@@ -3741,11 +3733,26 @@ Debugging Options
mame ibm_5150 -watchdog 30
+.. _mame-commandline-debuggerhost:
+
+**-debugger_host** *<address>*
+
+ Set the IP address to listen on to accept GDB connections when using the
+ GDB stub debugger module (see the
+ :ref:`debugger <mame-commandline-debugger>` option).
+
+ The default is ``localhost``.
+
+ Example:
+ .. code-block:: bash
+
+ mame rfjet -debug -debugger gdbstub -debugger_host 0.0.0.0
+
.. _mame-commandline-debuggerport:
**-debugger_port** *<port>*
- Set the TCP port number to listen on for GDB connections when using the GDB
+ Set the TCP port number to accept GDB connections on when using the GDB
stub debugger module (see the :ref:`debugger <mame-commandline-debugger>`
option).
@@ -3989,7 +3996,7 @@ Core Misc Options
Specifies the type of UI to use, either ``simple`` or ``cabinet``.
- The default is Cabinet (**-ui cabinet**).
+ The default is cabinet (**-ui cabinet**).
Example:
.. code-block:: bash
@@ -4025,9 +4032,9 @@ Core Misc Options
**\-[no]ui_mouse**
- Displays a mouse cursor when using the built-in UI for MAME.
+ Displays a mouse cursor when using the built-in MAME user interface.
- The default is (**-noui_mouse**).
+ The default is ON (**-ui_mouse**).
.. _mame-commandline-language:
diff --git a/docs/source/commandline/commandline-index.rst b/docs/source/commandline/commandline-index.rst
index 50500066d6f..cb6b9a7dfb4 100644
--- a/docs/source/commandline/commandline-index.rst
+++ b/docs/source/commandline/commandline-index.rst
@@ -298,6 +298,7 @@ Core Debugging Options
| :ref:`debugscript <mame-commandline-debugscript>`
| :ref:`[no]update_in_pause <mame-commandline-updateinpause>`
| :ref:`watchdog <mame-commandline-watchdog>`
+| :ref:`debugger_host <mame-commandline-debuggerhost>`
| :ref:`debugger_port <mame-commandline-debuggerport>`
| :ref:`debugger_font <mame-commandline-debuggerfont>`
| :ref:`debugger_font_size <mame-commandline-debuggerfontsize>`
@@ -423,10 +424,12 @@ SDL Keyboard Mapping
| :ref:`keymap_file <mame-scommandline-keymapfile>`
-SDL Joystick Mapping
+SDL Input Options
~~~~~~~~~~~~~~~~~~~~
-| :ref:`sixaxis <mame-scommandline-sixaxis>`
+| :ref:`[no]enable_touch <mame-scommandline-enabletouch>`
+| :ref:`[no]sixaxis <mame-scommandline-sixaxis>`
+| :ref:`[no]dual_lightgun <mame-scommandline-duallightgun>`
SDL Lightgun Mapping
diff --git a/docs/source/commandline/sdlconfig.rst b/docs/source/commandline/sdlconfig.rst
index eea4b959e60..a6f3a7d8e51 100644
--- a/docs/source/commandline/sdlconfig.rst
+++ b/docs/source/commandline/sdlconfig.rst
@@ -61,8 +61,16 @@ SDL Keyboard Mapping
Keymap file name. Default is ``keymap.dat``.
-SDL Joystick Mapping
---------------------
+SDL Input Options
+-----------------
+
+.. _mame-scommandline-enabletouch:
+
+**-enable_touch**
+
+ Enable support for touch input. If this option is switched off, mouse input
+ simulated from touch devices will be used instead. Default is OFF
+ (**-noenable_touch**)
.. _mame-scommandline-sixaxis:
@@ -72,6 +80,23 @@ SDL Joystick Mapping
undesirable behaviour with other controllers. Only affects the ``sdljoy``
joystick provider. Default is OFF (**-nosixaxis**)
+.. _mame-scommandline-duallightgun:
+
+**-[no]dual_lightgun** / **-[no]dual**
+
+ Controls whether or not MAME attempts to track two lightguns that appear as
+ a single mouse. This option requires the :ref:`lightgun option
+ <mame-commandline-nolightgun>` to be on and the :ref:`lightgunprovider
+ option <mame-commandline-lightgunprovider>` to be set to *sdl*.
+
+ This option supports dual lightgun setups that work by setting the mouse
+ pointer location at the moment a lightgun trigger is activated. The primary
+ and secondary triggers on the first lightgun correspond to the first and
+ second mouse buttons, and the primary and secondary triggers on the second
+ lightgun correspond to the third and fourth mouse buttons.
+
+ The default is OFF (**-nodual_lightgun**).
+
SDL Lightgun Mapping
--------------------
diff --git a/docs/source/conf.py b/docs/source/conf.py
index e7f52cf5e9e..dd4277f9919 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-2023, MAMEdev and contributors'
+copyright = u'1997-2025, 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.262'
+version = '0.277'
# The full version, including alpha/beta/rc tags.
-release = '0.262'
+release = '0.277'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
index df18b248374..a3dc9e4bec9 100644
--- a/docs/source/contributing/index.rst
+++ b/docs/source/contributing/index.rst
@@ -134,11 +134,24 @@ to all kinds of changes):
steps to evade them. If you enable GitHub Actions, consider not
pushing individual commits if you don’t need them to be automatically
built, or cancelling workflow runs when you don’t need the results.
+* If your submission is a computer or other device such as a synthesizer
+ or sampler which requires a disk, tape, cartridge, or other media to
+ start up and run, please consider creating a software list containing
+ at least one example of that media. This helps everyone making changes
+ to shared MAME components to easily verify if the changes negatively
+ impact your code.
+* When submitting any new non-arcade machine, but especially a machine
+ which does not auto-boot and requires some interaction to start up
+ and be usable, consider adding usage instructions to the
+ `System-Specific Setup and Information <https://wiki.mamedev.org/index.php/System-Specific_Setup_and_Information>`_
+ page of the `MAME Wiki <https://wiki.mamedev.org>`_. Anyone can edit
+ the wiki after creating an account, and sub-pages for your system
+ which discuss technical details of the system are also welcome.
We have guidelines for specific parts of the source:
.. toctree::
- :titlesonly:
+ :titlesonly:
- cxx
- softlist
+ cxx
+ softlist
diff --git a/docs/source/debugger/exceptionpoint.rst b/docs/source/debugger/exceptionpoint.rst
index 52a8ee67a19..46ce7b8d41a 100644
--- a/docs/source/debugger/exceptionpoint.rst
+++ b/docs/source/debugger/exceptionpoint.rst
@@ -1,21 +1,21 @@
.. _debugger-exceptionpoint-list:
-Exception Point Debugger Commands
-=================================
+Exceptionpoint Debugger Commands
+================================
:ref:`debugger-command-epset`
- sets a new exception point
+ sets a new exceptionpoint
:ref:`debugger-command-epclear`
- clears a specific exception point or all exception points
+ clears a specific exceptionpoint or all exceptionpoints
:ref:`debugger-command-epdisable`
- disables a specific exception point or all exception points
+ disables a specific exceptionpoint or all exceptionpoints
:ref:`debugger-command-epenable`
- enables a specific exception point or all exception points
+ enables a specific exceptionpoint or all exceptionpoints
:ref:`debugger-command-eplist`
- lists exception points
+ lists exceptionpoints
-Exception points halt execution and activate the debugger when
-a CPU raises a particular exception number.
+Exceptionpoints halt execution and activate the debugger when a CPU
+raises a particular exception number.
.. _debugger-command-epset:
@@ -25,24 +25,24 @@ epset
**ep[set] <type>[,<condition>[,<action>]]**
-Sets a new exception point for exceptions of type **<type>**. The
+Sets a new exceptionpoint for exceptions of type **<type>**. The
optional **<condition>** parameter lets you specify an expression that
-will be evaluated each time the exception point is hit. If the result
-of the expression is true (non-zero), the exception point will actually
+will be evaluated each time the exceptionpoint is hit. If the result
+of the expression is true (non-zero), the exceptionpoint will actually
halt execution at the start of the exception handler; otherwise,
execution will continue with no notification. The optional **<action>**
-parameter provides a command that is executed whenever the exception
-point is hit and the **<condition>** is true. Note that you may need to
-embed the action within braces ``{ }`` in order to prevent commas and
-semicolons from being interpreted as applying to the ``epset`` command
-itself.
+parameter provides a command that is executed whenever the
+exceptionpoint is hit and the **<condition>** is true. Note that you
+may need to embed the action within braces ``{ }`` in order to prevent
+commas and semicolons from being interpreted as applying to the
+``epset`` command itself.
The numbering of exceptions depends upon the CPU type. Causes of
exceptions may include internally or externally vectored interrupts,
errors occurring within instructions and system calls.
-Each exception point that is set is assigned an index which can be used
-in other exception point commands to reference this exception point.
+Each exceptionpoint that is set is assigned an index which can be used
+in other exceptionpoint commands to reference this exceptionpoint.
Examples:
@@ -60,17 +60,17 @@ epclear
**epclear [<epnum>[,…]]**
-The epclear command clears exception points. If **<epnum>** is
-specified, only the requested exception points are cleared, otherwise
-all exception points are cleared.
+The epclear command clears exceptionpoints. If **<epnum>** is
+specified, only the requested exceptionpoints are cleared, otherwise
+all exceptionpoints are cleared.
Examples:
``epclear 3``
- Clear exception point index 3.
+ Clear exceptionpoint index 3.
``epclear``
- Clear all exception points.
+ Clear all exceptionpoints.
Back to :ref:`debugger-exceptionpoint-list`
@@ -82,19 +82,19 @@ epdisable
**epdisable [<epnum>[,…]]**
-The epdisable command disables exception points. If **<epnum>** is
-specified, only the requested exception points are disabled, otherwise
-all exception points are disabled. Note that disabling an exception
-point does not delete it, it just temporarily marks the exception
-point as inactive.
+The epdisable command disables exceptionpoints. If **<epnum>** is
+specified, only the requested exceptionpoints are disabled, otherwise
+all exceptionpoints are disabled. Note that disabling an
+exceptionpoint does not delete it, it just temporarily marks the
+exceptionpoint as inactive.
Examples:
``epdisable 3``
- Disable exception point index 3.
+ Disable exceptionpoint index 3.
``epdisable``
- Disable all exception points.
+ Disable all exceptionpoints.
Back to :ref:`debugger-exceptionpoint-list`
@@ -106,17 +106,17 @@ epenable
**epenable [<epnum>[,…]]**
-The epenable command enables exception points. If **<epnum>** is
-specified, only the requested exception points are enabled, otherwise
-all exception points are enabled.
+The epenable command enables exceptionpoints. If **<epnum>** is
+specified, only the requested exceptionpoints are enabled, otherwise
+all exceptionpoints are enabled.
Examples:
``epenable 3``
- Enable exception point index 3.
+ Enable exceptionpoint index 3.
``epenable``
- Enable all exception points.
+ Enable all exceptionpoints.
Back to :ref:`debugger-exceptionpoint-list`
@@ -128,7 +128,7 @@ eplist
**eplist**
-The eplist command lists all the current exception points, along with
+The eplist command lists all the current exceptionpoints, along with
their index and any conditions or actions attached to them.
Back to :ref:`debugger-exceptionpoint-list`
diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst
index cdaf9ca4019..c01ef20dea8 100644
--- a/docs/source/debugger/general.rst
+++ b/docs/source/debugger/general.rst
@@ -190,15 +190,22 @@ available:
%c
Prints the corresponding argument as an 8-bit character.
-%[0][<n>]d
+%[-][0][<n>]d
Prints the corresponding argument as a decimal number with optional
- minimum field width and zero fill.
-%[0][<n>]o
+ left justification, zero fill and minimum field width.
+%[-][0][<n>]o
Prints the corresponding argument as an octal number with optional
- minimum field width and zero fill using lowercase letters.
-%[0][<n>]x
- Prints the corresponding argument as a hexadecimal number with
- optional minimum field width and zero fill using uppercase letters.
+ left justification, zero fill and minimum field width.
+%[-][0][<n>]x
+ Prints the corresponding argument as a lowercase hexadecimal number
+ with optional left justification, zero fill and minimum field width.
+%[-][0][<n>]X
+ Prints the corresponding argument as an uppercase hexadecimal number
+ with optional left justification, zero fill and minimum field width.
+%[-][<n>][.[<n>]]s
+ Prints a null-terminated string of 8-bit characters from the address
+ and address space given by the corresponding argument, with optional
+ left justification, minimum and maximum field widths.
\%%
Prints a literal percent symbol.
\\n
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index 51c8d408fd8..a4559842b39 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -9,11 +9,11 @@ All Platforms
-------------
* To compile MAME, you need a C++17 compiler and runtime library. We
- support building with GCC version 7.2 or later and clang version 6 or
- later. MAME should run with GNU libstdc++ version 7.2 or later or
- libc++ version 7 or later. The initial release of any major version
+ support building with GCC version 10.3 or later and clang version 11
+ or later. MAME should run with GNU libstdc++ version 10.3 or later or
+ libc++ version 11 or later. The initial release of any major version
of GCC should be avoided. For example, if you want to compile MAME
- with GCC 10, you should use version 10.3 or later.
+ with GCC 12, you should use version 12.1 or later.
* Whenever you are changing build parameters, (for example changing
optimisation settings, or adding tools to the compile list), or system
@@ -86,10 +86,11 @@ Microsoft Windows
MAME for Windows is built using the MSYS2 environment. You will need Windows 7
or later and a reasonably up-to-date MSYS2 installation. We strongly recommend
building MAME on a 64-bit system. Instructions may need to be adjusted for
-32-bit systems.
+32-bit systems. Building for 64-bit ARM (AArch64) requires a 64-bit ARM system
+running Windows 11 or later.
* A pre-packaged MSYS2 installation including the prerequisites for building
- MAME can be downloaded from the `MAME Build Tools
+ MAME for 64-bit x86-64 can be downloaded from the `MAME Build Tools
<http://mamedev.org/tools/>`_ page.
* After initial installation, you can update the MSYS2 environment using the
**pacman** (Arch package manage) command.
@@ -98,7 +99,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.6 or later.
+ will need to install the MSYS2 packages for SDL 2 version 2.0.14 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.
@@ -120,20 +121,7 @@ with MSYS2 and the **pacman** package manager.
verification for this repository (``SigLevel = Never``).
* Install packages necessary to build MAME. At the very least, you’ll need
``bash``, ``git``, ``make``.
-* For 64-bit builds you’ll need ``mingw-w64-x86_64-gcc`` and
- ``mingw-w64-x86_64-python``.
-* For 32-bit builds you’ll need ``mingw-w64-i686-gcc`` and
- ``mingw-w64-i686-python``.
* For debugging you may want to install ``gdb``.
-* To link using the LLVM linker (generally much faster than the GNU linker),
- you’ll need ``mingw-w64-x86_64-lld`` and ``mingw-w64-x86_64-libc++`` for
- 64-bit builds, or ``mingw-w64-i686-lld`` and ``mingw-w64-i686-libc++`` for
- 32-bit builds.
-* To build against the portable SDL interfaces, you’ll need
- ``mingw-w64-x86_64-SDL2`` and ``mingw-w64-x86_64-SDL2_ttf`` for 64-bit builds,
- or ``mingw-w64-i686-SDL2`` and ``mingw-w64-i686-SDL2_ttf`` for 32-bit builds.
-* To build the Qt debugger, you’ll need ``mingw-w64-x86_64-qt5`` for 64-bit
- builds, or ``mingw-w64-i686-qt5`` for 32-bit builds.
* To build the HTML user/developer documentation, you’ll need
``mingw-w64-x86_64-librsvg``, ``mingw-w64-x86_64-python-sphinx``,
``mingw-w64-x86_64-python-sphinx_rtd_theme`` and
@@ -146,18 +134,53 @@ with MSYS2 and the **pacman** package manager.
``mingw-w64-x86_64-texlive-latex-extra`` and
``mingw-w64-x86_64-texlive-fonts-recommended`` (or
``mingw-w64-i686-texlive-latex-extra`` and
- ``mingw-w64-i686-texlive-fonts-recommended`` for a 32-but MinGW environment).
+ ``mingw-w64-i686-texlive-fonts-recommended`` for a 32-bit MinGW environment).
* To generate API documentation from source, you’ll need ``doxygen``.
* If you plan to rebuild bgfx shaders and you want to rebuild the GLSL parser,
you’ll need ``bison``.
-* For 64-bit builds, open **MSYS2 MinGW 64-bit** from the start menu, and set
- up the environment variables ``MINGW64`` to ``/mingw64`` and ``MINGW32`` to an
- empty string (e.g. using the command **export MINGW64=/mingw64 MINGW32=** in
- the Bash shell).
-* For 32-bit builds, open **MSYS2 MinGW 32-bit** from the start menu, and set
- up the environment variables ``MINGW32`` to ``/mingw32`` and ``MINGW64`` to an
- empty string (e.g. using the command **export MINGW32=/mingw32 MINGW64=** in
- the Bash shell).
+
+The additional packages you’ll need depend on the CPU architecture you’re
+building for.
+
+**64-bit x86-64**
+
+* You’ll need ``mingw-w64-x86_64-gcc`` and ``mingw-w64-x86_64-python``.
+* To link using the LLVM linker (generally much faster than the GNU linker),
+ you’ll need ``mingw-w64-x86_64-lld``, ``mingw-w64-x86_64-llvm`` and
+ ``mingw-w64-x86_64-libc++``.
+* To build against the portable SDL interfaces, you’ll need
+ ``mingw-w64-x86_64-SDL2`` and ``mingw-w64-x86_64-SDL2_ttf``.
+* To build the Qt debugger, you’ll need ``mingw-w64-x86_64-qt5``.
+* Open the **mingw64.exe** helper from the **msys64** installation folder or the
+ **MSYS2 MinGW 64-bit** shortcut from the start menu to start a Bash shell
+ configured with the correct paths and environment variables.
+
+**32-bit x86**
+
+* You’ll need ``mingw-w64-i686-gcc`` and ``mingw-w64-i686-python``.
+* To link using the LLVM linker (generally much faster than the GNU linker),
+ you’ll need ``mingw-w64-i686-lld``, ``mingw-w64-i686-llvm`` and
+ ``mingw-w64-i686-libc++``.
+* To build against the portable SDL interfaces, you’ll need
+ ``mingw-w64-i686-SDL2`` and ``mingw-w64-i686-SDL2_ttf``.
+* To build the Qt debugger, you’ll need ``mingw-w64-i686-qt5``.
+* Open the **mingw32.exe** helper from the **msys64** installation folder or the
+ **MSYS2 MinGW 32-bit** shortcut from the start menu to start a Bash shell
+ configured with the correct paths and environment variables.
+
+**64-bit ARM (AArch64)**
+
+* You’ll need ``mingw-w64-clang-aarch64-clang``,
+ ``mingw-w64-clang-aarch64-python`` and ``mingw-w64-clang-aarch64-gcc-compat``.
+* To link using the LLVM linker (generally much faster than the GNU linker),
+ you’ll need ``mingw-w64-clang-aarch64-lld``, ``mingw-w64-clang-aarch64-llvm``
+ and ``mingw-w64-clang-aarch64-libc++``.
+* To build against the portable SDL interfaces, you’ll need
+ ``mingw-w64-clang-aarch64-SDL2`` and ``mingw-w64-clang-aarch64-SDL2_ttf``.
+* To build the Qt debugger, you’ll need ``mingw-w64-clang-aarch64-qt5``.
+* Open the **clangarm64.exe** helper from the **msys64** installation folder to
+ start a Bash shell configured with the correct paths and environment
+ variables.
For example you could use these commands to ensure you have the packages you
need to compile MAME, omitting the ones for configurations you don’t plan to
@@ -166,12 +189,18 @@ once::
pacman -Syu
pacman -S curl git make
- pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-libc++ mingw-w64-x86_64-lld mingw-w64-x86_64-python
+ pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-python
+ pacman -S mingw-w64-x86_64-llvm mingw-w64-x86_64-libc++ mingw-w64-x86_64-lld
pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf
pacman -S mingw-w64-x86_64-qt5
- pacman -S mingw-w64-i686-gcc mingw-w64-i686-libc++ mingw-w64-i686-lld mingw-w64-i686-python
+ pacman -S mingw-w64-i686-gcc mingw-w64-i686-python
+ pacman -S mingw-w64-i686-llvm mingw-w64-i686-libc++ mingw-w64-i686-lld
pacman -S mingw-w64-i686-SDL2 mingw-w64-i686-SDL2_ttf
pacman -S mingw-w64-i686-qt5
+ pacman -S mingw-w64-clang-aarch64-clang mingw-w64-clang-aarch64-python mingw-w64-clang-aarch64-gcc-compat
+ pacman -S mingw-w64-clang-aarch64-lld mingw-w64-clang-aarch64-llvm mingw-w64-clang-aarch64-libc++
+ pacman -S mingw-w64-clang-aarch64-SDL2 mingw-w64-clang-aarch64-SDL2_ttf
+ pacman -S mingw-w64-clang-aarch64-qt5
You could use these commands to install the current version of the
mame-essentials package and add the MAME package repository to your pacman
@@ -184,9 +213,9 @@ configuration::
Building with Microsoft Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* You can generate Visual Studio 2019 projects using **make vs2019**. The
+* You can generate Visual Studio 2022 projects using **make vs2022**. The
solution and project files will be created in
- ``build/projects/windows/mame/vs2019`` by default (the name of the ``build``
+ ``build/projects/windows/mame/vs2022`` by default (the name of the ``build``
folder can be changed using the ``BUILDDIR`` option). This will always
regenerate the settings, so **REGENIE=1** is *not* needed.
* Adding **MSBUILD=1** to the make options will build the solution using
@@ -210,10 +239,10 @@ with helpful information on using the pacman package management tool.
The MSYS2 environment includes two kinds of tools: MSYS2 tools designed to work
in a UNIX-like environment on top of Windows, and MinGW tools designed to work
in a more Windows-like environment. The MSYS2 tools are installed in
-``/usr/bin`` while the MinGW tools are installed in ``/ming64/bin`` and/or
-``/mingw32/bin`` (relative to the MSYS2 installation directory). MSYS2 tools
-work best in an MSYS2 terminal, while MinGW tools work best in a Microsoft
-command prompt.
+``/usr/bin`` while the MinGW tools are installed in ``/ming64/bin``,
+``/mingw32/bin`` and/or ``/clangarm64/bin`` (relative to the MSYS2 installation
+directory). MSYS2 tools work best in an MSYS2 terminal, while MinGW tools work
+best in a Microsoft command prompt.
The most obvious symptom of this is that arrow keys don’t work in interactive
programs if you run them in the wrong kind of terminal. If you run MinGW gdb or
@@ -222,9 +251,9 @@ be possible to interrupt an attached program with gdb. Similarly it may be very
difficult to edit using MSYS2 vim in a Microsoft command prompt window.
MAME is built using the MinGW compilers, so the MinGW directories are included
-earlier in the ``PATH`` for the build environments. If you want to use an
-interactive MSYS2 program from an MSYS2 shell, you may need to type the absolute
-path to avoid using the MinGW equivalent instead.
+earlier in the ``PATH`` environment variable for the build environments. If you
+want to use an interactive MSYS2 program from an MSYS2 shell, you may need to
+type the absolute path to avoid using the MinGW equivalent instead.
MSYS2 gdb may have issues debugging MinGW programs like MAME. You may get
better results by installing the MinGW version of gdb and running it from a
@@ -233,16 +262,19 @@ Microsoft command prompt window to debug MAME.
GNU make supports both POSIX-style shells (e.g. bash) and the Microsoft cmd.exe
shell. One issue to be aware of when using the cmd.exe shell is that the
``copy`` command doesn’t provide a useful exit status, so file copy tasks can
-fail silently.
+fail silently. This may cause your build to appear to succeed while producing
+incorrect results.
It is not possible to cross-compile a 32-bit version of MAME using 64-bit MinGW
tools on Windows, the 32-bit MinGW tools must be used. This causes issues due
-to the size of MAME. It is not possible to link a full 32-bit MAME build
-including the SDL OS-dependent layer and the Qt debugger. GNU ld and lld will
-both run out of memory, leaving an output file that doesn’t work. It’s also
-impossible to make a 32-bit build with full local variable symbols. GCC may run
-out of memory, and certain source files may exceed the limit of 32,768 sections
-imposed by the PE/COFF object file format.
+to the size of MAME. It’s impossible to make a 32-bit build with full local
+variable symbols. GCC may run out of memory, and certain source files may
+exceed the limit of 32,768 sections imposed by the PE/COFF object file format.
+
+A complete build of MAME including line number symbols exceeds the size limit
+imposed by the PE file format and cannot be run. Workarounds include including
+only a subset of the systems supported by MAME or extracting symbols to a
+separate file and stripping excess symbols from the MAME executable.
.. _compiling-fedora:
@@ -251,10 +283,15 @@ Fedora Linux
------------
You’ll need a few prerequisites from your Linux distribution. Make sure you get
-SDL2 2.0.6 or later as earlier versions lack required functionality::
+SDL 2 version 2.0.14 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
+If you want to use the more efficient LLVM tools for archiving static libraries
+and linking, you’ll need to install the corresponding packages::
+
+ sudo dnf install lld llvm
+
Compilation is exactly as described above in All Platforms.
To build the HTML user/developer documentation, you’ll need Sphinx, as well as
@@ -273,7 +310,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.6 or later as earlier versions lack required functionality::
+SDL 2 version 2.0.14 or later as earlier versions lack required functionality::
sudo apt-get install git build-essential python3 libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake
@@ -299,9 +336,8 @@ Compilation is exactly as described above in All Platforms.
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.6 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also
+You’ll need a few prerequisites to get started. Make sure you’re on macOS 11.0
+Big Sur or later. You will need SDL 2 version 2.0.14 or later. 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.
@@ -317,7 +353,7 @@ package manager.
* Type **xcode-select --install** to install additional tools necessary for MAME
(also available as a package on ADC).
-Next you’ll need to get SDL2 installed.
+Next you’ll need to get SDL 2 installed.
* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the
*macOS* .dmg file
@@ -349,7 +385,7 @@ above in All Platforms.
Emscripten Javascript and HTML
------------------------------
-First, download and install Emscripten 2.0.25 or later by following the
+First, download and install Emscripten 3.1.35 or later by following the
instructions at the `official site <https://emscripten.org/docs/getting_started/downloads.html>`_.
Once Emscripten has been installed, it should be possible to compile MAME
@@ -559,6 +595,10 @@ Optional features
TOOLS
Set to **1** to build additional tools along with the emulator, including
**unidasm**, **chdman**, **romcmp**, and **srcclean**.
+EMULATOR
+ When set to **0**, the main emulator target will not be created. This is
+ intended to be used in conjunction with setting **TOOLS** to **1** to build
+ the additional tools without building the emulator.
NO_OPENGL
Set to **1** to disable building the OpenGL video output module.
NO_USE_PORTAUDIO
@@ -673,11 +713,6 @@ USE_SYSTEM_LIB_PORTMIDI
USE_SYSTEM_LIB_PORTAUDIO
Set to **1** to prefer the system installation of the PortAudio library over
the version provided with the MAME source.
-USE_BUNDLED_LIB_SDL2
- Set to **1** to prefer the version of SDL provided with the MAME source over
- the system installation. (This is enabled by default for Visual Studio and
- Android builds. For other configurations, the system installation of SDL is
- preferred.)
USE_SYSTEM_LIB_UTF8PROC
Set to **1** to prefer the system installation of the Julia utf8proc library
over the version provided with the MAME source.
@@ -754,15 +789,16 @@ the Microsoft Windows SDK, you must do one of the following:
Visual Studio project files. This will set the target Windows version to
Windows 8 (6.2). The resulting binaries may not run on earlier versions of
Windows.
-* Install the DirectX SDL and configure the **osd_windows** project to search
- the DirectX header/library paths before searching the Microsoft Windows SDK
- paths.
+* Install the `DirectX SDK <https://www.microsoft.com/en-US/download/details.aspx?id=6812>`_ (already included since Windows 8.0 SDK and
+ automatically installed with Visual Studio 2013 and later). Configure the
+ **osd_windows** project to search the DirectX header/library paths before
+ searching the Microsoft Windows SDK paths.
The MSVC compiler produces spurious warnings about potentially uninitialised
local variables. You currently need to add ``NOWERROR=1`` to the options passed
to make when generating the Visual Studio project files. This stops warnings
from being treated as errors. (MSVC seems to lack options to control which
-specific warnings are treated as error, which other compilers support.)
+specific warnings are treated as errors, which other compilers support.)
.. _compiling-unusual:
diff --git a/docs/source/license.rst b/docs/source/license.rst
index e58d21b6dea..b8fae5d341b 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-2023 MAMEDev and contributors
+ Copyright (c) 1997-2025 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/luascript/ref-common.rst b/docs/source/luascript/ref-common.rst
index c08d3676621..6a7c735951c 100644
--- a/docs/source/luascript/ref-common.rst
+++ b/docs/source/luascript/ref-common.rst
@@ -99,6 +99,12 @@ emu.add_machine_post_load_notifier(callback)
Add a callback to receive notification after the emulated system is restored
to a previously saved state. Returns a
:ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.register_sound_update(callback)
+ Add a callback to receive new samples that have been created. The samples
+ are coming from the sound devices for which the hook property has been set
+ to true. The callback gets one parameter which is a hash with device tag
+ as key and a (channel-sized) vector of (buffer-sized) vector of samples
+ in the -1..1 range.
emu.print_error(message)
Print an error message.
emu.print_warning(message)
diff --git a/docs/source/luascript/ref-core.rst b/docs/source/luascript/ref-core.rst
index f761b20f5de..ad6dc24d330 100644
--- a/docs/source/luascript/ref-core.rst
+++ b/docs/source/luascript/ref-core.rst
@@ -404,9 +404,8 @@ sound.debugger_mute (read/write)
sound.system_mute (read/write)
A Boolean indicating whether sound output is muted at the request of the
emulated system.
-sound.attenuation (read/write)
- The output volume attenuation in decibels. Should generally be a negative
- integer or zero.
+sound.volume (read/write)
+ The output volume in decibels. Should generally be a negative or zero.
sound.recording (read-only)
A Boolean indicating whether sound output is currently being recorded to a
WAV file.
@@ -587,9 +586,6 @@ driver.is_bios_root (read-only)
driver.requires_artwork (read-only)
A Boolean indicating whether the system requires external artwork to be
usable.
-driver.clickable_artwork (read-only)
- A Boolean indicating whether the system requires clickable artwork features
- to be usable.
driver.unofficial (read-only)
A Boolean indicating whether this is an unofficial but common user
modification to a system.
diff --git a/docs/source/luascript/ref-devices.rst b/docs/source/luascript/ref-devices.rst
index 1c3eabdbd2d..fe25e0b0591 100644
--- a/docs/source/luascript/ref-devices.rst
+++ b/docs/source/luascript/ref-devices.rst
@@ -67,6 +67,9 @@ manager.machine.images
manager.machine.slots
Returns a device enumerator that will iterate over
:ref:`slot devices <luascript-ref-dislot>` in the system.
+manager.machine.sounds
+ Returns a device enumerator that will iterate over
+ :ref:`sound devices <luascript-ref-disound>` in the system.
emu.device_enumerator(device, [depth])
Returns a device enumerator that will iterate over
:ref:`devices <luascript-ref-device>` in the sub-tree starting at the
@@ -624,6 +627,52 @@ image.device (read-only)
The underlying :ref:`device <luascript-ref-device>`.
+.. _luascript-ref-disound:
+
+Sound device interface
+---------------------
+
+Wraps MAME’s ``device_sound_interface`` class which is a mix-in implemented by
+devices that input and/or output sound.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.sounds[tag]
+ Gets an sound device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a slot device.
+
+Properties
+~~~~~~~~~~
+
+sound.inputs (read-only)
+ Number of sound inputs of the device.
+
+sound.outputs (read-only)
+ Number of sound outputs of the device.
+
+sound.microphone (read-only)
+ True if the device is a microphone, false otherwise
+
+sound.speaker (read-only)
+ True if the device is a speaker, false otherwise
+
+sound.io_positions[] (read-only)
+ Non-empty only for microphones and speakers, indicates the positions of
+ the inputs or outputs as (x, y, z) coordinates (e.g. [-0.2, 0.0, 1.0])
+
+sound.io_names[] (read-only)
+ Non-empty only for microphones and speakers, indicates the positions of
+ the inputs or outputs as strings (e.g. Front Left)
+
+sound.hook
+ A boolean indicating whether to tap the output samples of this device in
+ the global sound hook.
+
+sound.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+
+
.. _luascript-ref-dislot:
Slot device interface
diff --git a/docs/source/luascript/ref-input.rst b/docs/source/luascript/ref-input.rst
index 7390d46743f..f146d6c78ff 100644
--- a/docs/source/luascript/ref-input.rst
+++ b/docs/source/luascript/ref-input.rst
@@ -750,16 +750,6 @@ uiinput:reset()
Clears pending events and UI input states. Should be called when leaving a
modal state where input is handled directly (e.g. configuring an input
combination).
-uiinput:find_mouse()
- Returns host system mouse pointer X position, Y position, button state, and
- the :ref:`render target <luascript-ref-rendertarget>` it falls in. The
- position is in host pixels, where zero is at the top/left. The button state
- is a Boolean indicating whether the primary mouse button is pressed.
-
- If the mouse pointer is not over one of MAME’s windows, this may return the
- position and render target from when the mouse pointer was most recently
- over one of MAME’s windows. The render target may be ``nil`` if the mouse
- pointer is not over one of MAME’s windows.
uiinput:pressed(type)
Returns a Boolean indicating whether the specified UI input has been
pressed. The input type is an enumerated value.
diff --git a/docs/source/luascript/ref-render.rst b/docs/source/luascript/ref-render.rst
index 265e52b5016..1ebe11df3e1 100644
--- a/docs/source/luascript/ref-render.rst
+++ b/docs/source/luascript/ref-render.rst
@@ -754,6 +754,10 @@ manager.machine.video.snapshot_target
Properties
~~~~~~~~~~
+target.ui_container (read-only)
+ The :ref:`render container <luascript-ref-rendercontainer>` for drawing user
+ interface elements over this render target, or ``nil`` for hidden render
+ targets (targets that are not shown to the user directly).
target.index (read-only)
The 1-based index of the render target. This has O(n) complexity.
target.width (read-only)
@@ -810,6 +814,9 @@ Instantiation
manager.machine.render.ui_container
Gets the render container used to draw the user interface, including menus,
sliders and pop-up messages.
+manager.machine.render.targets[index].ui_container
+ Gets the render container used to draw user interface elements over a
+ particular render target.
manager.machine.screens[tag].container
Gets the render container used to draw a given screen.
@@ -1057,6 +1064,66 @@ view:set_recomputed_callback(cb)
View coordinates are recomputed in various events, including the window
being resized, entering or leaving full-screen mode, and changing the zoom
to screen area setting.
+view:set_pointer_updated_callback(cb)
+ Set a function to receive notifications when a pointer enters, moves or
+ changes button states over the view. The function must accept nine
+ arguments:
+
+ * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``).
+ * The pointer ID (a non-negative integer that will not change for the
+ lifetime of a pointer).
+ * The device ID for grouping pointers to recognise multi-touch gestures
+ (non-negative integer).
+ * Horizontal position in layout coordinates.
+ * Vertical position in layout coordinates.
+ * A bit mask representing the currently pressed buttons.
+ * A bit mask representing the buttons that were pressed in this update.
+ * A bit mask representing the buttons that were released in this update.
+ * The click count (positive for multi-click actions, or negative if a click
+ is turned into a hold or drag).
+
+ Call with ``nil`` to remove the callback.
+view:set_pointer_left_callback(cb)
+ Set a function to receive notifications when a pointer leaves the view
+ normally. The function must accept seven arguments:
+
+ * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``).
+ * The pointer ID (a non-negative integer that will not change for the
+ lifetime of a pointer). The ID may be reused for a new pointer after
+ receiving this notification.
+ * The device ID for grouping pointers to recognise multi-touch gestures
+ (non-negative integer).
+ * Horizontal position in layout coordinates.
+ * Vertical position in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ * The click count (positive for multi-click actions, or negative if a click
+ is turned into a hold or drag).
+
+ Call with ``nil`` to remove the callback.
+view:set_pointer_aborted_callback(cb)
+ Set a function to receive notifications when a pointer leaves the view
+ abnormally. The function must accept seven arguments:
+
+ * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``).
+ * The pointer ID (a non-negative integer that will not change for the
+ lifetime of a pointer). The ID may be reused for a new pointer after
+ receiving this notification.
+ * The device ID for grouping pointers to recognise multi-touch gestures
+ (non-negative integer).
+ * Horizontal position in layout coordinates.
+ * Vertical position in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ * The click count (positive for multi-click actions, or negative if a click
+ is turned into a hold or drag).
+
+ Call with ``nil`` to remove the callback.
+view:set_forget_pointers_callback(cb)
+ Set a function to receive notifications when the view should stop processing
+ pointer input. The function must accept no arguments. Call with ``nil`` to
+ remove the callback.
+
+ This can happen in a number of situations, including the view configuration
+ changing or a menu taking over input handling.
Properties
~~~~~~~~~~
@@ -1085,10 +1152,16 @@ view.bounds (read-only)
effective bounds of the view in its current configuration. The coordinates
are in view units, which are arbitrary but assumed to have square aspect
ratio.
-view.has_art
+view.has_art (read-only)
A Boolean indicating whether the view has any non-screen items, including
items that are not visible because the user has hidden the item collection
that they belong to.
+view.show_pointers (read/write)
+ A Boolean that sets whether mouse and pen pointers should be displayed for
+ the view.
+view.hide_inactive_pointers (read/write)
+ A Boolean that sets whether mouse pointers for the view should be hidden
+ after a period of inactivity.
.. _luascript-ref-renderlayitem:
diff --git a/docs/source/techspecs/audio_effects.rst b/docs/source/techspecs/audio_effects.rst
new file mode 100644
index 00000000000..12228b97444
--- /dev/null
+++ b/docs/source/techspecs/audio_effects.rst
@@ -0,0 +1,147 @@
+Audio effects
+=============
+
+.. contents:: :local:
+
+
+1. Generalities
+---------------
+
+The audio effects are effects that are applied to the sound between
+the speaker devices and the actual sound output. In the current
+implementation the effect chain is fixed (but not the effect
+parameters), and the parameters are stored in the cfg files. They are
+honestly not really designed for extensibility yet, if ever.
+
+Adding an effect requires working on four parts:
+
+* audio_effects/aeffects.* for effect object creation and "publishing"
+* audio_effects/youreffect.* for the effect implementation
+* frontend/mame/ui/audioeffects.cpp to be able to instantiate the effect configuration menu
+* frontend/mame/ui/audioyoureffect.* to implement the effect configuration menu
+
+2. audio_effects/aeffects.*
+---------------------------
+
+The audio_effect class in the aeffect sources provides three things:
+
+* an enum value to designate the effect type and which must match its
+ position in the chain (iow, the effect chain follows the enum order),
+ in the .h
+* the effect name in the audio_effect::effect_names array in the .cpp
+* the creation of a correct effect object in audio_effect::create in the .cpp
+
+
+
+3. audio_effects/youreffect.*
+-----------------------------
+
+This is where you implement the effect. It takes the shape of an
+audio_effect_youreffect class which derives from audio_effect.
+
+The methods to implement are:
+
+.. code-block:: C++
+
+ audio_effect_youreffect(u32 sample_rate, audio_effect *def);
+
+ virtual int type() const override;
+ virtual void config_load(util::xml::data_node const *ef_node) override;
+ virtual void config_save(util::xml::data_node *ef_node) const override;
+ virtual void default_changed() override;
+ virtual u32 history_size() const; // optional
+
+The constructor must pass the parameters to ``audio_effect`` and
+initialize the effect parameters. ``type`` must return the enum value
+for the effect. ``config_load`` and ``config_save`` should load or
+save the effect parameters from/to the cfg file xml tree.
+``default_changed`` is called when the parameters in ``m_default`` are
+changed and the parameters may need to be updated. ``history_size``
+allows to tell how many samples should still be available of the
+previous input frame. Note that this number must not depend on the
+parameters and only on the sample rate.
+
+An effect has a number of parameters that can come from three sources:
+
+* fixed default value
+* equivalent effect object from the default effect chain
+* user setting through the UI
+
+The first two are recognized through the value of ``m_default`` which
+gets the value of ``def`` in the constructor. When it's nullptr, the
+value to use when not set by the user is the fixed one, otherwise it's
+the one in ``m_default``.
+
+At minimum an effect should have a parameter allowing to bypass it.
+
+Managing a parameter uses four methods:
+
+* ``type param() const;`` returns the current parameter value
+* ``void set_param(type value);`` sets the current parameter value and marks it as set by the user
+* ``bool isset_param() const;`` returns true is the parameter was set by the user
+* ``void reset_param();`` resets the parameter to the default value (from m_default or fixed) and marks it as not set by the user
+
+``config_save`` must only save the user-set parameters.
+``config_load`` must retrieve the parameters that are present and mark
+them as set by the user and reset all the others.
+
+Finally the actual implementation goes into the ``apply`` method:
+
+.. code-block:: C++
+
+ virtual void apply(const emu::detail::output_buffer_flat<sample_t> &src, emu::detail::output_buffer_flat<sample_t> &dest) override;
+
+That method takes two buffers with the same number of channels and has
+to apply the effect to ``src`` to produce ``dest``. The
+``output_buffer_flat`` is non-interleaved with independant per-channel
+buffers.
+
+To make bypassing easier, the ``copy(src, dest)`` method of
+audio_effect allows to copy the samples from ``src`` to ``dest``
+without changing them.
+
+The effect application part should looks like:
+
+.. code-block:: C++
+
+ u32 samples = src.available_samples();
+ dest.prepare_space(samples);
+ u32 channels = src.channels();
+
+ // generate channels * samples results and put them in dest
+
+ dest.commit(samples);
+
+To get pointers to the buffers, one uses:
+
+.. code-block:: C++
+
+ const sample_t *source = src.ptrs(channel, source_index); // source_index must be in [-history_size()..samples-1]
+ sample_t *destination = dest.ptrw(channel, destination_index); // destination_index must be in [0..samples-1]
+
+The samples pointed by source and destination are contiguous. The
+number of channels will not change from one apply call to another, the
+number of samples will vary though. Also the call happens in a
+different thread than the main thread and also in a different thread
+than the parameter setting calls are made from.
+
+
+
+
+4. frontend/mame/ui/audioeffects.cpp
+------------------------------------
+
+Here it suffices to add a creation of the menu
+menu_audio_effect_youreffect in menu_audio_effects::handle. The menu
+effect will pick the effect names from audio_effect (in aeffect.*).
+
+
+5. frontend/mame/ui/audioyoureffect.*
+-------------------------------------
+
+This is used to implement the configuration menu for the effect. It's
+a little complicated because it needs to generate the list of
+parameters and their values, set left or right arrow flags depending
+on the possible modifications, dim them (FLAG_INVERT) when not set by
+the user, and manage the arrows and clear keys to change them. Just
+copy an existing one and change it as needed.
diff --git a/docs/source/techspecs/cpu_device.rst b/docs/source/techspecs/cpu_device.rst
new file mode 100644
index 00000000000..c21a20a4fe7
--- /dev/null
+++ b/docs/source/techspecs/cpu_device.rst
@@ -0,0 +1,229 @@
+CPU devices
+===========
+
+.. contents:: :local:
+
+
+1. Overview
+-----------
+
+CPU devices derivatives are used, unsurprisingly, to implement the
+emulation of CPUs, MCUs and SOCs. A CPU device is first a combination
+of ``device_execute_interface``, ``device_memory_interface``,
+``device_state_interface`` and ``device_disasm_interface``. Refer to
+the associated documentations when they exist.
+
+Two more functionalities are specific to CPU devices which are the DRC
+and the interruptibility support.
+
+
+2. DRC
+------
+
+TODO.
+
+
+3. Interruptibility
+-------------------
+
+3.1 Definition
+~~~~~~~~~~~~~~
+
+An interruptible CPU is defined as a core which is able to suspend the
+execution of one instruction at any time, exit execute_run, then at
+the next call of ``execute_run`` keep going from where it was. This
+includes being able to abort an issued memory access, quit
+execute_run, then upon the next call of execute_run reissue the exact
+same access.
+
+
+3.2 Implementation requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Memory accesses must be done with ``read_interruptible`` or
+``write_interruptible`` on a ``memory_access_specific`` or a
+``memory_access_cache``. The access must be done as bus width and bus
+alignment.
+
+After each access the core must test whether ``icount <= 0``. This
+test should be done after ``icount`` is decremented of the time taken
+by the access itself, to limit the number of tests. When ``icount``
+reaches 0 or less it means that the instruction emulation needs to be
+suspended.
+
+To know whether the access needs to be re-issued,
+``access_to_be_redone()`` needs to be called. If it returns true then
+the time taken by the access needs to be credited back, since it
+hasn't yet happened, and the access will need to be re-issued. The
+call to ``access_to_be_redone()`` clears the reissue flag. If you
+need to check the flag without clearing it use
+``access_to_be_redone_noclear()``.
+
+The core needs to do enough bookkeeping to eventually restart the
+instruction execution just before the access or just after the test,
+depending on the need of reissue.
+
+Finally, to indicate to the rest of the infrastructure the support, it
+must override cpu_is_interruptible() to return true.
+
+
+3.3 Example implementation with generators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To ensure decent performance, the current implementations (h8, 6502
+and 68000) use a python generator to generate two versions of each
+instruction interpreter, one for the normal emulation, and one for
+restarting the instruction.
+
+The restarted version looks like that (for a 4-cycles per access cpu):
+
+.. code-block:: C++
+
+ void device::execute_inst_restarted()
+ {
+ switch(m_inst_substate) {
+ case 0:
+ [...]
+
+ m_address = [...];
+ m_mask = [...];
+ [[fallthrough]];
+ case 42:
+ m_result = specific.read_interruptible(m_address, m_mask);
+ m_icount -= 4;
+ if(m_icount <= 0) {
+ if(access_to_be_redone()) {
+ m_icount += 4;
+ m_inst_substate = 42;
+ } else
+ m_inst_substate = 43;
+ return;
+ }
+ [[fallthrough]];
+ case 43:
+ [...] = m_result;
+ [...]
+ }
+ m_inst_substate = 0;
+ return;
+ }
+
+The non-restarted version is the same thing with the switch and the
+final ``m_inst_substate`` clearing removed.
+
+.. code-block:: C++
+
+ void device::execute_inst_non_restarted()
+ {
+ [...]
+ m_address = [...];
+ m_mask = [...];
+ m_result = specific.read_interruptible(m_address, m_mask);
+ m_icount -= 4;
+ if(m_icount <= 0) {
+ if(access_to_be_redone()) {
+ m_icount += 4;
+ m_inst_substate = 42;
+ } else
+ m_inst_substate = 43;
+ return;
+ }
+ [...] = m_result;
+ [...]
+ return;
+ }
+
+The main loop then looks like this:
+
+.. code-block:: C++
+
+ void device::execute_run()
+ {
+ if(m_inst_substate)
+ call appropriate restarted instruction handler
+ while(m_icount > 0) {
+ debugger_instruction_hook(m_pc);
+ call appropriate non-restarted instruction handler
+ }
+ }
+
+The idea is thus that ``m_inst_substate`` indicates where in an
+instruction one is, but only when an interruption happens. It
+otherwise stays at 0 and is essentially never looked at. Having two
+versions of the interpretation allows to remove the overhead of the
+switch and the end-of-instruction substate clearing.
+
+It is not a requirement to use a generator-based that method, but a
+different one which does not have unacceptable performance
+implications has not yet been found.
+
+3.4 Bus contention cpu_device interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The main way to setup bus contention is through the memory maps.
+Lower-level access can be obtained through some methods on cpu_device
+though.
+
+.. code-block:: C++
+
+ bool cpu_device::access_before_time(u64 access_time, u64 current_time) noexcept;
+
+The method ``access_before_time`` allows to try to run an access at a
+given time in cpu cycles. It takes the current time
+(``total_cycles()``) and the expected time for the access. If there
+aren't enough cycles to reach that time the remaining cycles are eaten
+and the method returns true to tell not to do the access and call the
+method again eventually. Otherwise enough cycles are eaten to reach
+the access time and false is returned to tell to do the access.
+
+
+.. code-block:: C++
+
+ bool cpu_device::access_before_delay(u32 cycles, const void *tag) noexcept;
+
+The method ``access_before_delay`` allows to try to run an access
+after a given delay. The tag is an opaque, non-nullptr value used to
+characterize the source of the delay, so that the delay is not applied
+multiple times. Similarly to the previous method cycles are eaten and
+true is returned to abort the access, false to execute it.
+
+.. code-block:: C++
+
+ void cpu_device::access_after_delay(u32 cycles) noexcept;
+
+The method ``access_after_delay`` allows to add a delay after an
+access is done. There is no abort possible, hence no return boolean.
+
+.. code-block:: C++
+
+ void cpu_device::defer_access() noexcept;
+
+The method ``defer_access`` tells the cpu that we need to wait for an
+external event. It marks the access as to be redone, and eats all the
+remaining cycles of the timeslice. The idea is then that the access
+will be retried after time advances up to the next global system
+synchronisation event (sync, timer timeout or set_input_line). This
+is the method to use when for instance waiting on a magic latch for
+data expected from scsi transfers, which happen on timer timeouts.
+
+.. code-block:: C++
+
+ void cpu_device::retry_access() noexcept;
+
+The method ``retry_access`` tells the cpu that the access will need to
+be retried, and nothing else. This can easily reach a situation of
+livelock, so be careful. It is used for instance to simulate a wait
+line (for the z80 for instance) which is controlled through
+set_input_line. The idea is that the device setting wait does the
+set_input_line and a retry_access. The cpu core, as long as the wait
+line is set just eats cycles. Then, when the line is cleared the core
+will retry the access.
+
+
+3.5 Interaction with DRC
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+At this point, interruptibility and DRC are entirely incompatible. We
+do not have a method to quit the generated code before or after an
+access. It's theorically possible but definitely non-trivial.
+
diff --git a/docs/source/techspecs/device_sound_interface.rst b/docs/source/techspecs/device_sound_interface.rst
new file mode 100644
index 00000000000..8355781effc
--- /dev/null
+++ b/docs/source/techspecs/device_sound_interface.rst
@@ -0,0 +1,318 @@
+The device_sound_interface
+==========================
+
+.. contents:: :local:
+
+
+1. The sound system
+-------------------
+
+The device sound interface is the entry point for devices that handle
+sound input and/or output. The sound system is built on the concept
+of *streams* which connect devices together with resampling and mixing
+applied transparently as needed. Microphones (audio input) and
+speakers (audio output) are specific known devices which use the same
+interface.
+
+2. Devices using device_sound_interface
+---------------------------------------
+
+2.1 Initialisation
+~~~~~~~~~~~~~~~~~~
+
+Sound streams must be created in the device_start (or
+interface_pre_start) method.
+
+.. code-block:: C++
+
+ sound_stream *stream_alloc(int inputs, int outputs, int sample_rate, sound_stream_flags flags = STREAM_DEFAULT_FLAGS);
+
+A stream is created with ``stream_alloc``. It takes the number of
+input and output channels, the sample rate and optionally flags.
+
+The sample rate can be SAMPLE_RATE_INPUT_ADAPTIVE,
+SAMPLE_RATE_OUTPUT_ADAPTIVE or SAMPLE_RATE_ADAPTIVE. In that case the
+chosen sample rate is the highest one among the inputs, outputs or
+both respectively. In case of loop, the chosen sample rate is the
+configured global sample rate.
+
+The only available non-default flag is STREAM_SYNCHRONOUS. When set,
+the sound generation method will be called for every sample
+individually. It's necessary for DSPs that run a program on every
+sample. but on the other hand it's expensive, so only to be used when
+required.
+
+Devices can create multiple streams. It's rare though. Some Yamaha
+chips should but don't. Inputs and outputs are numbered from 0 and
+arrange all streams in the order they are created.
+
+
+2.2 Sound input/output
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ virtual void sound_stream_update(sound_stream &stream);
+
+This method is required to be implemented to consume the input samples
+and/or compute the output ones. The stream to update for is passed as
+the parameter. See the streams section, specifically sample access,
+to see how to write the method.
+
+
+2.3 Stream information
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ int inputs() const;
+ int outputs() const;
+ std::pair<sound_stream *, int> input_to_stream_input(int inputnum) const;
+ std::pair<sound_stream *, int> output_to_stream_output(int outputnum) const;
+
+The method ``inputs`` returns the total number of inputs in the
+streams created by the device. The method ``outputs`` similarly
+counts the outputs. The other two methods allow to grab the stream
+and channel number for the device corresponding to the global input or
+output number.
+
+
+2.4 Gain management
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ float input_gain(int inputnum) const;
+ float output_gain(int outputnum) const;
+ void set_input_gain(int inputnum, float gain);
+ void set_output_gain(int outputnum, float gain);
+ void set_route_gain(int source_channel, device_sound_interface *target, int target_channel, float gain);
+
+ float user_output_gain() const;
+ float user_output_gain(int outputnum) const;
+ void set_user_output_gain(float gain);
+ void set_user_output_gain(int outputnum, float gain);
+
+Those methods allow to set the gain on every step of the routes
+between streams. All gains are multipliers, with default value 1.0.
+The steps are, from samples output in ``sound_stream_update`` to
+samples read in the next device's ``sound_stream_update``:
+
+* Per-channel output gain
+* Per-channel user output gain
+* Per-device user output gain
+* Per-route gain
+* Per-channel input gain
+
+The user gains must not be set from the driver, they're for use by the
+user interface (the sliders) and are saved in the game configuration.
+The other gains are for driver/device use, and are saved in save
+states.
+
+
+2.5 Routing setup
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ device_sound_interface &add_route(u32 output, const device_finder<T, R> &target, double gain, u32 channel = 0)
+ device_sound_interface &add_route(u32 output, const char *target, double gain, u32 channel = 0);
+ device_sound_interface &add_route(u32 output, device_sound_interface &target, double gain, u32 channel = 0);
+
+ device_sound_interface &reset_routes();
+
+Routes between devices, e.g. between streams, are set at configuration
+time. The method ``add_route`` must be called on the source device
+and gives the channel on the source device, the target device, the
+gain, and optionally the channel on the target device. The constant
+``ALL_OUTPUTS`` can be used to add a route from every channel of the
+source to a given channel of the destination.
+
+The method ``reset_routes`` is used to remove all the routes setup on
+a given source device.
+
+
+.. code-block:: C++
+
+ u32 get_sound_requested_inputs() const;
+ u32 get_sound_requested_outputs() const;
+ u64 get_sound_requested_inputs_mask() const;
+ u64 get_sound_requested_outputs_mask() const;
+
+Those methods are useful for devices which want to behave differently
+depending on what routes are set up on them. You get either the max
+number of requested channel plus one (which is the number of channels
+when all channels are routed, but is more useful when there are gaps)
+or a mask of use for channels 0-63. Note that ``ALL_OUTPUTS`` does
+not register any specific output or output count.
+
+
+
+3. Streams
+----------
+
+3.1 Generalities
+~~~~~~~~~~~~~~~~
+
+Streams are endpoints associated with devices and, when connected
+together, ensure the transmission of audio data between them. A
+stream has a number of inputs (which can be zero) and outputs (same)
+and one sample rate which is common to all inputs and outputs. The
+connections are set up at the machine configuration level and the sound
+system ensures mixing and resampling is done transparently.
+
+Samples in streams are encoded as sample_t. In the current
+implementation, this is a float. Nominal values are between -1 and 1,
+but clamping at the device level is not recommended (unless that's
+what happens in hardware of course) because the gain values, volume
+and effects can easily avoid saturation.
+
+They are implemented in the class ``sound_stream``.
+
+
+3.2 Characteristics
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ device_t &device() const;
+ bool input_adaptive() const;
+ bool output_adaptive() const;
+ bool synchronous() const;
+ u32 input_count() const;
+ u32 output_count() const;
+ u32 sample_rate() const;
+ attotime sample_period() const;
+
+
+3.3 Sample access
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ s32 samples() const;
+
+ void put(s32 output, s32 index, sample_t sample);
+ void put_clamp(s32 output, s32 index, sample_t sample, sample_t clamp = 1.0);
+ void put_int(s32 output, s32 index, s32 sample, s32 max);
+ void put_int_clamp(s32 output, s32 index, s32 sample, s32 maxclamp);
+ void add(s32 output, s32 index, sample_t sample);
+ void add_int(s32 output, s32 index, s32 sample, s32 max);
+ void fill(s32 output, sample_t value, s32 start, s32 count);
+ void fill(s32 output, sample_t value, s32 start);
+ void fill(s32 output, sample_t value);
+ void copy(s32 output, s32 input, s32 start, s32 count);
+ void copy(s32 output, s32 input, s32 start);
+ void copy(s32 output, s32 input);
+ sample_t get(s32 input, s32 index) const;
+ sample_t get_output(s32 output, s32 index) const;
+
+Those are the methods used to implement ``sound_stream_update``.
+First ``samples`` tells how many samples to consume and/or generate.
+The to-generate samples, if any, are pre-cleared (e.g. set to zero).
+
+Input samples are retrieved with ``get``, where ``input`` is the
+stream channel number and ``index`` the sample number.
+
+Generated samples are written with the put variants. ``put`` sets a
+sample_t in channel ``output`` at position ``index``. ``put_clamp``
+does the same but first clamps the value to +/-``clamp``. ``put_int``
+does it with an integer ``sample`` but pre-divides it by ``max``.
+``put_int_clamp`` does the same but also pre-clamps within
+-``maxclamp`` and ``maxclamp``-1, which is the normal range for a
+2-complement value.
+
+``add`` and ``add_int`` are similar but add the value of the sample to
+what's there instead of replacing. ``get_output`` gets the currently
+stored output value.
+
+``fill`` sets a range of an output channel to a given ``value``.
+``start`` tells where to start (default index 0), ``count`` how many
+(default up to the end of the buffer).
+
+``copy`` does the same as fill but gets its value from the indentical
+position in an input channel.
+
+Note that clamping should not be used unless it actually happens in
+hardware. Between gains and effects there is a fair chance saturation
+can be avoided later in the chain.
+
+
+3.4 Timing
+~~~~~~~~~~
+
+.. code-block:: C++
+ u32 sample_rate() const;
+ attotime sample_period() const;
+
+ u64 start_index() const;
+ u64 end_index() const;
+ attotime start_time() const;
+ attotime end_time() const;
+
+ attotime sample_to_time(u64 index) const;
+
+``sample_rate`` gives the current sample rate of the stream and
+``sample_period`` the corresponding duration.
+
+Within a call to the update callback, ``start_index`` gives the number
+(starting at zero at system power on) and ``start_time`` the time of
+the first sample to compute in the update. ``end_index`` and
+``end_time`` correspondingly indicate one past the last sample to
+update, or in other words the first sample of the next update call.
+Outside of an update callback, they all point to the first sample of
+the next update call.
+
+Finally ``sample_to_time`` allows to convert from a sample number to a
+time.
+
+Note that in case of change of sample rate sample numbers are
+recalculated to end up as if the stream had had the new rate from the
+start. And the times will still be such that sample 0 is at time 0.
+
+
+3.5 Gain management
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ float user_output_gain() const;
+ void set_user_output_gain(float gain);
+ float user_output_gain(s32 output) const;
+ void set_user_output_gain(s32 output, float gain);
+
+ float input_gain(s32 input) const;
+ void set_input_gain(s32 input, float gain);
+ void apply_input_gain(s32 input, float gain);
+ float output_gain(s32 output) const;
+ void set_output_gain(s32 output, float gain);
+ void apply_output_gain(s32 output, float gain);
+
+
+This is similar to the device gain control, with a twist: apply
+multiplies the current gain by the given value.
+
+
+3.6 Misc. actions
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ void set_sample_rate(u32 sample_rate);
+ void update();
+
+The method ``set_sample_rate`` allows to change the sample rate of the
+stream. The method ``update`` triggers a call of
+``sound_stream_update`` on the stream and the ones it depends on to
+reach the current time in terms of samples.
+
+
+4. Devices using device_mixer_interface
+---------------------------------------
+
+The device mixer interface is used for devices that want to relay
+sound in the device tree without acting on it. It's very useful on
+for instance slot devices connectors, where the slot device may have
+an audio connection with the main system. They are routed like every
+other sound device, create the streams automatically and copy input to
+output. Nothing needs to be done in the device.
diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst
index ee41de889d8..72c678b4ca6 100644
--- a/docs/source/techspecs/index.rst
+++ b/docs/source/techspecs/index.rst
@@ -15,8 +15,13 @@ MAME’s source or working on scripts that run within the MAME framework.
device_memory_interface
device_rom_interface
device_disasm_interface
+ device_sound_interface
memory
+ cpu_device
floppy
nscsi
m6502
+ uml_instructions
poly_manager
+ audio_effects
+ osd_audio
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index d9976faf00d..a014756a32b 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -690,6 +690,11 @@ element. This means a view can reference elements and groups that appear after
it in the file, and parameters from the enclosing scope will have their final
values from the end of the ``mamelayout`` element.
+A ``view`` element may have a ``showpointers`` attribute to set whether mouse
+and pen pointers should be shown for the view. If present, the value must be
+either ``yes`` or ``no``. If the ``showpointers`` attribute is not present, pen
+and mouse pointers are shown for views that contain items bound to I/O ports.
+
The following child elements are allowed inside a ``view`` element:
bounds
@@ -1188,7 +1193,7 @@ Clickable items
If a view item (``element`` or ``screen`` element) has ``inputtag`` and
``inputmask`` attribute values that correspond to a digital switch field in the
emulated system, clicking the element will activate the switch. The switch
-will remain active as long as the mouse button is held down and the pointer is
+will remain active as long as the primary button is held down and the pointer is
within the item’s current bounds. (Note that the bounds may change depending on
the item’s animation state, see :ref:`layfile-interact-itemanim`).
@@ -1197,6 +1202,12 @@ device that caused the layout file to be loaded. The ``inputmask`` attribute
must be an integer specifying the bits of the I/O port field that the item
should activate. This sample shows instantiation of clickable buttons:
+The ``clickthrough`` attribute controls whether clicks can pass through the view
+item to other view items drawn above it. The ``clickthrough`` attribute must be
+``yes`` or ``no`` if present. The default is ``no`` (clicks do not pass
+through) for view items with ``inputtag`` and ``inputmask`` attributes, and
+``yes`` (clicks pass through) for other view items.
+
.. code-block:: XML
<element ref="btn_3" inputtag="X2" inputmask="0x10">
@@ -1209,9 +1220,8 @@ should activate. This sample shows instantiation of clickable buttons:
<bounds x="1.775" y="5.375" width="1.0" height="1.0" />
</element>
-When handling mouse input, MAME treats all layout elements as being rectangular,
-and only activates the first clickable item whose area includes the location of
-the mouse pointer.
+When handling pointer input, MAME treats all layout elements as being
+rectangular.
.. _layfile-interact-elemstate:
diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst
index be6166a7146..f3ff505c9df 100644
--- a/docs/source/techspecs/layout_script.rst
+++ b/docs/source/techspecs/layout_script.rst
@@ -495,8 +495,8 @@ providing what’s needed:
* ``emu.print_verbose``, ``emu.print_error``, ``emu.print_warning``,
``emu.print_info`` and ``emu.print_debug`` functions for diagnostic output.
* Standard Lua ``tonumber``, ``tostring``, ``pairs`` and ``ipairs`` functions,
- and ``table`` and ``string`` objects for manipulating strings, tables and
- other containers.
+ and ``math``, ``table`` and ``string`` objects for manipulating numbers,
+ strings, tables and other containers.
* Standard Lua ``print`` function for text output to the console.
@@ -563,6 +563,96 @@ Dimensions recomputed
The callback function has no return value and takes no parameters. Call
with ``nil`` as the argument to remove the event handler.
+Pointer updated
+ ``view:set_pointer_updated_callback(cb)``
+
+ Called when a pointer enters, moves or changes button state over the view.
+
+ The callback function is passed nine arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the currently pressed buttons. The primary button
+ is the least significant bit.
+ * A bit mask representing the buttons that were pressed in this update. The
+ primary button is the least significant bit.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Pointer left
+ ``view:set_pointer_left_callback(cb)``
+
+ Called when a pointer leaves the view normally. After receiving this event,
+ the pointer ID may be reused for a new pointer.
+
+ The callback function is passed seven arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Pointer aborted
+ ``view:set_pointer_aborted_callback(cb)``
+
+ Called when a pointer leaves the view abnormally. After receiving this
+ event, the pointer ID may be reused for a new pointer.
+
+ The callback function is passed seven arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Forget pointers
+ ``view:set_forget_pointers_callback(cb)``
+
+ Called when the view should stop processing pointer input. This can happen
+ in a number of situations, including:
+
+ * The user activated a menu.
+ * The view configuration will change.
+ * The view will be deactivated.
+
+ The callback function has no return value and takes no parameters. Call
+ with ``nil`` as the argument to remove the event handler.
.. _layscript-events-item:
@@ -692,4 +782,5 @@ Draw
The callback is passed two arguments: the element state (an integer) and the
32-bit ARGB bitmap at the required size. The callback must not attempt to
- resize the bitmap.
+ resize the bitmap. Call with ``nil`` as the argument to remove the event
+ handler.
diff --git a/docs/source/techspecs/m6502.rst b/docs/source/techspecs/m6502.rst
index 7d67423abb8..f5d55fc9af4 100644
--- a/docs/source/techspecs/m6502.rst
+++ b/docs/source/techspecs/m6502.rst
@@ -92,7 +92,7 @@ At a minimum, the class must include a constructor and an enum picking up the co
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.
+If the CPU has in addition its own opcodes, their declaration must be done through a macro, see e.g. m65c02. The .inc file will provide the definitions.
Dispatch tables
@@ -365,7 +365,7 @@ A negative icount means that the CPU won't be able to do anything for some time
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).
+Some variants currently in the process of being supported change instruction set depending on an internal flag, either switching to a 16-bit 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).
Current TO-DO:
--------------
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index ebdca9646d1..9f0a31758c7 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -276,6 +276,77 @@ or the view can be disabled using the ``disable`` method. A disabled
view can be re-enabled at any time.
+.. _3.5:
+
+3.5 Bus contention handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some specific CPUs have been upgraded to be interruptible which allows
+to add bus contention and wait states capabitilites. Being
+interruptible means, in practice, that an instruction can be
+interrupted at any time and the execute_run method of the core exited.
+Other devices can then run, then eventually controls returns to the
+core and the instruction continues from the point it was started.
+Importantly, this can be triggered from a handler and even be used to
+interrupt just before the access that is currently done
+(e.g. continuation will redo the access).
+
+The CPUs supporting that declare their capability by overriding the
+method ``cpu_is_interruptible`` to return true.
+
+Three intermediate contention handlers can be added to accesses:
+
+* ``before_delay``: wait a number of cycles before doing the access.
+* ``after_delay``: wait a number of cycles after doing the access.
+* ``before_time``: wait for a given time before doing the access.
+
+For the delay handlers, a method or lambda is called which returns the
+number of cycles to wait (as a u32).
+
+The ``before_time`` is special. First, the time is compared to the
+current value of cpu->total_cycles(). That value is the number of
+cycles elapsed since the last reset of the cpu. It is passed as a
+parameter to the method as a u64 and must return the earliest time as
+a u64 when the access can be done, which can be equal to the passed-in
+time. From there two things can happen: either the running cpu has
+enough cycles left to consume to reach that time. In that case, the
+necessary number of cycles is consumed, and the access is done.
+Otherwise, when there isn't enough, the remaining cycles are consumed,
+the access aborted, scheduling happens, and eventually the access is
+redone. In that case the method is called again with the new current
+time, and must return the (probably same) earliest time again. This
+will happen until enough cycles to consume are available to directly
+do the access.
+
+This approach allows to for instance handle consecutive DMAs. A first
+DMA grabs the bus for a transfer. This shows up as the method
+answering for the earliest time for access the time of the end of the
+dma. If no timer happens until that time the access will then happen
+just after the dma finishes. But if a timer elapses before that and
+as a consequence another dma is queued while the first is running, the
+cycle will be aborted for lack of remaining time, and the method will
+eventually be called again. It will then give the time of when the
+second dma will finish, and all will be well.
+
+It can also allow to reduce said earlier time when circumstances
+require it. For instance a PIO latch that waits up to 64 cycles that
+data arrives can indicate that current time + 64 as a target (which
+will trigger a bus error for instance) but if a timer elapses and
+fills the latch meanwhile the method will be called again and that
+time can just return the current time to let the access pass though.
+Beware that if the timer elapsing did not fill the latch then the
+method must return the time it returned previously, e.g. the initial
+access time + 64, otherwise irrelevant timers happening or simply
+scheduling quantum effects will delay the timeout, possibly to
+infinity if the quantum is small enough.
+
+Contention handlers on the same address are taken into account in the
+``before_time``, ``before_delay`` then ``after_delay`` order.
+Contention handlers of the same type on the same address at
+last-one-wins. Installing any non-contention handler on a range where
+a contention handler was removes it.
+
+
4. Address maps API
-------------------
@@ -292,13 +363,14 @@ The general syntax for entries uses method chaining:
.. code-block:: C++
- map(start, end).handler(...).handler_qualifier(...).range_qualifier();
+ map(start, end).handler(...).handler_qualifier(...).range_qualifier().contention();
The values start and end define the range, the handler() block
determines how the access is handled, the handler_qualifier() block
-specifies some aspects of the handler (memory sharing for instance) and
-the range_qualifier() block refines the range (mirroring, masking, lane
-selection, etc.).
+specifies some aspects of the handler (memory sharing for instance)
+and the range_qualifier() block refines the range (mirroring, masking,
+lane selection, etc.). The contention methods handle bus contention
+and wait states for cpus supporting them.
The map follows a “last one wins” principle, where the handler specified
last is selected when multiple handlers match a given address.
@@ -607,7 +679,20 @@ behaviour. An example of use the i960 which marks burstable zones
that way (they have a specific hardware-level support).
-4.5 View setup
+4.5 Contention
+~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ (...).before_time(method).(...)
+ (...).before_delay(method).(...)
+ (...).after_delay(method).(...)
+
+These three methods allow to add the contention methods to a handler.
+See section `3.5`_. Multiple methods can be handler to one handler.
+
+
+4.6 View setup
~~~~~~~~~~~~~~
.. code-block:: C++
@@ -641,6 +726,7 @@ can be installed only once. A view can also be part of “what was there
before”.
+
5. Address space dynamic mapping API
------------------------------------
@@ -803,8 +889,32 @@ with an optional mirror and flags.
Install a device address with an address map in a space. The
``unitmask``, ``cswidth`` and ``flags`` arguments are optional.
-5.9 View installation
-~~~~~~~~~~~~~~~~~~~~~
+5.9 Contention
+~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ using ws_time_delegate = device_delegate<u64 (offs_t, u64)>;
+ using ws_delay_delegate = device_delegate<u32 (offs_t)>;
+
+ space.install_read_before_time(addrstart, addrend, addrmirror, ws_time_delegate)
+ space.install_write_before_time(addrstart, addrend, addrmirror, ws_time_delegate)
+ space.install_readwrite_before_time(addrstart, addrend, addrmirror, ws_time_delegate)
+
+ space.install_read_before_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+ space.install_write_before_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+ space.install_readwrite_before_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+
+ space.install_read_after_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+ space.install_write_after_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+ space.install_readwrite_after_delay(addrstart, addrend, addrmirror, ws_delay_delegate)
+
+Install a contention handler in the decode path. The addrmirror
+parameter is optional.
+
+
+5.10 View installation
+~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: C++
@@ -820,3 +930,35 @@ by indexing to call a dynamic mapping method on it.
A view can be installed into a variant of another view without issues,
with only the usual constraint of single installation.
+
+5.11 Taps
+~~~~~~~~~
+
+.. code-block:: C++
+
+ using tap = std::function<void (offs_t offset, uNN &data, uNN mem_mask)
+
+ memory_passthrough_handler mph = space.install_read_tap(addrstart, addrend, name, read_tap, &mph);
+ memory_passthrough_handler mph = space.install_write_tap(addrstart, addrend, name, write_tap, &mph);
+ memory_passthrough_handler mph = space.install_readwrite_tap(addrstart, addrend, name, read_tap, write_tap, &mph);
+
+ mph.remove();
+
+A tap is a method that is be called when a specific range of addresses
+is accessed without overriding the actual access. Taps can change the
+data passed around. A write tap happens before the access, and can
+change the value to be written. A read tap happens after the access,
+and can change the value returned.
+
+Taps must be of the same width and alignement than the bus. Multiple
+taps can act over the same addresses.
+
+The ``memory_passthrough_handler`` object collates a number of taps
+and allow to remove them all in one call. The ``mph`` parameter is
+optional and a new one will be created if absent.
+
+Taps are lost when a new handler is installed at the same addresses
+(under the usual principle of last one wins). If they need to be
+preserved, one should install a change notifier on the address space,
+and remove + reinstall the taps when notified.
+
diff --git a/docs/source/techspecs/osd_audio.rst b/docs/source/techspecs/osd_audio.rst
new file mode 100644
index 00000000000..82e03d999ef
--- /dev/null
+++ b/docs/source/techspecs/osd_audio.rst
@@ -0,0 +1,348 @@
+OSD audio support
+=================
+
+Introduction
+------------
+
+The audio support in Mame tries to allow the user to freely map
+between the emulated system audio outputs (called speakers) and the
+host system audio. A part of it is the OSD support, where a
+host-specific module ensures the interface between Mame and the host.
+This is the documentation for that module.
+
+Note: this is currenty output-only, but input should follow.
+
+
+Capabitilies
+------------
+
+The OSD interface is designed to allow three levels of support,
+depending on what the API allows and the amount of effort to expend.
+Those are:
+
+* Level 1: One or more audio targets, only one stream allowed per target
+ (aka exclusive mode)
+* Level 2: One or more audio targets, multiple streams per target
+* Level 3: One or more audio targets, multiple streams per target, user-visible
+ per-stream-channel volume control
+
+In any case we support having the user use an external interface to
+change the target of a stream and, in level 3, change the volumes. By
+support we mean storing the information in the per-game configuration
+and keeping the internal UI in sync.
+
+
+Terminology
+-----------
+
+For this module, we use the terms:
+
+* node: some object we can send audio to. Can be physical, like speakers,
+ or virtual, like an effect system. It should have a unique, user-presentable
+ name for the UI.
+* port: a channel of a node, has a name (non-unique, like "front left") and a
+ 3D position
+* stream: a connection to a node with allows to send audio to it
+
+
+Reference documentation
+-----------------------
+
+Adding a module
+~~~~~~~~~~~~~~~
+
+Adding a module is done by adding a cpp file to src/osd/modules/sound
+which follows this structure,
+
+.. code-block:: C++
+
+ // License/copyright
+ #include "sound_module.h"
+ #include "modules/osdmodules.h"
+
+ #ifdef MODULE_SUPPORT_KEY
+
+ #include "modules/lib/osdobj_common.h"
+
+ // [...]
+ namespace osd {
+ namespace {
+
+ class sound_module_class : public osd_module, public sound_module
+ {
+ sound_module_class() : osd_module(OSD_SOUND_PROVIDER, "module_name"),
+ sound_module()
+ // ...
+ };
+
+ }
+ }
+ #else
+ namespace osd { namespace {
+ MODULE_NOT_SUPPORTED(sound_module_class, OSD_SOUND_PROVIDER, "module_name")
+ }}
+ #endif
+
+ MODULE_DEFINITION(SOUND_MODULE_KEY, osd::sound_module_class)
+
+In that code, four names must be chosen:
+
+* MODULE_SUPPORT_KEY some #define coming from the genie scripts to tell that
+ this particular module can be compiled (like NO_USE_PIPEWIRE or SDLMAME_MACOSX)
+* sound_module_class is the name of the class which makes up the module
+ (like sound_coreaudio)
+* module_name is the name to be used in -sound <xxx> to select that particular
+ module (like coreaudio)
+* SOUND_MODULE_KEY is a symbol that represents the module internally (like
+ SOUND_COREAUDIO)
+
+The file path needs to be added to scripts/src/osd/modules.lua in
+osdmodulesbuild() and the module reference to
+src/osd/modules/lib/osdobj_common.cpp in
+osd_common_t::register_options with the line:
+
+.. code-block:: C++
+
+ REGISTER_MODULE(m_mod_man, SOUND_MODULE_KEY);
+
+This should ensure that the module is reachable through -sound <xxx>
+on the appropriate hosts.
+
+
+Interface
+~~~~~~~~~
+
+The full interface is:
+
+.. code-block:: C++
+
+ virtual bool split_streams_per_source() const override;
+ virtual bool external_per_channel_volume() const override;
+
+ virtual int init(osd_interface &osd, osd_options const &options) override;
+ virtual void exit() override;
+
+ virtual uint32_t get_generation() override;
+ virtual osd::audio_info get_information() override;
+ virtual uint32_t stream_sink_open(uint32_t node, std::string name, uint32_t rate) override;
+ virtual uint32_t stream_source_open(uint32_t node, std::string name, uint32_t rate) override;
+ virtual void stream_set_volumes(uint32_t id, const std::vector<float> &db) override;
+ virtual void stream_close(uint32_t id) override;
+ virtual void stream_sink_update(uint32_t id, const int16_t *buffer, int samples_this_frame) override;
+ virtual void stream_source_update(uint32_t id, int16_t *buffer, int samples_this_frame) override;
+
+
+The class sound_module provides defaults for minimum capabilities: one
+stereo target and stream at default sample rate. To support that,
+only *init*, *exit* and *stream_update* need to be implemented.
+*init* is called at startup and *exit* when quitting and can do
+whatever they need to do. *stream_sink_update* will be called on a
+regular basis with a buffer of sample_this_frame * 2 * int16_t with the
+audio to play. From this point in the documentation we'll assume more
+than a single stereo channel is wanted.
+
+
+Capabilities
+~~~~~~~~~~~~
+
+Two methods are used by the module to indicate the level of capability
+of the module:
+
+* split_streams_per_source() should return true when having multiple streams
+ for one target is expected (e.g. Level 2 or 3)
+* external_per_channel_volume() should return true when the streams have
+ per-channel volume control that can be externally controlled (e.g. Level 3)
+
+
+Hardware information and generations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The core runs on the assumption that the host hardware capabilities
+can change at any time (bluetooth devices coming and going, usb
+hot-plugging...) and that the module has some way to keep tabs on what
+is happening, possibly using multi-threading. To keep it
+lightweight-ish, we use the concept of a *generation* which is a
+32-bit number that is incremented by the module every time something
+changes. The core checks the current generation value at least once
+every update (once per frame, usually) and if it changed asks for the
+new state and detects and handles the differences. *generation*
+should be "eventually stable", e.g. it eventually stops changing when
+the user stops changing things all the time. A systematic increment
+every frame would be a bad idea.
+
+.. code-block:: C++
+
+ virtual uint32_t get_generation() override;
+
+That method returns the current generation number. It's called at a
+minimum once per update, which usually means per frame. It whould be
+reasonably lightweight when nothing special happens.
+
+.. code-block: C++
+
+ virtual osd::audio_info get_information() override;
+
+ struct audio_rate_range {
+ uint32_t m_default_rate;
+ uint32_t m_min_rate;
+ uint32_t m_max_rate;
+ };
+
+ struct audio_info {
+ struct node_info {
+ std::string m_name;
+ uint32_t m_id;
+ audio_rate_range m_rate;
+ std::vector<std::string> m_port_names;
+ std::vector<std::array<double, 3>> m_port_positions;
+ uint32_t m_sinks;
+ uint32_t m_sources;
+ };
+
+ struct stream_info {
+ uint32_t m_id;
+ uint32_t m_node;
+ std::vector<float> m_volumes;
+ };
+
+ uint32_t m_generation;
+ uint32_t m_default_sink;
+ uint32_t m_default_source;
+ std::vector<node_info> m_nodes;
+ std::vector<stream_info> m_streams;
+ };
+
+This method must provide all the information about the current state
+of the host and the module. This state is:
+
+* m_generation: The current generation number
+* m_nodes: The vector available nodes (*node_info*)
+
+ * m_name: The name of the node
+ * m_id: The numeric ID of the node
+ * m_rate: The minimum, maximum and preferred sample rate for the node
+ * m_port_names: The vector of port names
+ * m_port_positions: The vector of 3D position of the ports. Refer to
+ src/emu/speaker.h for the "standard" positions
+ * m_sinks: Number of sinks (inputs)
+ * m_sources: Number of sources (outputs)
+
+* m_default_sink: ID of the node that is the current "system default" for
+ audio output, 0 if there's no such concept
+* m_default_source: same for audio input (currently unused)
+* m_streams: The vector of active streams (*stream_info*)
+
+ * m_id: The numeric ID of the stream
+ * m_node: The target node of the stream
+ * m_volumes: empty if *external_per_channel_volume* is false, current volume
+ value per-channel otherwise
+
+IDs, for nodes and streams, are (independant) 32-bit unsigned non-zero
+values associated to respectively nodes and streams. IDs should not
+be reused. A node that goes away then comes back should get a new ID.
+A stream closing does not allow reuse of its ID.
+
+If a node has both sources and sinks, the sources are *monitors* of
+the sinks, e.g. they're loopbacks. They should have the same count in
+such a case.
+
+When external control exists, a module should change the value of
+*stream_info::m_node* when the user changes it, and same for
+*stream_info::m_volumes*. Generation number should be incremented
+when this happens, so that the core knows to look for changes.
+
+Volumes are floats in dB, where 0 means 100% and -96 means no sound.
+audio.h provides osd::db_to_linear and osd::linear_to_db if such a
+conversion is needed.
+
+There is an inherent race condition with this system, because things
+can change at any point after returning for the method. The idea is
+that the information returned must be internally consistent (a stream
+should not point to a node ID that does not exist in the structure,
+same for default sink) and that any external change from that state
+should increment the generation number, but that's it. Through the
+generation system the core will eventually be in sync with reality.
+
+
+Input and output streams
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ virtual uint32_t stream_sink_open(uint32_t node, std::string name, uint32_t rate) override;
+ virtual uint32_t stream_source_open(uint32_t node, std::string name, uint32_t rate) override;
+ virtual void stream_set_volumes(uint32_t id, const std::vector<float> &db) override;
+ virtual void stream_close(uint32_t id) override;
+ virtual void stream_sink_update(uint32_t id, const int16_t *buffer, int samples_this_frame) override;
+ virtual void stream_source_update(uint32_t id, int16_t *buffer, int samples_this_frame) override;
+
+Streams are the concept used to send or receive audio from/to the host
+audio system. A stream is first opened through *stream_sink_open* for
+speakers and *stream_source_open* for microphones and targets a
+specific node at a specific sample rate. It is given a name for use
+by the host sound services for user UI purposes (currently the game
+name if split_streams_per_source is false, the
+speaker_device/microphone_device tag if true). The returned ID must
+be a non-zero, never-used-before for streams value in case of success.
+Failures, like when the node went away between the *get_information*
+call and the open one, should be silent and return zero.
+
+*stream_set_volumes* is used only when *external_per_channel_volume*
+is true and is used by the core to set the per-channel volume. The
+call should just be ignored if the stream ID does not exist (or is
+zero). Do not try to apply volumes in the module if the host API
+doesn't provide for it, let the core handle it.
+
+*stream_close* closes a stream, The call should just be ignored if the
+stream ID does not exist (or is zero).
+
+Opening a stream, closing a stream or changing the volume does not
+need to touch the generation number.
+
+*stream_sink_update* is the method used to send data to the node
+through a given stream. It provides a buffer of *samples_this_frame*
+* *node channel count* channel-interleaved int16_t values. The
+lifetime of the data in the buffer or the buffer pointer itself is
+undefined after return from the method call. The call should just be
+ignored if the stream ID does not exist (or is zero).
+
+*stream_source_update* is the equivalent to retrieve data from a node,
+writing to the buffer instead of reading from it. The constraints are
+identical.
+
+When a stream goes away because the target node is lost it should just
+be removed from the information, and the core will pick up the node
+departure and close the stream.
+
+Given the assumed raceness of the interface, all the methods should be
+tolerant of obsolete or zero IDs being used by the core, and that is
+why ID reuse must be avoided. Also the update methods and the
+open/close/volume ones may be called at the same time in different
+threads.
+
+
+Helper class *abuffer*
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ class abuffer {
+ public:
+ abuffer(uint32_t channels);
+ void get(int16_t *data, uint32_t samples);
+ void push(const int16_t *data, uint32_t samples);
+ uint32_t channels() const;
+ };
+
+The class *abuffer* is a helper provided by *sound_module* to buffer
+audio input or output. It automatically drops data when there is
+an overflow and duplicates the last sample on underflow. It must
+first be initialized with the number of channels, which can be
+retrieved with *channels()* if needed. *push* sends
+*samples* * *channels* 16-bit samples in the buffer. *get* retrieves
+*samples* * *channels* 16-bit samples from the buffer, on a FIFO basis.
+
+It is not protected against multithreading, but uses no class
+variables. So just don't read and write from one specific abuffer
+instance at the same time. The system sound interface mandated
+locking should be enough to ensure that.
diff --git a/docs/source/techspecs/uml_instructions.rst b/docs/source/techspecs/uml_instructions.rst
new file mode 100644
index 00000000000..5d379dd1c60
--- /dev/null
+++ b/docs/source/techspecs/uml_instructions.rst
@@ -0,0 +1,1582 @@
+.. _umlinst:
+
+UML Instruction Reference
+=========================
+
+.. contents::
+ :local:
+ :depth: 2
+
+
+.. _umlinst-intro:
+
+Introduction
+------------
+
+UML is the instruction set used by MAME’s recompiler framework.
+Front-ends translate code running on the guest CPUs to UML instructions,
+and back-ends convert the UML instructions to a form that can be
+executed or interpreted on the host system.
+
+
+.. _umlinst-flow:
+
+Flow control
+------------
+
+.. _umlinst-comment:
+
+COMMENT
+~~~~~~~
+
+Insert a comment into logged UML code.
+
++--------------------+---------------------------------+
+| Disassembly | Usage |
++====================+=================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| comment string | UML_COMMENT(block, string); |
++--------------------+---------------------------------+
+
+Operands
+^^^^^^^^
+
+string
+ The comment text as a pointer to a NUL-terminated string. This must
+ remain valid until code is generated for the block.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-nop:
+
+NOP
+~~~
+
+No operation.
+
++-----------------+---------------------+
+| Disassembly | Usage |
++=================+=====================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| nop | UML_NOP(block); |
++-----------------+---------------------+
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-label:
+
+LABEL
+~~~~~
+
+Associate a location with a label number local to the current generated
+code block. Label numbers must not be reused within a generated code
+block. The :ref:`JMP <umlinst-jmp>` instruction may be used to transfer
+control to the location associated with a label number.
+
++-------------------+------------------------------+
+| Disassembly | Usage |
++===================+==============================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| label label | UML_LABEL(block, label); |
++-------------------+------------------------------+
+
+Operands
+^^^^^^^^
+
+label (label number)
+ The label number to associate with the current location. A label
+ number must not be used more than once within a generated code
+ block.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-handle:
+
+HANDLE
+~~~~~~
+
+Mark a location as an entry point of a subroutine. Subroutines may be
+called using the :ref:`CALLH <umlinst-callh>` and :ref:`EXH
+<umlinst-exh>` instructions, and also by the `HASHJMP <umlinst-hashjmp>`
+if no location is associated with the specified mode and emulated
+program counter.
+
++--------------------+--------------------------------+
+| Disassembly | Usage |
++====================+================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| handle handle | UML_HANDLE(block, handle); |
++--------------------+--------------------------------+
+
+Operands
+^^^^^^^^
+
+handle (code handle)
+ The code handle to bind to the current location. The handle must
+ already be allocated, and must not have been bound since the last
+ generated code reset (all handles are implicitly unbound when
+ resetting the generated code cache).
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-hash:
+
+HASH
+~~~~
+
+Associate a location with the specified mode and emulated program
+counter values. The :ref:`HASHJMP <umlinst-hashjmp>` instruction may be
+used to transfer control to the location associated with a mode and
+emulated program counter value.
+
+This is usually used to mark the location of the generated code for an
+emulated instruction or sequence of instructions.
+
++---------------------+------------------------------+
+| Disassembly | Usage |
++=====================+==============================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| hash mode,pc | UML_HASH(block, mode, pc); |
++---------------------+------------------------------+
+
+Operands
+^^^^^^^^
+
+mode (32-bit – immediate, map variable)
+ The mode to associate with the current location in the generated
+ code. Must be greater than or equal to zero and less than the
+ number of modes specified when creating the recompiler context.
+pc (32-bit – immediate, map variable)
+ The emulated program counter value to associate with the current
+ location in the generated code.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-jmp:
+
+JMP
+~~~
+
+Jump to the location associated with a label number within the current
+block.
+
++------------------------+-----------------------------------+
+| Disassembly | Usage |
++========================+===================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| jmp label | UML_JMP(block, label); |
+| jmp label,cond | UML_JMPc(block, cond, label); |
++------------------------+-----------------------------------+
+
+Operands
+^^^^^^^^
+
+label (label number)
+ The label number associated with the location to jump to in the
+ current generated code block. The label number must be associated
+ with a location in the generated code block before the block is
+ finalised.
+cond (condition)
+ If supplied, a condition that must be met to jump to the specified
+ label. If the condition is not met, execution will continue with
+ the following instruction.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-callh:
+
+CALLH
+~~~~~
+
+Call the subroutine beginning at the specified code handle.
+
++-------------------------+--------------------------------------+
+| Disassembly | Usage |
++=========================+======================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| callh handle | UML_CALLH(block, handle); |
+| callh handle,cond | UML_CALLHc(block, handle, cond); |
++-------------------------+--------------------------------------+
+
+Operands
+^^^^^^^^
+
+handle (code handle)
+ Handle located at the entry point of the subroutine to call. The
+ handle must already be allocated but does not need to be bound until
+ the instruction is executed. Calling a handle that was unbound at
+ code generation time may produce less efficient code than calling a
+ handle that was already bound.
+cond (condition)
+ If supplied, a condition that must be met for the subroutine to be
+ called. If the condition is not met, the subroutine will not be
+ called.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-exh:
+
+EXH
+~~~
+
+Set the ``EXP`` register and call the subroutine beginning at the
+specified code handle. The ``EXP`` register is a 32-bit special
+function register that may be retrieved with the :ref:`GETEXP
+<umlinst-getexp>` instruction.
+
++-----------------------------+-----------------------------------------+
+| Disassembly | Usage |
++=============================+=========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| exh handle,arg | UML_EXH(block, handle, arg); |
+| exh handle,arg,cond | UML_EXHc(block, handle, arg, cond); |
++-----------------------------+-----------------------------------------+
+
+Operands
+^^^^^^^^
+
+handle (code handle)
+ Handle located at the entry point of the subroutine to call. The
+ handle must already be allocated but does not need to be bound until
+ the instruction is executed. Calling a handle that was unbound at
+ code generation time may produce less efficient code than calling a
+ handle that was already bound.
+arg (32-bit – memory, integer register, immediate, map variable)
+ Value to store in the ``EXP`` register.
+cond (condition)
+ If supplied, a condition that must be met for the subroutine to be
+ called. If the condition is not met, the subroutine will not be
+ called and the ``EXP`` register will not be modified.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``arg`` operand are truncated to 32 bits.
+
+.. _umlinst-ret:
+
+RET
+~~~
+
+Return from a subroutine, transferring control to the instruction
+following the :ref:`CALLH <umlinst-callh>` or :ref:`EXH <umlinst-exh>`
+instruction used to call the subroutine. This instruction must only be
+used within generated code subroutines. The :ref:`EXIT <umlinst-exit>`
+instruction must be used to exit from the generated code.
+
++------------------+----------------------------+
+| Disassembly | Usage |
++==================+============================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| ret | UML_RET(block); |
+| ret cond | UML_RETc(block, cond); |
++------------------+----------------------------+
+
+Operands
+^^^^^^^^
+
+cond (condition)
+ If supplied, a condition that must be met to return from the
+ subroutine. If the condition is not met, execution will continue
+ with the following instruction.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-hashjmp:
+
+HASHJMP
+~~~~~~~
+
+Unwind all nested generated code subroutine frames and transfer control
+to the location associated with the specified mode and emulated program
+counter values. If no location is associated with the specified mode
+and program counter values, call the subroutine beginning at the
+specified code handle. Note that all nested generated code subroutine
+frames are unwound in either case.
+
+This is usually used to jump to the generated code corresponding to the
+emulated code at a particular address when it is not known to be in the
+current generated code block or when the mode changes.
+
++----------------------------+-----------------------------------------+
+| Disassembly | Usage |
++============================+=========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| hashjmp mode,pc,handle | UML_HASHJMP(block, mode, pc, handle); |
++----------------------------+-----------------------------------------+
+
+Operands
+^^^^^^^^
+
+mode (32-bit – memory, integer register, immediate, map variable)
+ The mode associated with the location in the generated code to
+ transfer control to. Must be greater than or equal to zero and less
+ than the number of modes specified when creating the recompiler
+ context.
+pc (32-bit – memory, integer register, immediate, map variable)
+ The emulated program counter value associated with the location in
+ the generated code to transfer control to.
+handle (code handle)
+ Handle located at the entry point of the subroutine to call if no
+ location in the generated code is associated with the specified mode
+ and emulated program counter values. The handle must already be
+ allocated but does not need to be bound until the instruction is
+ executed. Calling a handle that was unbound at code generation time
+ may produce less efficient code than calling a handle that was
+ already bound.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+.. _umlinst-exit:
+
+EXIT
+~~~~
+
+Exit from the generated code, returning control to the caller. May be
+used from within any level of nested subroutine calls in the generated
+code.
+
++-----------------------+----------------------------------+
+| Disassembly | Usage |
++=======================+==================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| exit arg, | UML_EXIT(block, arg); |
+| exit arg,,cond | UML_EXITc(block, arg, cond); |
++-----------------------+----------------------------------+
+
+Operands
+^^^^^^^^
+
+arg (32-bit – memory, integer register, immediate, map variable)
+ The value to return to the caller.
+cond (condition)
+ If supplied, a condition that must be met to exit from the generated
+ code. If the condition is not met, execution will continue with the
+ following instruction.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``arg`` operand are truncated to 32 bits.
+
+.. _umlinst-callc:
+
+CALLC
+~~~~~
+
+Call a C function with the signature ``void (*)(void *)``.
+
++---------------------------+-----------------------------------------+
+| Disassembly | Usage |
++===========================+=========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| callc func,arg | UML_CALLC(block, func, arg); |
+| callc func,arg,cond | UML_CALLCc(block, func, arg, cond); |
++---------------------------+-----------------------------------------+
+
+Operands
+^^^^^^^^
+
+func (C function)
+ Function pointer to the function to call.
+arg (memory)
+ Argument to pass to the function.
+cond (condition)
+ If supplied, a condition that must be met for the function to be
+ called. If the condition is not met, the function will not be
+ called.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+.. _umlinst-debug:
+
+DEBUG
+~~~~~
+
+Call the debugger instruction hook function if appropriate.
+
+If the debugger is active, this should be executed before each emulated
+instruction. Any emulated CPU state kept in UML registers should be
+flushed to memory before executing this instruction and reloaded
+afterwards to ensure the debugger can display and modify values
+correctly.
+
++-----------------+---------------------------+
+| Disassembly | Usage |
++=================+===========================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| debug pc | UML_DEBUG(block, pc); |
++-----------------+---------------------------+
+
+Operands
+^^^^^^^^
+
+pc (32-bit – memory, integer register, immediate, map variable)
+ The emulated program counter value to supply to the debugger
+ instruction hook function.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``pc`` operand are truncated to 32 bits.
+
+.. _umlinst-break:
+
+BREAK
+~~~~~
+
+Break into the host debugger if attached. Has no effect or crashes if
+no host debugger is attached depending on the host system and
+configuration. This is intended as a developer aid and should not be
+left in final code.
+
++-----------------+-----------------------+
+| Disassembly | Usage |
++=================+=======================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| break | UML_BREAK(block); |
++-----------------+-----------------------+
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+
+.. _umlinst-datamove:
+
+Data movement
+-------------
+
+.. _umlinst-mov:
+
+MOV
+~~~
+
+Copy an integer value.
+
++--------------------------+---------------------------------------+
+| Disassembly | Usage |
++==========================+=======================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| mov dst,src | UML_MOV(block, dst, src); |
+| mov dst,src,cond | UML_MOVc(block, cond, dst, src); |
+| dmov dst,src | UML_DMOV(block, dst, src); |
+| dmov dst,src,cond | UML_DMOVc(block, cond, dst, src); |
++--------------------------+---------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value will be copied to.
+src (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The source value to copy.
+cond (condition)
+ If supplied, a condition that must be met to copy the value. If the
+ condition is not met, the instruction will have no effect.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``src`` operand are truncated to the
+ instruction size.
+* Converted to :ref:`NOP <umlinst-nop>` if the ``src`` and ``dst``
+ operands refer to the same memory location or register and the
+ instruction size is no larger than the destination size.
+
+.. _umlinst-fmov:
+
+FMOV
+~~~~
+
+Copy a floating point value. The binary value will be preserved even if
+it is not a valid representation of a floating point number.
+
++--------------------------+----------------------------------------+
+| Disassembly | Usage |
++==========================+========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fsmov dst,src | UML_FSMOV(block, dst, src); |
+| fsmov dst,src,cond | UML_FSMOVc(block, cond, dst, src); |
+| fdmov dst,src | UML_FDMOV(block, dst, src); |
+| fdmov dst,src,cond | UML_FDMOVc(block, cond, dst, src); |
++--------------------------+----------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, floating point register)
+ The destination where the value will be copied to.
+src (32-bit or 64-bit – memory, floating point register)
+ The source value to copy.
+cond (condition)
+ If supplied, a condition that must be met to copy the value. If the
+ condition is not met, the instruction will have no effect.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Converted to :ref:`NOP <umlinst-nop>` if the ``src`` and ``dst``
+ operands refer to the same memory location or register.
+
+.. _umlinst-fcopyi:
+
+FCOPYI
+~~~~~~
+
+Reinterpret an integer value as a floating point value. The binary
+value will be preserved even if it is not a valid representation of a
+floating point number.
+
++---------------------+-----------------------------------+
+| Disassembly | Usage |
++=====================+===================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fscopyi dst,src | UML_FSCOPYI(block, dst, src); |
+| fdcopyi dst,src | UML_FDCOPYI(block, dst, src); |
++---------------------+-----------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, floating point register)
+ The destination where the value will be copied to.
+src (32-bit or 64-bit – memory, integer register)
+ The source value to copy.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-icopyf:
+
+ICOPYF
+~~~~~~
+
+Reinterpret a floating point value as an integer value. The binary
+value will be preserved even if it is not a valid representation of a
+floating point number.
+
++---------------------+-----------------------------------+
+| Disassembly | Usage |
++=====================+===================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| icopyfs dst,src | UML_ICOPYFS(block, dst, src); |
+| icopyfd dst,src | UML_ICOPYFD(block, dst, src); |
++---------------------+-----------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value will be copied to.
+src (32-bit or 64-bit – memory, floating point register)
+ The source value to copy.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-load:
+
+LOAD
+~~~~
+
+Load an unsigned integer value from a memory location with variable
+displacement. The value is zero-extended to the size of the
+destination. Host system rules for integer alignment must be followed.
+
++---------------------------------------+------------------------------------------------------+
+| Disassembly | Usage |
++=======================================+======================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| load dst,base,index,size_scale | UML_LOAD(block, dst, base, index, size, scale); |
+| dload dst,base,index,size_scale | UML_DLOAD(block, dst, base, index, size, scale); |
++---------------------------------------+------------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value read from memory will be stored.
+base (memory)
+ The base address of the area of memory to read from.
+index (32-bit – memory, integer register, immediate, map variable)
+ The displacement value added to the base address to calculate the
+ address to read from. This value may be scaled by a factor of 1, 2,
+ 4 or 8 depending on the ``scale`` operand. Note that this is always
+ a 32-bit operand interpreted as a signed integer, irrespective of
+ the instruction size.
+size (access size)
+ The size of the value to read. Must be ``SIZE_BYTE`` (8-bit),
+ ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or ``SIZE_QWORD``
+ (64-bit). Note that this operand controls the size of the value
+ read from memory while the instruction size sets the size of the
+ ``dst`` operand.
+scale (index scale)
+ The scale factor to apply to the ``index`` operand. Must be
+ ``SCALE_x1``, ``SCALE_x2``, ``SCALE_x4`` or ``SCALE_x8`` to multiply
+ by 1, 2, 4 or 8, respectively (shift left by 0, 1, 2 or 3 bits).
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-loads:
+
+LOADS
+~~~~~
+
+Load a signed integer value from a memory location with variable
+displacement. The value is sign-extended to the size of the
+destination. Host system rules for integer alignment must be followed.
+
++---------------------------------------+-------------------------------------------------------+
+| Disassembly | Usage |
++=======================================+=======================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| loads dst,base,index,size_scale | UML_LOADS(block, dst, base, index, size, scale); |
+| dloads dst,base,index,size_scale | UML_DLOADS(block, dst, base, index, size, scale); |
++---------------------------------------+-------------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value read from memory will be stored.
+base (memory)
+ The base address of the area of memory to read from.
+index (32-bit – memory, integer register, immediate, map variable)
+ The displacement value added to the base address to calculate the
+ address to read from. This value may be scaled by a factor of 1, 2,
+ 4 or 8 depending on the ``scale`` operand. Note that this is always
+ a 32-bit operand interpreted as a signed integer, irrespective of
+ the instruction size.
+size (access size)
+ The size of the value to read. Must be ``SIZE_BYTE`` (8-bit),
+ ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or ``SIZE_QWORD``
+ (64-bit). Note that this operand controls the size of the value
+ read from memory while the instruction size sets the size of the
+ ``dst`` operand.
+scale (index scale)
+ The scale factor to apply to the ``index`` operand. Must be
+ ``SCALE_x1``, ``SCALE_x2``, ``SCALE_x4`` or ``SCALE_x8`` to multiply
+ by 1, 2, 4 or 8, respectively (shift left by 0, 1, 2 or 3 bits).
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-store:
+
+STORE
+~~~~~
+
+Store an integer value to a location in memory with variable
+displacement. Host system rules for integer alignment must be followed.
+
++---------------------------------------+-------------------------------------------------------+
+| Disassembly | Usage |
++=======================================+=======================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| store base,index,src,size_scale | UML_STORE(block, base, index, src, size, scale); |
+| dstore base,index,src,size_scale | UML_DSTORE(block, base, index, src, size, scale); |
++---------------------------------------+-------------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+base (memory)
+ The base address of the area of memory to write to.
+index (32-bit – memory, integer register, immediate, map variable)
+ The displacement value added to the base address to calculate the
+ address to write to. This value may be scaled by a factor of 1, 2,
+ 4 or 8 depending on the ``scale`` operand. Note that this is always
+ a 32-bit operand interpreted as a signed integer, irrespective of
+ the instruction size.
+src (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The value to write to memory.
+size (access size)
+ The size of the value to write. Must be ``SIZE_BYTE`` (8-bit),
+ ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or ``SIZE_QWORD``
+ (64-bit). Note that this operand controls the size of the value
+ written to memory while the instruction size sets the size of the
+ ``src`` operand.
+scale (index scale)
+ The scale factor to apply to the ``index`` operand. Must be
+ ``SCALE_x1``, ``SCALE_x2``, ``SCALE_x4`` or ``SCALE_x8`` to multiply
+ by 1, 2, 4 or 8, respectively (shift left by 0, 1, 2 or 3 bits).
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-fload:
+
+FLOAD
+~~~~~
+
+Load a floating point value from a memory location with variable
+displacement. The binary value will be preserved even if it is not a
+valid representation of a floating point number. Host system rules for
+memory access alignment must be followed.
+
++----------------------------+------------------------------------------+
+| Disassembly | Usage |
++============================+==========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fsload dst,base,index | UML_FSLOAD(block, dst, base, index); |
+| fdload dst,base,index | UML_FDLOAD(block, dst, base, index); |
++----------------------------+------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, floating point register)
+ The destination where the value read from memory will be stored.
+base (memory)
+ The base address of the area of memory to read from.
+index (32-bit – memory, integer register, immediate, map variable)
+ The displacement value added to the base address to calculate the
+ address to read from. This value will be scaled by the instruction
+ size (multiplied by 4 or 8). Note that this is always a 32-bit
+ operand interpreted as a signed integer, irrespective of the
+ instruction size.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-fstore:
+
+FSTORE
+~~~~~~
+
+Store a floating point value to a memory location with variable
+displacement. The binary value will be preserved even if it is not a
+valid representation of a floating point number. Host system rules for
+memory access alignment must be followed.
+
++----------------------------+-------------------------------------------+
+| Disassembly | Usage |
++============================+===========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fsstore base,index,src | UML_FSSTORE(block, base, index, src); |
+| fdstore base,index,src | UML_FDSTORE(block, base, index, src); |
++----------------------------+-------------------------------------------+
+
+Operands
+^^^^^^^^
+
+base (memory)
+ The base address of the area of memory to write to.
+index (32-bit – memory, integer register, immediate, map variable)
+ The displacement value added to the base address to calculate the
+ address to write to. This value will be scaled by the instruction
+ size (multiplied by 4 or 8). Note that this is always a 32-bit
+ operand interpreted as a signed integer, irrespective of the
+ instruction size.
+src (32-bit or 64-bit – memory, floating point register)
+ The value to write to memory.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-getexp:
+
+GETEXP
+~~~~~~
+
+Copy the value of the ``EXP`` register. The ``EXP`` register can be set
+using the :ref:`EXH <umlinst-exh>` instruction.
+
++-----------------+-----------------------------+
+| Disassembly | Usage |
++=================+=============================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| getexp dst | UML_GETEXP(block, dst); |
++-----------------+-----------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit – memory, integer register)
+ The destination to copy the value of the ``EXP`` register to. Note
+ that the ``EXP`` register can only hold a 32-bit value.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-mapvar:
+
+MAPVAR
+~~~~~~
+
+Set the value of a map variable starting at the current location in the
+current generated code block.
+
++--------------------------+---------------------------------------+
+| Disassembly | Usage |
++==========================+=======================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| mapvar mapvar,value | UML_MAPVAR(block, mapvar, value); |
++--------------------------+---------------------------------------+
+
+Operands
+^^^^^^^^
+
+mapvar (map variable)
+ The map variable to set the value of.
+value (32-bit – immediate, map variable)
+ The value to set the map variable to. Note that map variables can
+ only hold 32-bit values.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Unchanged. |
++---------------+------------+
+| overflow (V) | Unchanged. |
++---------------+------------+
+| zero (Z) | Unchanged. |
++---------------+------------+
+| sign (S) | Unchanged. |
++---------------+------------+
+| unordered (U) | Unchanged. |
++---------------+------------+
+
+.. _umlinst-recover:
+
+RECOVER
+~~~~~~~
+
+Retrieve the value of a map variable at the location of the call
+instruction in the outermost generated code frame. This instruction
+should only be used from within a generated code subroutine. Results
+are undefined if this instruction is executed from outside any
+generated code subroutines.
+
++------------------------+--------------------------------------+
+| Disassembly | Usage |
++========================+======================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| recover dst,mapvar | UML_RECOVER(block, dst, mapvar); |
++------------------------+--------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit – memory, integer register)
+ The destination to copy the value of the map variable to. Note that
+ map variables can only hold 32-bit values.
+mapvar (map variable)
+ The map variable to retrieve the value of from the outermost
+ generated code frame.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+
+.. _umlinst-memaccess:
+
+Emulated memory access
+----------------------
+
+.. _umlinst-read:
+
+READ
+~~~~
+
+Read from an emulated address space. The access mask is implied to have
+all bits set.
+
++---------------------------------+-----------------------------------------------+
+| Disassembly | Usage |
++=================================+===============================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| read dst,addr,space_size | UML_READ(block, dst, addr, size, space); |
+| dread dst,addr,space_size | UML_DREAD(block, dst, addr, size, space); |
++---------------------------------+-----------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value read from the emulated address space
+ will be stored.
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to read from in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+size (access size)
+ The size of the emulated memory access. Must be ``SIZE_BYTE``
+ (8-bit), ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or
+ ``SIZE_QWORD`` (64-bit). Note that this operand controls the size
+ of the emulated memory access while the instruction size sets the
+ size of the ``dst`` operand.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
+
+.. _umlinst-readm:
+
+READM
+~~~~~
+
+Read from an emulated address space with access mask specified.
+
++--------------------------------------+------------------------------------------------------+
+| Disassembly | Usage |
++======================================+======================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| readm dst,addr,mask,space_size | UML_READM(block, dst, addr, mask, size, space); |
+| dreadm dst,addr,mask,space_size | UML_DREADM(block, dst, addr, mask, size, space); |
++--------------------------------------+------------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, integer register)
+ The destination where the value read from the emulated address space
+ will be stored.
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to read from in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+mask (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The access mask for the emulated memory access.
+size (access size)
+ The size of the emulated memory access. Must be ``SIZE_BYTE``
+ (8-bit), ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or
+ ``SIZE_QWORD`` (64-bit). Note that this operand controls the size
+ of the emulated memory access while the instruction size sets the
+ size of the ``dst`` and ``mask`` operands.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
+* Immediate values for the ``mask`` operand are truncated to the access
+ size.
+* Converted to :ref:`READ <umlinst-read>` if the ``mask`` operand is an
+ immediate value with all bits set.
+
+.. _umlinst-write:
+
+WRITE
+~~~~~
+
+Write to an emulated address space. The access mask is implied to have
+all bits set.
+
++---------------------------------+------------------------------------------------+
+| Disassembly | Usage |
++=================================+================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| write addr,src,space_size | UML_WRITE(block, addr, src, size, space); |
+| dwrite addr,src,space_size | UML_DWRITE(block, addr, src, size, space); |
++---------------------------------+------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to write to in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+src (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The value to write to the emulated address space.
+size (access size)
+ The size of the emulated memory access. Must be ``SIZE_BYTE``
+ (8-bit), ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or
+ ``SIZE_QWORD`` (64-bit). Note that this operand controls the size
+ of the emulated memory access while the instruction size sets the
+ size of the ``src`` operand.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
+* Immediate values for the ``src`` operand are truncated to the access
+ size.
+
+.. _umlinst-writem:
+
+WRITEM
+~~~~~~
+
+Write to an emulated address space with access mask specified.
+
++--------------------------------------+-------------------------------------------------------+
+| Disassembly | Usage |
++======================================+=======================================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| writem addr,src,mask,space_size | UML_WRITEM(block, addr, src, mask, size, space); |
+| dwritem addr,src,mask,space_size | UML_DWRITEM(block, addr, src, mask, size, space); |
++--------------------------------------+-------------------------------------------------------+
+
+Operands
+^^^^^^^^
+
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to write to in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+src (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The value to write to the emulated address space.
+mask (32-bit or 64-bit – memory, integer register, immediate, map variable)
+ The access mask for the emulated memory access.
+size (access size)
+ The size of the emulated memory access. Must be ``SIZE_BYTE``
+ (8-bit), ``SIZE_WORD`` (16-bit), ``SIZE_DWORD`` (32-bit) or
+ ``SIZE_QWORD`` (64-bit). Note that this operand controls the size
+ of the emulated memory access while the instruction size sets the
+ size of the ``src`` and ``mask`` operands.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
+* Immediate values for the ``src`` and ``mask`` operands are truncated
+ to the access size.
+* Converted to :ref:`WRITE <umlinst-read>` if the ``mask`` operand is an
+ immediate value with all bits set.
+
+.. _umlinst-fread:
+
+FREAD
+~~~~~
+
+Read a floating point value from an emulated address space. The binary
+value will be preserved even if it is not a valid representation of a
+floating point number. The access mask is implied to have all bits set.
+
++---------------------------------+------------------------------------------+
+| Disassembly | Usage |
++=================================+==========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fsread dst,addr,space_size | UML_FSREAD(block, dst, addr, space); |
+| fdread dst,addr,space_size | UML_FDREAD(block, dst, addr, space); |
++---------------------------------+------------------------------------------+
+
+Operands
+^^^^^^^^
+
+dst (32-bit or 64-bit – memory, floating point register)
+ The destination where the value read from the emulated address space
+ will be stored.
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to read from in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
+
+.. _umlinst-fwrite:
+
+FWRITE
+~~~~~~
+
+Write a floating point value to an emulated address space. The binary
+value will be preserved even if it is not a valid representation of a
+floating point number. The access mask is implied to have all bits set.
+
++---------------------------------+-------------------------------------------+
+| Disassembly | Usage |
++=================================+===========================================+
+| .. code-block:: | .. code-block:: C++ |
+| | |
+| fswrite addr,src,space_size | UML_FSWRITE(block, addr, src, space); |
+| fdwrite addr,src,space_size | UML_FDWRITE(block, addr, src, space); |
++---------------------------------+-------------------------------------------+
+
+Operands
+^^^^^^^^
+
+addr (32-bit – memory, integer register, immediate, map variable)
+ The address to write to in the emulated address space. Note that
+ this is always a 32-bit operand, irrespective of the instruction
+ size.
+src (32-bit or 64-bit – memory, floating point register)
+ The value to write to the emulated address space.
+ will be stored.
+space (address space number)
+ An integer identifying the address space to read from. May be
+ ``SPACE_PROGRAM``, ``SPACE_DATA``, ``SPACE_IO`` or ``SPACE_OPCODES``
+ for one of the common CPU address spaces, or a non-negative integer
+ cast to ``memory_space``.
+
+Flags
+^^^^^
+
++---------------+------------+
+| carry (C) | Undefined. |
++---------------+------------+
+| overflow (V) | Undefined. |
++---------------+------------+
+| zero (Z) | Undefined. |
++---------------+------------+
+| sign (S) | Undefined. |
++---------------+------------+
+| unordered (U) | Undefined. |
++---------------+------------+
+
+Simplification rules
+^^^^^^^^^^^^^^^^^^^^
+
+* Immediate values for the ``addr`` operand are truncated to 32 bits.
diff --git a/docs/source/tools/castool.rst b/docs/source/tools/castool.rst
index b4d8f81467f..73fb095d9b1 100644
--- a/docs/source/tools/castool.rst
+++ b/docs/source/tools/castool.rst
@@ -9,7 +9,7 @@ Castool is part of the MAME project. It shares large portions of code with MAME,
Using Castool
-=============
+-------------
Castool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this:
@@ -30,7 +30,7 @@ Example usage:
Castool Formats
-===============
+---------------
These are the formats supported by Castool for conversion to .WAV files.
diff --git a/docs/source/tools/chdman.rst b/docs/source/tools/chdman.rst
new file mode 100644
index 00000000000..cbf16fcba75
--- /dev/null
+++ b/docs/source/tools/chdman.rst
@@ -0,0 +1,457 @@
+.. _chdman:
+
+chdman – CHD (Compressed Hunks of Data) File Manager
+====================================================
+
+chdman can be used to create, convert, check the integrity of and extract data
+from media images in CHD (Compressed Hunks of Data) format.
+
+The basic usage is ``chdman <command> <option>...``
+
+.. contents:: :local:
+
+
+.. _chdman-commonopts:
+
+Common options
+--------------
+
+The options available depend on the command, but the following options are
+used by multiple commands:
+
+--input <file> / -i <file>
+ Specify the input file. This option is required for most commands. The
+ input file formats supported depend on the command
+--inputparent <chdfile> / -ip <chdfile>
+ Specify the parent CHD file for the input file. This option is supported for
+ most commands that operate on CHD format input files. This option must be
+ used if the input file is a *delta CHD*, storing only the hunks that differ
+ from its parent CHD,
+--inputstartbyte <offset> / -isb <offset>
+ Specify the offset to the data in the input file in bytes. This is useful
+ for creating CHD format files from input files that contain a header before
+ the start of the data, or for extracting partial content from a CHD format
+ file. May not be specified in combination with the
+ ``--inputstarthunk``/``-ish`` option.
+--inputstarthunk <offset> / -ish <offset>
+ Specify the offset to the data in the input file in hunks. May not be
+ specified in combination with the ``--inputstartbyte``/``-isb`` option.
+--inputbytes <length> / -ib <length>
+ Specify the amount of input data to use in bytes, starting from the offset
+ to the data in the input file. This is useful for creating CHD format files
+ from input files that contain additional content after the data, or for
+ extracting partial content from a CHD format file. May not be specified in
+ combination with the ``--inputhunks``/``-ih`` option.
+--inputhunks <length> / -ih <length>
+ Specify the amount of input data to use in hunks, starting from the offset
+ to the data in the input file. May not be specified in combination with the
+ ``--inputbytes``/``-ib`` option.
+--output <file> / -o <file>
+ Specify the output file name. This option is required for commands that
+ produce output files. The output file formats supported depend on the
+ command.
+--outputparent <chdfile> / -op <chdfile>
+ Specify the parent CHD file for the output file. This option is supported
+ for commands that produce CHD format output files. Using this option
+ produces a *delta CHD*, storing only the hunks that differ from its parent
+ CHD. The parent CHD should be the same media type and size, with the same
+ hunk size.
+--compression none|<type>[,<type>]... / -c none|<type>[,<type>]...
+ Specify compression algorithms to use. This option is supported for commands
+ that produce CHD format output files. Specify ``none`` to disable
+ compression, or specify up to four comma-separated compression algorithms.
+ See :ref:`compression algorithms <chdman-compression>` for supported
+ compression algorithms. Compression must be disable to create writable media
+ image files.
+--hunksize <bytes> / -hs <bytes>
+ Specifies the hunk size in bytes. This option is supported for commands that
+ produce CHD format output files. The hunk size must be no smaller than
+ 16 bytes and no larger than 1048576 bytes (1 MiB). The hunk size must be a
+ multiple of the sector size or unit size of the media. Larger hunk sizes may
+ give better compression ratios, but reduce performance for small random
+ reads as an entire hunk needs to be read and decompressed at a time.
+--force / -f
+ Overwrite output files if they already exist. This option is supported for
+ commands that produce output files.
+--verbose / -v
+ Enable verbose output. This prints more detailed information for some
+ commands.
+--numprocessors <count> / -np <count>
+ Limit the maximum number of concurrent threads used for data compression.
+ This option is supported for commands that produce CHD format output files.
+
+
+.. _chdman-commands:
+
+Commands
+--------
+
+info
+~~~~
+
+Display information about a CHD format file. Information includes:
+
+* CHD format version and compression algorithms used.
+* Compressed and uncompressed sizes and overall compression ratio.
+* Hunk size, unit size and number of hunks in the file.
+* SHA1 digests of the data and metadata.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--verbose`` / ``-v``
+
+verify
+~~~~~~
+
+Verify the integrity of a CHD format file. The input file must be a read-only
+CHD format file (the integrity of writable CHD files cannot be verified). Note
+that this command modifies its input file if the ``--fix``/``-f`` option is
+specified.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+
+Additional options:
+
+* ``--fix`` / ``-f``
+
+createraw
+~~~~~~~~~
+
+Create a CHD format file from a raw media image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>``
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+--unitsize <bytes> / -us <bytes> (required)
+ The unit size for the output CHD file in bytes. This is the smallest unit
+ of data that can be addressed within the CHD file. It should match the
+ sector size or page size of the source media. The hunk size must be a whole
+ multiple of the unit size. The unit size must be specified if no parent CHD
+ file for the output is supplied. If a parent CHD file for the output is
+ supplied, the unit size must match the unit size of the parent CHD file.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the unit size not larger than 4 KiB if the unit
+ size is not larger than 4 KiB (4096 bytes).
+* The unit size if it is larger than 4 KiB (4096 bytes).
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac``.
+
+createhd
+~~~~~~~~
+
+Create a CHD format hard disk image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+* ``--sectorsize <bytes>`` / ``-ss <bytes>``
+* ``--size <bytes>`` / ``-s <bytes>``
+* ``--chs <cylinders>,<heads>,<sectors>`` / ``-chs <cylinders>,<heads>,<sectors>``
+* ``--template <template>`` / ``-tp <template>``
+
+Creates a blank (zero-filled) hard disk image if no input file is supplied. The
+input start/length (``--inputstartbyte``/``-isb``,
+``--inputstarthunk``/``-ish``, ``--inputbytes``/``-ib`` and
+``--inputhunks``/``-ih`` options) cannot be used if no input file is supplied.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the sector size not larger than 4 KiB if the
+ sector size is not larger than 4 KiB (4096 bytes).
+* The sector size if it is larger than 4 KiB (4096 bytes).
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac`` if an input file is supplied, or ``none`` if no input
+file is supplied.
+
+createcd
+~~~~~~~~
+
+Create a CHD format CD-ROM image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or eight sectors per hunk (18,816 bytes) otherwise.
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``cdlz,cdzl,cdfl``.
+
+createdvd
+~~~~~~~~~
+
+Create a CHD format DVD-ROM image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or two sectors per hunk (4096 bytes) otherwise.
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac``.
+
+createld
+~~~~~~~~
+
+Create a CHD format LaserDisc image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+* ``--inputstartframe <offset>`` / ``-isf <offset>``
+* ``--inputframes <length>`` / ``-if <length>``
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``avhu``.
+
+extractraw
+~~~~~~~~~~
+
+Extract data from a CHD format raw media image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extracthd
+~~~~~~~~~
+
+Extract data from a CHD format hard disk image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extractcd
+~~~~~~~~~
+
+Extract data from a CHD format CD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--outputbin <file>`` / ``-ob <file>``
+* ``--splitbin`` / ``-sb``
+
+extractdvd
+~~~~~~~~~~
+
+Extract data from a CHD format DVD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extractld
+~~~~~~~~~
+
+Extract data from a CHD format DVD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--inputstartframe <offset>`` / ``-isf <offset>``
+* ``--inputframes <length>`` / ``-if <length>``
+
+addmeta
+~~~~~~~
+
+Add a metadata item to a CHD format file. Note that this command modifies its
+input file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+* ``--valuetext <text>`` / ``-vt <text>``
+* ``--valuefile <file>`` / ``-vf <file>``
+* ``--nochecksum`` / ``-nocs``
+
+delmeta
+~~~~~~~
+
+Delete a metadata item from a CHD format file. Note that this command modifies
+its input file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+
+dumpmeta
+~~~~~~~~
+
+Extract metadata items from a CHD format file to the standard output or to a
+file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>``
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+
+listtemplates
+~~~~~~~~~~~~~
+
+List available hard disk templates. This command does not accept any options.
+
+
+.. _chdman-compression:
+
+Compression algorithms
+----------------------
+
+The following compression algorithms are supported:
+
+zlib – zlib deflate
+ Compresses data using the zlib deflate algorithm.
+zstd – Zstandard
+ Compresses data using the Zstandard algorithm. This gives very good
+ compression and decompression performance with better compression ratios than
+ zlib deflate, but older software may not support CHD files that use Zstandard
+ compression.
+lzma – Lempel-Ziv-Markov chain algorithm
+ Compresses data using the Lempel-Ziv-Markov-chain algorithm (LZMA). This
+ gives high compression ratios at the cost of poor compression and
+ decompression performance.
+huff – Huffman coding
+ Compresses data using 8-bit Huffman entropy coding.
+flac – Free Lossless Audio Codec
+ Compresses data as two-channel (stereo) 16-bit 44.1 kHz PCM audio using the
+ Free Lossless Audio Codec (FLAC). This gives good compression ratios if the
+ media contains 16-bit PCM audio data.
+cdzl – zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the zlib deflate algorithm.
+cdzs – Zstandard for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Zstandard algorithm. This gives very good compression and
+ decompression performance with better compression ratios than zlib deflate,
+ but older software may not support CHD files that use Zstandard compression.
+cdlz - Lempel-Ziv-Markov chain algorithm/zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Lempel-Ziv-Markov chain algorithm (LZMA) for audio data and the
+ zlib deflate algorithm for subchannel data. This gives high compression
+ ratios at the cost of poor compression and decompression performance.
+cdfl – Free Lossless Audio Codec/zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Free Lossless Audio Codec (FLAC) for audio data and the zlib
+ deflate algorithm for subchannel data. This gives good compression ratios
+ for audio CD tracks.
+avhu – Huffman coding for audio-visual data
+ This is a specialised compression algorithm for audio-visual (A/V) data. It
+ should only be used for LaserDisc CHD files.
diff --git a/docs/source/tools/floptool.rst b/docs/source/tools/floptool.rst
index f2e24eac56f..bf71c296aee 100644
--- a/docs/source/tools/floptool.rst
+++ b/docs/source/tools/floptool.rst
@@ -9,7 +9,7 @@ Floptool is part of the MAME project. It shares large portions of code with MAME
Using Floptool
-==============
+--------------
Floptool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this:
@@ -33,7 +33,7 @@ Example usage:
Floptool Formats
-================
+----------------
These are the formats supported by Floptool for conversion to other formats.
diff --git a/docs/source/tools/imgtool.rst b/docs/source/tools/imgtool.rst
index 7efa850ca93..e54638ea59b 100644
--- a/docs/source/tools/imgtool.rst
+++ b/docs/source/tools/imgtool.rst
@@ -10,7 +10,7 @@ Imgtool is part of the MAME project. It shares large portions of code with MAME,
**Some portions of Imgtool are 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:
@@ -32,7 +32,7 @@ Further details vary with each subcommand. Also note that not all subcommands a
Imgtool Subcommands
-===================
+-------------------
**create**
@@ -151,7 +151,7 @@ Imgtool Subcommands
Imgtool 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, the following filters are supported:
diff --git a/docs/source/tools/index.rst b/docs/source/tools/index.rst
index 6d0551bf1d1..4086f924b99 100644
--- a/docs/source/tools/index.rst
+++ b/docs/source/tools/index.rst
@@ -1,12 +1,14 @@
MAME External Tools
--------------------
+===================
-This section covers various extra tools that come with your MAME distribution (e.g. *imgtool*)
+This section describes additional tools that are built alongside and typically
+distributed with MAME.
.. toctree::
- :titlesonly:
+ :titlesonly:
- imgtool
- castool
- floptool
- othertools
+ chdman
+ imgtool
+ castool
+ floptool
+ othertools
diff --git a/docs/source/tools/othertools.rst b/docs/source/tools/othertools.rst
index ebf31719d16..5a24dc6c5bb 100644
--- a/docs/source/tools/othertools.rst
+++ b/docs/source/tools/othertools.rst
@@ -25,38 +25,40 @@ This tool is used in regression testing to compare PNG screenshot results with t
nltool
------
-Discrete component conversion tool. Most users will not need to work with this.
+Discrete component conversion tool.
+
nlwav
-----
-Discrete component conversion and testing tool. Most users will not need to work with this.
+Discrete component conversion and testing tool.
jedutil
-------
-PAL/PLA/PLD/GAL dump handling tool. It can convert between the industry-standard JED format and MAME's proprietary packed binary format and it can show logic equations for the types of devices it knows the internal logic of. Most users will not need to work with this.
+PAL/PLA/PLD/GAL dump handling tool. It can convert between the industry-standard JED format and MAME's proprietary packed binary format and it can show logic equations for the types of devices it knows the internal logic of.
ldresample
----------
-This tool recompresses video data for laserdisc and VHS dumps. Most users will not need to work with this.
+This tool recompresses video data for laserdisc and VHS dumps.
+
ldverify
--------
-This tool is used for comparing laserdisc or VHS CHD images with the source AVI. Most users will not need to work with this.
+This tool is used for comparing laserdisc or VHS CHD images with the source AVI.
romcmp
------
-This tool is used to perform basic data comparisons and integrity checks on binary dumps. With the -h switch, it can also be used to calculate hash functions. Most users will not need to work with this.
+This tool is used to perform basic data comparisons and integrity checks on binary dumps. With the -h switch, it can also be used to calculate hash functions.
unidasm
-------
-Universal disassembler for many of the architectures supported in MAME. Most users will not need to work with this.
+Universal disassembler for many of the architectures supported in MAME.
diff --git a/docs/source/usingmame/defaultkeys.rst b/docs/source/usingmame/defaultkeys.rst
index f7a7e8ba682..9892c86cb1f 100644
--- a/docs/source/usingmame/defaultkeys.rst
+++ b/docs/source/usingmame/defaultkeys.rst
@@ -72,13 +72,6 @@ and saving/loading save states.
**Delete**
Clear/reset to default when highlighting an entry on the input
configuration, cheat options, and plugin options pages.
-**P**
- Pauses the emulated machine.
-**Left Shift+P**
- While paused, advances to next frame. If rewind is enabled, a new rewind
- save state is also captured.
-**Left Shift+~**
- While paused, loads the most recent rewind save state.
**F1**
Power the machine on for machines that have specific power button behavior.
**F2**
@@ -134,18 +127,20 @@ and saving/loading save states.
* **Enter** - switch to palette/colortable mode.
Note: Not all systems have decoded graphics and/or tilemaps.
-**Left Ctrl+F5**
- Toggle Filter.
- (*SDL MAME only*)
-**Left Alt+Left Ctrl+F5**
- Toggle HLSL Post-Processing.
- (*Windows non-SDL MAME only*)
+**Left Shift+F4**
+ While paused, loads the most recent rewind save state.
+**F5**
+ Pauses the emulated machine.
+**Left Shift+F5**
+ While paused, advances to next frame. If rewind is enabled, a new rewind
+ save state is also captured.
**F6**
- Toggle cheat mode. (if started with “-cheat”)
-**Left Ctrl+F6**
- Decrease Prescaling.
-**Left Ctrl+F7**
- Increase Prescaling.
+ Create a save state. Requires an additional keypress to identify the state,
+ similar to the load option above. If an existing save state is present, it
+ will also appear in the selection menu to allow overwriting of that save
+ state.
+**Left Shift+F6**
+ Create a quick save state.
**F7**
Load a save state. You will be prompted to press a key or select from the
menu to determine which save state you wish to load.
@@ -155,16 +150,27 @@ and saving/loading save states.
receive a warning that the save state may not be valid when attempting to
save or load.*
**Left Shift+F7**
- Create a save state. Requires an additional keypress to identify the state,
- similar to the load option above. If an existing save state is present, it
- will also appear in the selection menu to allow overwriting of that save
- state.
+ Load a quick save state.
**F8**
Decrease frame skipping on the fly.
+**Left Shift+F8**
+ Toggle cheat mode. (if started with “-cheat”)
+**Left Alt+F8**
+ Decrease Prescaling.
+ (*SDL MAME only*)
**F9**
Increase frame skipping on the fly.
+**Left Alt+F9**
+ Increase Prescaling.
+ (*SDL MAME only*)
**F10**
Toggle speed throttling.
+**Left Alt+F10**
+ Toggle HLSL Post-Processing.
+ (*Windows non-SDL MAME only*)
+**Left Alt+F10**
+ Toggle Filter.
+ (*SDL MAME only*)
**F11**
Toggles speed display.
**Left Shift+F11**
@@ -179,14 +185,9 @@ and saving/loading save states.
Begin recording AVI video.
**Left Alt+F12**
Take HLSL Rendered Snapshot.
-**Insert**
+**Insert** (Windows non-SDL MAME)/**Page Down** (SDL MAME)
Fast forward. While held, runs game with throttling disabled and with the
maximum frameskip.
- (*Windows non-SDL MAME only*)
-**Page Down**
- Fast forward. While held, runs game with throttling disabled and with the
- maximum frameskip.
- (*SDL MAME only*)
**Left Alt+Enter**
Toggles between full-screen and windowed mode.
**Scroll Lock**/**Forward Delete** (Mac Desktop)/**fn-Delete** (Mac Laptop)
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index 9bae9407acc..963bb42ecae 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -27,7 +27,7 @@ settings.
Emulated system inputs are ignored while menus are displayed. You can still
pause or resume the running system while most menus are displayed by pressing
-the **Pause** key or button (**P** on the keyboard by default).
+the **Pause** key or button (**F5** on the keyboard by default).
If you start MAME without specifying a system on the command line, the system
selection menu will be shown (assuming the
@@ -110,6 +110,14 @@ Network Devices
Shows the Network Devices menu, where you can set up emulated network
adapters that support bridging to a host network. This item is not shown if
there are no network adaptors that support bridging in the running system.
+Audio Mixer
+ Shows the :ref:`Audio Mixer <menus-audiomixer>` menu, where you
+ decide how to connect your system audio inputs and outputs to the
+ emulated system's microphones and speakers.
+Audio Effects
+ Shows the :ref:`Audio Effects <menus-audioeffects>` menu, which
+ allows to configure the audio effects applied between the emulated
+ system's speakers and the actual system audio outputs.
Slider Controls
Shows the Slider Controls menu, where you can adjust various settings,
including video adjustments and individual sound channel levels.
@@ -285,3 +293,113 @@ graphical form below the menu. Digital control states are either zero
ID** to copy the device’s ID to the clipboard. This is useful for setting up
:ref:`stable controller IDs <devicemap>` in :ref:`controller configuration files
<ctrlrcfg>`.
+
+
+.. _menus-audiomixer:
+
+Audio Mixer menu
+----------------
+
+The Audio Mixer menu allows to establish connections between emulated
+speakers and microphones, and system audio inputs and outputs. It
+uses the standard up/down arrows to select a device and/or current
+mapping, left/right arrows to change a value (system audio port,
+level, channel...) and [ ] to change column. In addition the (by
+default) F key adds a full mapping, C a channel mapping, and Delete
+clears a mapping.
+
+A full mapping sends all channels of a speaker to the appropriate(s)
+channel(s) of the system output, and similarly retrieves all channels
+of a microphone from the appropriate(s) input(s) of a system input.
+For instance a mono speaker will send audio to both channels of a
+stereo system output.
+
+A channel mapping maps between one channel of speaker or a microphone
+and one channel of a system input or output. It can be a little
+tedious, but it allows for instance to take two mono speakers and turn
+it into the left and right channels of a system output, which is
+useful for some cabinets.
+
+Every mapping has a configurable volume associated. When changing the
+volume, optionally hold shift/ctrl/alt keys to adjust the step amount.
+
+The mapping configuration is saved in the system cfg file.
+
+Some OSes propose an external interface to change mappings and volumes
+dynamically, for instance pipewire on linux. Mame does its best to
+follow that and keep the information in the cfg file for future runs.
+
+
+.. _menus-audioeffects:
+
+Audio Effects menu
+------------------
+
+This menu allows to configure the audio effects that are applied to
+the speaker outputs between the speaker device and the audio mixer.
+In other words, the output channels as seen in the audio mixer are the
+outputs of the effect chains. Each speaker has an independant effect
+chain applied.
+
+The chain itself is not configurable it is always in order:
+
+* Filter
+* Compressor
+* Reverb
+* EQ
+
+The parameters of each are fully configurable though. A configured
+parameter shows as white, a default as grey, and Clear allows to go
+back to the default value. The default parameters for the chain of a
+given speaker are the parameters of the Default chain, and the default
+parameters of the Default chain are fixed. The default chain allows
+to create a global setup that one likes and have it applied everywhere
+by default.
+
+In addition, this menu allows to choose the resampler to use when
+converting sample rates between emulated devices. The type allows to
+choose between a fast, lower quality one, "LoFi", and a slow, high
+quality one "HQ". The HQ resampler is configurable. The latency
+indicates the max latency of the resampler, which allows better
+quality when higher, the filter length balances quality and speed
+where a high value is highest quality but slowest speed, and phases
+balances quality and resampler creation time, with one again higher
+means better but slower.
+
+
+Filter effect
+~~~~~~~~~~~~~
+
+This effect proposes an order-2 high-pass and order-2 low-pass filter.
+The high-pass filter allows to remove the DC offset some emulated
+hardware has which can create saturation when not needed. The
+low-pass filter (defaulting to off) allows to reproduce how muffled
+the sound of a number of cabinets and TVs were.
+
+The Q factor defines how sharp the transition is, the higher the
+sharper. Over 0.7 the filter starts amplifying the frequencies around
+the cutoff though, which can be surprising.
+
+
+Compression effect
+~~~~~~~~~~~~~~~~~~
+
+Not implemented yet.
+
+
+Reverb effect
+~~~~~~~~~~~~~
+
+Not implemented yet.
+
+
+EQ effect
+~~~~~~~~~
+
+The 5-band parametric equalizer allows to amplify or reduce certain
+bands of frequency in the spectrum. The three middle filters, and
+also the extreme ones if configured as "Peak", change frequencies
+around the cutoff. The Q factor selects the sharpness of the peak,
+the higher the sharper. The extreme filters in "Shelf" mode move all
+the frequencies under (or over) the cutoff frequency.
+
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index 60bb55618a2..94c7eba413d 100644
--- a/docs/source/usingmame/ui.rst
+++ b/docs/source/usingmame/ui.rst
@@ -136,9 +136,9 @@ pointing device:
* Click menu items to highlight them.
* Double-click menu items to select them.
* Click the left- or right-pointing triangle to adjust settings.
-* For menus with too many items to fit on the screen, click the upward- or
- downward-pointing triangle at the top or bottom to scroll up or down by one
- screen at a time.
+* For menus or text boxes with too many items or lines to fit on the screen,
+ press on the upward- or downward-pointing triangle at the top or bottom to
+ scroll up or down.
* Use vertical scrolling gestures to scroll menus or text boxes with too many
items or lines to fit on the screen.
* Click toolbar items to select them, or hover over them to see a description.
@@ -148,6 +148,28 @@ combinations to the **Show/Hide Menu**, **Pause**, **UI Back** and/or
**UI Cancel** inputs to make it possible to use MAME without a keyboard.
+.. _ui-menus-touch:
+
+Using a touch screen
+~~~~~~~~~~~~~~~~~~~~
+
+MAME has basic support for navigating menus using a touch screen:
+
+* Tap menu items to highlight them.
+* Double-tap menu items to select them.
+* Swipe left or right (horizontally) on the highlighted menu item to adjust the
+ setting if applicable.
+* Swipe up or down (vertically) to scroll menus or text boxes with too many
+ items to fit on the screen.
+* For menus or text boxes with too many items or lines to fit on the screen,
+ press on the upward- or downward-pointing triangle at the top or bottom to
+ scroll up or down.
+
+Note that for SDL-based MAME, the
+:ref:`enable_touch <mame-scommandline-enabletouch>` option must be switched on
+to use touch screen support.
+
+
.. _ui-inptcfg:
Configuring inputs
@@ -493,6 +515,8 @@ or info source with left/right. When focus is on the info/image tabs,
left/right switch between tabs. When focus is on the image/info tabs or source,
you can scroll the info using up, down, page up, page down, home and end.
+You can move focus to an area by clicking on it with the middle mouse button.
+
.. _ui-simpleselmenu:
diff --git a/docs/source/whatis.rst b/docs/source/whatis.rst
index b7b9e11c4a9..9e6218042dc 100644
--- a/docs/source/whatis.rst
+++ b/docs/source/whatis.rst
@@ -19,7 +19,7 @@ that were its initial focus.
|
| **MAME®**
-| **Copyright © 1997-2023 MAMEdev and contributors**
+| **Copyright © 1997-2025 MAMEdev and contributors**
| **MAME is a registered trademark of Gregory Ember**
|