/*
 * 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 */