SCRYDOSBox-XReferenceRunrun_forAlso in MAME

DOSBox-XRun

run_for

Run for a number of frames or milliseconds of emulated time and come back stopped.

run_for(milliseconds=0, frames=0, seconds=30.0, disarm_watches=false)

Try it

On Bricks, the game this repository builds, stopped at brick_hit in the middle of a game.
Ask

Run three frames, then stop.

Call
run_for(frames=3)
Reply 5 of 18 fields
{
  "verdict": "ELAPSED",
  "polls": 3,
  "frame_before": 244,
  "frame_after": 247,
  "cycles": 68499
}

ELAPSED says the three frames ran out as asked. The frame counter went from 244 to 247 in three stops at the retrace, and the cpu spent 68499 cycles.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "verdict": "ELAPSED",
  "polls": 3,
  "pc": "<volatile>",
  "cpu_mode": "real",
  "frame": 247,
  "regs": "<volatile>",
  "watches": [],
  "cause": "<volatile>",
  "e9": {"lines_total": 1, "truncated": false, "lines": ["Bochs port E9h: HIT 5 0"], "mark": "<volatile>"},
  "stop_seq": 11,
  "instruction": "<volatile>",
  "emulated_before_s": "<volatile>",
  "emulated_after_s": "<volatile>",
  "frame_before": 244,
  "frame_after": 247,
  "cycles": 68499
}

Arguments

milliseconds integer, default 0
How much emulated time to run, in milliseconds. Give this or frames, never both.
frames integer, default 0
How many frames to run, each counted at the screen's vertical retrace. Give this or milliseconds, never both.
seconds number (> 0, <= 600.0), default 30.0
How long to wait for the run to end, in real seconds. 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: ELAPSED, the frames or time asked for ran out, as asked; TIMEOUT, the wait gave up; OTHER_STOP, a breakpoint or a watch stopped it first.
frame_after
The frame counter after the run; frame_before is the one before. Unavailable, with why, when RUNSTATE prints no frame count.
emulated_after_s
The emulated clock after the run, in seconds; emulated_before_s is the one before.
cycles
The cpu cycles the run took. A count only on a session started on the normal cpu core; otherwise unavailable, with why.
polls
How many retraces the run stopped at.
retrace_pending
true when a stop at the next retrace is still armed in the debugger, so the next resume stops there.
All 21 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • cycles (integer or object)
  • e9 (object)
  • emulated_after_s (number or object)
  • emulated_before_s (number)
  • enrichment (object)
  • frame (integer or object)
  • frame_after (integer or object)
  • frame_before (integer or object)
  • instruction (DosboxInstruction)
  • pc (string or object)
  • polls (integer)
  • regs (object)
  • retrace_pending (boolean)
  • stop_seq (integer)
  • verdict (string)
  • watches (array)
  • disarmed_watches (array)
  • not_rearmed (array)

What it refuses

Why it works this way

The run is the debugger's VRT command, once per frame. By milliseconds it still ends on a retrace, the first at or past the time asked, so it can run over by up to one frame. A stop between two retraces is not one a replay could reach again.

A breakpoint that stops the run in the middle of a frame leaves that frame's retrace stop armed in the debugger. The reply is OTHER_STOP with retrace_pending: true, and the next resume stops at the next retrace. The first later stop that none of your breakpoints explains names that retrace as the likeliest cause.

An ELAPSED run of N frames, with nothing else able to stop the machine, moves frame by exactly N. On a dynamic cpu core a code breakpoint set after its code already ran can fail to stop the frames after it. So ELAPSED there does not prove its address was not reached, which note says.

More on why
  • The stop of a change watch or an interrupt breakpoint cannot be told from a retrace, so it counts as a frame. note says when one is set.
  • A TIMEOUT whose VRT is still running is interrupted where it stands, with its retrace left pending.
  • note states what the reply cannot prove: a breakpoint or a watch that is set, a clock that could not be read.
  • A run does not mark the session altered.
  • The call reports progress to the client while it waits.
The contract your client receives
Text
Run for `frames` display frames (one `VRT` each) or `milliseconds` of emulated time (exactly
one) and come back STOPPED. `milliseconds` runs whole frames, so it ends at the first
retrace at or past the time asked, up to one frame later. Reports progress while it waits.
`disarm_watches=true` disarms the watches for this pass, so none of them cuts it. Needs the machine stopped.

Reply: `verdict` (`ELAPSED`, `OTHER_STOP`, `TIMEOUT`), `polls`, `emulated_before_s`,
`emulated_after_s`, `frame_before`, `frame_after`, `cycles` (a count on the normal core, else
unavailable with why), `retrace_pending` (a retrace stop is left armed), `note`,
the stop: `pc` (`SSSS:OOOOOOOO`), `cpu_mode`, `stop_seq`, `frame`, `instruction`, `regs`, `watches`, `cause`, `regpoint_hit` (a registerpoint stopped it) and `e9`. INVALID: `no_progress`, `unexpected_answer`.

Reference: REFERENCE.md, Running and stopping.
Tools