SCRYMAMEReferenceReadfindAlso in DOSBox-X

MAMERead

find

Find every address in a range of memory that holds a given sequence of bytes.

find(data_hex, ref="", length=0, symbol_class="", cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset, right after start.
Ask

Find where the ROM holds the bytes 7c 04 2b, the instruction that adds one to the credits.

Call
find(data_hex="7c042b", ref="0xa000", length=24576)
Reply 5 of 10 fields
{
  "summary": "find 7c042b in 0x6000 bytes at 0xa000: 1 hit",
  "span": {"from": "0x0000a000", "length": 24576, "source": "ref+length"},
  "hits": ["0x0000b583"],
  "hits_total": 1,
  "truncated": false
}

One address holds those bytes, 0xb583. span says which bytes were searched: 24576 from 0xa000, the whole ROM.

The whole reply
JSON
{
  "summary": "find 7c042b in 0x6000 bytes at 0xa000: 1 hit",
  "status": "ok",
  "ref": "0xa000",
  "addr": "0x0000a000",
  "length": 24576,
  "span": {"from": "0x0000a000", "length": 24576, "source": "ref+length"},
  "hits": ["0x0000b583"],
  "hits_total": 1,
  "truncated": false,
  "cpu": ":maincpu"
}

Arguments

data_hex string, required
The bytes to look for, as hex: 1 to 126 whole bytes.
ref string, default ""
Where the range begins: a symbol or a 0x address. Give it with length, or give symbol_class instead.
length integer, default 0
How many bytes to search from ref.
symbol_class string, default ""
A class of the symbol file, DATA or CODE say, searched from its first symbol to its last. It replaces ref and length.
cpu string, default ""
The cpu whose program memory is searched. Left empty, the one the debugger is showing.

What comes back

hits
The addresses where the bytes begin, at most 400; past that, the highest are kept.
hits_total
How many addresses hold the bytes, listed or not.
truncated
true when there are more hits than hits lists.
span
The bytes that were searched, as from, length and source, so zero hits says where there are none.
All 9 reply fields
  • addr (string)
  • cpu (string or object)
  • hits (array)
  • hits_total (integer)
  • length (integer)
  • ref (string)
  • span (object)
  • symbol_class (string)
  • truncated (boolean)

What it refuses

Why it works this way

A hit is where the bytes begin, so a match that starts inside the range and runs past its end counts.

A linker map gives no sizes, so a class is searched only up to the start of its last symbol; span carries a note saying so.

There is no search of the whole address space, because the symbol file does not say where it ends. MAME's console takes each byte as a parameter of its own, which limits them to 126.

The contract your client receives
Text
Every address in `length` bytes from `ref` holding `data_hex` (whole hex bytes,
1..126), in the program space of `cpu` (`subcpu`; the visible one when empty).

`symbol_class` (`DATA`, `CODE`...) replaces `ref`+`length` with that class's symbol range,
which misses a match past the last symbol's start. Both, neither, or an unknown class is
refused. A range past the program space is `bad_argument`.

Reply: `ref` (with `ref`), `addr`, `length`, `span` (`from`, `length`, `source`), `hits` (at
most 400, highest kept), `hits_total`, `truncated`, `cpu`, `symbol_class`. An
unreadable console answer is `status: INVALID`.

Reference: REFERENCE.md, Reading and writing.
Tools