SCRYMAMEReferenceRunrun_toAlso in DOSBox-X

MAMERun

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

On Gridlee, a free ROM from mamedev.org, started with the names in gridlee-symbols.yaml and stopped right after a coin is dropped.
Ask

Run until the game counts the coin I dropped, and check that its frame-wait loop keeps running meanwhile.

Call
run_to(ref="count_coin", control="wait_frame", seconds=300)
Reply 5 of 14 fields
{
  "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
JSON
{
  "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 0x address or a symbol. Give this or screen, 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 ref or an anchored screen.
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
true takes 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 TARGET is ok even with none.
controls
One row per control counted on the target's cpu: its ref, its cpu and hits_in_run. It comes with a run to a ref or 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 anchor took.
screen
After a run to a screen: its screen, layer and mode, and judged, 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

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_silent still carries the stop's readings, a note, and control_dasm: the code at each control (ref, cpu, dasm).
  • disarmed_watches lists the watches taken off and not_rearmed those not set again, by ref and cpu. After session_broken they stay off.
The contract your client receives
Text
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.
Tools