SCRYDOSBox-XReferenceMachineinterrupt_vectors

DOSBox-XMachine

interrupt_vectors

See which handler each interrupt vector points at, and which program, DOS block or BIOS block holds that handler.

interrupt_vectors(number=null)

Try it

On Bricks, the game this repository builds, stopped at its play screen.
Ask

Who handles the mouse interrupt, INT 33h?

Call
interrupt_vectors(number="0x33")
Reply 3 of 7 fields
{
  "summary": "interrupt_vectors INT 33: C402:00000010, mcbs 9FFF SC (DOS)",
  "cpu_mode": "real",
  "counts": {"vectors": 256, "held": 112, "named": 0}
}

INT 33h points at C402:0010, inside the memory block at segment 9FFF, which is marked as DOS's. Of the 256 vectors, 112 sit in a known block (held) and none has a symbol (named).

The whole reply
JSON
{
  "summary": "interrupt_vectors INT 33: C402:00000010, mcbs 9FFF SC (DOS)",
  "status": "ok",
  "cpu_mode": "real",
  "vectors": [
    {
      "number": "0x33",
      "seg_off": "C402:00000010",
      "addr": "0x000c4030",
      "mcbs": {
        "memory": "upper",
        "mcb_seg": "9FFF",
        "size_bytes": 180224,
        "psp_seg": "0008",
        "notes": "DOS",
        "filename": "SC"
      }
    }
  ],
  "counts": {"vectors": 256, "held": 112, "named": 0},
  "sources": {
    "vectors": ["INTVEC"],
    "mcbs": ["DOS MCBS"],
    "kern": ["DOS KERN"],
    "bios_mem": ["BIOS MEM"],
    "control": ["CPU"]
  },
  "coverage_note": "read from the debugger's own listings at this stop. `gdt` and `ldt` are absent: the cpu is in real mode, where the debugger reads the interrupt vector table as descriptors. `paging` is absent: paging is off"
}

Arguments

number integer or string, optional
One vector to return, 0x00 to 0xFF, as an integer or 0x text. Left out, all 256 come back.

What comes back

vectors
One row per vector: number, the handler's seg_off and linear addr, the block that holds it under mcbs, kern or bios_mem, and the nearest symbol.
counts
vectors, how many the table has; held, how many sit in a known block; named, how many have a symbol.
cpu_mode
The mode at this stop: real, VM86, protected or paged. In protected mode the table read is the IDT.
coverage_note
What could not be worked out, and why: a vector with no addr, a handler no block holds, a table still empty.
sources
The debugger command behind the vectors and behind each listing the blocks came from.
All 5 reply fields
  • counts (object)
  • coverage_note (string)
  • cpu_mode (string or object)
  • sources (object)
  • vectors (array)

What it refuses

Why it works this way

Each handler is matched to the block of memory that holds it, so the reply says which program hooked a vector with no earlier table to compare. The first block holding the address wins: mcbs, then kern, then bios_mem.

Right after start every vector reads 0000:0000: DOS has not filled the table yet.

symbol is what symbols_find(linear=...) answers for the handler, given only between the table's lowest and highest symbol.

More on why

The debugger writes the table to a file, MCPIVT.TXT, which the server reads and removes. The whole table is read even for one number, with the listings machine_map reads, one exchange with the debugger each.

The contract your client receives
Text
Which handler every interrupt vector points at and what holds it, from the debugger's
`INTVEC` table: a handler is placed in the MCB, kernel or BIOS block holding it and named by
loaded symbols. `number` (`0x` hex or an integer, 0x00 to 0xFF) narrows the reply to one
vector. In protected mode the
table is the IDT.

Reply: `cpu_mode`, `vectors` (each `number` as `0x` hex, `seg_off`, `addr`, a holder row,
`symbol`),
`counts`, `sources`, `coverage_note`.

Refused: `number` out of range or a `MCPIVT.TXT` already there (`bad_argument`); a running
guest (`not_stopped`); an incomplete table (`unexpected_answer`); `machine_map`'s listing
refusals.

Reference: REFERENCE.md, Reading and writing.
Tools