diff options
author | 2020-12-16 02:18:52 +1100 | |
---|---|---|
committer | 2020-12-16 02:18:52 +1100 | |
commit | 503332a9867f9aa27fc77cd9e762626d22d213ef (patch) | |
tree | e60fba6664a3d980d5f62846982bde381a25c3f7 /docs/source/techspecs | |
parent | b5f78fe38358b68fc54416328f764cf4e2bf3333 (diff) |
-Lua cleanup and documentation migration checkpoint.
* Cleaned up some more of the Lua inteface. Mostly replacing methods
with properties, some consistency fixes, a few renames, some more
exposed functionality, and a couple of properties that have no
business being set from scripts made read-only.
* Moved a lot more Lua documentation out of source comments into the
documentation, and expanded on it in the process.
* Got more UI code out of the input manager.
* Changed input sequence poller to a polymorphic class where you
specify your intention upfront.
* Changed the cheat plugin to use UI Clear to clear hotkey assignments
and leave them unchanged if the user starts assignment but doesn't
press any switches.
* Ported AJR's fix for over-eager double-click recognition from SDL to
Windows OSD.
-goldnpkr.cpp: Cleaned up inputs, using standard keyout and payout types
and key assignments.
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r-- | docs/source/techspecs/luareference.rst | 1195 | ||||
-rw-r--r-- | docs/source/techspecs/memory.rst | 2 |
2 files changed, 1194 insertions, 3 deletions
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst index ac606f02293..c61939daf0b 100644 --- a/docs/source/techspecs/luareference.rst +++ b/docs/source/techspecs/luareference.rst @@ -58,6 +58,989 @@ c:index_of(v) value. +.. _luareference-mem: + +Memory system +------------- + +MAME’s Lua interface exposes various memory system objects, including address +spaces, memory shares, memory banks, and memory regions. Scripts can read from +and write to the emulated memory system. + +.. _luareference-mem-manager: + +Memory manager +~~~~~~~~~~~~~~ + +Wraps MAME’s ``memory_manager`` class, which allows the memory shares, banks and +regions in a system to be enumerated. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():memory() + Gets the global memory manager instance for the emulated system. + +Properties +^^^^^^^^^^ + +memory.shares[] + The :ref:`memory shares <luareference-mem-share>` in the system, indexed by + absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all + other supported operations have O(1) complexity. +memory.banks[] + The :ref:`memory banks <luareference-mem-bank>` in the system, indexed by + absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all + other supported operations have O(1) complexity. +memory.regions[] + The :ref:`memory regions <luareference-mem-region>` in the system, indexed + by absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; + all other supported operations have O(1) complexity. + +.. _luareference-mem-space: + +Address space +~~~~~~~~~~~~~ + +Wraps MAME’s ``address_space`` class, which represent’s an address space +belonging to a device. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag].spaces[name] + Gets the address space with the specified name for a given device. Note + that names are specific to the device type. + +Methods +^^^^^^^ + +space:read_i{8,16,32,64}(addr) + Reads a signed integer value of the size in bits from the specified address. +space:read_u{8,16,32,64}(addr) + Reads an unsigned integer value of the size in bits from the specified + address. +space:write_i{8,16,32,64}(addr, val) + Writes a signed integer value of the size in bits to the specified address. +space:write_u{8,16,32,64}(addr, val) + Writes an unsigned integer value of the size in bits to the specified + address. +space:readv_i{8,16,32,64}(addr) + Reads a signed integer value of the size in bits from the specified virtual + address. The address is translated with the debug read intent. Returns + zero if address translation fails. +space:readv_u{8,16,32,64}(addr) + Reads an unsigned integer value of the size in bits from the specified + virtual address. The address is translated with the debug read intent. + Returns zero if address translation fails. +space:writev_i{8,16,32,64}(addr, val) + Writes a signed integer value of the size in bits to the specified virtual + address. The address is translated with the debug write intent. Does not + write if address translation fails. +space:writev_u{8,16,32,64}(addr, val) + Writes an unsigned integer value of the size in bits to the specified + virtual address. The address is translated with the debug write intent. + Does not write if address translation fails. +space:read_direct_i{8,16,32,64}(addr) + Reads a signed integer value of the size in bits from the specified address + one byte at a time by obtaining a read pointer for each byte address. If + a read pointer cannot be obtained for a byte address, the corresponding + result byte will be zero. +space:read_direct_u{8,16,32,64}(addr) + Reads an unsigned integer value of the size in bits from the specified + address one byte at a time by obtaining a read pointer for each byte + address. If a read pointer cannot be obtained for a byte address, the + corresponding result byte will be zero. +space:write_direct_i{8,16,32,64}(addr, val) + Writes a signed integer value of the size in bits to the specified address + one byte at a time by obtaining a write pointer for each byte address. If + a write pointer cannot be obtained for a byte address, the corresponding + byte will not be written. +space:write_direct_u{8,16,32,64}(addr, val) + Writes an unsigned integer value of the size in bits to the specified + address one byte at a time by obtaining a write pointer for each byte + address. If a write pointer cannot be obtained for a byte address, the + corresponding byte will not be written. +space:read_range(start, end, width, [step]) + Reads a range of addresses as a binary string. The end address must be + greater than or equal to the start address. The width must be 8, 16, 30 or + 64. If the step is provided, it must be a positive number of elements. + +Properties +^^^^^^^^^^ + +space.name (read-only) + The display name for the address space. +space.shift (read-only) + The address address granularity for the address space specified as the shift + required to translate a byte address to a native address. Positive values + shift towards the most significant bit (left) and negative values shift + towards the least significant bit (right). +space.index (read-only) + The zero-based space index. Some space indices have special meanings for + the debugger. +space.address_mask (read-only) + The address mask for the space. +space.data_width (read-only) + The data width for the space in bits. +space.endianness (read-only) + The Endianness of the space (``"big"`` or ``"little"``). +space.map (read-only) + The configured :ref:`address map <luareference-mem-map>` for the space or + ``nil``. + +.. _luareference-mem-map: + +Address map +~~~~~~~~~~~ + +Wraps MAME’s ``address_map`` class, used to configure handlers for an address +space. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag].spaces[name].map + Gets the configured address map for an address space, or ``nil`` if no map + is configured. + +Properties +^^^^^^^^^^ + +map.spacenum (read-only) + The address space number of the address space the map is associated with +map.device (read-only) + The device that owns the address space the map is associated with. +map.unmap_value (read-only) + The constant value to return from unmapped reads. +map.global_mask (read-only) + Global mask to be applied to all addresses when accessing the space. +map.entries[] (read-only) + The configured :ref:`entries <luareference-mem-mapentry>` in the address + map. Uses 1-based integer indices. The index operator and the ``at`` + method have O(n) complexity. + +.. _luareference-mem-mapentry: + +Address map entry +~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``address_map_entry`` class, representing an entry in a configured +address map. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag].spaces[name].map.entries[index] + Gets an entry from the configured map for an address space. + +Properties +^^^^^^^^^^ + +entry.address_start (read-only) + Start address of the entry’s range. +entry.address_end (read-only) + End address of the entry’s range (inclusive). +entry.address_mirror (read-only) + Address mirror bits. +entry.address_end (read-only) + Address mask bits. Only valid for handlers. +entry.mask (read-only) + Lane mask, indicating which data lines on the bus are connected to the + handler. +entry.cswidth (read-only) + The trigger width for a handler that isn’t connected to all the data lines. +entry.read (read-only) + :ref:`Additional data <luareference-memory-handlerdata>` for the read + handler. +entry.write (read-only) + :ref:`Additional data <luareference-memory-handlerdata>` for the write + handler. +entry.share (read-only) + Memory share tag for making RAM entries accessible or ``nil``. +entry.address_end (read-only) + Explicit memory region tag for ROM entries, or ``nil``. +entry.region_offset (read-only) + Starting offset in memory region for ROM entries. + +.. _luareference-memory-handlerdata: + +Address map handler data +~~~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``map_handler_data`` class, which provides configuration data to +handlers in address maps. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag].spaces[name].map.entries[index].read + Gets the read handler data for an address map entry. +manager:machine().devices[tag].spaces[name].map.entries[index].write + Gets the write handler data for an address map entry. + +Properties +^^^^^^^^^^ + +data.handlertype (read-only) + Handler type. Will be one of ``"none"``, ``"ram"``, ``"rom"``, ``"nop"``, + ``"unmap"``, ``"delegate"``, ``"port"``, ``"bank"``, ``"submap"``, or + ``"unknown"``. Note that multiple handler type values can yield + ``"delegate"`` or ``"unknown"``. +data.bits (read-only) + Data width for the handler in bits. +data.name (read-only) + Display name for the handler, or ``nil``. +data.tag (read-only) + Tag for I/O ports and memory banks, or ``nil``. + +.. _luareference-mem-share: + +Memory share +~~~~~~~~~~~~ + +Wraps MAME’s ``memory_share`` class, representing a named allocated memory zone. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():memory().shares[tag] + Gets a memory share by absolute tag, or ``nil`` if no such memory share + exists. +manager:machine().devices[tag]:memshare(tag) + Gets a memory share by tag relative to a device, or ``nil`` if no such + memory share exists. + +Methods +^^^^^^^ + +share:read_i{8,16,32,64}(offs) + Reads a signed integer value of the size in bits from the specified offset + in the memory share. +share:read_u{8,16,32,64}(offs) + Reads an unsigned integer value of the size in bits from the specified + offset in the memory share. +share:write_i{8,16,32,64}(offs, val) + Writes a signed integer value of the size in bits to the specified offset in + the memory share. +share:write_u{8,16,32,64}(offs, val) + Writes an unsigned integer value of the size in bits to the specified offset + in the memory share. + +Properties +^^^^^^^^^^ + +share.tag (read-only) + The absolute tag of the memory share. +share.size (read-only) + The size of the memory share in bytes. +share.length (read-only) + The length of the memory share in native width elements. +share.endianness (read-only) + The Endianness of the memory share (``"big"`` or ``"little"``). +share.bitwidth (read-only) + The native element width of the memory share in bits. +share.bytewidth (read-only) + The native element width of the memory share in bytes. + +.. _luareference-mem-bank: + +Memory bank +~~~~~~~~~~~ + +Wraps MAME’s ``memory_bank`` class, representing a named memory zone +indirection. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():memory().banks[tag] + Gets a memory region by absolute tag, or ``nil`` if no such memory bank + exists. +manager:machine().devices[tag]:membank(tag) + Gets a memory region by tag relative to a device, or ``nil`` if no such + memory bank exists. + +Properties +^^^^^^^^^^ + +bank.tag (read-only) + The absolute tag of the memory bank. +bank.entry (read/write) + The currently selected zero-based entry number. + +.. _luareference-mem-region: + +Memory region +~~~~~~~~~~~~~ + +Wraps MAME’s ``memory_region`` class, representing a memory region used to store +read-only data like ROMs or the result of fixed decryptions. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():memory().regions[tag] + Gets a memory region by absolute tag, or ``nil`` if no such memory region + exists. +manager:machine().devices[tag]:memregion(tag) + Gets a memory region by tag relative to a device, or ``nil`` if no such + memory region exists. + +Methods +^^^^^^^ + +region:read_i{8,16,32,64}(offs) + Reads a signed integer value of the size in bits from the specified offset + in the memory region. +region:read_u{8,16,32,64}(offs) + Reads an unsigned integer value of the size in bits from the specified + offset in the memory region. +region:write_i{8,16,32,64}(offs, val) + Writes a signed integer value of the size in bits to the specified offset in + the memory region. +region:write_u{8,16,32,64}(offs, val) + Writes an unsigned integer value of the size in bits to the specified offset + in the memory region. + +Properties +^^^^^^^^^^ + +region.tag (read-only) + The absolute tag of the memory region. +region.size (read-only) + The size of the memory region in bytes. +region.length (read-only) + The length of the memory region in native width elements. +region.endianness (read-only) + The Endianness of the memory region (``"big"`` or ``"little"``). +region.bitwidth (read-only) + The native element width of the memory region in bits. +region.bytewidth (read-only) + The native element width of the memory region in bytes. + + +.. _luareference-input: + +Input system +------------ + +Allows scripts to get input from the user, and access I/O ports in the emulated +system. + +.. _luareference-input-ioportman: + +I/O port manager +~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O +ports and handles input configuration. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport() + Gets the global I/O port manager instance for the emulated machine. + +Methods +^^^^^^^ + +ioport:count_players() + Returns the number of player controllers in the system. +ioport:type_group(type, player) + Returns the I/O port group for the specified I/O port type and player + number. The I/O port type is an enumerated value. The player number is a + zero-based index. Returns an integer giving the grouping for the input. + + This should be called with values obtained from I/O port fields to provide + canonical grouping in an input configuration UI. +ioport:type_seq(type, player, seqtype) + Get the configured input sequence for the specified input type, player and + sequence type. The sequence type must be ``"standard"``, ``"increment"`` + or ``"decrement"``. This provides access to general input configuration. + +Properties +^^^^^^^^^^ + +ioport.ports[] + Gets the emulated :ref:`I/O ports <luareference-input-ioport>` in the + system. Keys are absolute tags. The ``at`` and ``index_of`` methods have + O(n) complexity; all other supported operations have O(1) complexity. +ioport.natkeyboard + Gets the :ref:`natural keyboard manager <luareference-input-natkbd>`, used + for controlling keyboard and keypad input to the emulated system. + +.. _luareference-input-natkbd: + +Natural keyboard manager +~~~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and +keypad inputs. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport().natkeyboard + Gets the global natural keyboard manager instance for the emulated machine. + +Methods +^^^^^^^ + +natkeyboard:post(text) + Post literal text to the emulated machine. The machine must have keyboard + inputs with character bindings, and the correct keyboard input device must + be enabled. +natkeyboard:post_coded(text) + Post text to the emulated machine. Brace-enclosed codes are interpreted in + the text. The machine must have keyboard inputs with character bindings, + and the correct keyboard input device must be enabled. + + The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``, + ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``, + ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``, + ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``, + ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``. +natkeyboard:paste() + Post the contents of the host clipboard to the emulated machine. The + machine must have keyboard inputs with character bindings, and the correct + keyboard input device must be enabled. +natkeyboard:dump() + Returns a string with a human-readable description of the keyboard and + keypad input devices in the system, whether they are enabled, and their + character bindings. + +Properties +^^^^^^^^^^ + +natkeyboard.empty (read-only) + A Boolean indicating whether the natural keyboard manager’s input buffer is + empty. +natkeyboard.full (read-only) + A Boolean indicating whether the natural keyboard manager’s input buffer is + full. +natkeyboard.can_post (read-only) + A Boolean indicating whether the emulated system supports posting character + data via the natural keyboard manager. +natkeyboard.is_posting (read-only) + A Boolean indicating whether posted character data is currently being + delivered to the emulated system. +natkeyboard.in_use (read/write) + A Boolean indicating whether “natural keyboard” mode is enabled. When + “natural keyboard” mode is enabled, the natural keyboard manager translates + host character input to emulated system keystrokes. +natkeyboard.keyboards[] + Gets the :ref:`keyboard/keypad input devices <luareference-input-kbddev>` in + the emulated system, indexed by absolute device tag. Index get has O(n) + complexity; all other supported operations have O(1) complexity. + +.. _luareference-input-kbddev: + +Keyboard input device +~~~~~~~~~~~~~~~~~~~~~ + +Represents a keyboard or keypad input device managed by the +:ref:`natural keyboard manager <luareference-input-natkbd>`. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport().natkeyboard.keyboards[tag] + Gets the keyboard input device with the specified tag, or ``nil`` if the tag + does not correspond to a keyboard input device. + +Properties +^^^^^^^^^^ + +keyboard.device (read-only) + The underlying device. +keyboard.tag (read-only) + The absolute tag of the underlying device. +keyboard.basetag (read-only) + The last component of the tag of the underlying device, or ``"root"`` for + the root machine device. +keyboard.name (read-only) + The human-readable description of the underlying device type. +keyboard.shortname (read-only) + The identifier for the underlying device type. +keyboard.is_keypad (read-only) + A Boolean indicating whether the underlying device has keypad inputs but no + keyboard inputs. This is used when determining which keyboard input devices + should be enabled by default. +keyboard.enabled (read/write) + A Boolean indicating whether the device’s keyboard and/or keypad inputs are + enabled. + +.. _luareference-input-ioport: + +I/O port +~~~~~~~~ + +Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport().ports[tag] + Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not + correspond to an I/O port. +manager:machine().devices[devtag]:ioport(porttag) + Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such + I/O port exists. + +Methods +^^^^^^^ + +port:read() + Read the current input value. Returns a 32-bit integer. +port:write(value, mask) + Write to the I/O port output fields that are set in the specified mask. The + value and mask must be 32-bit integers. Note that this does not set values + for input fields. +port:field(mask) + Get the first :ref:`I/O port field <luareference-input-field>` corresponding + to the bits that are set in the specified mask, or ``nil`` if there is no + corresponding field. + +Properties +^^^^^^^^^^ + +port.device (read-only) + The device that owns the I/O port. +port.tag (read-only) + The absolute tag of the I/O port +port.active (read-only) + A mask indicating which bits of the I/O port correspond to active fields + (i.e. not unused or unassigned bits). +port.live (read-only) + The live state of the I/O port. +port.fields[] (read-only) + Gets a table of :ref:`fields <luareference-input-field>` indexed by name. + +.. _luareference-input-field: + +I/O port field +~~~~~~~~~~~~~~ + +Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport().ports[tag]:field[mask] + Gets a field for the given port by bit mask. +manager:machine():ioport().ports[tag].fields[name] + Gets a field for the given port by display name. + +Methods +^^^^^^^ + +field:set_value(value) + Set the value of the I/O port field. For digital fields, the value is + compared to zero to determine whether the field should be active; for + analog fields, the value must be right-aligned and in the correct range. +field:set_input_seq(seqtype, seq) + Set the input sequence for the specified sequence type. This is used to + configure per-machine input settings. The sequence type must be + ``"standard"``, ``"increment"`` or ``"decrement"``. +field:input_seq(seq_type) + Get the configured input sequence for the specified sequence type. This + gets per-machine input settings. The sequence type must be ``"standard"``, + ``"increment"`` or ``"decrement"``. +field:set_default_input_seq(seq_type, seq) + Set the default input sequence for the specified sequence type. This is + used to configure general input settings. The sequence type must be + ``"standard"``, ``"increment"`` or ``"decrement"``. +field:default_input_seq(seq_type) + Gets the default input sequence for the specified sequence type. This is + gets general input settings. The sequence type must be ``"standard"``, + ``"increment"`` or ``"decrement"``. +field:keyboard_codes(shift) + Gets a table of characters corresponding to the field for the specified + shift state. The shift state is a bit mask of active shift keys. + +Properties +^^^^^^^^^^ + +field.device (read-only) + The device that owns the port that the field belongs to. +field.port (read-only) + The :ref:`I/O port <luareference-input-ioport>` that the field belongs to. +field.live (read-only) + The :ref:`live state <luareference-input-fieldlive>` of the field. +field.type (read-only) + The input type of the field. This is an enumerated value. +field.name (read-only) + The display name for the field. +field.default_name (read-only) + The name for the field from the emulated system’s configuration (cannot be + overridden by scripts or plugins). +field.player (read-only) + Zero-based player number for the field. +field.mask (read-only) + Bits in the I/O port corresponding to this field. +field.defvalue (read-only) + The field’s default value +field.sensitivity (read-only) + The sensitivity or gain for analog fields +field.way (read-only) + The number of directions allowed by the restrictor plate/gate for a digital + joystick, or zero (0) for other inputs. +field.type_class (read-only) + The type class for the input field – one of ``"keyboard"``, + ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``. +field.is_analog (read-only) + A Boolean indicating whether the field is an analog axis or positional + control. +field.is_digital_joystick (read-only) + A Boolean indicating whether the field corresponds to a digital joystick + switch. +field.enabled (read-only) + A Boolean indicating whether the field is enabled. +field.optional (read-only) + A Boolean indicating whether the field is optional and not required to use + the emulated system. +field.cocktail (read-only) + A Boolean indicating whether the field is only used when the system is + configured for a cocktail table cabinet. +field.toggle (read-only) + A Boolean indicating whether the field corresponds to a hardware toggle + switch or push-on, push-off button. +field.rotated (read-only) + A Boolean indicating whether the field corresponds to a control that is + rotated relative its standard orientation. +field.analog_reverse (read-only) + A Boolean indicating whether the field corresponds to an analog control that + increases in the opposite direction to the convention (e.g. larger values + when a pedal is released or a joystick is moved to the left). +field.analog_reset (read-only) + A Boolean indicating whether the field corresponds to an incremental + position input (e.g. a dial or trackball axis) that should be reset to zero + for every video frame. +field.analog_wraps (read-only) + A Boolean indicating whether the field corresponds to an analog input that + wraps from one end of its range to the other (e.g. an incremental position + input like a dial or trackball axis). +field.analog_invert (read-only) + A Boolean indicating whether the field corresponds to an analog input that + has its value ones-complemented. +field.impulse (read-only) + A Boolean indicating whether the field corresponds to a digital input that + activates for a fixed amount of time. +field.crosshair_scale (read-only) + The scale factor for translating the field’s range to crosshair position. A + value of one (1) translates the field’s full range to the full width or + height the screen. +field.crosshair_offset (read-only) + The offset for translating the field’s range to crosshair position. +field.user_value (read/write) + The value for DIP switch or configuration settings. +field.settings[] (read-only) + Gets a table of the currently enabled settings for a DIP switch or + configuration field, indexed by value. + +.. _luareference-input-fieldlive: + +Live I/O port field state +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O +port field. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():ioport().ports[tag]:field(mask).live + Gets the live state for an I/O port field. + +Properties +^^^^^^^^^^ + +live.name + Display name for the field. + +.. _luareference-input-inputman: + +Input manager +~~~~~~~~~~~~~ + +Wraps MAME’s ``input_manager`` class, which reads host input devices and checks +whether configured inputs are active. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input() + Gets the global input manager instance for the emulated system. + +Methods +^^^^^^^ + +input:code_value(code) + Gets the current value for the host input corresponding to the specified + code. Returns a signed integer value, where zero is the neutral position. +input:code_pressed(code) + Returns a Boolean indicating whether the host input corresponding to the + specified code has a non-zero value (i.e. it is not in the neutral + position). +input:code_pressed_once(code) + Returns a Boolean indicating whether the host input corresponding to the + specified code has moved away from the neutral position since the last time + it was checked using this function. The input manager can track a limited + number of inputs this way. +input:code_name(code) + Get display name for an input code. +input:code_to_token(code) + Get token string for an input code. This should be used when saving + configuration. +input:code_from_token(token) + Convert a token string to an input code. Returns the invalid input code if + the token is not valid or belongs to an input device that is not present. +input:seq_pressed(seq) + Returns a Boolen indicating whether the supplied input sequence is currently + pressed. +input:seq_clean(seq) + Remove invalid elements from the supplied input sequence. Returns the new, + cleaned input sequence. +input:seq_name(seq) + Get display text for an inptu sequence. +input:seq_to_tokens(seq) + Convert an input sequence to a token string. This should be used when + saving configuration. +input:seq_from_tokens(tokens) + Convert a token string to an input sequence. This should be used when + loading configuration. +input:axis_code_poller() + Returns an :ref:`input code poller <luareference-input-codepoll>` for + obtaining an analog host input code. +input:switch_code_poller() + Returns an :ref:`input code poller <luareference-input-codepoll>` for + obtaining a host switch input code. +input:keyboard_code_poller() + Returns an :ref:`input code poller <luareference-input-codepoll>` for + obtaining a host switch input code that only considers keyboard input + devices. +input:axis_sequence_poller() + Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for + obtaining an input sequence for configuring an analog input. +input:axis_sequence_poller() + Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for + obtaining an input sequence for configuring a digital input. + +Properties +^^^^^^^^^^ + +input.device_classes[] (read-only) + Gets a table of host + :ref:`input device classes <luareference-input-devclass>` indexed by name. + +.. _luareference-input-codepoll: + +Input code poller +~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being +activated. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input():axis_code_poller() + Returns an input code poller that polls for analog inputs being activated. +manager:machine():input():switch_code_poller() + Returns an input code poller that polls for host switch inputs being + activated. +manager:machine():input():keyboard_code_poller() + Returns an input code poller that polls for host switch inputs being + activated, only considering keyboard input devices. + +Methods +^^^^^^^ + +poller:reset() + Resets the polling logic. Active switch inputs are cleared and initial + analog input positions are set. +poller:poll() + Returns an input code corresponding to the first relevant host input that + has been activated since the last time the method was called. Returns the + invalid input code if no relevant input has been activated. + +.. _luareference-input-seqpoll: + +Input sequence poller +~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to +assign host input combinations to emulated inputs and other actions. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input():axis_sequence_poller() + Returns an input sequence poller for assigning host inputs to an analog + input. +manager:machine():input():switch_sequence_poller() + Returns an input sequence poller for assigning host inputs to a switch + input. + +Methods +^^^^^^^ + +poller:start([seq]) + Start polling. If a sequence is supplied, it is used as a starting + sequence: for analog inputs, the user can cycle between the full range, and + the positive and negative portions of an axis; for switch inputs, an “or” + code is appended and the user can add an alternate host input combination. +poller:poll() + Polls for for user input and updates the sequence if appropriate. Returns a + Boolean indicating whether sequence input is complete. If this method + returns false, you should continue polling. + +Properties +^^^^^^^^^^ + +poller.sequence (read-only) + The current input sequence. This is updated while polling. It is possible + for the sequence to become invalid. +poller.valid (read-only) + A Boolean indicating whether the current input sequence is valid. +poller.modified (read-only) + A Boolean indicating whether the sequence was changed by any user input + since starting polling. + +.. _luareference-input-devclass: + +Host input device class +~~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``input_class`` class, representing a category of host input +devices (e.g. keyboards or joysticks). + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input().device_classes[name] + Gets an input device class by name. + +Properties +^^^^^^^^^^ + +devclass.name (read-only) + The device class name. +devclass.enabled (read-only) + A Boolean indicating whether the device class is enabled. +devclass.multi (read-only) + A Boolean indicating whether the device class supports multiple devices, or + inputs from all devices in the class are combined and treated as a single + device. +devclass.devices[] (read-only) + Gets a table of :ref:`host input devices <luareference-input-inputdev>` in + the class. Keys are one-based indices. + +.. _luareference-input-inputdev: + +Host input device +~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``input_device`` class, representing a host input device. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input().device_classes[name].devices[index] + Gets a specific host input device. + +Properties +^^^^^^^^^^ + +inputdev.name (read-only) + Display name for the device. This is not guaranteed to be unique. +inputdev.id (read-only) + Unique identifier string for the device. This may not be human-readable. +inputdev.devindex (read-only) + Device index within the device class. This is not necessarily the same as + the index in the ``devices`` property of the device class – the ``devindex`` + indices may not be contiguous. +inputdev.items (read-only) + Gets a table of :ref:`input items <luareference-input-inputitem>`, indexed + by item ID. The item ID is an enumerated value. + +.. _luareference-input-inputitem: + +Host input device item +~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g. +a key, button, or axis). + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():input().device_classes[name].devices[index].items[id] + Gets an individual host input item. The item ID is an enumerated value. + +Properties +^^^^^^^^^^ + +item.name (read-only) + The display name of the input item. Note that this is just the name of the + item itself, and does not include the device name. The full display name + for the item can be obtained by calling the ``code_name`` method on the + :ref:`input manager <luareference-input-inputman>` with the item’s code. +item.code (read-only) + The input item’s identification code. This is used by several + :ref:`input manager <luareference-input-inputman>` methods. +item.token (read-only) + The input item’s token string. Note that this is a token fragment for the + item itself, and does not include the device portion. The full token for + the item can be obtained by calling the ``code_to_token`` method on the + :ref:`input manager <luareference-input-inputman>` with the item’s code. +item.current (read-only) + The item’s current value. This is a signed integer where zero is the + neutral position. + +.. _luareference-input-uiinput: + +UI input manager +~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():uiinput() + Gets the global UI input manager instance for the machine. + +Methods +^^^^^^^ + +uiinput:find_mouse() + Returns host system mouse pointer X position, Y position, button state, and + the :ref:`render target <luareference-render-target>` 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. +uiinput:pressed_repeat(type, speed) + Returns a Boolean indicating whether the specified UI input has been + pressed or auto-repeat has been triggered at the specified speed. The input + type is an enumerated value; the speed is an interval in sixtieths of a + second. + +Properties +^^^^^^^^^^ + +uiinput.presses_enabled (read/write) + Whether the UI input manager will check for UI inputs frame updates. + + .. _luareference-render: Render system @@ -312,10 +1295,10 @@ container.yscale (read/write) The container’s Y scale factor. This is a floating-point number. container.xoffset (read/write) The container’s X offset. This is a floating-point number where one (1) - represents the X size of the container. + corresponds to the X size of the container. container.yoffset (read/write) The container’s Y offset. This is a floating-point number where one (1) - represents the Y size of the container. + corresponds to the Y size of the container. container.is_empty (read-only) A Boolean indicating whether the container has no items. @@ -580,3 +1563,211 @@ item.element_state (read-only) item.animation_state (read-only) Get the current animation state. This will call the animation state callback function to handle bindings. + + +.. _luareference-debug: + +Debugger +-------- + +Some of MAME’s core debugging features can be controlled from Lua script. The +debugger must be enabled to use the debugging features (usually by passing +``-debug`` on the command line). + +.. _luareference-debug-manager: + +Debugger manager +~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``debugger_manager`` class, providing the main interface to control +the debugger. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine():debugger() + Returns the global debugger manager instance, or ``nil`` if the debugger is + not enabled. + +Methods +^^^^^^^ + +debugger:command(str) + Execute a debugger console command. The argument is the command string. + The output is sent to both the debugger console and the Lua console. + +Properties +^^^^^^^^^^ + +debugger.consolelog[] (read-only) + The lines in the console log (output from debugger commands). This + container only supports index and length operations. +debugger.errorlog[] (read-only) + The lines in the error log (``logerror`` output). This container only + supports index and length operations. +debugger.visible_cpu (read/write) + The CPU device with debugger focus. Changes become visible in the debugger + console after the next step. Setting to a device that is not a CPU has no + effect. +debugger.execution_state (read/write) + Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is + stopped in the debugger. + +.. _luareference-debug-devdebug: + +Device debugger interface +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Wraps MAME’s ``device_debug`` class, providing the debugger interface to an +emulated CPU device. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag]:debug() + Returns the debugger interface for an emulated CPU device, or ``nil`` if the + device is not a CPU. + +Methods +^^^^^^^ + +debug:step([cnt]) + Step by the specified number of instructions. If the instruction count is + not provided, it defaults to a single instruction. +debug:go() + Run the emulated CPU. +debug:bpset(addr, [cond], [act]) + Set a breakpoint at the specified address, with an optional condition and + action. If the action is not specified, it defaults to just breaking into + the debugger. Returns the breakpoint number for the new breakpoint. + + If specified, the condition must be a debugger expression that will be + evaluated each time the breakpoint is hit. Execution will only be stopped + if the expression evaluates to a non-zero value. If the condition is not + specified, it defaults to always active. +debug:bpenable([bp]) + Enable the specified breakpoint, or all breakpoints for the device if no + breakpoint number is specified. Returns whether the specified number + matched a breakpoint if a breakpoint number is specified, or ``nil`` if no + breakpoint number is specified. +debug:bpdisable([bp]) + Disable the specified breakpoint, or all breakpoints for the device if no + breakpoint number is specified. Returns whether the specified number + matched a breakpoint if a breakpoint number is specified, or ``nil`` if no + breakpoint number is specified. +debug:bpclear([bp]) + Clear the specified breakpoint, or all breakpoints for the device if no + breakpoint number is specified. Returns whether the specified number + matched a breakpoint if a breakpoint number is specified, or ``nil`` if no + breakpoint number is specified. +debug:bplist() + Returns a table of breakpoints for the device. The keys are the breakpoint + numbers, and the values are + :ref:`breakpoint objects <luareference-debug-breakpoint>`. +debug:wpset(space, type, addr, len, [cond], [act]) + Set a watchpoint over the specified address range, with an optional + condition and action. The type must be ``"r"``, ``"w"`` or ``"rw"`` for a + read, write or read/write breakpoint. If the action is not specified, it + defaults to just breaking into the debugger. Returns the watchpoint number + for the new watchpoint. + + If specified, the condition must be a debugger expression that will be + evaluated each time the breakpoint is hit. Execution will only be stopped + if the expression evaluates to a non-zero value. For all watchpoints, a + ``wpaddr`` variable is set to the address that triggered the watchpoint. + When a watchpoint is triggered by a write, a ``wpdata`` variable is set to + the data being written. If the condition is not specified, it defaults to + always active. +debug:wpenable([wp]) + Enable the specified watchpoint, or all watchpoints for the device if no + watchpoint number is specified. Returns whether the specified number + matched a watchpoint if a watchpoint number is specified, or ``nil`` if no + watchpoint number is specified. +debug:wpdisable([wp]) + Disable the specified watchpoint, or all watchpoints for the device if no + watchpoint number is specified. Returns whether the specified number + matched a watchpoint if a watchpoint number is specified, or ``nil`` if no + watchpoint number is specified. +debug:wpclear([wp]) + Clear the specified watchpoint, or all watchpoints for the device if no + watchpoint number is specified. Returns whether the specified number + matched a watchpoint if a watchpoint number is specified, or ``nil`` if no + watchpoint number is specified. +debug:wplist(space) + Returns a table of watchpoints for the specified address space of the + device. The keys are the watchpoint numbers, and the values are + :ref:`watchpoint objects <luareference-debug-watchpoint>`. + +.. _luareference-debug-breakpoint: + +Breakpoint +~~~~~~~~~~ + +Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an +emulated CPU device. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag]:debug():bplist()[bp] + Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no + breakpoint corresponds to the specified index. + +Properties +^^^^^^^^^^ + +breakpoint.index (read-only) + The breakpoint’s index. The can be used to enable, disable or clear the + breakpoint via the + :ref:`CPU debugger interface <luareference-debug-devdebug>`. +breakpoint.enabled (read-only) + A Boolean indicating whether the breakpoint is currently enabled. +breakpoint.address (read-only) + The breakpoint’s address. +breakpoint.condition (read-only) + A debugger expression evaluated each time the breakpoint is hit. The action + will only be triggered if this expression evaluates to a non-zero value. An + empty string if no condition was specified. +breakpoint.action (read-only) + An action the debugger will run when the breakpoint is hit and the condition + evaluates to a non-zero value. An empty string if no action was specified. + +.. _luareference-debug-watchpoint: + +Watchpoint +~~~~~~~~~~ + +Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an +emulated CPU device. + +Instantiation +^^^^^^^^^^^^^ + +manager:machine().devices[tag]:debug():wplist(space)[wp] + Gets the specified watchpoint for an address space of an emulated CPU + device, or ``nil`` if no watchpoint in the address space corresponds to the + specified index. + +Properties +^^^^^^^^^^ + +watchpoint.index (read-only) + The watchpoint’s index. The can be used to enable, disable or clear the + watchpoint via the + :ref:`CPU debugger interface <luareference-debug-devdebug>`. +watchpoint.enabled (read-only) + A Boolean indicating whether the watchpoint is currently enabled. +watchpoint.type (read-only) + Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write + watchpoint. +watchpoint.address (read-only) + The starting address of the watchpoint’s address range. +watchpoint.length (read-only) + The length of the watchpoint’s address range. +watchpoint.condition (read-only) + A debugger expression evaluated each time the watchpoint is hit. The action + will only be triggered if this expression evaluates to a non-zero value. An + empty string if no condition was specified. +watchpoint.action (read-only) + An action the debugger will run when the watchpoint is hit and the condition + evaluates to a non-zero value. An empty string if no action was specified. diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst index 65b4ad93cb1..76a79ef6d76 100644 --- a/docs/source/techspecs/memory.rst +++ b/docs/source/techspecs/memory.rst @@ -522,7 +522,7 @@ or banks. (...).mirror(mask) Duplicate the range on the addresses reachable by setting any of the 1 -bits present in mask. For instance, a range 0-0x1f with mask 0x300 +bits present in mask. For instance, a range 0-0x1f with mirror 0x300 will be present on 0-0x1f, 0x100-0x11f, 0x200-0x21f and 0x300-0x31f. The addresses passed in to the handler stay in the 0-0x1f range, the mirror bits are not seen by the handler. |