mirror of
https://github.com/mamedev/mame.git
synced 2024-11-18 10:06:19 +01:00
6e60af32c1
sega_beena_cart.xml: Put page scans in individual data areas. frontend/mame/luaengine_mem.cpp: Added a raw read function for memory regions. plugins/layout: Added bitmap classes to layout sandbox.
459 lines
17 KiB
ReStructuredText
459 lines
17 KiB
ReStructuredText
.. _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.
|