SCRYMAMEReferenceRunrun_toAlso in DOSBox-X
run_to
Run until the program reaches an address, or a screen of the screen map, and stop there.
run_to(ref="", control="", screen="", seconds=30.0, disarm_watches=false, condition="", cpu="")
Try it
Run until the game counts the coin I dropped, and check that its frame-wait loop keeps running meanwhile.
run_to(ref="count_coin", control="wait_frame", seconds=300){
"summary": "run_to count_coin: TARGET, control counted 1",
"verdict": "TARGET",
"control_hits": 1,
"controls": [
{"ref": "wait_frame", "cpu": ":maincpu", "hits_in_run": 1}
],
"pc": "0x0000b583"
}The run reached count_coin, which is what TARGET says. The control wait_frame ran once on the way, so breakpoints were firing.
The whole reply
{
"summary": "run_to count_coin: TARGET, control counted 1",
"status": "ok",
"verdict": "TARGET",
"control_hits": 1,
"controls": [
{"ref": "wait_frame", "cpu": ":maincpu", "hits_in_run": 1}
],
"cause": "target count_coin",
"stop_seq": 18,
"pc": "0x0000b583",
"cpu": ":maincpu",
"frame": 552,
"regs": {
"A": "0x01",
"B": "0xcf",
"D": "0x01cf",
"X": "0xe199",
"Y": "0xf2e6",
"U": "0x7acf",
"PC": "0xb583",
"S": "0x07fc",
"CC": "0xa4",
"DP": "0x00"
},
"instruction": {
"address": "B583",
"bytes": "7C042B",
"text": "INC $042B",
"symbol": "count_coin",
"delta": 0,
"comment": "a coin: INC credits, then the BCD copy"
},
"following": ["B586: 86 01 LDA #$01", "B588: BB 04 2C ADDA $042C", "B58B: 19 DAA", "B58C: B7 04 2C STA $042C", "B58F: 39 RTS", "B590: 96 F4 LDA <$F4", "... 8 more"],
"errorlog": "<volatile>"
}Arguments
- ref string, default
"" - The address to stop at: a
0xaddress or a symbol. Give this orscreen, never both. - control string, default
"" - An address known to run often, counted beside the target, so that "the target never ran" can be told from "nothing ran". Required with
refor an anchoredscreen. - screen string, default
"" - A screen of the loaded screen map, the file naming a program's screens. With an
anchor, an address the map gives it, the run goes there; without, frame by frame. - seconds number (> 0, <= 600.0), default
30.0 - How long to wait for the stop, in real seconds, before the server interrupts the machine. Left out, 30.
- disarm_watches boolean, default
false truetakes your watches off for this run, so none of them stops it, and sets them again at the end.- condition string, default
"" - Stop at the target only when this expression holds, in the debugger's own grammar with bare numbers read as hex:
w@DemoLen==0x25. - cpu string, default
"" - The cpu the target and the control are set on. Left empty, the visible one.
What comes back
- verdict
- How the run ended:
TARGET, the target was reached;TIMEOUT, the wait gave up;OTHER_STOP, a breakpoint or a watch nobody targeted stopped it first. - control_hits
- How many times the controls ran during the run. A
TARGETisokeven with none. - controls
- One row per control counted on the target's cpu: its
ref, itscpuandhits_in_run. It comes with a run to arefor an anchor. - target_disarmed
- Whether the run's own breakpoint at the target was removed. It comes only when it was not, or when the interrupt at the time limit was answered late or never.
- frames
- How many frames a run to a screen with no
anchortook. - screen
- After a run to a screen: its
screen,layerandmode, andjudged, whether the map checked the screen there.
All 38 reply fields
disarmed_watches(array)not_rearmed(array)addr(string)call(string)evaluated_by(string)lines_ahead(integer)pc_before(string)reader_steps(integer)resent(integer)thread_errors(integer)armed(boolean)command_chars(integer)condition(string)control(string)control_dasm(array)control_hits(integer)console_reruns(integer)control_on(array)controls(array)cpu(string or object)following(array of string)frames(integer)instruction(StopInstruction)errorlog(object)frame(integer)limit_chars(integer)pc(string)ref(string)regpoint_hit(object)regs(object)screen(object)state(string)stop_seq(integer)stored(boolean)target_disarmed(boolean)verdict(string)watch_hit(object)watches(array)
What it refuses
- A
ref, acontrolor ascreenthat the symbol table or the screen map does not name (unknown_ref). - No
controlwith arefor an anchored screen, or acontrolordisarm_watcheswith a screen that has no anchor (bad_argument). - A target at a control's address, or at an address where one of your breakpoints already stops (
bad_argument). - A
conditiontoo long for one console command; the reply givescommand_charsandlimit_chars(bad_argument). - A target MAME's console accepted and does not list, found before the machine moves (
readback_refused). - A
TIMEOUTduring which no control ran: nothing was learned about the target (control_silent). - Another stop before any control ran (
cut_by_other_stop). - An interrupt at the time limit that got no answer: the machine may still be running, so call
stop(not_settled). - A screen map that no longer matches the screen at its anchor (
stale_map). - A machine that is running (
not_stopped).
Why it works this way
Several different mistakes leave a MAME breakpoint silent, and each looks exactly like "that routine is never called". The control counting beside the target tells them apart. A TIMEOUT with no control hit is refused, because it cannot tell a wrong address from a right one that runs less often than assumed.
The target is a temporary breakpoint of the run's own, removed when the run ends. It cannot share an address with a breakpoint you set, since a stop there could not be told from the target's. A stop at the target's address is TARGET only when it is the target cpu's.
disarm_watches is for a watch on a byte written every frame, which would otherwise stop every later run.
More on why
A control on another cpu runs another program, and runs even while the target's cpu is held in reset, so it cannot say that cpu ran. Naming one is unknown_ref, with control_on and the breakpoint_at(..., cpu=) call that fixes it.
Both breakpoints are read back from MAME's list before the machine moves. A target the console took and does not list would otherwise come back TIMEOUT beside a control that ran. One listed without its condition is removed first, or every later run would stop there.
When the time limit passes the server interrupts the machine. An interrupt answered late is a TIMEOUT whose cause says "answered late". One never answered is not_settled with no cause: call stop, and if stop fails as well, close then start.
A removal MAME refuses after the stop does not undo the stop. The reply keeps its readings with target_disarmed: false, and note names the debug("bpclear 0x<row>") that removes the breakpoint. declaration_clear cannot, because the target was never one of yours.
control_silentstill carries the stop's readings, anote, andcontrol_dasm: the code at each control (ref,cpu,dasm).disarmed_watcheslists the watches taken off andnot_rearmedthose not set again, byrefandcpu. Aftersession_brokenthey stay off.
Related tools
The contract your client receives
Run to `ref` and stop, with a control counting meanwhile.
`ref` is armed on `cpu` (the visible one when empty). `control` is required with a `ref` or an
anchored screen: a place the program runs often while the target is awaited, counted each time
it does, declared as a control on that cpu if it is new (`breakpoint_at(role="control")` does
the same ahead of time), and the cpu's other declared controls count too. `condition`: stop
only when it holds, bare numbers hex (`w@DemoLen==0x25`). `disarm_watches=true` disarms the watches for this pass, so none of them cuts it. Needs a stopped
machine. Refused: an unresolved ref, an empty or unresolved control, an over-long
`condition`.
`screen`: a mapped screen's name instead of `ref` (exactly one). If the screen names an `anchor` (set by `screen_map_write`), run to it (`control`
required): a `verified` map judges it there (`stale_map` when it no longer holds), a
`consolidated` one takes it as shown. If it names none, a frame at a time until the map names it,
within `seconds`; a `control` or `disarm_watches` is refused there (`bad_argument`). Reply: `screen` (`screen`, `layer`,
`mode`, `judged`), `frames` run. Refused: an unmapped screen (`unknown_ref`).
Reply: `verdict` (`TARGET`, `TIMEOUT`, `OTHER_STOP`), `control_hits`, `controls` (each `ref`,
`cpu`, `hits_in_run`; a run to a ref or an anchor), `target_disarmed` (the target was left
armed or the interrupt went unanswered), `frames` (a screen with no anchor), the
stop survey (`stop_seq`, `pc`, `regs`, `instruction`, `following` when the listing runs on).
INVALID has no `verdict`: `control_silent`, `cut_by_other_stop`, `not_settled`, `stale_map`.
Reference: REFERENCE.md, Running and stopping.