SCRYDOSBox-XReferenceHardwarepic

DOSBox-XHardware

pic

Read the 8259 interrupt controllers, or mask, unmask, acknowledge, raise or lower one interrupt line.

pic(method, irq=null)

Try it

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

Which interrupt lines are masked right now?

Call
pic(method="read")
Reply 2 of 4 fields
{
  "summary": "pic read: 2 controllers, masked 3, 5, 6, 7, 10, 11, requested none",
  "status": "ok"
}

Two controllers, with lines 3, 5, 6, 7, 10 and 11 masked and none requested. The whole reply below has a row for each controller and each line.

The whole reply
JSON
{
  "summary": "pic read: 2 controllers, masked 3, 5, 6, 7, 10, 11, requested none",
  "status": "ok",
  "controllers": [
    {
      "controller": "master",
      "icw_index": 0,
      "icw_words": 0,
      "special": false,
      "auto_eoi": false,
      "rotate_eoi": false,
      "single": false,
      "request_issr": false,
      "vector_base": "0x08",
      "active_irq": {"available": false, "why": "no line is in service"},
      "isr": "0x00",
      "isrr": "0xFF",
      "isr_ignore": "0x00"
    },
    {
      "controller": "slave",
      "icw_index": 0,
      "icw_words": 0,
      "special": false,
      "auto_eoi": false,
      "rotate_eoi": false,
      "single": false,
      "request_issr": false,
      "vector_base": "0x70",
      "active_irq": {"available": false, "why": "no line is in service"},
      "isr": "0x00",
      "isrr": "0xFF",
      "isr_ignore": "0x00"
    }
  ],
  "irqs": [
    {"irq": 0, "vector": "0x08", "requested": false, "masked": false, "in_service": false},
    {"irq": 1, "vector": "0x09", "requested": false, "masked": false, "in_service": false},
    {
      "irq": 2,
      "vector": "0x0A",
      "requested": false,
      "masked": false,
      "in_service": false,
      "cascade": true
    },
    {"irq": 3, "vector": "0x0B", "requested": false, "masked": true, "in_service": false},
    {"irq": 4, "vector": "0x0C", "requested": false, "masked": false, "in_service": false},
    {"irq": 5, "vector": "0x0D", "requested": false, "masked": true, "in_service": false},
    "... 10 more"
  ]
}

The six methods

method what it does
read Lists the controllers and every line. It writes nothing.
mask Masks line irq.
unmask Unmasks line irq.
acknowledge Clears the in-service bit of line irq.
raise Raises the request of line irq.
lower Lowers the request of line irq.

Arguments

method one of "read", "mask", "unmask", "acknowledge", "raise", "lower", required
read, or one of the five actions above.
irq integer (>= 0, <= 15), optional
The interrupt line an action works on, 0 to 15; 8 to 15 are on the slave controller. read takes none.

What comes back

controllers
On read: one row per controller, master then slave, with its vector_base, its active_irq and the registers isr and isrr.
irqs
On read: one row per line, with irq, vector, and whether it is requested, masked and in_service. cascade marks the line that links the two controllers.
line
After an action: the row of that line as it reads now, with the keys of an irqs row.
method
After an action: the action taken, with irq the line.
All 5 reply fields
  • controllers (array)
  • irq (integer)
  • irqs (array)
  • line (object)
  • method (string)

What it refuses

Why it works this way

The debugger takes any line number and acts on none past 15, so irq is checked before anything is sent.

Only a mask is read back. A raised line on an unmasked input may already have been taken by the cpu when the listing is read, so line says what the line holds afterwards.

A controller's active_irq is its own line in service, 0 to 7. With none it is unavailable: the emulator writes 8 there, which would read as a ninth line.

More on why

Every action marks the session altered, which says this session has written to the machine. A read does not.

The controllers rows also carry icw_index, icw_words, special, auto_eoi, rotate_eoi, single, request_issr and isr_ignore: the rest of the 8259's state, named as the debugger's PIC listing prints it.

The contract your client receives
Text
The 8259 interrupt controllers, which decide which hardware interrupt reaches the CPU.
Needs the machine stopped.

`read`: Reply: `controllers` (each `controller`, `vector_base`, `active_irq` (unavailable
with none in service), `isr`, `isrr`, `auto_eoi`, ...), `irqs` (each `irq`, `vector`,
`requested`, `masked`, `in_service`, `cascade`).

`mask`, `unmask`, `acknowledge` (clear its in-service bit), `raise`, `lower` (its request line):
`irq` 0 to 15. Marks the session `altered`. The timer is IRQ 0: `raise` it to run its
handler on demand. Reply: `method`, `irq`, `line` (its row after).

Refused (`bad_argument`): an `irq` out of range or on a slave this machine lacks, an
argument the method does not take. `no_channel`: a build with no `PIC` command.
`readback_refused`: a mask or unmask the listing does not show after. `not_stopped`: a
running guest. `unexpected_answer`: a listing of another shape.

Reference: REFERENCE.md, The machine's hardware.
Tools