SCRYDOSBox-XReferenceRunstepAlso in MAME

DOSBox-XRun

step

Execute a few instructions, going into calls or over them.

step(count=1, mode="into")

Try it

On Bricks, the game this repository builds, stopped at brick_hit, where the run_to example above ends.
Ask

Execute two instructions and show me where the program is now.

Call
step(count=2)
Reply 7 of 18 fields
{
  "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
JSON
{
  "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"
into or over, as above.

What comes back

instructions_completed
How many instructions ran. Fewer than asked when an over did not come back and the remaining steps were not sent.
mode
The mode the steps ran in.
before
Where the machine was before the steps, as SEG:OFF; after is where it is now.
moved
false when 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

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.

The contract your client receives
Text
`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`.
Tools