SCRYDOSBox-XReferenceRunrun_toAlso in MAME

DOSBox-XRun

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)

Try it

On Bricks, the game this repository builds, stopped on its play screen with its symbols loaded.
Ask

Run until the ball hits a brick, and check that the game's retrace wait keeps running meanwhile.

Call
run_to(ref="brick_hit", control="retrace", seconds=60)
Reply 5 of 17 fields
{
  "summary": "run_to brick_hit: TARGET at 08DF:000002C8, control counted 34",
  "verdict": "TARGET",
  "target_disarmed": true,
  "control_hits": 34,
  "controls": [
    {"ref": "retrace", "at": "08DF:0580", "hits_in_run": 34, "removed": true}
  ]
}

The run reached brick_hit, which is what TARGET says. The control retrace ran 34 times on the way, so breakpoints were firing, and both breakpoints of the run are removed.

The whole reply
JSON
{
  "summary": "run_to brick_hit: TARGET at 08DF:000002C8, control counted 34",
  "status": "ok",
  "verdict": "TARGET",
  "target": "08DF:02C8",
  "ref": "brick_hit",
  "pc": "08DF:000002C8",
  "cpu_mode": "real",
  "target_disarmed": true,
  "control_hits": 34,
  "controls": [
    {"ref": "retrace", "at": "08DF:0580", "hits_in_run": 34, "removed": true}
  ],
  "frame": 36,
  "regs": {
    "EAX": "0x00000005",
    "EBX": "0x00000707",
    "ECX": "0x005b0020",
    "EDX": "0x00000000",
    "ESI": "0x00000039",
    "EDI": "0x000064e4",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffa",
    "EIP": "0x000002c8",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [
    {
      "ref": "ball_x",
      "by": "symbol",
      "mode": "show",
      "length": 8,
      "fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
      "state": "evaluated",
      "value": {"x": 230, "y": 78, "dx": 2, "dy": -2},
      "bytes": "e6004e000200feff"
    }
  ],
  "cause": "run_to's target brick_hit at 08DF:000002C8",
  "e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
  "stop_seq": 3,
  "instruction": {
    "address": "08DF:000002C8",
    "bytes": "88DF",
    "text": "mov bh, bl",
    "flow": "sequential",
    "code_bits": 16,
    "bytes_from": "memory",
    "comment": "AL = row, BL = column of the brick that falls",
    "symbol": "brick_hit",
    "delta": 0
  }
}

Arguments

ref string, default ""
The address to stop at: a loaded symbol or a hex SEG:OFF. 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.

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: its ref, at (where the debugger set it), hits_in_run and removed. It comes with a run to a ref or an anchor.
target_disarmed
Whether the run's own breakpoint at the target was removed.
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 21 reply fields
  • disarmed_watches (array)
  • not_rearmed (array)
  • cause (string)
  • regpoint_hit (object)
  • control_hits (integer)
  • controls (array)
  • cpu_mode (string or object)
  • e9 (object)
  • enrichment (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • pc (string)
  • ref (string)
  • regs (object)
  • screen (object)
  • frames (integer)
  • stop_seq (integer)
  • target (string)
  • target_disarmed (boolean)
  • verdict (string)
  • watches (array)

What it refuses

Why it works this way

A breakpoint can stay silent for reasons that have nothing to do with the program, as one set in ROM does. That looks exactly like "that routine is never called". The control counting beside the target tells them apart, so a TIMEOUT with no control hit is refused: it proves nothing about the target.

The target is a temporary breakpoint of the run's own, removed however the run ends. The debugger's breakpoints are persistent, so one left behind would stop the next resume at an address none of your breakpoints names. target is that breakpoint as the debugger lists it.

disarm_watches is for a watch on a byte written every frame, which would otherwise stop every later run.

More on why

A dynamic cpu core runs its recompiled blocks past a code breakpoint without checking it, so a run there could miss its target and read as "never reached". start, run_to and breakpoint_at say so in note when the conf's [cpu] core= or a -set "cpu core=..." flag selects it.

That note names the way out, start(flags=["-set", "cpu core=normal"]). auto is noted by run_to and breakpoint_at too, because its protected-mode code runs on the dynamic core. normal is not noted.

A control stops the machine at each hit, and the server counts it and resumes. Pick a control that runs a few times during the run: each hit costs a stop and a resume. control_silent and cut_by_other_stop still carry the stop's readings.

With disarm_watches the watches are removed from the debugger for the run and set again at its stop. Their addresses are worked out afresh, so a watch on a pointer that moved follows it. One that cannot be set there waits for the next stop, and not_rearmed names it with why.

  • disarmed_watches lists, by ref, the watches taken off for the run.
  • If the call fails with no reply, what it took off is set again or left waiting. The next stop's applied_on_stop says when.
  • A watch the debugger kept in spite of the removal is named in note, since it could still stop the run.
The contract your client receives
Text
Run until a symbol or a `SEG:OFF` and say where it stopped.

`ref`: a loaded symbol or hex `SEG:OFF`. `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, so a bound that expires with no control hit is INVALID, not "it did not arrive"; each
control `breakpoint_at(role="control")` declared counts too. `disarm_watches=true` disarms the watches for this pass, so none of them cuts it. Needs a
stopped machine. Refused: an absent or ambiguous name. On a dynamic cpu core, or `auto`
(protected-mode code runs dynamic), which can pass over a breakpoint inside a compiled block,
`note` says so.

`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`, `OTHER_STOP`, `TIMEOUT`), `target_disarmed`, `control_hits`,
`controls` (`ref`, `at`, `hits_in_run`; a run to a ref or an anchor), `frames` (a screen with
no anchor), `note`, the stop (`pc`, `frame`, `regs`, `cause`). INVALID: `control_silent`,
`cut_by_other_stop`, `not_settled`, `stale_map`.

Reference: REFERENCE.md, Running and stopping.
Tools