SCRYDOSBox-XReferenceScanscanAlso in MAME
scan
Find the byte that holds a value nobody has named: start from a whole range and keep only what changes as the value does.
scan(method, ref="", length=null, cell_bytes=null, operator=null, value=null, limit=null)
Try it
Find the byte that holds the score: scan the 216 bytes from row_colours, and filter once a brick has fallen.
scan(method="start", ref="row_colours", cell_bytes=1, length=216){
"summary": "scan start: row_colours, 216 cells of 1 byte",
"seg_off": "08DF:00000590",
"length": 216,
"cell_bytes": 1,
"hits_total": 216
}Then, with the score at 60 after the first brick:
scan(method="filter", value=60){
"summary": "scan filter: = 60, 2 left",
"iterations": 1,
"hits": [
{"seg_off": "08DF:00000597", "addr": "0x00009387", "value": "0x3c"},
{"seg_off": "08DF:00000615", "addr": "0x00009405", "value": "0x3c"}
],
"hits_total": 2
}Of 216 bytes, two hold 60 (0x3c). One of them, 08DF:00000615, is where read_memory finds the symbol score.
The two replies, whole
The first call's:
{
"summary": "scan start: row_colours, 216 cells of 1 byte",
"status": "ok",
"ref": "row_colours",
"seg_off": "08DF:00000590",
"length": 216,
"cell_bytes": 1,
"addr": "0x00009380",
"hits_total": 216
}The second call's:
{
"summary": "scan filter: = 60, 2 left",
"status": "ok",
"operator": "=",
"value": "0x3c",
"iterations": 1,
"closed": false,
"hits": [
{"seg_off": "08DF:00000597", "addr": "0x00009387", "value": "0x3c"},
{"seg_off": "08DF:00000615", "addr": "0x00009405", "value": "0x3c"}
],
"hits_total": 2,
"truncated": false
}The three methods
| method | what it does |
|---|---|
start |
Opens a scan: every cell of the range is a candidate. |
filter |
Keeps the candidates whose value passes a comparison. |
clear |
Ends the scan. |
Arguments
- method one of
"start","filter","clear", required start,filterorclear, as above.- ref string, default
"" - Where the range begins, for
start: aSEG:OFFaddress or a symbol. - length integer, optional
- How many bytes to scan, for
start: at most0xFFFFFF, and a whole number of candidates. - cell_bytes one of
1,2,4, optional - The size of each candidate: 1, 2 or 4 bytes, low byte first. Left out, one byte.
- operator one of
"=","!",">",">=","<","<=", optional - The comparison a
filtermakes. Left out,=. - value integer or string, optional
- What each candidate is compared with: an integer or a
0xstring. Left out, what it held atstart. - limit integer (>= 1, <= 400), optional
- How many of the candidates left the reply lists: 1 to 400. Left out, 40.
What comes back
- hits_total
- How many candidates are left.
- hits
- The first
limitof them, each with its address and its value now. None are listed while more than 400 are left. - iterations
- How many filters this scan has taken.
- closed
truewhen a filter left no candidate, which ends the scan.- truncated
truewhen there are more candidates thanhitslists.
All 13 reply fields
addr(string)cell_bytes(integer)cleared(boolean)closed(boolean)hits(array)hits_total(integer)iterations(integer or object)length(integer)operator(string)ref(string)seg_off(string)truncated(boolean)value(string or object)
What it refuses
- An argument the method does not take.
- A second
startwhile a scan is open, or afilterwith none (needs_call). - A
valuewider than the scan's candidates (bad_argument). - A range that runs past the memory the debugger addresses (
bad_argument).
Why it works this way
The candidates live in the debugger's own value scanner, MEMFIND, not in the reply. So a scan over a large range costs one command, and the addresses are listed only once few enough are left.
That scanner holds one scan at a time, which is why a second start is refused until you clear.
Without a value, a filter compares each candidate with what it held at start: ! keeps the ones that changed, > the ones that grew. A few rounds leave the one address.
Related tools
The contract your client receives
Value scan: find a variable no map names (the debugger's `MEMFIND`). One scan at a time.
`start`: every cell of `cell_bytes` (little-endian) over `length` bytes from `ref` is a
candidate. Reply: `ref`, `seg_off`, `length`, `cell_bytes`, `addr`, `hits_total`.
`filter`: keep the cells whose content satisfies `operator` (`=` default) against `value`
(an integer or a `0x` string), or with no `value` against what each held at `start`; none
left closes the scan. Reply: `operator`, `value`, `iterations`, `closed`, `hits` (the first
`limit`, default 40), `hits_total`, `truncated`, `note`.
`clear`: cancel the open scan. Reply: `cleared`.
Refused: an argument the method does not take; a scan already open, in the debugger's
words; a `value` wider than the cell.
Reference: REFERENCE.md, Reading and writing.