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
run_toRun until the program reaches an address, or a screen of the screen map, and stop there.run_forRun for a number of frames or milliseconds of emulated time and come back stopped.traceRun a number of instructions with the debugger's CPU log on and get every address executed, grouped by symbol.screen_waitRun until the screen shows a text, a mapped screen, a black palette or a change of screen, and stop there.stepExecute a few instructions, going into calls or over them.resumeLet the machine run, either with no deadline or waiting a while for it to stop.waitLet a running program play for a while and see where it is after, without stopping it.stopStop a running machine where it is and read where it stopped.