SCRYDOSBox-XReferenceRunrun_toAlso in MAME
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
Run until the ball hits a brick, and check that the game's retrace wait keeps running meanwhile.
run_to(ref="brick_hit", control="retrace", seconds=60){
"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
{
"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 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.
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: its
ref,at(where the debugger set it),hits_in_runandremoved. It comes with a run to arefor 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
anchortook. - screen
- After a run to a screen: its
screen,layerandmode, andjudged, 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
- A
refor acontrolthat no loaded symbol table holds, or ascreenthe map does not name (unknown_ref). - A name that several symbols share (
ambiguous_ref). - No
controlwith arefor an anchored screen, or acontrolordisarm_watcheswith a screen that has no anchor (bad_argument). - A control at the target's address (
bad_argument). - A breakpoint the debugger does not list after being told to set it, 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). - A machine that did not report stopped after the interrupt at the time limit (
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
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_watcheslists, byref, 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_stopsays when. - A watch the debugger kept in spite of the removal is named in
note, since it could still stop the run.
Related tools
The contract your client receives
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.