SCRYDOSBox-XReferenceRunAlso in MAME

The Run tools

These tools let the program run and stop it again: to an address, for a number of frames, one instruction at a time, or with no deadline. Most other tools read the machine only while it is stopped, and REFERENCE.md says which ones answer while it runs.

A frame is counted here at the vertical retrace: the moment the display finishes drawing a frame and goes back to the top of the screen. DOS programs wait for it before they draw. The debugger's VRT command runs to the next one.

What every stop returns

A reply that ends at a stop carries the same readings whatever the call was about: stop_seq, pc, cpu_mode, frame, instruction, regs, watches, cause and e9. REFERENCE.md describes each.

frame counts the frames the emulator's vertical timer has started since power-on, so a frame number names one instant of a run, and perform(until_frame=F) relies on it. It belongs to this run, not to a saved state: after a load it goes on counting.

The count is read from RUNSTATE, the debugger command that says whether the machine is stopped. A build whose RUNSTATE prints no frames= leaves frame unavailable, saying so.

When the machine stopped and the stop could not be read, the reply keeps the tool's own fields. In place of the stop's readings it carries enrichment, as available: false with why.

A stop inside the BIOS ROM is where the machine stood, not where your program is: a program that called the BIOS is inside a handler there. The note gives the address and the calls that leave it, because step there stays inside the handler, one instruction at a time.

The tools