summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript/ref-mem.rst
blob: 0987889d3dca69c261b1ecf534d10cf63c52aceb (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
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.