SCRYDOSBox-XReferenceBreakpointsbreakpoint_interrupt

DOSBox-XBreakpoints

breakpoint_interrupt

Stop the machine when the program calls an interrupt, optionally only one ah function of it.

breakpoint_interrupt(number, ah=null, detail=false)

Try it

On Bricks, the game this repository builds, stopped in play just after its quit flag was written, so its next pass of the main loop exits.
Ask

Stop the game when it calls DOS to exit.

Call
breakpoint_interrupt(number="0x21", ah="0x4C")
Reply 6 of 8 fields
{
  "summary": "breakpoint_interrupt BPINT 21 AH=4C: stored",
  "status": "ok",
  "ref": "BPINT 21 AH=4C",
  "stored": true,
  "armed": true,
  "entry": "BPINT 21 AH=4C"
}

Then let the game run, for a minute at most:

Call
resume(seconds=60)
Reply 4 of 15 fields
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:0000013C",
  "verdict": "OTHER_STOP",
  "cause": "most likely the held `BPINT 21 AH=4C`: the guest is at `int 21`, at 08DF:0000013C",
  "pc": "08DF:0000013C"
}

BPINT 21 AH=4C is the breakpoint's name, which declaration_clear takes. The game then stops at its exit call, and cause gives that interrupt breakpoint as the most likely reason.

The two replies, whole

The first call's:

JSON
{
  "summary": "breakpoint_interrupt BPINT 21 AH=4C: stored",
  "status": "ok",
  "ref": "BPINT 21 AH=4C",
  "stored": true,
  "armed": true,
  "entry": "BPINT 21 AH=4C",
  "omitted": ["output", "output_chars", "clipped"],
  "how": "detail=True adds what the debugger printed for this command"
}

The second call's:

JSON
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:0000013C",
  "status": "ok",
  "verdict": "OTHER_STOP",
  "omitted": ["output", "output_chars", "clipped"],
  "how": "detail=True adds what the debugger printed for this command",
  "waited_s": "<volatile>",
  "pc": "08DF:0000013C",
  "cpu_mode": "real",
  "frame": "<volatile>",
  "regs": {
    "EAX": "0x00004c00",
    "EBX": "0x0000000f",
    "ECX": "0x005b0004",
    "EDX": "0x00000000",
    "ESI": "0x00000615",
    "EDI": "0x00006192",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffe",
    "EIP": "0x0000013c",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [
    {
      "ref": "lives",
      "by": "symbol",
      "mode": "freeze",
      "length": 1,
      "fmt": "u8",
      "addr": "08DF:00000617",
      "frozen_hex": "03",
      "entries": ["FM 00000617 (03)"],
      "bytes": "03",
      "state": "holding"
    }
  ],
  "cause": "most likely the held `BPINT 21 AH=4C`: the guest is at `int 21`, at 08DF:0000013C",
  "e9": {"lines_total": 1, "truncated": false, "lines": ["Bochs port E9h: HIT 5 0"], "mark": "<volatile>"},
  "stop_seq": "<volatile>",
  "instruction": {
    "address": "08DF:0000013C",
    "bytes": "CD21",
    "text": "int 0x21",
    "flow": "call",
    "code_bits": 16,
    "bytes_from": "memory",
    "symbol": "main_loop",
    "delta": 33
  }
}

Arguments

number integer or string, required
The interrupt, 0x00 to 0xFF, as an integer or a 0x string: "0x21" is DOS.
ah integer or string, optional
Stop only when AH holds this function number, 0x00 to 0xFF. Left out, every call of the interrupt stops.
detail boolean, default false
true adds what the debugger printed for the command, as output.

What comes back

ref
The breakpoint's name, such as BPINT 21 AH=4B. declaration_clear takes it.
armed
true once the debugger holds it. false while the program runs: it is set at the next stop.
state
pending, and only while the program runs.
entry
The debugger's own row for it, once armed.
already_stored
true when the same breakpoint was saved already: nothing was stacked.
output
With detail=True, the end of what the debugger printed. output_chars is its full length, and clipped says it was cut.
All 9 reply fields
  • already_stored (boolean)
  • armed (boolean)
  • clipped (boolean)
  • entry (string)
  • ref (string)
  • output (string)
  • output_chars (integer)
  • state (string)
  • stored (boolean)

What it refuses

Why it works this way

It brings a running program back at that interrupt. stop brings it back wherever it is, and a key pressed on the host cannot. Set it before resume.

It is saved under its BPINT text, so declaration_list shows it and declaration_clear(kind="breakpoint") removes it by ref. It is never cleared by the debugger's row number, which would delete whichever row sits there.

Setting the same one again does nothing, checked against the debugger's list. Sent twice, the debugger stacks a second row that a later clear leaves behind as foreign.

More on why
  • A DJGPP program can be caught at interrupt 0x31 with ah=2.
  • output comes only from a call that set a new breakpoint: one left pending or already armed typed nothing.
  • Without detail, omitted names the fields left out.
  • stored is true once the server saved it.
The contract your client receives
Text
Break on an interrupt, optionally one `ah` function. Arm it before `resume`. `number` and
`ah` are `0x` hex (`"0x21"` for DOS) or integers, 0x00 to 0xFF. Pending while the guest
runs.

Reply: `ref` (e.g. `BPINT 21 AH=4B`, what `declaration_clear` takes), `stored`,
`already_stored`, `armed`, `state` (while the guest runs), `entry` (once armed);
with `detail=True` also `output`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools