riscv64: virtio-keyboard-pci, interrupt-driven keyboard input (item 4.3.5c)

Punch list §25 item 4.3.5c complete.

Amended from a nonexistent MMIO transport to PCI (matching the board's
actual virtio-blk-pci precedent). New virtio-input driver: eventq with
pre-posted buffers, PLIC source computed at runtime from PCI slot/pin
(derived live from this host's QEMU riscv64 DTB), mandatory ISR-status
read, PCI interrupt-disable-bit check. New VKBD-EVENT/VKBD-DEBUG FORTH
words. Verified with a real QEMU sendkey keypress: exact KEY_A/press
match, two real interrupts serviced, zero exceptions. Three-arch
acceptance boot clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

include/starkernel/pci.h

@@ -31,11 +31,15 @@
 #define PCI_CFG_BAR5         0x24
 #define PCI_CFG_CAP_PTR      0x34
 #define PCI_CFG_INT_LINE     0x3C
+#define PCI_CFG_INT_PIN      0x3D   /* 0=none, 1=INTA .. 4=INTD (item 4.3.5c/4.3.5d) */
 
 /* PCI command register bits */
 #define PCI_CMD_IO_SPACE     (1u << 0)
 #define PCI_CMD_MEM_SPACE    (1u << 1)
 #define PCI_CMD_BUS_MASTER   (1u << 2)
+#define PCI_CMD_INTX_DISABLE (1u << 10)  /* item 4.3.5c/4.3.5e: pci_enable() never
+                                           * clears this -- if firmware left it set,
+                                           * INTx never asserts. Check explicitly. */
 
 /* BAR type flags */
 #define PCI_BAR_TYPE_MASK    0x1u

include/starkernel/virtio_input.h

@@ -0,0 +1,68 @@
+/*
+ * virtio_input.h — Virtio 1.0 input device driver for StarKernel (item 4.3.5c)
+ *
+ * riscv64-only today (PCI transport, PLIC interrupt routing). aarch64's
+ * 4.3.5e reuses this device identity/event shape over the same PCI
+ * transport with GIC routing instead; riscv64/aarch64-specific pieces stay
+ * in their own arch trees, not here.
+ *
+ * Interrupt-driven end to end: the driver pre-posts empty event buffers
+ * into the eventq and the device fills+posts them asynchronously, signalled
+ * by the PLIC (via 4.3.5b's claim/complete substrate) — no polling.
+ */
+
+#ifndef STARKERNEL_VIRTIO_INPUT_H
+#define STARKERNEL_VIRTIO_INPUT_H
+
+#include <stdint.h>
+
+/* virtio PCI vendor (same device family as virtio-blk) */
+#define VIRTIO_INPUT_PCI_VENDOR_ID  0x1AF4u
+/* Modern-ID formula 0x1040 + VIRTIO_ID_INPUT, VIRTIO_ID_INPUT = 18, per
+ * this build host's /usr/include/linux/virtio_ids.h. No legacy/transitional
+ * ID exists for virtio-input (postdates the legacy 0.9.5 spec). */
+#define VIRTIO_INPUT_PCI_DEVICE_ID  0x1052u
+
+/* struct virtio_input_event, per /usr/include/linux/virtio_input.h (BSD
+ * licensed, same wire format this driver decodes). */
+typedef struct {
+    uint16_t type;
+    uint16_t code;
+    uint32_t value;
+} VirtioInputEvent;
+
+/* EV_KEY, per /usr/include/linux/input-event-codes.h */
+#define VIRTIO_INPUT_EV_KEY  0x01u
+
+/*
+ * virtio_input_find_keyboard — locate a virtio-keyboard-pci device on the
+ *                              PCI bus, initialise the driver, compute and
+ *                              enable its PLIC interrupt source (item
+ *                              4.3.5c's own derivation, FABRIC.md §27.5.2),
+ *                              and pre-post the eventq's receive buffers.
+ *
+ * Returns  0 on success.
+ * Returns -1 if no virtio-keyboard-pci device was found on the PCI bus.
+ * Returns -2 on driver initialisation failure (bad BAR, queue setup, etc.).
+ */
+int virtio_input_find_keyboard(void);
+
+/*
+ * virtio_input_isr — called from riscv64_interrupt_handler() when the PLIC
+ *                    claim matches this driver's computed source. Reads the
+ *                    ISR-status capability (mandatory — the routed source
+ *                    is level-triggered; skipping this leaves it latched),
+ *                    drains the used ring, pushes decoded EV_KEY events into
+ *                    the diagnostic ring buffer (keyboard_words.c), and
+ *                    re-posts drained buffers to the eventq's avail ring.
+ */
+void virtio_input_isr(void);
+
+/*
+ * virtio_input_pop_event — diagnostic-ring consumer for keyboard_words.c's
+ *                          VKBD-EVENT, same shape as i8042_pop_scancode().
+ * Returns 1 and fills *code and *value if an event was available, 0 otherwise.
+ */
+int virtio_input_pop_event(uint16_t *code, uint32_t *value);
+
+#endif /* STARKERNEL_VIRTIO_INPUT_H */