summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript/ref-mem.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/luascript/ref-mem.rst')
-rw-r--r--docs/source/luascript/ref-mem.rst459
1 files changed, 459 insertions, 0 deletions
diff --git a/docs/source/luascript/ref-mem.rst b/docs/source/luascript/ref-mem.rst
new file mode 100644
index 00000000000..0987889d3dc
--- /dev/null
+++ b/docs/source/luascript/ref-mem.rst
@@ -0,0 +1,459 @@
+.. _luascript-ref-mem:
+
+Lua Memory System Classes
+=========================
+
+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.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-memman:
+
+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 <luascript-ref-memshare>` 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 <luascript-ref-membank>` 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 <luascript-ref-memregion>` 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.
+
+
+.. _luascript-ref-addrspace:
+
+Address space
+-------------
+
+Wraps MAME’s ``address_space`` class, which represents 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.
+space:add_change_notifier(callback)
+ Add a callback to receive notifications for handler changes in address
+ space. The callback function is passed a single string as an argument,
+ either ``r`` if read handlers have potentially changed, ``w`` if write
+ handlers have potentially changed, or ``rw`` if both read and write handlers
+ have potentially changed.
+
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+space:install_read_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on reads from the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data read,
+ and the memory access mask. The offset is the absolute offset into the
+ address space. To modify the data being read, return the modified value
+ from the callback function as an integer. If the callback does not return
+ an integer, the data will not be modified.
+space:install_write_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on write to the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data
+ written, and the memory access mask. The offset is the absolute offset into
+ the address space. To modify the data being written, return the modified
+ value from the callback function as an integer. If the callback does not
+ return an integer, the data will not be modified.
+
+Properties
+~~~~~~~~~~
+
+space.name (read-only)
+ The display name for the address space.
+space.shift (read-only)
+ The 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 <luascript-ref-addrmap>` for the space or
+ ``nil``.
+
+
+.. _luascript-ref-addrspacetap:
+
+Pass-through handler
+--------------------
+
+Tracks a pass-through handler installed in an
+:ref:`address space <luascript-ref-addrspace>`. A memory pass-through handler
+receives notifications on accesses to a specified range of addresses, and can
+modify the data that is read or written if desired. Note that pass-through handler
+callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on reads
+ from the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on writes to
+ the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+
+Methods
+~~~~~~~
+
+passthrough:reinstall()
+ Reinstalls the pass-through handler in the address space. May be necessary
+ if the handler is removed due to other changes to handlers in the address
+ space.
+passthrough:remove()
+ Removes the pass-through handler from the address space. The associated
+ callback will not be called in response to future memory accesses.
+
+Properties
+~~~~~~~~~~
+
+passthrough.addrstart (read-only)
+ The inclusive start address of the address range monitored by the
+ pass-through handler (i.e. the lowest address that the handler will be
+ notified for).
+passthrough.addrend (read-only)
+ The inclusive end address of the address range monitored by the pass-through
+ handler (i.e. the highest address that the handler will be notified for).
+passthrough.name (read-only)
+ The display name for the pass-through handler.
+
+
+.. _luascript-ref-addrmap:
+
+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 <luascript-ref-addrmapentry>` in the address
+ map. Uses 1-based integer indices. The index operator and the ``at``
+ method have O(n) complexity.
+
+
+.. _luascript-ref-addrmapentry:
+
+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_mask (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 <luascript-ref-memhandlerdata>` for the read handler.
+entry.write (read-only)
+ :ref:`Additional data <luascript-ref-memhandlerdata>` for the write handler.
+entry.share (read-only)
+ Memory share tag for making RAM entries accessible or ``nil``.
+entry.region (read-only)
+ Explicit memory region tag for ROM entries, or ``nil``. For ROM entries,
+ ``nil`` infers the region from the device tag.
+entry.region_offset (read-only)
+ Starting offset in memory region for ROM entries.
+
+
+.. _luascript-ref-memhandlerdata:
+
+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``.
+
+
+.. _luascript-ref-memshare:
+
+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.
+
+
+.. _luascript-ref-membank:
+
+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.
+
+
+.. _luascript-ref-memregion:
+
+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(offs, len)
+ Reads up to the specified length in bytes from the specified offset in the
+ memory region. The bytes read will be returned as a string. If the
+ specified length extends beyond the end of the memory region, the returned
+ string will be shorter than requested. Note that the data will be in host
+ byte order.
+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. The offset is specified in bytes. Reading beyond the
+ end of the memory region returns zero.
+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. The offset is specified in bytes. Reading
+ beyond the end of the memory region returns zero.
+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. The offset is specified in bytes. Attempting to write
+ beyond the end of the memory region has no effect.
+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. The offset is specified in bytes. Attempting to
+ write beyond the end of the memory region has no effect.
+
+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.