SCRYDOSBox-XReferenceHardwarepic
pic
Read the 8259 interrupt controllers, or mask, unmask, acknowledge, raise or lower one interrupt line.
pic(method, irq=null)
Try it
Which interrupt lines are masked right now?
pic(method="read"){
"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
{
"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.
readtakes none.
What comes back
- controllers
- On
read: one row percontroller,masterthenslave, with itsvector_base, itsactive_irqand the registersisrandisrr. - irqs
- On
read: one row per line, withirq,vector, and whether it isrequested,maskedandin_service.cascademarks 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
irqsrow. - method
- After an action: the action taken, with
irqthe line.
All 5 reply fields
controllers(array)irq(integer)irqs(array)line(object)method(string)
What it refuses
- A machine that is running (
not_stopped). - An
irqoutside 0 to 15, or on a slave controller this machine does not have (bad_argument). - An argument the method does not take (
bad_argument). - A DOSBox-X whose debugger has no
PICcommand (no_channel). - A
maskorunmaskthe listing does not show afterwards (readback_refused). - A listing in a shape the tool does not know (
unexpected_answer).
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.
Related tools
The contract your client receives
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.