usb/host/xhci.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
5  * Based on xHCI host controller driver in linux-kernel
29 /* Max number of USB devices for any host controller - limit in section 6.1 */
31 /* Section 5.3.3 - MaxPorts */
42  * connect status, over-current status, port speed, and device removable.
43  * connect status and port speed are also sticky - meaning they're in
44  * the AUX well and they aren't changed by a hot, warm, or cold reset.
55  * bit 4 (port reset)
63  * warm port reset changed (reserved zero for USB 2.0 ports),
64  * over-current, reset, link state, and L1 change
91 /* bits 7:0 - how long is the Capabilities register */
96 /* HCSPARAMS1 - hcs_params1 - bitmasks */
102 /* bits 24:31, Max Ports - max value is 0x7F = 127 ports */
107 /* HCSPARAMS2 - hcs_params2 - bitmasks */
108 /* bits 0:3, frames or uframes that SW needs to queue transactions
111 /* bits 4:7, max number of Event Ring segments */
113 /* bits 21:25 Hi 5 bits of Scratchpad buffers SW must allocate for the HW */
114 /* bit 26 Scratchpad restore - for save/restore HW state - not used yet */
115 /* bits 27:31 Lo 5 bits of Scratchpad buffers SW must allocate for the HW */
118 /* HCSPARAMS3 - hcs_params3 - bitmasks */
124 /* HCCPARAMS - hcc_params - bitmasks */
125 /* true: HC can use 64-bit address pointers */
129 /* true: HC uses 64-byte Device Context structures
130  * FIXME 64-byte context structures aren't supported yet.
137 /* true: HC has Light HC Reset Capability */
143 /* Max size for Primary Stream Arrays - 2^(n+1), where n is bits 12:15 */
145 /* Extended Capabilities pointer from PCI base - section 5.3.6 */
148 /* db_off bitmask - bits 0:1 reserved */
151 /* run_regs_off bitmask - bits 0:4 reserved */
177 /* USBCMD - USB command - command bitmasks */
178 /* start/stop HC execution - do not write unless HC is halted*/
180 /* Reset HC - resets internal HC state machine and all registers (except
181  * PCI config regs).  HC does NOT drive a USB reset on the downstream ports.
185 /* Event Interrupt Enable - a '1' allows interrupts from the host controller */
187 /* Host System Error Interrupt Enable - get out-of-band signal for HC errors */
190 /* light reset (port status stays unchanged) - reset completed when this is 0 */
195 /* Enable Wrap Event - '1' means xHC generates an event when MFINDEX wraps. */
197 /* MFINDEX power management - '1' means xHC can stop MFINDEX counter if all root
198  * hubs are in U3 (selective suspend), disconnect, disabled, or powered-off.
200  * disabled, or powered-off state.
205 /* USBSTS - USB status - status bitmasks */
206 /* HC not running - set to 1 when run/stop bit is cleared. */
210 /* event interrupt - clear this prior to clearing any IP flags in IR set*/
215 /* save state status - '1' means xHC is saving state */
217 /* restore state status - '1' means xHC is restoring state */
221 /* true: Controller Not Ready to accept doorbell or op reg writes after reset */
223 /* true: internal Host Controller Error - SW needs to reset and reinitialize */
228  * DNCTRL - Device Notification Control Register - dev_notification bitmasks
235  * SW does need to pay attention to function wake notifications.
239 /* CRCR - Command Ring Control Register - cmd_ring bitmasks */
243 /* stop ring immediately - abort the currently executing command */
248 /* Command Ring pointer - bit mask for the lower 32 bits. */
251 /* CONFIG - Configure Register - config_reg bitmasks */
252 /* bits 0:7 - maximum number of device slots enabled (NumSlotsEn) */
254 /* bits 8:31 - reserved and should be preserved */
256 /* PORTSC - Port Status and Control Register - port_status_base bitmasks */
262 /* true: port has an over-current condition */
264 /* true: port reset signaling asserted */
266 /* Port Link State - bits 5:8
278  * 0 - undefined speed - port hasn't be initialized by a reset yet
279  * 1 - full speed
280  * 2 - low speed
281  * 3 - high speed
282  * 4 - super speed
283  * 5-15 reserved
305 /* Port Link State Write Strobe - set this when changing link state */
311 /* true: warm reset for a USB 3.0 device is done.  A "hot" reset puts the port
312  * into an enabled state, and the device into the default state.  A "warm" reset
314  * SW can also look at the Port Reset register to see when warm reset is done.
317 /* true: over-current change */
319 /* true: reset change - 1 to 0 transition of PORT_RESET */
321 /* port link status change - set on some port link state transitions:
323  *  --------------------------------------------------------------------------
324  *  - U3 to Resume		Wakeup signaling from a device
325  *  - Resume to Recovery to U0	USB 3.0 device resume
326  *  - Resume to U0		USB 2.0 device resume
327  *  - U3 to Recovery to U0	Software resume of USB 3.0 device complete
328  *  - U3 to U0			Software resume of USB 2.0 device complete
329  *  - U2 to U0			L1 resume of USB 2.1 device complete
330  *  - U0 to U0 (???)		L1 entry rejection by USB 2.1 device
331  *  - U0 to disabled		L1 entry error with USB 2.1 device
332  *  - Any state to inactive	Error on USB 3.0 port
335 /* port configure error change - port failed to configure its link partner */
342 /* wake on over-current (enable) */
345 /* true: device is removable - for USB 3.0 roothub emulation */
347 /* Initiate a warm port reset - complete when PORT_WRC is '1' */
350 /* We mark duplicate entries with -1 */
351 #define DUPLICATE_ENTRY ((u8)(-1))
353 /* Port Power Management Status and Control - port_power_base bitmasks */
372 * struct xhci_intr_reg - Interrupt Register Set
373 * @irq_pending:	IMAN - Interrupt Management Register.  Used to enable
375 * @irq_control:	IMOD - Interrupt Moderation Register.
377 * @erst_size:		Number of segments in the
382 * Each interrupter (defined by a MSI-X vector) has an event ring and an Event
401 /* THIS IS BUGGY - FIXME - IP IS WRITE 1 TO CLEAR */
412 /* Counter used to count down the time to the next interrupt - HW use only */
420 /* Dequeue ERST Segment Index (DESI) - Segment number (or alias)
424 /* Event Handler Busy (EHB) - is the event ring scheduled to be serviced by
432  * @microframe_index:	MFINDEX - current microframe number
447  * Bits  0 -  7: Endpoint target
448  * Bits  8 - 15: RsvdZ
449  * Bits 16 - 31: Stream ID
466  * @port_info:		Port offset, count, and protocol-defined information.
499  * @dev_info2:	Max exit latency for device number, root hub port number
503  * Slot Context - section 6.2.1.1.  This assumes the HC uses 32-byte context
504  * structures.  If the HC uses 64-byte contexts, there is an additional 32 bytes
517 /* Route String - 0:19 */
519 /* Device speed - values defined by PORTSC Device Speed field - 20:23 */
522 /* Is this LS/FS device connected through a HS hub? - bit 25 */
524 /* Set if the device is a hub - bit 26 */
526 /* Index of the last valid endpoint context in this device context - 27:31 */
529 #define LAST_CTX_TO_EP_NUM(p)	(((p) >> 27) - 1)
534 /* Max Exit Latency (ms) - worst case time to wake up all links in dev path */
536 /* Root hub port number that is needed to access the USB device */
541 /* Maximum number of ports under a hub device */
546  * TT Hub Slot ID - for low or full speed devices attached to a high-speed hub
548  * this low or full-speed device.  '0' if attached to root hub port.
552  * The number of the downstream facing port of the high-speed hub
559 /* USB device address - assigned by the HC */
578  * @deq:	64-bit ring dequeue pointer address.  If the endpoint only
586  * Endpoint Context - section 6.2.1.2.This assumes the HC uses 32-byte context
587  * structures.If the HC uses 64-byte contexts, there is an additional 32 bytes
595 	/* offset 0x14 - 0x1f reserved for HC internal use */
601  * Endpoint State - bits 0:2
602  * 0 - disabled
603  * 1 - running
604  * 2 - halted due to halt condition - ok to manipulate endpoint ring
605  * 3 - stopped
606  * 4 - TRB error
607  * 5-7 - reserved
615 /* Mult - Max number of burtst within an interval, in EP companion desc. */
620 /* Interval - period between requests to an endpoint - 125u increments. */
631  * Force Event - generate transfer events for all TRBs for this endpoint
649 /* bit 7 is Host Initiate Disable - for disabling stream selection */
690  * @dev_context_ptr	array of 64-bit DMA addresses for device contexts
693 	/* 64-bit device addresses; we only write 32-bit addresses */
696 /* TODO: write function to set the 64-bit device DMA address */
699  * might not be able to handle the maximum number of devices possible.
704 	/* 64-bit buffer address, or immediate data */
718 /* Completion Code - only applicable for some types of TRBs */
731 	/* TRB Error - some TRB field is invalid */
733 	/* Stall Error - USB device is stalled */
735 	/* Resource Error - HC doesn't have memory for that device configuration */
737 	/* Bandwidth Error - not enough room in schedule for this dev config */
739 	/* No Slots Available Error - HC ran out of device slots */
743 	/* Slot Not Enabled Error - doorbell rung for disabled device slot */
749 	/* Ring Underrun - doorbell rung for an empty isoc OUT ep ring */
751 	/* Ring Overrun - isoc IN ep ring is empty when ep is scheduled to RX */
755 	/* Parameter Error - Context parameter is invalid */
757 	/* Bandwidth Overrun Error - isoc ep exceeded its allocated bandwidth */
759 	/* Context State Error - illegal context state transition requested */
761 	/* No Ping Response Error - HC didn't get PING_RESPONSE in time to TX */
767 	/* Missed Service Error - HC couldn't service an isoc ep within interval */
773 	/* Stopped - transfer was terminated by a stop endpoint command */
778 	/* Control Abort Error - Debug Capability - control pipe aborted */
783 	/* Isoc Buffer Overrun - an isoc IN ep sent more data than could fit in TD */
785 	/* Event Lost Error - xHC has an "internal event overrun condition" */
787 	/* Undefined Error - reported when other error codes don't apply */
791 	/* Secondary Bandwidth Error - may be returned by a Configure Endpoint cmd */
799 	/* 64-bit segment pointer*/
826 /* Stop Endpoint TRB - ep_index to endpoint ID for this TRB */
827 #define TRB_TO_EP_INDEX(p)		((((p) & (0x1f << 16)) >> 16) - 1)
840 /* Port ID - bits 31:24 */
846 /* transfer_len bitmasks - bits 0:16 */
849 /* Interrupter Target - which MSI-X vector to target the completion event at */
857 /* Cycle bit - indicates TRB ownership by HC or HCD */
921 	/* Transfer Ring No-op (not for the command ring) */
934 	/* Reset Endpoint Command */
940 	/* Reset Device Command */
950 	/* Force Header Command - generate a transaction or link management packet */
952 	/* No-op Command - not for transfer rings */
954 	/* TRB IDs 24-31 reserved */
968 	/* Device Notification Event - device sent function wake notification */
970 	/* MFINDEX Wrap Event - microframe counter wrapped */
972 	/* TRB IDs 40-47 reserved, 48-63 is vendor-defined */
973 	/* Nec vendor-specific command completion event. */
980 /* Above, but for __le32 types -- can avoid work by swapping constants: */
988  * since the command ring is 64-byte aligned.
993 #define MAX_RSVD_CMD_TRBS	(TRBS_PER_SEGMENT - 3)
1025 	/* 64-bit event ring segment address */
1047  * Initial allocated size of the ERST, in number of entries */
1049 /* Initial number of event segment rings allocated */
1051 /* Initial allocated size of the ERST, in number of entries */
1087 	/* Rings saved to ensure old alt settings can be re-instated */
1092 /* TODO: copied from ehci.h - can be refactored? */
1106  * Some xHCI implementations may support 64-bit address pointers.  Registers
1107  * with 64-bit address pointers should be written to with dword accesses by
1109  * xHCI implementations that do not support 64-bit address pointers will ignore
1148 /* HC not running - set to 1 when run/stop bit is cleared. */
1163 /* bits 7:0 - how long is the Capabilities register */
1170 /* Extended capability IDs - ID 0 reserved */
1176 /* IDs 6-9 reserved */
1178 /* USB Legacy Support Capability - section 7.1.1 */
1182 /* USB Legacy Support Capability - section 7.1.1 */
1186 /* USB Legacy Support Control and Status Register  - section 7.1.2 */
1192 /* USB 2.0 xHCI 0.96 L1C capability - section 7.2.2.1.3.2 */
1195 /* USB 2.0 xHCI 1.0 hardware LMP capability - section 7.2.2.1.3.2 */
1199 /* start/stop HC execution - do not write unless HC is halted*/
1201 /* Event Interrupt Enable - get irq when EINT bit is set in USBSTS register */
1203 /* Host System Error Interrupt Enable - get irq when HSEIE bit set in USBSTS */
1205 /* Enable Wrap Event - '1' means xHC generates an event when MFINDEX wraps. */
1210 /* true: Controller Not Ready to accept doorbell or op reg writes after reset */
1270  * xhci_deregister() - Unregister an XHCI controller
1273  * @return 0 if registered, -ve on error
1278  * xhci_register() - Register a new XHCI controller
1283  * @return 0 if registered, -ve on error