SCRYDOSBox-XReferenceRunrun_forAlso in MAME
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
brick_hit in the middle of a game.Run three frames, then stop.
run_for(frames=3){
"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
{
"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 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:
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_beforeis the one before. Unavailable, with why, whenRUNSTATEprints no frame count. - emulated_after_s
- The emulated clock after the run, in seconds;
emulated_before_sis the one before. - cycles
- The cpu cycles the run took. A count only on a session started on the
normalcpu core; otherwise unavailable, with why. - polls
- How many retraces the run stopped at.
- retrace_pending
truewhen 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
- Both
millisecondsandframesabove zero, or neither, or a negative one (bad_argument). - A run during which the emulated clock did not move (
no_progress). millisecondswhenRUNSTATEgave no clock to count from; nothing ran (unexpected_answer).- A DOSBox-X whose debugger has no
RUNSTATEcommand (no_channel). - A machine that is running (
not_stopped).
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.
notesays when one is set. - A
TIMEOUTwhoseVRTis still running is interrupted where it stands, with its retrace left pending. notestates 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.
Related tools
The contract your client receives
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.