/* * 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 /* ------------------------------------------------------------------------- * 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) /* HCSPARAMS2: Max Scratchpad Buffers is a 10-bit field split across two * non-adjacent locations (xHCI 1.2 spec table 5-13) — Hi bits[25:21], * Lo bits[31:27]. Zero means the controller needs no scratchpad buffers * (common for simple emulated controllers, but verify live, not assumed). */ #define XHCI_HCSPARAMS2_MAX_SCRATCHPAD_BUFS(v) \ ((((uint32_t)(v) >> 21) & 0x1Fu) << 5 | (((uint32_t)(v) >> 27) & 0x1Fu)) /* ------------------------------------------------------------------------- * 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_LINK 6 /* ring-wraparound marker, Command/Transfer Rings only */ #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 /* Control bits used only by Link TRBs */ #define XHCI_TRB_CONTROL_TC (1u << 1) /* Toggle Cycle */ /* Command Completion Event TRB layout (xHCI 1.2 spec table 6-32): * parameter[63:4] = Command TRB Pointer, status[31:24] = Completion Code, * status[23:0] = unused here, control[31:24] = Slot ID (Enable Slot's * result, also present on Address Device completions). */ #define XHCI_EVT_COMPLETION_CODE(status) (((uint32_t)(status) >> 24) & 0xFFu) #define XHCI_EVT_SLOT_ID(control) (((uint32_t)(control) >> 24) & 0xFFu) #define XHCI_COMPLETION_CODE_SUCCESS 1u /* Port Status Change Event TRB layout (xHCI 1.2 spec table 6-34): * parameter[31:24] = Port ID (1-based, matches PORTSC array indexing * 1..MaxPorts); parameter[23:0] and the rest of the TRB are reserved. */ #define XHCI_PSC_EVT_PORT_ID(parameter) (((uint32_t)(parameter) >> 24) & 0xFFu) /* ------------------------------------------------------------------------- * 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)) /* Milestone 2e: upper bound on ports tracked for connect/disconnect -> * Enable Slot correlation (xhci_dev_t.port_slot_id). PORTSC's own field * width allows up to 255 ports (XHCI_HCSPARAMS1_MAX_PORTS is 8 bits), but * no real or QEMU-emulated root hub this driver targets comes close to * that; 32 is comfortably generous and keeps this a fixed, not * heap-allocated, array. */ #define XHCI_MAX_TRACKED_PORTS 32u #endif /* STARKERNEL_XHCI_H */