diff options
Diffstat (limited to 'docs/source/luascript/ref-mem.rst')
-rw-r--r-- | docs/source/luascript/ref-mem.rst | 459 |
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. |