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.

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 memory shares 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 memory banks 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 memory regions 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.

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 notifier subscription.

space: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 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 pass-through handler 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 address map for the space or nil.

Pass-through handler ¶

Tracks a pass-through handler installed in an address space. 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 address space.
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 address space.

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.

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 entries in the address map. Uses 1-based integer indices. The index operator and the at method have O(n) complexity.

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): Additional data for the read handler.
entry.write (read-only): Additional data 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.

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.

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.

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.