/*
 * xhci_driver.h — xHCI USB host controller driver public API for StarKernel
 *
 * Register-layout definitions live in xhci.h; this header is the driver's
 * own state and public entry points, matching virtio_blk.h's split.
 */

#ifndef STARKERNEL_XHCI_DRIVER_H
#define STARKERNEL_XHCI_DRIVER_H

#include <stdint.h>
#include "starkernel/pci.h"
#include "starkernel/xhci.h"

/* Driver state for one xHCI controller instance. Only one controller is
 * supported (matches virtio_blk's single-device precedent). */
typedef struct {
    PciDevice          pci;
    uint64_t           bar0_phys;   /* physical MMIO base, BAR0 */
    xhci_cap_regs_t    *cap;        /* BAR0 + 0 */
    xhci_op_regs_t     *op;         /* BAR0 + cap->cap_length */
    xhci_runtime_regs_t *runtime;   /* BAR0 + cap->rts_off */
    xhci_doorbell_t     *doorbell;  /* BAR0 + cap->db_off */
    uint32_t            max_slots;
    uint32_t            max_ports;
    uint32_t            max_intrs;
    uint32_t            max_scratchpad_bufs;

    /* Set up by xhci_bringup(); NULL/0 until then. */
    void                *dcbaa;          /* Device Context Base Address Array */
    void                *scratchpad_arr; /* array of scratchpad buffer pointers, if any */
    xhci_trb_t          *cmd_ring;       /* Command Ring, XHCI_RING_TRB_COUNT TRBs */
    uint32_t            cmd_ring_cycle;  /* current Command Ring Cycle State (RCS) */
    xhci_trb_t          *evt_ring;       /* Event Ring, XHCI_RING_TRB_COUNT TRBs */
    void                *evt_ring_seg_table; /* Event Ring Segment Table (1 entry) */
    uint32_t            evt_ring_cycle;  /* current Event Ring Cycle State */
} xhci_dev_t;

/*
 * xhci_find_and_map — locate the xHCI controller on PCI bus 0, enable it
 *                     (I/O+MEM+bus-master), map its BAR0 MMIO region, and
 *                     fill in the four register-region pointers in *dev.
 *
 * dev must point to a zero-initialised xhci_dev_t.
 *
 * Returns  0 on success.
 * Returns -1 if no xHCI device was found on the PCI bus.
 * Returns -2 if the BAR0 mapping failed.
 */
int xhci_find_and_map(xhci_dev_t *dev);

/*
 * xhci_bringup — reset the controller, allocate and program the DCBAA,
 *                Command Ring, and Event Ring (Interrupter 0), then start
 *                the controller (RUN/STOP=1) and confirm it left the
 *                halted state.
 *
 * Must be called after a successful xhci_find_and_map(). Does not enable
 * interrupts (USBCMD.INTE / IMAN.IE) — that's wired in a later increment
 * alongside the actual interrupt handler.
 *
 * Returns  0 on success.
 * Returns -1 on reset timeout.
 * Returns -2 on allocation failure.
 * Returns -3 if the controller failed to leave the halted state after RUN.
 */
int xhci_bringup(xhci_dev_t *dev);

#endif /* STARKERNEL_XHCI_DRIVER_H */