LithosAnanake/include/starkernel/xhci.h

/*
 * xhci.h — xHCI (Extensible Host Controller Interface, USB 3.x) register
 * layout and shared constants for StarKernel's USB host controller driver.
 *
 * Register layout from the xHCI 1.2 specification. Four MMIO regions, each
 * reached via an offset from PCI BAR0:
 *   Capability Registers  — at BAR0 + 0, fixed layout, CAPLENGTH gives the
 *                            offset to Operational Registers
 *   Operational Registers — at BAR0 + CAPLENGTH
 *   Runtime Registers     — at BAR0 + RTSOFF (read from Capability Registers)
 *   Doorbell Array        — at BAR0 + DBOFF  (read from Capability Registers)
 *
 * Struct fields are `volatile`, naturally aligned, NOT __attribute__((packed))
 * — matching virtio_blk.c's precedent and its documented riscv64 lesson:
 * packed structs force byte-wise loads/stores on strict-alignment targets,
 * and QEMU's MMIO handlers for exact-width registers can misbehave under
 * byte-wise access. The xHCI spec's register layout is naturally aligned at
 * every offset, so this translates directly without padding tricks.
 *
 * QEMU's `qemu-xhci` device identifies as PCI vendor 0x1B36 (Red Hat, Inc.),
 * device 0x000D — confirmed live via QMP `query-pci` against a real running
 * instance (not assumed from memory), 2026-08-22.
 */

#ifndef STARKERNEL_XHCI_H
#define STARKERNEL_XHCI_H

#include <stdint.h>

/* -------------------------------------------------------------------------
 * PCI identification
 * ------------------------------------------------------------------------- */

#define XHCI_PCI_VENDOR_ID  0x1B36u  /* Red Hat, Inc. (QEMU qemu-xhci) */
#define XHCI_PCI_DEVICE_ID  0x000Du

/* -------------------------------------------------------------------------
 * Capability Registers (BAR0 + 0)
 * ------------------------------------------------------------------------- */

typedef struct {
    volatile uint8_t  cap_length;    /* offset to Operational Registers */
    volatile uint8_t  reserved0;
    volatile uint16_t hci_version;   /* BCD xHCI spec version */
    volatile uint32_t hcs_params1;   /* MaxSlots[7:0], MaxIntrs[18:8], MaxPorts[31:24] */
    volatile uint32_t hcs_params2;   /* IST, ERST Max, scratchpad buffer counts */
    volatile uint32_t hcs_params3;   /* U1/U2 device exit latencies */
    volatile uint32_t hcc_params1;   /* AC64, BNC, CSZ, xECP pointer[31:16], etc. */
    volatile uint32_t db_off;        /* Doorbell Array offset (low 2 bits reserved) */
    volatile uint32_t rts_off;       /* Runtime Register Space offset (low 5 bits reserved) */
    volatile uint32_t hcc_params2;
} xhci_cap_regs_t;

#define XHCI_HCSPARAMS1_MAX_SLOTS(v)  ((uint32_t)(v) & 0xFFu)
#define XHCI_HCSPARAMS1_MAX_INTRS(v)  (((uint32_t)(v) >> 8)  & 0x7FFu)
#define XHCI_HCSPARAMS1_MAX_PORTS(v)  (((uint32_t)(v) >> 24) & 0xFFu)

/* -------------------------------------------------------------------------
 * Operational Registers (BAR0 + cap_length)
 * ------------------------------------------------------------------------- */

typedef struct {
    volatile uint32_t usb_cmd;       /* Run/Stop, HC Reset, Interrupter Enable, ... */
    volatile uint32_t usb_sts;       /* HCHalted, HSE, EINT, PCD, CNR, HCE */
    volatile uint32_t page_size;     /* bit N set => 2^(N+12)-byte pages supported */
    volatile uint32_t reserved0[2];
    volatile uint32_t dn_ctrl;       /* Device Notification Control */
    volatile uint64_t crcr;          /* Command Ring Control Register */
    volatile uint32_t reserved1[4];
    volatile uint64_t dcbaap;        /* Device Context Base Address Array Pointer */
    volatile uint32_t config;        /* MaxSlotsEn[7:0] */
    /* Port Register Sets follow at a fixed offset (0x400 from Operational
     * base), not contiguous with the fields above — accessed via
     * xhci_port_regs() below, not as a struct member. */
} xhci_op_regs_t;

