hybrid: interrupts to userspace, and a crashed driver that stays crashed

docs/plan/hybrid.md mechanism 3. A process asks for a device's interrupts with
PCIIOC_IRQ and then reads them, which is how Linux's uio does it and for the
same reason: a descriptor composes with poll, and a driver that stops reading
falls behind rather than losing events. read() returns a count rather than a
flag, so a driver that was busy sees it missed three and acts once.

Proven against an e1000e by asserting a cause through its ICS register and
reading the interrupt back out in userspace:

    interrupts routed here (line 10)
    interrupt delivered, count = 1
    ICR = 0x80000004

0x80000004 is the cause the test set plus INT_ASSERTED -- the device's own
register, read by userspace as its acknowledgement.

**The masking is the design, not a detail.** A PCI line is level-triggered and
stays asserted until the cause is cleared at the device, which is a different
register on every chip and so is something only the driver can do. The kernel
masks the line on arrival and userspace's write() unmasks it. Signalling EOI on
a still-asserted line re-enters the handler immediately and for ever; this
kernel did exactly that by accident at 72,000 interrupts a second, and what it
looked like from outside was a clock running seven times slow (§13).

Which decides what happens when a driver dies mid-interrupt: the line is left
**masked**. The instinct is to unmask -- do not leave the device dead -- and it
is wrong, because unmasking an asserted line with no handler is a crashed
driver taking the machine down with it. Masked is safe and not permanent: the
next PCIIOC_IRQ arms it. Both halves verified by crashing a driver on purpose
and then starting another one.

A line already carrying kernel handlers is refused outright. Masking is
per-line, so handing out a shared one would silence whichever kernel driver is
also there, with nothing logged. MSI is the real answer and pci_msi_enable() is
already in the tree waiting for a caller.

Also fixed, found by running the crash twice: DMA buffers were never returned
when a process exited. The arena is 4 MB and contiguous, so a driver that
restarts a few times exhausted it -- "out of DMA memory, 3584 free" -- which is
a poor property for an interface whose whole promise is that a driver can crash
and come back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2

include/pciuser.h

@@ -19,8 +19,7 @@
 //   - to be given it, exclusively                                CLAIM
 //   - to reach its registers                                     mmap(BAR)
 //   - memory it can hand to the device                           DMA
-//   - to be told when the device wants attention                 (interrupts,
-//                                                                 not yet)
+//   - to be told when the device wants attention                 IRQ + read()
 //
 // There is no IOMMU. A process holding a DMA buffer can point the device at
 // any physical address, so this isolates a driver against its own *bugs* and
@@ -81,6 +80,37 @@ struct pciuser_dma {
 #define PCIIOC_CLAIM    0x9002   // in: int index -- take it from the kernel
 #define PCIIOC_RELEASE  0x9003   // in: int index
 #define PCIIOC_DMA      0x9004   // struct pciuser_dma
+#define PCIIOC_IRQ      0x9005   // in: int index -- deliver this device's
+                                 //     interrupts to this process
+
+// Interrupts arrive by *reading* this device, which is how Linux's uio does it
+// and for the same reason: a descriptor composes with poll, and a driver that
+// stops reading falls behind rather than losing events.
+//
+//     ioctl(fd, PCIIOC_IRQ, &index);
+//     for (;;) {
+//         unsigned long long n;
+//         read(fd, &n, sizeof n);      // blocks until the device interrupts
+//         ... service the device, and ACK IT AT THE DEVICE ...
+//         write(fd, &n, sizeof n);     // re-arm
+//     }
+//
+// **The write is not optional.** A PCI interrupt line is level-triggered: it
+// stays asserted until the driver clears the cause *at the device*, and the
+// kernel cannot do that because clearing it is device-specific -- it is a
+// different register on every chip. So the kernel masks the line when the
+// interrupt arrives and leaves it masked until the write says the device has
+// been dealt with.
+//
+// Without that, EOI is signalled on a line that is still asserted and the
+// interrupt re-fires immediately, for ever. That is not hypothetical: it
+// happened in this kernel, at 72,000 interrupts a second, and what it looked
+// like from userspace was a clock running seven times slow.
+// See docs/history/kernel.md section 13.
+//
+// One device per process. A driver drives one thing; if you need two, run two.
+
+
 
 // Registers are reached with mmap() on this device, where the *offset is the
 // physical address of the BAR*: