SCRYMAMEReferenceReadread_block
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
Read four bytes of the sprite memory, from its byte 12 on.
read_block(tag="spriteram", offset=12, length=4){
"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
{
"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,
blitramor:blitram. Give this orref, never both. - ref string, default
"" - An address inside the block, instead of its tag: a symbol or a
0xaddress whose address-map entry names the block. - offset integer or string, default
0 - Where to start inside the block, with
tag: an integer or a0xstring. 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
refis looked up in. Left empty, the one the debugger is showing.
What comes back
- hex
- The bytes, two hex characters each.
- kind
shareorregion, 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.addrandaddr_cpusay whatrefresolved 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
- Both
tagandref, or neither;offsetwithref;cpuwithtag; atagholding whitespace (bad_argument). - A read that runs past the block's end (
bad_argument). - A tag the machine does not have; the refusal's
tagslists the ones it has (unknown_ref). - A
refno address-map entry covers, or whose entry names no block;map_entrythen gives that entry'sstartandend(unknown_ref).
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.
Related tools
The contract your client receives
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.