/* USBCMD bits */
#define XHCI_USBCMD_RUN        (1u << 0)  /* Run/Stop: 1 = run */
#define XHCI_USBCMD_HCRST      (1u << 1)  /* HC Reset */
#define XHCI_USBCMD_INTE       (1u << 2)  /* Interrupter Enable */
#define XHCI_USBCMD_HSEE       (1u << 3)  /* Host System Error Enable */

/* USBSTS bits */
#define XHCI_USBSTS_HCH        (1u << 0)  /* HC Halted */
#define XHCI_USBSTS_HSE        (1u << 2)  /* Host System Error */
#define XHCI_USBSTS_EINT       (1u << 3)  /* Event Interrupt */
#define XHCI_USBSTS_PCD        (1u << 4)  /* Port Change Detect */
#define XHCI_USBSTS_CNR        (1u << 11) /* Controller Not Ready */
#define XHCI_USBSTS_HCE        (1u << 12) /* Host Controller Error */

/* CRCR bits (low bits of the 64-bit register; pointer occupies bits[63:6]) */
#define XHCI_CRCR_RCS          (1ull << 0) /* Ring Cycle State */
#define XHCI_CRCR_CS            (1ull << 1) /* Command Stop */
#define XHCI_CRCR_CA            (1ull << 2) /* Command Abort */
#define XHCI_CRCR_CRR            (1ull << 3) /* Command Ring Running (read-only) */
#define XHCI_CRCR_PTR_MASK      (~0x3Full)  /* pointer must be 64-byte aligned */

/* CONFIG */
#define XHCI_CONFIG_MAX_SLOTS_EN(n)  ((uint32_t)(n) & 0xFFu)

/* Port Register Set — array at Operational base + 0x400, 0x10 bytes each,
 * indexed 0..(MaxPorts-1) for ports numbered 1..MaxPorts. */
typedef struct {
    volatile uint32_t portsc;    /* Port Status and Control */
    volatile uint32_t portpmsc;  /* Port Power Management Status and Control */
    volatile uint32_t portli;    /* Port Link Info */
    volatile uint32_t porthlpmc; /* Port Hardware LPM Control */
} xhci_port_regs_t;

#define XHCI_PORT_REGS_OFFSET   0x400u

/* PORTSC bits (subset needed for hotplug + reset) */
#define XHCI_PORTSC_CCS         (1u << 0)  /* Current Connect Status */
#define XHCI_PORTSC_PED         (1u << 1)  /* Port Enabled/Disabled */
#define XHCI_PORTSC_PR          (1u << 4)  /* Port Reset */
#define XHCI_PORTSC_PLS_MASK    (0xFu << 5) /* Port Link State */
#define XHCI_PORTSC_PP          (1u << 9)  /* Port Power */
#define XHCI_PORTSC_SPEED_MASK  (0xFu << 10)
#define XHCI_PORTSC_CSC         (1u << 17) /* Connect Status Change */
#define XHCI_PORTSC_PEC         (1u << 18) /* Port Enabled/Disabled Change */
#define XHCI_PORTSC_PRC         (1u << 21) /* Port Reset Change */
/* Writing 1 to a _C (change) bit clears it (RW1CS) — writing 0 has no effect.
 * PORTSC also has RW1CS bits interleaved with RW bits; always read-modify-
 * write with the change bits masked to 0 unless intentionally clearing one,
 * to avoid accidentally acknowledging an event by a stray read-modify-write. */

/* -------------------------------------------------------------------------
 * Runtime Registers (BAR0 + rts_off)
 * ------------------------------------------------------------------------- */

typedef struct {
    volatile uint32_t iman;      /* Interrupt Management: bit0=IP, bit1=IE */
    volatile uint32_t imod;      /* Interrupt Moderation */
    volatile uint32_t erstsz;    /* Event Ring Segment Table Size */
    volatile uint32_t reserved0;
    volatile uint64_t erstba;    /* Event Ring Segment Table Base Address */
    volatile uint64_t erdp;      /* Event Ring Dequeue Pointer; bit3=EHB */
} xhci_intr_regs_t;

typedef struct {
    volatile uint32_t mf_index;  /* Microframe Index */
    volatile uint32_t reserved0[7];
    /* Interrupter Register Sets follow, one xhci_intr_regs_t per interrupter,
     * starting immediately after this 0x20-byte header. Interrupter 0 is
     * accessed via xhci_intr_regs_t at (runtime_base + 0x20). */
} xhci_runtime_regs_t;

#define XHCI_IMAN_IP            (1u << 0)  /* Interrupt Pending */
#define XHCI_IMAN_IE            (1u << 1)  /* Interrupt Enable */
#define XHCI_ERDP_EHB           (1ull << 3) /* Event Handler Busy */
#define XHCI_ERDP_PTR_MASK      (~0xFull)  /* pointer occupies bits[63:4] */

/* -------------------------------------------------------------------------
 * Doorbell Array (BAR0 + db_off) — array of uint32_t, one per device slot
 * plus doorbell 0 for the Command Ring. Write-only.
 * ------------------------------------------------------------------------- */

typedef volatile uint32_t xhci_doorbell_t;

#define XHCI_DB_TARGET(ep)      ((uint32_t)(ep) & 0xFFu) /* 0 = command ring */
#define XHCI_DB_STREAM_ID(sid)  (((uint32_t)(sid) & 0xFFFFu) << 16)

/* -------------------------------------------------------------------------
 * TRB (Transfer Request Block) — 16 bytes, the unit of both Command Ring
 * and Event Ring entries (and Transfer Rings, used later for BOT I/O).
 * ------------------------------------------------------------------------- */

typedef struct {
    volatile uint64_t parameter;
    volatile uint32_t status;
    volatile uint32_t control;
} xhci_trb_t;

#define XHCI_TRB_CONTROL_CYCLE       (1u << 0)  /* Cycle bit */
#define XHCI_TRB_CONTROL_TYPE_SHIFT  10
#define XHCI_TRB_CONTROL_TYPE_MASK   (0x3Fu << XHCI_TRB_CONTROL_TYPE_SHIFT)
#define XHCI_TRB_TYPE(ctrl)          (((ctrl) & XHCI_TRB_CONTROL_TYPE_MASK) >> XHCI_TRB_CONTROL_TYPE_SHIFT)

/* TRB types used by this driver (subset — xHCI defines many more) */
#define XHCI_TRB_TYPE_ENABLE_SLOT_CMD      9
#define XHCI_TRB_TYPE_ADDRESS_DEVICE_CMD    11
#define XHCI_TRB_TYPE_TRANSFER_EVENT         32
#define XHCI_TRB_TYPE_COMMAND_COMPLETION_EVT 33
#define XHCI_TRB_TYPE_PORT_STATUS_CHANGE_EVT 34

/* -------------------------------------------------------------------------
 * Ring sizing — decided up front per Milestone 2's punch list (2a).
 *
 * Fixed, single-page rings: 256 TRBs x 16 bytes = 4096 bytes = one page.
 * This project's usage (MSC hotplug detection + read/write to one drive at
 * a time) does not need a high-throughput, dynamically-growable ring —
 * matches this codebase's existing preference for fixed, page-sized
 * allocations over dynamic growth (e.g. KRD_MAX_BLOCKS's fixed 1024-block
 * RAMDRIVE). One Command Ring, one Event Ring (Interrupter 0 only — this
 * driver does not use multiple interrupters).
 * ------------------------------------------------------------------------- */

#define XHCI_RING_TRB_COUNT   256u
#define XHCI_RING_BYTES       (XHCI_RING_TRB_COUNT * sizeof(xhci_trb_t))

#endif /* STARKERNEL_XHCI_H */