SCRYMAMEReferenceReadread_block

MAMERead

read_block

Read bytes MAME keeps under a tag and no cpu can read back: write-only memory, or a ROM outside every cpu's address space.

read_block(tag="", ref="", offset=0, length=16, seconds=5.0, cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped once the game has drawn its sprites; the example session reads at frame 545.
Ask

Read four bytes of the sprite memory, from its byte 12 on.

Call
read_block(tag="spriteram", offset=12, length=4)
Reply 6 of 28 fields
{
  "summary": "read_block share :spriteram: 4 bytes at offset 0x0000000c of 0x800: 5b009394",
  "kind": "share",
  "tag": ":spriteram",
  "size": 2048,
  "offset": "0x0000000c",
  "hex": "5b009394"
}

spriteram is a share, a block MAME keeps by name, 2048 bytes long. The four bytes from offset 12 are 5b009394, one sprite's entry.

The whole reply
JSON
{
  "summary": "read_block share :spriteram: 4 bytes at offset 0x0000000c of 0x800: 5b009394",
  "status": "ok",
  "kind": "share",
  "tag": ":spriteram",
  "size": 2048,
  "bytewidth": 1,
  "endianness": "big",
  "offset": "0x0000000c",
  "length": 4,
  "hex": "5b009394",
  "evaluated_by": "one step",
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "call": "MAME_MCP_LUA_END#8",
  "pc_before": "0x0000fd80",
  "cause": "read_block: one step",
  "stop_seq": 10,
  "pc": "0x0000fd82",
  "cpu": ":maincpu",
  "frame": 545,
  "regs": {
    "A": "0xff",
    "B": "0x72",
    "D": "0xff72",
    "X": "0x0100",
    "Y": "0x00f1",
    "U": "0xc66d",
    "PC": "0xfd82",
    "S": "0x07f4",
    "CC": "0xf8",
    "DP": "0x00"
  },
  "instruction": {"address": "FD82", "bytes": "96B2", "text": "LDA    <$B2", "symbol": "irq", "delta": 2},
  "following": ["FD84: 84 03    ANDA   #$03", "FD86: 26 04    BNE    $FD8C", "FD88: 0C B3    INC    <$B3", "FD8A: 0C B4    INC    <$B4", "FD8C: B6 03 BE LDA    $03BE", "FD8F: 26 28    BNE    $FDB9", "... 9 more"],
  "errorlog": "<volatile>",
  "watches": [
    {
      "ref": "0xc",
      "cpu": ":maincpu",
      "state": "captured",
      "total": 3,
      "callback_errors": {
        "count": 0,
        "first": {"available": false, "why": "no callback raised"}
      },
      "since_last_stop": 0
    }
  ],
  "omitted": ["addr", "by", "fmt", "frame_as_of", "install_resent", "installed", "... 12 more"],
  "how": "`declaration_list(kind=\"watch\")` answers each watch whole: its declaration, the debugger's row for it, and a count's or a capture's tables"
}

Arguments

tag string, default ""
The block's name in MAME, blitram or :blitram. Give this or ref, never both.
ref string, default ""
An address inside the block, instead of its tag: a symbol or a 0x address whose address-map entry names the block.
offset integer or string, default 0
Where to start inside the block, with tag: an integer or a 0x string. Left out, its first byte.
length integer (>= 1, <= 1024), default 16
How many bytes: 1 to 1024. Left out, 16.
seconds number (> 0, <= 600.0), default 5.0
How long MAME's Lua console may take to answer. Left out, 5 seconds.
cpu string, default ""
The cpu whose address map ref is looked up in. Left empty, the one the debugger is showing.

What comes back

hex
The bytes, two hex characters each.
kind
share or region, MAME's two words for such a block.
tag
The block's tag as MAME spells it in full.
size
The block's length in bytes.
offset
Where the read began inside the block. With ref, the address's distance into it.
start
With ref: the first address of the map entry that names the block. addr and addr_cpu say what ref resolved to, and on which cpu.
All 34 reply fields
  • console_reruns (integer)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer)
  • pc (string)
  • regs (object)
  • resent (integer)
  • stop_seq (integer)
  • thread_errors (integer)
  • watches (array)
  • addr (string)
  • addr_cpu (string)
  • bytewidth (integer)
  • call (string)
  • endianness (string)
  • evaluated_by (string)
  • hex (string)
  • kind (string)
  • length (integer)
  • lines_ahead (integer)
  • map_entry (object)
  • offset (string)
  • pc_before (string)
  • pending (boolean)
  • reader_steps (integer)
  • regpoint_hit (object)
  • seen_bytes (integer)
  • size (integer)
  • start (string)
  • tag (string)
  • tags (object)
  • watch_hit (object)

What it refuses

Why it works this way

MAME keeps by tag two kinds of block that read_memory cannot reach. Memory that a handler only writes to, which MAME calls a share, answers zeros there. A ROM outside every cpu's address space, a region such as gfx1, is not there at all.

The bytes are the block after the instruction the read runs. To see the block as a write found it, stop one instruction earlier.

Past a block's end MAME answers zeros without complaint, which is why a read that runs past it is refused.

The contract your client receives
Text
Read `length` bytes (1..1024) of a block MAME keeps by tag: a share (what
`symbols_find` calls `latch`) or a region (a ROM no cpu maps).

`tag` (`blitram` or `:blitram`) with `offset`, or `ref` whose map entry names the block;
`cpu` names `ref`'s space; `seconds` bounds the console's answer.

Reply: `kind`, `tag`, `size`, `bytewidth`, `endianness`, `offset`, `length`, `hex`; with
`ref` also `addr`, `addr_cpu`, `start`; then the stop survey. `unknown_ref`: no such tag
(`tags` lists them) or `ref` in no entry naming a block. `bad_argument`: `offset` with
`ref`, `cpu` with `tag`, past the block's end.

Reference: REFERENCE.md, Reading and writing.
Tools