SCRYDOSBox-XReferenceBreakpointsbreakpoint_interrupt
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
Stop the game when it calls DOS to exit.
breakpoint_interrupt(number="0x21", ah="0x4C"){
"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:
resume(seconds=60){
"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:
{
"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:
{
"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,
0x00to0xFF, as an integer or a0xstring:"0x21"is DOS. - ah integer or string, optional
- Stop only when
AHholds this function number,0x00to0xFF. Left out, every call of the interrupt stops. - detail boolean, default
false trueadds what the debugger printed for the command, asoutput.
What comes back
- ref
- The breakpoint's name, such as
BPINT 21 AH=4B.declaration_cleartakes it. - armed
trueonce the debugger holds it.falsewhile 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
truewhen the same breakpoint was saved already: nothing was stacked.- output
- With
detail=True, the end of what the debugger printed.output_charsis its full length, andclippedsays 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
- A
numberor anahoutside0x00to0xFF(bad_argument).
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
0x31withah=2. outputcomes only from a call that set a new breakpoint: one leftpendingor already armed typed nothing.- Without
detail,omittednames the fields left out. storedistrueonce the server saved it.
Related tools
The contract your client receives
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.