iPXE
xhci.h
Go to the documentation of this file.
00001 #ifndef _IPXE_XHCI_H
00002 #define _IPXE_XHCI_H
00003 
00004 /** @file
00005  *
00006  * USB eXtensible Host Controller Interface (xHCI) driver
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <assert.h>
00013 #include <ipxe/pci.h>
00014 #include <ipxe/uaccess.h>
00015 #include <ipxe/usb.h>
00016 
00017 /** Minimum alignment required for data structures
00018  *
00019  * With the exception of the scratchpad buffer pages (which are
00020  * page-aligned), data structures used by xHCI generally require from
00021  * 16 to 64 byte alignment and must not cross an (xHCI) page boundary.
00022  * We simplify this requirement by aligning each structure on its own
00023  * size, with a minimum of a 64 byte alignment.
00024  */
00025 #define XHCI_MIN_ALIGN 64
00026 
00027 /** Maximum transfer size */
00028 #define XHCI_MTU 65536
00029 
00030 /** xHCI PCI BAR */
00031 #define XHCI_BAR PCI_BASE_ADDRESS_0
00032 
00033 /** Capability register length */
00034 #define XHCI_CAP_CAPLENGTH 0x00
00035 
00036 /** Host controller interface version number */
00037 #define XHCI_CAP_HCIVERSION 0x02
00038 
00039 /** Structural parameters 1 */
00040 #define XHCI_CAP_HCSPARAMS1 0x04
00041 
00042 /** Number of device slots */
00043 #define XHCI_HCSPARAMS1_SLOTS(params) ( ( (params) >> 0 ) & 0xff )
00044 
00045 /** Number of interrupters */
00046 #define XHCI_HCSPARAMS1_INTRS(params) ( ( (params) >> 8 ) & 0x3ff )
00047 
00048 /** Number of ports */
00049 #define XHCI_HCSPARAMS1_PORTS(params) ( ( (params) >> 24 ) & 0xff )
00050 
00051 /** Structural parameters 2 */
00052 #define XHCI_CAP_HCSPARAMS2 0x08
00053 
00054 /** Number of page-sized scratchpad buffers */
00055 #define XHCI_HCSPARAMS2_SCRATCHPADS(params) \
00056         ( ( ( (params) >> 16 ) & 0x3e0 ) | ( ( (params) >> 27 ) & 0x1f ) )
00057 
00058 /** Capability parameters */
00059 #define XHCI_CAP_HCCPARAMS1 0x10
00060 
00061 /** 64-bit addressing capability */
00062 #define XHCI_HCCPARAMS1_ADDR64(params) ( ( (params) >> 0 ) & 0x1 )
00063 
00064 /** Context size shift */
00065 #define XHCI_HCCPARAMS1_CSZ_SHIFT(params) ( 5 + ( ( (params) >> 2 ) & 0x1 ) )
00066 
00067 /** xHCI extended capabilities pointer */
00068 #define XHCI_HCCPARAMS1_XECP(params) ( ( ( (params) >> 16 ) & 0xffff ) << 2 )
00069 
00070 /** Doorbell offset */
00071 #define XHCI_CAP_DBOFF 0x14
00072 
00073 /** Runtime register space offset */
00074 #define XHCI_CAP_RTSOFF 0x18
00075 
00076 /** xHCI extended capability ID */
00077 #define XHCI_XECP_ID(xecp) ( ( (xecp) >> 0 ) & 0xff )
00078 
00079 /** Next xHCI extended capability pointer */
00080 #define XHCI_XECP_NEXT(xecp) ( ( ( (xecp) >> 8 ) & 0xff ) << 2 )
00081 
00082 /** USB legacy support extended capability */
00083 #define XHCI_XECP_ID_LEGACY 1
00084 
00085 /** USB legacy support BIOS owned semaphore */
00086 #define XHCI_USBLEGSUP_BIOS 0x02
00087 
00088 /** USB legacy support BIOS ownership flag */
00089 #define XHCI_USBLEGSUP_BIOS_OWNED 0x01
00090 
00091 /** USB legacy support OS owned semaphore */
00092 #define XHCI_USBLEGSUP_OS 0x03
00093 
00094 /** USB legacy support OS ownership flag */
00095 #define XHCI_USBLEGSUP_OS_OWNED 0x01
00096 
00097 /** USB legacy support control/status */
00098 #define XHCI_USBLEGSUP_CTLSTS 0x04
00099 
00100 /** Supported protocol extended capability */
00101 #define XHCI_XECP_ID_SUPPORTED 2
00102 
00103 /** Supported protocol revision */
00104 #define XHCI_SUPPORTED_REVISION 0x00
00105 
00106 /** Supported protocol minor revision */
00107 #define XHCI_SUPPORTED_REVISION_VER(revision) ( ( (revision) >> 16 ) & 0xffff )
00108 
00109 /** Supported protocol name */
00110 #define XHCI_SUPPORTED_NAME 0x04
00111 
00112 /** Supported protocol ports */
00113 #define XHCI_SUPPORTED_PORTS 0x08
00114 
00115 /** Supported protocol port offset */
00116 #define XHCI_SUPPORTED_PORTS_OFFSET(ports) ( ( (ports) >> 0 ) & 0xff )
00117 
00118 /** Supported protocol port count */
00119 #define XHCI_SUPPORTED_PORTS_COUNT(ports) ( ( (ports) >> 8 ) & 0xff )
00120 
00121 /** Supported protocol PSI count */
00122 #define XHCI_SUPPORTED_PORTS_PSIC(ports) ( ( (ports) >> 28 ) & 0x0f )
00123 
00124 /** Supported protocol slot */
00125 #define XHCI_SUPPORTED_SLOT 0x0c
00126 
00127 /** Supported protocol slot type */
00128 #define XHCI_SUPPORTED_SLOT_TYPE(slot) ( ( (slot) >> 0 ) & 0x1f )
00129 
00130 /** Supported protocol PSI */
00131 #define XHCI_SUPPORTED_PSI(index) ( 0x10 + ( (index) * 4 ) )
00132 
00133 /** Supported protocol PSI value */
00134 #define XHCI_SUPPORTED_PSI_VALUE(psi) ( ( (psi) >> 0 ) & 0x0f )
00135 
00136 /** Supported protocol PSI mantissa */
00137 #define XHCI_SUPPORTED_PSI_MANTISSA(psi) ( ( (psi) >> 16 ) & 0xffff )
00138 
00139 /** Supported protocol PSI exponent */
00140 #define XHCI_SUPPORTED_PSI_EXPONENT(psi) ( ( (psi) >> 4 ) & 0x03 )
00141 
00142 /** Default PSI values */
00143 enum xhci_default_psi_value {
00144         /** Full speed (12Mbps) */
00145         XHCI_SPEED_FULL = 1,
00146         /** Low speed (1.5Mbps) */
00147         XHCI_SPEED_LOW = 2,
00148         /** High speed (480Mbps) */
00149         XHCI_SPEED_HIGH = 3,
00150         /** Super speed */
00151         XHCI_SPEED_SUPER = 4,
00152 };
00153 
00154 /** USB command register */
00155 #define XHCI_OP_USBCMD 0x00
00156 
00157 /** Run/stop */
00158 #define XHCI_USBCMD_RUN 0x00000001UL
00159 
00160 /** Host controller reset */
00161 #define XHCI_USBCMD_HCRST 0x00000002UL
00162 
00163 /** USB status register */
00164 #define XHCI_OP_USBSTS 0x04
00165 
00166 /** Host controller halted */
00167 #define XHCI_USBSTS_HCH 0x00000001UL
00168 
00169 /** Page size register */
00170 #define XHCI_OP_PAGESIZE 0x08
00171 
00172 /** Page size */
00173 #define XHCI_PAGESIZE(pagesize) ( (pagesize) << 12 )
00174 
00175 /** Device notifcation control register */
00176 #define XHCI_OP_DNCTRL 0x14
00177 
00178 /** Command ring control register */
00179 #define XHCI_OP_CRCR 0x18
00180 
00181 /** Command ring cycle state */
00182 #define XHCI_CRCR_RCS 0x00000001UL
00183 
00184 /** Command abort */
00185 #define XHCI_CRCR_CA 0x00000004UL
00186 
00187 /** Command ring running */
00188 #define XHCI_CRCR_CRR 0x00000008UL
00189 
00190 /** Device context base address array pointer */
00191 #define XHCI_OP_DCBAAP 0x30
00192 
00193 /** Configure register */
00194 #define XHCI_OP_CONFIG 0x38
00195 
00196 /** Maximum device slots enabled */
00197 #define XHCI_CONFIG_MAX_SLOTS_EN(slots) ( (slots) << 0 )
00198 
00199 /** Maximum device slots enabled mask */
00200 #define XHCI_CONFIG_MAX_SLOTS_EN_MASK \
00201         XHCI_CONFIG_MAX_SLOTS_EN ( 0xff )
00202 
00203 /** Port status and control register */
00204 #define XHCI_OP_PORTSC(port) ( 0x400 - 0x10 + ( (port) << 4 ) )
00205 
00206 /** Current connect status */
00207 #define XHCI_PORTSC_CCS 0x00000001UL
00208 
00209 /** Port enabled */
00210 #define XHCI_PORTSC_PED 0x00000002UL
00211 
00212 /** Port reset */
00213 #define XHCI_PORTSC_PR 0x00000010UL
00214 
00215 /** Port link state */
00216 #define XHCI_PORTSC_PLS(pls) ( (pls) << 5 )
00217 
00218 /** Disabled port link state */
00219 #define XHCI_PORTSC_PLS_DISABLED XHCI_PORTSC_PLS ( 4 )
00220 
00221 /** RxDetect port link state */
00222 #define XHCI_PORTSC_PLS_RXDETECT XHCI_PORTSC_PLS ( 5 )
00223 
00224 /** Port link state mask */
00225 #define XHCI_PORTSC_PLS_MASK XHCI_PORTSC_PLS ( 0xf )
00226 
00227 /** Port power */
00228 #define XHCI_PORTSC_PP 0x00000200UL
00229 
00230 /** Time to delay after enabling power to a port */
00231 #define XHCI_PORT_POWER_DELAY_MS 20
00232 
00233 /** Port speed ID value */
00234 #define XHCI_PORTSC_PSIV(portsc) ( ( (portsc) >> 10 ) & 0xf )
00235 
00236 /** Port indicator control */
00237 #define XHCI_PORTSC_PIC(indicators) ( (indicators) << 14 )
00238 
00239 /** Port indicator control mask */
00240 #define XHCI_PORTSC_PIC_MASK XHCI_PORTSC_PIC ( 3 )
00241 
00242 /** Port link state write strobe */
00243 #define XHCI_PORTSC_LWS 0x00010000UL
00244 
00245 /** Time to delay after writing the port link state */
00246 #define XHCI_LINK_STATE_DELAY_MS 20
00247 
00248 /** Connect status change */
00249 #define XHCI_PORTSC_CSC 0x00020000UL
00250 
00251 /** Port enabled/disabled change */
00252 #define XHCI_PORTSC_PEC 0x00040000UL
00253 
00254 /** Warm port reset change */
00255 #define XHCI_PORTSC_WRC 0x00080000UL
00256 
00257 /** Over-current change */
00258 #define XHCI_PORTSC_OCC 0x00100000UL
00259 
00260 /** Port reset change */
00261 #define XHCI_PORTSC_PRC 0x00200000UL
00262 
00263 /** Port link state change */
00264 #define XHCI_PORTSC_PLC 0x00400000UL
00265 
00266 /** Port config error change */
00267 #define XHCI_PORTSC_CEC 0x00800000UL
00268 
00269 /** Port status change mask */
00270 #define XHCI_PORTSC_CHANGE                                      \
00271         ( XHCI_PORTSC_CSC | XHCI_PORTSC_PEC | XHCI_PORTSC_WRC | \
00272           XHCI_PORTSC_OCC | XHCI_PORTSC_PRC | XHCI_PORTSC_PLC | \
00273           XHCI_PORTSC_CEC )
00274 
00275 /** Port status and control bits which should be preserved
00276  *
00277  * The port status and control register is a horrendous mix of
00278  * differing semantics.  Some bits are written to only when a separate
00279  * write strobe bit is set.  Some bits should be preserved when
00280  * modifying other bits.  Some bits will be cleared if written back as
00281  * a one.  Most excitingly, the "port enabled" bit has the semantics
00282  * that 1=enabled, 0=disabled, yet writing a 1 will disable the port.
00283  */
00284 #define XHCI_PORTSC_PRESERVE ( XHCI_PORTSC_PP | XHCI_PORTSC_PIC_MASK )
00285 
00286 /** Port power management status and control register */
00287 #define XHCI_OP_PORTPMSC(port) ( 0x404 - 0x10 + ( (port) << 4 ) )
00288 
00289 /** Port link info register */
00290 #define XHCI_OP_PORTLI(port) ( 0x408 - 0x10 + ( (port) << 4 ) )
00291 
00292 /** Port hardware link power management control register */
00293 #define XHCI_OP_PORTHLPMC(port) ( 0x40c - 0x10 + ( (port) << 4 ) )
00294 
00295 /** Event ring segment table size register */
00296 #define XHCI_RUN_ERSTSZ(intr) ( 0x28 + ( (intr) << 5 ) )
00297 
00298 /** Event ring segment table base address register */
00299 #define XHCI_RUN_ERSTBA(intr) ( 0x30 + ( (intr) << 5 ) )
00300 
00301 /** Event ring dequeue pointer register */
00302 #define XHCI_RUN_ERDP(intr) ( 0x38 + ( (intr) << 5 ) )
00303 
00304 /** A transfer request block template */
00305 struct xhci_trb_template {
00306         /** Parameter */
00307         uint64_t parameter;
00308         /** Status */
00309         uint32_t status;
00310         /** Control */
00311         uint32_t control;
00312 };
00313 
00314 /** A transfer request block */
00315 struct xhci_trb_common {
00316         /** Reserved */
00317         uint64_t reserved_a;
00318         /** Reserved */
00319         uint32_t reserved_b;
00320         /** Flags */
00321         uint8_t flags;
00322         /** Type */
00323         uint8_t type;
00324         /** Reserved */
00325         uint16_t reserved_c;
00326 } __attribute__ (( packed ));
00327 
00328 /** Transfer request block cycle bit flag */
00329 #define XHCI_TRB_C 0x01
00330 
00331 /** Transfer request block toggle cycle bit flag */
00332 #define XHCI_TRB_TC 0x02
00333 
00334 /** Transfer request block chain flag */
00335 #define XHCI_TRB_CH 0x10
00336 
00337 /** Transfer request block interrupt on completion flag */
00338 #define XHCI_TRB_IOC 0x20
00339 
00340 /** Transfer request block immediate data flag */
00341 #define XHCI_TRB_IDT 0x40
00342 
00343 /** Transfer request block type */
00344 #define XHCI_TRB_TYPE(type) ( (type) << 2 )
00345 
00346 /** Transfer request block type mask */
00347 #define XHCI_TRB_TYPE_MASK XHCI_TRB_TYPE ( 0x3f )
00348 
00349 /** A normal transfer request block */
00350 struct xhci_trb_normal {
00351         /** Data buffer */
00352         uint64_t data;
00353         /** Length */
00354         uint32_t len;
00355         /** Flags */
00356         uint8_t flags;
00357         /** Type */
00358         uint8_t type;
00359         /** Reserved */
00360         uint16_t reserved;
00361 } __attribute__ (( packed ));
00362 
00363 /** A normal transfer request block */
00364 #define XHCI_TRB_NORMAL XHCI_TRB_TYPE ( 1 )
00365 
00366 /** Construct TD size field */
00367 #define XHCI_TD_SIZE(remaining) \
00368         ( ( ( (remaining) <= 0xf ) ? remaining : 0xf ) << 17 )
00369 
00370 /** A setup stage transfer request block */
00371 struct xhci_trb_setup {
00372         /** Setup packet */
00373         struct usb_setup_packet packet;
00374         /** Length */
00375         uint32_t len;
00376         /** Flags */
00377         uint8_t flags;
00378         /** Type */
00379         uint8_t type;
00380         /** Transfer direction */
00381         uint8_t direction;
00382         /** Reserved */
00383         uint8_t reserved;
00384 } __attribute__ (( packed ));
00385 
00386 /** A setup stage transfer request block */
00387 #define XHCI_TRB_SETUP XHCI_TRB_TYPE ( 2 )
00388 
00389 /** Setup stage input data direction */
00390 #define XHCI_SETUP_IN 3
00391 
00392 /** Setup stage output data direction */
00393 #define XHCI_SETUP_OUT 2
00394 
00395 /** A data stage transfer request block */
00396 struct xhci_trb_data {
00397         /** Data buffer */
00398         uint64_t data;
00399         /** Length */
00400         uint32_t len;
00401         /** Flags */
00402         uint8_t flags;
00403         /** Type */
00404         uint8_t type;
00405         /** Transfer direction */
00406         uint8_t direction;
00407         /** Reserved */
00408         uint8_t reserved;
00409 } __attribute__ (( packed ));
00410 
00411 /** A data stage transfer request block */
00412 #define XHCI_TRB_DATA XHCI_TRB_TYPE ( 3 )
00413 
00414 /** Input data direction */
00415 #define XHCI_DATA_IN 0x01
00416 
00417 /** Output data direction */
00418 #define XHCI_DATA_OUT 0x00
00419 
00420 /** A status stage transfer request block */
00421 struct xhci_trb_status {
00422         /** Reserved */
00423         uint64_t reserved_a;
00424         /** Reserved */
00425         uint32_t reserved_b;
00426         /** Flags */
00427         uint8_t flags;
00428         /** Type */
00429         uint8_t type;
00430         /** Direction */
00431         uint8_t direction;
00432         /** Reserved */
00433         uint8_t reserved_c;
00434 } __attribute__ (( packed ));
00435 
00436 /** A status stage transfer request block */
00437 #define XHCI_TRB_STATUS XHCI_TRB_TYPE ( 4 )
00438 
00439 /** Input status direction */
00440 #define XHCI_STATUS_IN 0x01
00441 
00442 /** Output status direction */
00443 #define XHCI_STATUS_OUT 0x00
00444 
00445 /** A link transfer request block */
00446 struct xhci_trb_link {
00447         /** Next ring segment */
00448         uint64_t next;
00449         /** Reserved */
00450         uint32_t reserved_a;
00451         /** Flags */
00452         uint8_t flags;
00453         /** Type */
00454         uint8_t type;
00455         /** Reserved */
00456         uint16_t reserved_c;
00457 } __attribute__ (( packed ));
00458 
00459 /** A link transfer request block */
00460 #define XHCI_TRB_LINK XHCI_TRB_TYPE ( 6 )
00461 
00462 /** A no-op transfer request block */
00463 #define XHCI_TRB_NOP XHCI_TRB_TYPE ( 8 )
00464 
00465 /** An enable slot transfer request block */
00466 struct xhci_trb_enable_slot {
00467         /** Reserved */
00468         uint64_t reserved_a;
00469         /** Reserved */
00470         uint32_t reserved_b;
00471         /** Flags */
00472         uint8_t flags;
00473         /** Type */
00474         uint8_t type;
00475         /** Slot type */
00476         uint8_t slot;
00477         /** Reserved */
00478         uint8_t reserved_c;
00479 } __attribute__ (( packed ));
00480 
00481 /** An enable slot transfer request block */
00482 #define XHCI_TRB_ENABLE_SLOT XHCI_TRB_TYPE ( 9 )
00483 
00484 /** A disable slot transfer request block */
00485 struct xhci_trb_disable_slot {
00486         /** Reserved */
00487         uint64_t reserved_a;
00488         /** Reserved */
00489         uint32_t reserved_b;
00490         /** Flags */
00491         uint8_t flags;
00492         /** Type */
00493         uint8_t type;
00494         /** Reserved */
00495         uint8_t reserved_c;
00496         /** Slot ID */
00497         uint8_t slot;
00498 } __attribute__ (( packed ));
00499 
00500 /** A disable slot transfer request block */
00501 #define XHCI_TRB_DISABLE_SLOT XHCI_TRB_TYPE ( 10 )
00502 
00503 /** A context transfer request block */
00504 struct xhci_trb_context {
00505         /** Input context */
00506         uint64_t input;
00507         /** Reserved */
00508         uint32_t reserved_a;
00509         /** Flags */
00510         uint8_t flags;
00511         /** Type */
00512         uint8_t type;
00513         /** Reserved */
00514         uint8_t reserved_b;
00515         /** Slot ID */
00516         uint8_t slot;
00517 } __attribute__ (( packed ));
00518 
00519 /** An address device transfer request block */
00520 #define XHCI_TRB_ADDRESS_DEVICE XHCI_TRB_TYPE ( 11 )
00521 
00522 /** A configure endpoint transfer request block */
00523 #define XHCI_TRB_CONFIGURE_ENDPOINT XHCI_TRB_TYPE ( 12 )
00524 
00525 /** An evaluate context transfer request block */
00526 #define XHCI_TRB_EVALUATE_CONTEXT XHCI_TRB_TYPE ( 13 )
00527 
00528 /** A reset endpoint transfer request block */
00529 struct xhci_trb_reset_endpoint {
00530         /** Reserved */
00531         uint64_t reserved_a;
00532         /** Reserved */
00533         uint32_t reserved_b;
00534         /** Flags */
00535         uint8_t flags;
00536         /** Type */
00537         uint8_t type;
00538         /** Endpoint ID */
00539         uint8_t endpoint;
00540         /** Slot ID */
00541         uint8_t slot;
00542 } __attribute__ (( packed ));
00543 
00544 /** A reset endpoint transfer request block */
00545 #define XHCI_TRB_RESET_ENDPOINT XHCI_TRB_TYPE ( 14 )
00546 
00547 /** A stop endpoint transfer request block */
00548 struct xhci_trb_stop_endpoint {
00549         /** Reserved */
00550         uint64_t reserved_a;
00551         /** Reserved */
00552         uint32_t reserved_b;
00553         /** Flags */
00554         uint8_t flags;
00555         /** Type */
00556         uint8_t type;
00557         /** Endpoint ID */
00558         uint8_t endpoint;
00559         /** Slot ID */
00560         uint8_t slot;
00561 } __attribute__ (( packed ));
00562 
00563 /** A stop endpoint transfer request block */
00564 #define XHCI_TRB_STOP_ENDPOINT XHCI_TRB_TYPE ( 15 )
00565 
00566 /** A set transfer ring dequeue pointer transfer request block */
00567 struct xhci_trb_set_tr_dequeue_pointer {
00568         /** Dequeue pointer */
00569         uint64_t dequeue;
00570         /** Reserved */
00571         uint32_t reserved;
00572         /** Flags */
00573         uint8_t flags;
00574         /** Type */
00575         uint8_t type;
00576         /** Endpoint ID */
00577         uint8_t endpoint;
00578         /** Slot ID */
00579         uint8_t slot;
00580 } __attribute__ (( packed ));
00581 
00582 /** A set transfer ring dequeue pointer transfer request block */
00583 #define XHCI_TRB_SET_TR_DEQUEUE_POINTER XHCI_TRB_TYPE ( 16 )
00584 
00585 /** A no-op command transfer request block */
00586 #define XHCI_TRB_NOP_CMD XHCI_TRB_TYPE ( 23 )
00587 
00588 /** A transfer event transfer request block */
00589 struct xhci_trb_transfer {
00590         /** Transfer TRB pointer */
00591         uint64_t transfer;
00592         /** Residual transfer length */
00593         uint16_t residual;
00594         /** Reserved */
00595         uint8_t reserved;
00596         /** Completion code */
00597         uint8_t code;
00598         /** Flags */
00599         uint8_t flags;
00600         /** Type */
00601         uint8_t type;
00602         /** Endpoint ID */
00603         uint8_t endpoint;
00604         /** Slot ID */
00605         uint8_t slot;
00606 } __attribute__ (( packed ));
00607 
00608 /** A transfer event transfer request block */
00609 #define XHCI_TRB_TRANSFER XHCI_TRB_TYPE ( 32 )
00610 
00611 /** A command completion event transfer request block */
00612 struct xhci_trb_complete {
00613         /** Command TRB pointer */
00614         uint64_t command;
00615         /** Parameter */
00616         uint8_t parameter[3];
00617         /** Completion code */
00618         uint8_t code;
00619         /** Flags */
00620         uint8_t flags;
00621         /** Type */
00622         uint8_t type;
00623         /** Virtual function ID */
00624         uint8_t vf;
00625         /** Slot ID */
00626         uint8_t slot;
00627 } __attribute__ (( packed ));
00628 
00629 /** A command completion event transfer request block */
00630 #define XHCI_TRB_COMPLETE XHCI_TRB_TYPE ( 33 )
00631 
00632 /** xHCI completion codes */
00633 enum xhci_completion_code {
00634         /** Success */
00635         XHCI_CMPLT_SUCCESS = 1,
00636         /** Short packet */
00637         XHCI_CMPLT_SHORT = 13,
00638         /** Command ring stopped */
00639         XHCI_CMPLT_CMD_STOPPED = 24,
00640 };
00641 
00642 /** A port status change transfer request block */
00643 struct xhci_trb_port_status {
00644         /** Reserved */
00645         uint8_t reserved_a[3];
00646         /** Port ID */
00647         uint8_t port;
00648         /** Reserved */
00649         uint8_t reserved_b[7];
00650         /** Completion code */
00651         uint8_t code;
00652         /** Flags */
00653         uint8_t flags;
00654         /** Type */
00655         uint8_t type;
00656         /** Reserved */
00657         uint16_t reserved_c;
00658 } __attribute__ (( packed ));
00659 
00660 /** A port status change transfer request block */
00661 #define XHCI_TRB_PORT_STATUS XHCI_TRB_TYPE ( 34 )
00662 
00663 /** A port status change transfer request block */
00664 struct xhci_trb_host_controller {
00665         /** Reserved */
00666         uint64_t reserved_a;
00667         /** Reserved */
00668         uint8_t reserved_b[3];
00669         /** Completion code */
00670         uint8_t code;
00671         /** Flags */
00672         uint8_t flags;
00673         /** Type */
00674         uint8_t type;
00675         /** Reserved */
00676         uint16_t reserved_c;
00677 } __attribute__ (( packed ));
00678 
00679 /** A port status change transfer request block */
00680 #define XHCI_TRB_HOST_CONTROLLER XHCI_TRB_TYPE ( 37 )
00681 
00682 /** A transfer request block */
00683 union xhci_trb {
00684         /** Template */
00685         struct xhci_trb_template template;
00686         /** Common fields */
00687         struct xhci_trb_common common;
00688         /** Normal TRB */
00689         struct xhci_trb_normal normal;
00690         /** Setup stage TRB */
00691         struct xhci_trb_setup setup;
00692         /** Data stage TRB */
00693         struct xhci_trb_data data;
00694         /** Status stage TRB */
00695         struct xhci_trb_status status;
00696         /** Link TRB */
00697         struct xhci_trb_link link;
00698         /** Enable slot TRB */
00699         struct xhci_trb_enable_slot enable;
00700         /** Disable slot TRB */
00701         struct xhci_trb_disable_slot disable;
00702         /** Input context TRB */
00703         struct xhci_trb_context context;
00704         /** Reset endpoint TRB */
00705         struct xhci_trb_reset_endpoint reset;
00706         /** Stop endpoint TRB */
00707         struct xhci_trb_stop_endpoint stop;
00708         /** Set transfer ring dequeue pointer TRB */
00709         struct xhci_trb_set_tr_dequeue_pointer dequeue;
00710         /** Transfer event */
00711         struct xhci_trb_transfer transfer;
00712         /** Command completion event */
00713         struct xhci_trb_complete complete;
00714         /** Port status changed event */
00715         struct xhci_trb_port_status port;
00716         /** Host controller event */
00717         struct xhci_trb_host_controller host;
00718 } __attribute__ (( packed ));
00719 
00720 /** An input control context */
00721 struct xhci_control_context {
00722         /** Drop context flags */
00723         uint32_t drop;
00724         /** Add context flags */
00725         uint32_t add;
00726         /** Reserved */
00727         uint32_t reserved_a[5];
00728         /** Configuration value */
00729         uint8_t config;
00730         /** Interface number */
00731         uint8_t intf;
00732         /** Alternate setting */
00733         uint8_t alt;
00734         /** Reserved */
00735         uint8_t reserved_b;
00736 } __attribute__ (( packed ));
00737 
00738 /** A slot context */
00739 struct xhci_slot_context {
00740         /** Device info */
00741         uint32_t info;
00742         /** Maximum exit latency */
00743         uint16_t latency;
00744         /** Root hub port number */
00745         uint8_t port;
00746         /** Number of downstream ports */
00747         uint8_t ports;
00748         /** TT hub slot ID */
00749         uint8_t tt_id;
00750         /** TT port number */
00751         uint8_t tt_port;
00752         /** Interrupter target */
00753         uint16_t intr;
00754         /** USB address */
00755         uint8_t address;
00756         /** Reserved */
00757         uint16_t reserved_a;
00758         /** Slot state */
00759         uint8_t state;
00760         /** Reserved */
00761         uint32_t reserved_b[4];
00762 } __attribute__ (( packed ));
00763 
00764 /** Construct slot context device info */
00765 #define XHCI_SLOT_INFO( entries, hub, speed, route ) \
00766         ( ( (entries) << 27 ) | ( (hub) << 26 ) | ( (speed) << 20 ) | (route) )
00767 
00768 /** An endpoint context */
00769 struct xhci_endpoint_context {
00770         /** Endpoint state */
00771         uint8_t state;
00772         /** Stream configuration */
00773         uint8_t stream;
00774         /** Polling interval */
00775         uint8_t interval;
00776         /** Max ESIT payload high */
00777         uint8_t esit_high;
00778         /** Endpoint type */
00779         uint8_t type;
00780         /** Maximum burst size */
00781         uint8_t burst;
00782         /** Maximum packet size */
00783         uint16_t mtu;
00784         /** Transfer ring dequeue pointer */
00785         uint64_t dequeue;
00786         /** Average TRB length */
00787         uint16_t trb_len;
00788         /** Max ESIT payload low */
00789         uint16_t esit_low;
00790         /** Reserved */
00791         uint32_t reserved[3];
00792 } __attribute__ (( packed ));
00793 
00794 /** Endpoint states */
00795 enum xhci_endpoint_state {
00796         /** Endpoint is disabled */
00797         XHCI_ENDPOINT_DISABLED = 0,
00798         /** Endpoint is running */
00799         XHCI_ENDPOINT_RUNNING = 1,
00800         /** Endpoint is halted due to a USB Halt condition */
00801         XHCI_ENDPOINT_HALTED = 2,
00802         /** Endpoint is stopped */
00803         XHCI_ENDPOINT_STOPPED = 3,
00804         /** Endpoint is halted due to a TRB error */
00805         XHCI_ENDPOINT_ERROR = 4,
00806 };
00807 
00808 /** Endpoint state mask */
00809 #define XHCI_ENDPOINT_STATE_MASK 0x07
00810 
00811 /** Endpoint type */
00812 #define XHCI_EP_TYPE(type) ( (type) << 3 )
00813 
00814 /** Control endpoint type */
00815 #define XHCI_EP_TYPE_CONTROL XHCI_EP_TYPE ( 4 )
00816 
00817 /** Input endpoint type */
00818 #define XHCI_EP_TYPE_IN XHCI_EP_TYPE ( 4 )
00819 
00820 /** Periodic endpoint type */
00821 #define XHCI_EP_TYPE_PERIODIC XHCI_EP_TYPE ( 1 )
00822 
00823 /** Endpoint dequeue cycle state */
00824 #define XHCI_EP_DCS 0x00000001UL
00825 
00826 /** Control endpoint average TRB length */
00827 #define XHCI_EP0_TRB_LEN 8
00828 
00829 /** An event ring segment */
00830 struct xhci_event_ring_segment {
00831         /** Base address */
00832         uint64_t base;
00833         /** Number of TRBs */
00834         uint32_t count;
00835         /** Reserved */
00836         uint32_t reserved;
00837 } __attribute__ (( packed ));
00838 
00839 /** A transfer request block command/transfer ring */
00840 struct xhci_trb_ring {
00841         /** Producer counter */
00842         unsigned int prod;
00843         /** Consumer counter */
00844         unsigned int cons;
00845         /** Ring size (log2) */
00846         unsigned int shift;
00847         /** Ring counter mask */
00848         unsigned int mask;
00849 
00850         /** I/O buffers */
00851         struct io_buffer **iobuf;
00852 
00853         /** Transfer request blocks */
00854         union xhci_trb *trb;
00855         /** Length of transfer request blocks */
00856         size_t len;
00857         /** Link TRB (if applicable) */
00858         struct xhci_trb_link *link;
00859 
00860         /** Doorbell register */
00861         void *db;
00862         /** Doorbell register value */
00863         uint32_t dbval;
00864 };
00865 
00866 /** An event ring */
00867 struct xhci_event_ring {
00868         /** Consumer counter */
00869         unsigned int cons;
00870         /** Event ring segment table */
00871         struct xhci_event_ring_segment *segment;
00872         /** Transfer request blocks */
00873         union xhci_trb *trb;
00874 };
00875 
00876 /**
00877  * Calculate doorbell register value
00878  *
00879  * @v target            Doorbell target
00880  * @v stream            Doorbell stream ID
00881  * @ret dbval           Doorbell register value
00882  */
00883 #define XHCI_DBVAL( target, stream ) ( (target) | ( (stream) << 16 ) )
00884 
00885 /**
00886  * Calculate space used in TRB ring
00887  *
00888  * @v ring              TRB ring
00889  * @ret fill            Number of entries used
00890  */
00891 static inline __attribute__ (( always_inline )) unsigned int
00892 xhci_ring_fill ( struct xhci_trb_ring *ring ) {
00893 
00894         return ( ring->prod - ring->cons );
00895 }
00896 
00897 /**
00898  * Calculate space remaining in TRB ring
00899  *
00900  * @v ring              TRB ring
00901  * @ret remaining       Number of entries remaining
00902  *
00903  * xHCI does not allow us to completely fill a ring; there must be at
00904  * least one free entry (excluding the Link TRB).
00905  */
00906 static inline __attribute__ (( always_inline )) unsigned int
00907 xhci_ring_remaining ( struct xhci_trb_ring *ring ) {
00908         unsigned int fill = xhci_ring_fill ( ring );
00909 
00910         /* We choose to utilise rings with ( 2^n + 1 ) entries, with
00911          * the final entry being a Link TRB.  The maximum fill level
00912          * is therefore
00913          *
00914          *   ( ( 2^n + 1 ) - 1 (Link TRB) - 1 (one slot always empty)
00915          *       == ( 2^n - 1 )
00916          *
00917          * which is therefore equal to the ring mask.
00918          */
00919         assert ( fill <= ring->mask );
00920         return ( ring->mask - fill );
00921 }
00922 
00923 /**
00924  * Calculate physical address of most recently consumed TRB
00925  *
00926  * @v ring              TRB ring
00927  * @ret trb             TRB physical address
00928  */
00929 static inline __attribute__ (( always_inline )) physaddr_t
00930 xhci_ring_consumed ( struct xhci_trb_ring *ring ) {
00931         unsigned int index = ( ( ring->cons - 1 ) & ring->mask );
00932 
00933         return virt_to_phys ( &ring->trb[index] );
00934 }
00935 
00936 /** Slot context index */
00937 #define XHCI_CTX_SLOT 0
00938 
00939 /** Calculate context index from USB endpoint address */
00940 #define XHCI_CTX(address)                                               \
00941         ( (address) ? ( ( ( (address) & 0x0f ) << 1 ) |                 \
00942                         ( ( (address) & 0x80 ) >> 7 ) ) : 1 )
00943 
00944 /** Endpoint zero context index */
00945 #define XHCI_CTX_EP0 XHCI_CTX ( 0x00 )
00946 
00947 /** End of contexts */
00948 #define XHCI_CTX_END 32
00949 
00950 /** Device context index */
00951 #define XHCI_DCI(ctx) ( (ctx) + 0 )
00952 
00953 /** Input context index */
00954 #define XHCI_ICI(ctx) ( (ctx) + 1 )
00955 
00956 /** Number of TRBs (excluding Link TRB) in the command ring
00957  *
00958  * This is a policy decision.
00959  */
00960 #define XHCI_CMD_TRBS_LOG2 2
00961 
00962 /** Number of TRBs in the event ring
00963  *
00964  * This is a policy decision.
00965  */
00966 #define XHCI_EVENT_TRBS_LOG2 6
00967 
00968 /** Number of TRBs in a transfer ring
00969  *
00970  * This is a policy decision.
00971  */
00972 #define XHCI_TRANSFER_TRBS_LOG2 6
00973 
00974 /** Maximum time to wait for BIOS to release ownership
00975  *
00976  * This is a policy decision.
00977  */
00978 #define XHCI_USBLEGSUP_MAX_WAIT_MS 100
00979 
00980 /** Maximum time to wait for host controller to stop
00981  *
00982  * This is a policy decision.
00983  */
00984 #define XHCI_STOP_MAX_WAIT_MS 100
00985 
00986 /** Maximum time to wait for reset to complete
00987  *
00988  * This is a policy decision.
00989  */
00990 #define XHCI_RESET_MAX_WAIT_MS 500
00991 
00992 /** Maximum time to wait for a command to complete
00993  *
00994  * The "address device" command involves waiting for a response to a
00995  * USB control transaction, and so we must wait for up to the 5000ms
00996  * that USB allows for devices to respond to control transactions.
00997  */
00998 #define XHCI_COMMAND_MAX_WAIT_MS USB_CONTROL_MAX_WAIT_MS
00999 
01000 /** Time to delay after aborting a command
01001  *
01002  * This is a policy decision
01003  */
01004 #define XHCI_COMMAND_ABORT_DELAY_MS 500
01005 
01006 /** Maximum time to wait for a port reset to complete
01007  *
01008  * This is a policy decision.
01009  */
01010 #define XHCI_PORT_RESET_MAX_WAIT_MS 500
01011 
01012 /** Intel PCH quirk */
01013 struct xhci_pch {
01014         /** USB2 port routing register original value */
01015         uint32_t xusb2pr;
01016         /** USB3 port SuperSpeed enable register original value */
01017         uint32_t usb3pssen;
01018 };
01019 
01020 /** Intel PCH quirk flag */
01021 #define XHCI_PCH 0x0001
01022 
01023 /** Intel PCH USB2 port routing register */
01024 #define XHCI_PCH_XUSB2PR 0xd0
01025 
01026 /** Intel PCH USB2 port routing mask register */
01027 #define XHCI_PCH_XUSB2PRM 0xd4
01028 
01029 /** Intel PCH SuperSpeed enable register */
01030 #define XHCI_PCH_USB3PSSEN 0xd8
01031 
01032 /** Intel PCH USB3 port routing mask register */
01033 #define XHCI_PCH_USB3PRM 0xdc
01034 
01035 /** Invalid protocol speed ID values quirk */
01036 #define XHCI_BAD_PSIV 0x0002
01037 
01038 /** An xHCI device */
01039 struct xhci_device {
01040         /** Registers */
01041         void *regs;
01042         /** Name */
01043         const char *name;
01044         /** Quirks */
01045         unsigned int quirks;
01046 
01047         /** Capability registers */
01048         void *cap;
01049         /** Operational registers */
01050         void *op;
01051         /** Runtime registers */
01052         void *run;
01053         /** Doorbell registers */
01054         void *db;
01055 
01056         /** Number of device slots */
01057         unsigned int slots;
01058         /** Number of interrupters */
01059         unsigned int intrs;
01060         /** Number of ports */
01061         unsigned int ports;
01062 
01063         /** Number of page-sized scratchpad buffers */
01064         unsigned int scratchpads;
01065 
01066         /** 64-bit addressing capability */
01067         int addr64;
01068         /** Context size shift */
01069         unsigned int csz_shift;
01070         /** xHCI extended capabilities offset */
01071         unsigned int xecp;
01072 
01073         /** Page size */
01074         size_t pagesize;
01075 
01076         /** USB legacy support capability (if present and enabled) */
01077         unsigned int legacy;
01078 
01079         /** Device context base address array */
01080         uint64_t *dcbaa;
01081 
01082         /** Scratchpad buffer area */
01083         userptr_t scratchpad;
01084         /** Scratchpad buffer array */
01085         uint64_t *scratchpad_array;
01086 
01087         /** Command ring */
01088         struct xhci_trb_ring command;
01089         /** Event ring */
01090         struct xhci_event_ring event;
01091         /** Current command (if any) */
01092         union xhci_trb *pending;
01093 
01094         /** Device slots, indexed by slot ID */
01095         struct xhci_slot **slot;
01096 
01097         /** USB bus */
01098         struct usb_bus *bus;
01099 
01100         /** Intel PCH quirk */
01101         struct xhci_pch pch;
01102 };
01103 
01104 /** An xHCI device slot */
01105 struct xhci_slot {
01106         /** xHCI device */
01107         struct xhci_device *xhci;
01108         /** USB device */
01109         struct usb_device *usb;
01110         /** Slot ID */
01111         unsigned int id;
01112         /** Slot context */
01113         struct xhci_slot_context *context;
01114         /** Route string */
01115         unsigned int route;
01116         /** Root hub port number */
01117         unsigned int port;
01118         /** Protocol speed ID */
01119         unsigned int psiv;
01120         /** Number of ports (if this device is a hub) */
01121         unsigned int ports;
01122         /** Transaction translator slot ID */
01123         unsigned int tt_id;
01124         /** Transaction translator port */
01125         unsigned int tt_port;
01126         /** Endpoints, indexed by context ID */
01127         struct xhci_endpoint *endpoint[XHCI_CTX_END];
01128 };
01129 
01130 /** An xHCI endpoint */
01131 struct xhci_endpoint {
01132         /** xHCI device */
01133         struct xhci_device *xhci;
01134         /** xHCI slot */
01135         struct xhci_slot *slot;
01136         /** USB endpoint */
01137         struct usb_endpoint *ep;
01138         /** Context index */
01139         unsigned int ctx;
01140         /** Endpoint type */
01141         unsigned int type;
01142         /** Endpoint interval */
01143         unsigned int interval;
01144         /** Endpoint context */
01145         struct xhci_endpoint_context *context;
01146         /** Transfer ring */
01147         struct xhci_trb_ring ring;
01148 };
01149 
01150 #endif /* _IPXE_XHCI_H */