SCRYMAMEReferenceReadfindAlso in DOSBox-X
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
start.Find where the ROM holds the bytes 7c 04 2b, the instruction that adds one to the credits.
find(data_hex="7c042b", ref="0xa000", length=24576){
"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
{
"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
0xaddress. Give it withlength, or givesymbol_classinstead. - length integer, default
0 - How many bytes to search from
ref. - symbol_class string, default
"" - A class of the symbol file,
DATAorCODEsay, searched from its first symbol to its last. It replacesrefandlength. - 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
truewhen there are more hits thanhitslists.- span
- The bytes that were searched, as
from,lengthandsource, 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
- Both
symbol_classand arefwithlength, or neither (bad_argument). - A class the symbol file does not have (
unknown_ref). - More than 126 bytes in
data_hex, or hex that is not whole bytes (bad_argument). - A range that runs past the cpu's program memory (
bad_argument). - A console answer that is neither hits nor
Not found(unexpected_answer).
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.
Related tools
The contract your client receives
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.