SCRYDOSBox-XReferenceRunstepAlso in MAME
step
Execute a few instructions, going into calls or over them.
step(count=1, mode="into")
Try it
brick_hit, where the run_to example above ends.Execute two instructions and show me where the program is now.
step(count=2){
"summary": "step 2: 2 done, at 08DF:000002CC",
"mode": "into",
"instructions_completed": 2,
"before": "08DF:000002C8",
"after": "08DF:000002CC",
"moved": true,
"stalled": 0
}Both instructions ran, from 08DF:000002C8 to 08DF:000002CC. stalled: 0 says neither of them left the address unchanged.
The whole reply
{
"summary": "step 2: 2 done, at 08DF:000002CC",
"status": "ok",
"mode": "into",
"asked": 2,
"moved": true,
"stalled": 0,
"before": "08DF:000002C8",
"after": "08DF:000002CC",
"instructions_completed": 2,
"pc": "08DF:000002CC",
"cpu_mode": "real",
"frame": 36,
"regs": {
"EAX": "0x00000000",
"EBX": "0x00000700",
"ECX": "0x005b0020",
"EDX": "0x00000000",
"ESI": "0x00000039",
"EDI": "0x000064e4",
"EBP": "0x0000091c",
"ESP": "0x0000fffa",
"EIP": "0x000002cc",
"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": "the stop `step` made after 2 steps, at 08DF:000002CC",
"e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
"stop_seq": 4,
"instruction": {
"address": "08DF:000002CC",
"bytes": "E81FFF",
"text": "call 0x1ee",
"flow": "call",
"code_bits": 16,
"bytes_from": "memory",
"symbol": "brick_hit",
"delta": 4
}
}The two modes
| mode | what it does |
|---|---|
into |
Executes one instruction, and enters a call. |
over |
Runs a CALL, an INT, a LOOP or a REP to the next instruction as one step. |
Arguments
- count integer (>= 1, <= 64), default
1 - How many instructions to execute. Left out, one.
- mode one of
"over","into", default"into" intoorover, as above.
What comes back
- instructions_completed
- How many instructions ran. Fewer than
askedwhen anoverdid not come back and the remaining steps were not sent. - mode
- The
modethe steps ran in. - before
- Where the machine was before the steps, as
SEG:OFF;afteris where it is now. - moved
falsewhen no step changed the address.- stalled
- How many steps left the address unchanged: an iteration of a
rep, a jump to itself or a halt.
All 18 reply fields
after(string)asked(integer)cause(string)regpoint_hit(object)before(string)cpu_mode(string or object)e9(object)enrichment(object)frame(integer or object)instruction(DosboxInstruction)instructions_completed(integer)mode(string)moved(boolean)pc(string)regs(object)stalled(integer)stop_seq(integer)watches(array)
What it refuses
overon a DOSBox-X whose debugger has noRUNSTATEcommand (no_channel).- A machine that is running (
not_stopped).
Why it works this way
into is the debugger's own STEPIN. over is built from several commands: a breakpoint on the next instruction, a run, a wait for the stop, and the breakpoint removed. That wait is why over needs RUNSTATE.
An over that has not come back within its time limit is interrupted where it stands, and the remaining steps are not sent. A machine that could not be stopped is left running, which session.running says. note appears when the step's own breakpoint could not be confirmed removed.
stalled is counted step by step, because comparing only the two ends would read a two-instruction loop as a step that went nowhere. The largest count limits cost, not risk: past it the tool to use is run_to.
Related tools
The contract your client receives
`count` instructions, each read back; `mode` `into` (the debugger's `STEPIN`) or `over` (a
CALL, INT, LOOP or REP run to the next instruction, which needs `RUNSTATE`). Needs the machine
stopped.
Reply: `mode`, `asked`, `before`, `after`, `instructions_completed`, `moved`, `stalled`
(CS:EIP unchanged after a step), `note` (a step over's own breakpoint not confirmed removed),
and the stop reply; an `over` that does not come back within its bound is stopped where it
stands, and no later step is sent. For longer runs `run_to`.