qemu/roms/ipxe/src/drivers/usb/xhci.h

   1 #ifndef _IPXE_XHCI_H
   2 #define _IPXE_XHCI_H
   3
   4 /** @file
   5  *
   6  * USB eXtensible Host Controller Interface (xHCI) driver
   7  *
   8  */
   9
  10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  11
  12 #include <assert.h>
  13 #include <ipxe/pci.h>
  14 #include <ipxe/uaccess.h>
  15 #include <ipxe/usb.h>
  16
  17 /** Minimum alignment required for data structures
  18  *
  19  * With the exception of the scratchpad buffer pages (which are
  20  * page-aligned), data structures used by xHCI generally require from
  21  * 16 to 64 byte alignment and must not cross an (xHCI) page boundary.
  22  * We simplify this requirement by aligning each structure on its own
  23  * size, with a minimum of a 64 byte alignment.
  24  */
  25 #define XHCI_MIN_ALIGN 64
  26
  27 /** Maximum transfer size */
  28 #define XHCI_MTU 65536
  29
  30 /** xHCI PCI BAR */
  31 #define XHCI_BAR PCI_BASE_ADDRESS_0
  32
  33 /** Capability register length */
  34 #define XHCI_CAP_CAPLENGTH 0x00
  35
  36 /** Host controller interface version number */
  37 #define XHCI_CAP_HCIVERSION 0x02
  38
  39 /** Structural parameters 1 */
  40 #define XHCI_CAP_HCSPARAMS1 0x04
  41
  42 /** Number of device slots */
  43 #define XHCI_HCSPARAMS1_SLOTS(params) ( ( (params) >> 0 ) & 0xff )
  44
  45 /** Number of interrupters */
  46 #define XHCI_HCSPARAMS1_INTRS(params) ( ( (params) >> 8 ) & 0x3ff )
  47
  48 /** Number of ports */
  49 #define XHCI_HCSPARAMS1_PORTS(params) ( ( (params) >> 24 ) & 0xff )
  50
  51 /** Structural parameters 2 */
  52 #define XHCI_CAP_HCSPARAMS2 0x08
  53
  54 /** Number of page-sized scratchpad buffers */
  55 #define XHCI_HCSPARAMS2_SCRATCHPADS(params) \
  56         ( ( ( (params) >> 16 ) & 0x3e0 ) | ( ( (params) >> 27 ) & 0x1f ) )
  57
  58 /** Capability parameters */
  59 #define XHCI_CAP_HCCPARAMS1 0x10
  60
  61 /** 64-bit addressing capability */
  62 #define XHCI_HCCPARAMS1_ADDR64(params) ( ( (params) >> 0 ) & 0x1 )
  63
  64 /** Context size shift */
  65 #define XHCI_HCCPARAMS1_CSZ_SHIFT(params) ( 5 + ( ( (params) >> 2 ) & 0x1 ) )
  66
  67 /** xHCI extended capabilities pointer */
  68 #define XHCI_HCCPARAMS1_XECP(params) ( ( ( (params) >> 16 ) & 0xffff ) << 2 )
  69
  70 /** Doorbell offset */
  71 #define XHCI_CAP_DBOFF 0x14
  72
  73 /** Runtime register space offset */
  74 #define XHCI_CAP_RTSOFF 0x18
  75
  76 /** xHCI extended capability ID */
  77 #define XHCI_XECP_ID(xecp) ( ( (xecp) >> 0 ) & 0xff )
  78
  79 /** Next xHCI extended capability pointer */
  80 #define XHCI_XECP_NEXT(xecp) ( ( ( (xecp) >> 8 ) & 0xff ) << 2 )
  81
  82 /** USB legacy support extended capability */
  83 #define XHCI_XECP_ID_LEGACY 1
  84
  85 /** USB legacy support BIOS owned semaphore */
  86 #define XHCI_USBLEGSUP_BIOS 0x02
  87
  88 /** USB legacy support BIOS ownership flag */
  89 #define XHCI_USBLEGSUP_BIOS_OWNED 0x01
  90
  91 /** USB legacy support OS owned semaphore */
  92 #define XHCI_USBLEGSUP_OS 0x03
  93
  94 /** USB legacy support OS ownership flag */
  95 #define XHCI_USBLEGSUP_OS_OWNED 0x01
  96
  97 /** USB legacy support control/status */
  98 #define XHCI_USBLEGSUP_CTLSTS 0x04
  99
 100 /** Supported protocol extended capability */
 101 #define XHCI_XECP_ID_SUPPORTED 2
 102
 103 /** Supported protocol revision */
 104 #define XHCI_SUPPORTED_REVISION 0x00
 105
 106 /** Supported protocol minor revision */
 107 #define XHCI_SUPPORTED_REVISION_VER(revision) ( ( (revision) >> 16 ) & 0xffff )
 108
 109 /** Supported protocol name */
 110 #define XHCI_SUPPORTED_NAME 0x04
 111
 112 /** Supported protocol ports */
 113 #define XHCI_SUPPORTED_PORTS 0x08
 114
 115 /** Supported protocol port offset */
 116 #define XHCI_SUPPORTED_PORTS_OFFSET(ports) ( ( (ports) >> 0 ) & 0xff )
 117
 118 /** Supported protocol port count */
 119 #define XHCI_SUPPORTED_PORTS_COUNT(ports) ( ( (ports) >> 8 ) & 0xff )
 120
 121 /** Supported protocol PSI count */
 122 #define XHCI_SUPPORTED_PORTS_PSIC(ports) ( ( (ports) >> 28 ) & 0x0f )
 123
 124 /** Supported protocol slot */
 125 #define XHCI_SUPPORTED_SLOT 0x0c
 126
 127 /** Supported protocol slot type */
 128 #define XHCI_SUPPORTED_SLOT_TYPE(slot) ( ( (slot) >> 0 ) & 0x1f )
 129
 130 /** Supported protocol PSI */
 131 #define XHCI_SUPPORTED_PSI(index) ( 0x10 + ( (index) * 4 ) )
 132
 133 /** Supported protocol PSI value */
 134 #define XHCI_SUPPORTED_PSI_VALUE(psi) ( ( (psi) >> 0 ) & 0x0f )
 135
 136 /** Supported protocol PSI mantissa */
 137 #define XHCI_SUPPORTED_PSI_MANTISSA(psi) ( ( (psi) >> 16 ) & 0xffff )
 138
 139 /** Supported protocol PSI exponent */
 140 #define XHCI_SUPPORTED_PSI_EXPONENT(psi) ( ( (psi) >> 4 ) & 0x03 )
 141
 142 /** Default PSI values */
 143 enum xhci_default_psi_value {
 144         /** Full speed (12Mbps) */
 145         XHCI_SPEED_FULL = 1,
 146         /** Low speed (1.5Mbps) */
 147         XHCI_SPEED_LOW = 2,
 148         /** High speed (480Mbps) */
 149         XHCI_SPEED_HIGH = 3,
 150         /** Super speed */
 151         XHCI_SPEED_SUPER = 4,
 152 };
 153
 154 /** USB command register */
 155 #define XHCI_OP_USBCMD 0x00
 156
 157 /** Run/stop */
 158 #define XHCI_USBCMD_RUN 0x00000001UL
 159
 160 /** Host controller reset */
 161 #define XHCI_USBCMD_HCRST 0x00000002UL
 162
 163 /** USB status register */
 164 #define XHCI_OP_USBSTS 0x04
 165
 166 /** Host controller halted */
 167 #define XHCI_USBSTS_HCH 0x00000001UL
 168
 169 /** Page size register */
 170 #define XHCI_OP_PAGESIZE 0x08
 171
 172 /** Page size */
 173 #define XHCI_PAGESIZE(pagesize) ( (pagesize) << 12 )
 174
 175 /** Device notifcation control register */
 176 #define XHCI_OP_DNCTRL 0x14
 177
 178 /** Command ring control register */
 179 #define XHCI_OP_CRCR 0x18
 180
 181 /** Command ring cycle state */
 182 #define XHCI_CRCR_RCS 0x00000001UL
 183
 184 /** Command abort */
 185 #define XHCI_CRCR_CA 0x00000004UL
 186
 187 /** Command ring running */
 188 #define XHCI_CRCR_CRR 0x00000008UL
 189
 190 /** Device context base address array pointer */
 191 #define XHCI_OP_DCBAAP 0x30
 192
 193 /** Configure register */
 194 #define XHCI_OP_CONFIG 0x38
 195
 196 /** Maximum device slots enabled */
 197 #define XHCI_CONFIG_MAX_SLOTS_EN(slots) ( (slots) << 0 )
 198
 199 /** Maximum device slots enabled mask */
 200 #define XHCI_CONFIG_MAX_SLOTS_EN_MASK \
 201         XHCI_CONFIG_MAX_SLOTS_EN ( 0xff )
 202
 203 /** Port status and control register */
 204 #define XHCI_OP_PORTSC(port) ( 0x400 - 0x10 + ( (port) << 4 ) )
 205
 206 /** Current connect status */
 207 #define XHCI_PORTSC_CCS 0x00000001UL
 208
 209 /** Port enabled */
 210 #define XHCI_PORTSC_PED 0x00000002UL
 211
 212 /** Port reset */
 213 #define XHCI_PORTSC_PR 0x00000010UL
 214
 215 /** Port link state */
 216 #define XHCI_PORTSC_PLS(pls) ( (pls) << 5 )
 217
 218 /** Disabled port link state */
 219 #define XHCI_PORTSC_PLS_DISABLED XHCI_PORTSC_PLS ( 4 )
 220
 221 /** RxDetect port link state */
 222 #define XHCI_PORTSC_PLS_RXDETECT XHCI_PORTSC_PLS ( 5 )
 223
 224 /** Port link state mask */
 225 #define XHCI_PORTSC_PLS_MASK XHCI_PORTSC_PLS ( 0xf )
 226
 227 /** Port power */
 228 #define XHCI_PORTSC_PP 0x00000200UL
 229
 230 /** Time to delay after enabling power to a port */
 231 #define XHCI_PORT_POWER_DELAY_MS 20
 232
 233 /** Port speed ID value */
 234 #define XHCI_PORTSC_PSIV(portsc) ( ( (portsc) >> 10 ) & 0xf )
 235
 236 /** Port indicator control */
 237 #define XHCI_PORTSC_PIC(indicators) ( (indicators) << 14 )
 238
 239 /** Port indicator control mask */
 240 #define XHCI_PORTSC_PIC_MASK XHCI_PORTSC_PIC ( 3 )
 241
 242 /** Port link state write strobe */
 243 #define XHCI_PORTSC_LWS 0x00010000UL
 244
 245 /** Time to delay after writing the port link state */
 246 #define XHCI_LINK_STATE_DELAY_MS 20
 247
 248 /** Connect status change */
 249 #define XHCI_PORTSC_CSC 0x00020000UL
 250
 251 /** Port enabled/disabled change */
 252 #define XHCI_PORTSC_PEC 0x00040000UL
 253
 254 /** Warm port reset change */
 255 #define XHCI_PORTSC_WRC 0x00080000UL
 256
 257 /** Over-current change */
 258 #define XHCI_PORTSC_OCC 0x00100000UL
 259
 260 /** Port reset change */
 261 #define XHCI_PORTSC_PRC 0x00200000UL
 262
 263 /** Port link state change */
 264 #define XHCI_PORTSC_PLC 0x00400000UL
 265
 266 /** Port config error change */
 267 #define XHCI_PORTSC_CEC 0x00800000UL
 268
 269 /** Port status change mask */
 270 #define XHCI_PORTSC_CHANGE                                      \
 271         ( XHCI_PORTSC_CSC | XHCI_PORTSC_PEC | XHCI_PORTSC_WRC | \
 272           XHCI_PORTSC_OCC | XHCI_PORTSC_PRC | XHCI_PORTSC_PLC | \
 273           XHCI_PORTSC_CEC )
 274
 275 /** Port status and control bits which should be preserved
 276  *
 277  * The port status and control register is a horrendous mix of
 278  * differing semantics.  Some bits are written to only when a separate
 279  * write strobe bit is set.  Some bits should be preserved when
 280  * modifying other bits.  Some bits will be cleared if written back as
 281  * a one.  Most excitingly, the "port enabled" bit has the semantics
 282  * that 1=enabled, 0=disabled, yet writing a 1 will disable the port.
 283  */
 284 #define XHCI_PORTSC_PRESERVE ( XHCI_PORTSC_PP | XHCI_PORTSC_PIC_MASK )
 285
 286 /** Port power management status and control register */
 287 #define XHCI_OP_PORTPMSC(port) ( 0x404 - 0x10 + ( (port) << 4 ) )
 288
 289 /** Port link info register */
 290 #define XHCI_OP_PORTLI(port) ( 0x408 - 0x10 + ( (port) << 4 ) )
 291
 292 /** Port hardware link power management control register */
 293 #define XHCI_OP_PORTHLPMC(port) ( 0x40c - 0x10 + ( (port) << 4 ) )
 294
 295 /** Event ring segment table size register */
 296 #define XHCI_RUN_ERSTSZ(intr) ( 0x28 + ( (intr) << 5 ) )
 297
 298 /** Event ring segment table base address register */
 299 #define XHCI_RUN_ERSTBA(intr) ( 0x30 + ( (intr) << 5 ) )
 300
 301 /** Event ring dequeue pointer register */
 302 #define XHCI_RUN_ERDP(intr) ( 0x38 + ( (intr) << 5 ) )
 303
 304 /** A transfer request block template */
 305 struct xhci_trb_template {
 306         /** Parameter */
 307         uint64_t parameter;
 308         /** Status */
 309         uint32_t status;
 310         /** Control */
 311         uint32_t control;
 312 };
 313
 314 /** A transfer request block */
 315 struct xhci_trb_common {
 316         /** Reserved */
 317         uint64_t reserved_a;
 318         /** Reserved */
 319         uint32_t reserved_b;
 320         /** Flags */
 321         uint8_t flags;
 322         /** Type */
 323         uint8_t type;
 324         /** Reserved */
 325         uint16_t reserved_c;
 326 } __attribute__ (( packed ));
 327
 328 /** Transfer request block cycle bit flag */
 329 #define XHCI_TRB_C 0x01
 330
 331 /** Transfer request block toggle cycle bit flag */
 332 #define XHCI_TRB_TC 0x02
 333
 334 /** Transfer request block chain flag */
 335 #define XHCI_TRB_CH 0x10
 336
 337 /** Transfer request block interrupt on completion flag */
 338 #define XHCI_TRB_IOC 0x20
 339
 340 /** Transfer request block immediate data flag */
 341 #define XHCI_TRB_IDT 0x40
 342
 343 /** Transfer request block type */
 344 #define XHCI_TRB_TYPE(type) ( (type) << 2 )
 345
 346 /** Transfer request block type mask */
 347 #define XHCI_TRB_TYPE_MASK XHCI_TRB_TYPE ( 0x3f )
 348
 349 /** A normal transfer request block */
 350 struct xhci_trb_normal {
 351         /** Data buffer */
 352         uint64_t data;
 353         /** Length */
 354         uint32_t len;
 355         /** Flags */
 356         uint8_t flags;
 357         /** Type */
 358         uint8_t type;
 359         /** Reserved */
 360         uint16_t reserved;
 361 } __attribute__ (( packed ));
 362
 363 /** A normal transfer request block */
 364 #define XHCI_TRB_NORMAL XHCI_TRB_TYPE ( 1 )
 365
 366 /** Construct TD size field */
 367 #define XHCI_TD_SIZE(remaining) \
 368         ( ( ( (remaining) <= 0xf ) ? remaining : 0xf ) << 17 )
 369
 370 /** A setup stage transfer request block */
 371 struct xhci_trb_setup {
 372         /** Setup packet */
 373         struct usb_setup_packet packet;
 374         /** Length */
 375         uint32_t len;
 376         /** Flags */
 377         uint8_t flags;
 378         /** Type */
 379         uint8_t type;
 380         /** Transfer direction */
 381         uint8_t direction;
 382         /** Reserved */
 383         uint8_t reserved;
 384 } __attribute__ (( packed ));
 385
 386 /** A setup stage transfer request block */
 387 #define XHCI_TRB_SETUP XHCI_TRB_TYPE ( 2 )
 388
 389 /** Setup stage input data direction */
 390 #define XHCI_SETUP_IN 3
 391
 392 /** Setup stage output data direction */
 393 #define XHCI_SETUP_OUT 2
 394
 395 /** A data stage transfer request block */
 396 struct xhci_trb_data {
 397         /** Data buffer */
 398         uint64_t data;
 399         /** Length */
 400         uint32_t len;
 401         /** Flags */
 402         uint8_t flags;
 403         /** Type */
 404         uint8_t type;
 405         /** Transfer direction */
 406         uint8_t direction;
 407         /** Reserved */
 408         uint8_t reserved;
 409 } __attribute__ (( packed ));
 410
 411 /** A data stage transfer request block */
 412 #define XHCI_TRB_DATA XHCI_TRB_TYPE ( 3 )
 413
 414 /** Input data direction */
 415 #define XHCI_DATA_IN 0x01
 416
 417 /** Output data direction */
 418 #define XHCI_DATA_OUT 0x00
 419
 420 /** A status stage transfer request block */
 421 struct xhci_trb_status {
 422         /** Reserved */
 423         uint64_t reserved_a;
 424         /** Reserved */
 425         uint32_t reserved_b;
 426         /** Flags */
 427         uint8_t flags;
 428         /** Type */
 429         uint8_t type;
 430         /** Direction */
 431         uint8_t direction;
 432         /** Reserved */
 433         uint8_t reserved_c;
 434 } __attribute__ (( packed ));
 435
 436 /** A status stage transfer request block */
 437 #define XHCI_TRB_STATUS XHCI_TRB_TYPE ( 4 )
 438
 439 /** Input status direction */
 440 #define XHCI_STATUS_IN 0x01
 441
 442 /** Output status direction */
 443 #define XHCI_STATUS_OUT 0x00
 444
 445 /** A link transfer request block */
 446 struct xhci_trb_link {
 447         /** Next ring segment */
 448         uint64_t next;
 449         /** Reserved */
 450         uint32_t reserved_a;
 451         /** Flags */
 452         uint8_t flags;
 453         /** Type */
 454         uint8_t type;
 455         /** Reserved */
 456         uint16_t reserved_c;
 457 } __attribute__ (( packed ));
 458
 459 /** A link transfer request block */
 460 #define XHCI_TRB_LINK XHCI_TRB_TYPE ( 6 )
 461
 462 /** A no-op transfer request block */
 463 #define XHCI_TRB_NOP XHCI_TRB_TYPE ( 8 )
 464
 465 /** An enable slot transfer request block */
 466 struct xhci_trb_enable_slot {
 467         /** Reserved */
 468         uint64_t reserved_a;
 469         /** Reserved */
 470         uint32_t reserved_b;
 471         /** Flags */
 472         uint8_t flags;
 473         /** Type */
 474         uint8_t type;
 475         /** Slot type */
 476         uint8_t slot;
 477         /** Reserved */
 478         uint8_t reserved_c;
 479 } __attribute__ (( packed ));
 480
 481 /** An enable slot transfer request block */
 482 #define XHCI_TRB_ENABLE_SLOT XHCI_TRB_TYPE ( 9 )
 483
 484 /** A disable slot transfer request block */
 485 struct xhci_trb_disable_slot {
 486         /** Reserved */
 487         uint64_t reserved_a;
 488         /** Reserved */
 489         uint32_t reserved_b;
 490         /** Flags */
 491         uint8_t flags;
 492         /** Type */
 493         uint8_t type;
 494         /** Reserved */
 495         uint8_t reserved_c;
 496         /** Slot ID */
 497         uint8_t slot;
 498 } __attribute__ (( packed ));
 499
 500 /** A disable slot transfer request block */
 501 #define XHCI_TRB_DISABLE_SLOT XHCI_TRB_TYPE ( 10 )
 502
 503 /** A context transfer request block */
 504 struct xhci_trb_context {
 505         /** Input context */
 506         uint64_t input;
 507         /** Reserved */
 508         uint32_t reserved_a;
 509         /** Flags */
 510         uint8_t flags;
 511         /** Type */
 512         uint8_t type;
 513         /** Reserved */
 514         uint8_t reserved_b;
 515         /** Slot ID */
 516         uint8_t slot;
 517 } __attribute__ (( packed ));
 518
 519 /** An address device transfer request block */
 520 #define XHCI_TRB_ADDRESS_DEVICE XHCI_TRB_TYPE ( 11 )
 521
 522 /** A configure endpoint transfer request block */
 523 #define XHCI_TRB_CONFIGURE_ENDPOINT XHCI_TRB_TYPE ( 12 )
 524
 525 /** An evaluate context transfer request block */
 526 #define XHCI_TRB_EVALUATE_CONTEXT XHCI_TRB_TYPE ( 13 )
 527
 528 /** A reset endpoint transfer request block */
 529 struct xhci_trb_reset_endpoint {
 530         /** Reserved */
 531         uint64_t reserved_a;
 532         /** Reserved */
 533         uint32_t reserved_b;
 534         /** Flags */
 535         uint8_t flags;
 536         /** Type */
 537         uint8_t type;
 538         /** Endpoint ID */
 539         uint8_t endpoint;
 540         /** Slot ID */
 541         uint8_t slot;
 542 } __attribute__ (( packed ));
 543
 544 /** A reset endpoint transfer request block */
 545 #define XHCI_TRB_RESET_ENDPOINT XHCI_TRB_TYPE ( 14 )
 546
 547 /** A stop endpoint transfer request block */
 548 struct xhci_trb_stop_endpoint {
 549         /** Reserved */
 550         uint64_t reserved_a;
 551         /** Reserved */
 552         uint32_t reserved_b;
 553         /** Flags */
 554         uint8_t flags;
 555         /** Type */
 556         uint8_t type;
 557         /** Endpoint ID */
 558         uint8_t endpoint;
 559         /** Slot ID */
 560         uint8_t slot;
 561 } __attribute__ (( packed ));
 562
 563 /** A stop endpoint transfer request block */
 564 #define XHCI_TRB_STOP_ENDPOINT XHCI_TRB_TYPE ( 15 )
 565
 566 /** A set transfer ring dequeue pointer transfer request block */
 567 struct xhci_trb_set_tr_dequeue_pointer {
 568         /** Dequeue pointer */
 569         uint64_t dequeue;
 570         /** Reserved */
 571         uint32_t reserved;
 572         /** Flags */
 573         uint8_t flags;
 574         /** Type */
 575         uint8_t type;
 576         /** Endpoint ID */
 577         uint8_t endpoint;
 578         /** Slot ID */
 579         uint8_t slot;
 580 } __attribute__ (( packed ));
 581
 582 /** A set transfer ring dequeue pointer transfer request block */
 583 #define XHCI_TRB_SET_TR_DEQUEUE_POINTER XHCI_TRB_TYPE ( 16 )
 584
 585 /** A no-op command transfer request block */
 586 #define XHCI_TRB_NOP_CMD XHCI_TRB_TYPE ( 23 )
 587
 588 /** A transfer event transfer request block */
 589 struct xhci_trb_transfer {
 590         /** Transfer TRB pointer */
 591         uint64_t transfer;
 592         /** Residual transfer length */
 593         uint16_t residual;
 594         /** Reserved */
 595         uint8_t reserved;
 596         /** Completion code */
 597         uint8_t code;
 598         /** Flags */
 599         uint8_t flags;
 600         /** Type */
 601         uint8_t type;
 602         /** Endpoint ID */
 603         uint8_t endpoint;
 604         /** Slot ID */
 605         uint8_t slot;
 606 } __attribute__ (( packed ));
 607
 608 /** A transfer event transfer request block */
 609 #define XHCI_TRB_TRANSFER XHCI_TRB_TYPE ( 32 )
 610
 611 /** A command completion event transfer request block */
 612 struct xhci_trb_complete {
 613         /** Command TRB pointer */
 614         uint64_t command;
 615         /** Parameter */
 616         uint8_t parameter[3];
 617         /** Completion code */
 618         uint8_t code;
 619         /** Flags */
 620         uint8_t flags;
 621         /** Type */
 622         uint8_t type;
 623         /** Virtual function ID */
 624         uint8_t vf;
 625         /** Slot ID */
 626         uint8_t slot;
 627 } __attribute__ (( packed ));
 628
 629 /** A command completion event transfer request block */
 630 #define XHCI_TRB_COMPLETE XHCI_TRB_TYPE ( 33 )
 631
 632 /** xHCI completion codes */
 633 enum xhci_completion_code {
 634         /** Success */
 635         XHCI_CMPLT_SUCCESS = 1,
 636         /** Short packet */
 637         XHCI_CMPLT_SHORT = 13,
 638         /** Command ring stopped */
 639         XHCI_CMPLT_CMD_STOPPED = 24,
 640 };
 641
 642 /** A port status change transfer request block */
 643 struct xhci_trb_port_status {
 644         /** Reserved */
 645         uint8_t reserved_a[3];
 646         /** Port ID */
 647         uint8_t port;
 648         /** Reserved */
 649         uint8_t reserved_b[7];
 650         /** Completion code */
 651         uint8_t code;
 652         /** Flags */
 653         uint8_t flags;
 654         /** Type */
 655         uint8_t type;
 656         /** Reserved */
 657         uint16_t reserved_c;
 658 } __attribute__ (( packed ));
 659
 660 /** A port status change transfer request block */
 661 #define XHCI_TRB_PORT_STATUS XHCI_TRB_TYPE ( 34 )
 662
 663 /** A port status change transfer request block */
 664 struct xhci_trb_host_controller {
 665         /** Reserved */
 666         uint64_t reserved_a;
 667         /** Reserved */
 668         uint8_t reserved_b[3];
 669         /** Completion code */
 670         uint8_t code;
 671         /** Flags */
 672         uint8_t flags;
 673         /** Type */
 674         uint8_t type;
 675         /** Reserved */
 676         uint16_t reserved_c;
 677 } __attribute__ (( packed ));
 678
 679 /** A port status change transfer request block */
 680 #define XHCI_TRB_HOST_CONTROLLER XHCI_TRB_TYPE ( 37 )
 681
 682 /** A transfer request block */
 683 union xhci_trb {
 684         /** Template */
 685         struct xhci_trb_template template;
 686         /** Common fields */
 687         struct xhci_trb_common common;
 688         /** Normal TRB */
 689         struct xhci_trb_normal normal;
 690         /** Setup stage TRB */
 691         struct xhci_trb_setup setup;
 692         /** Data stage TRB */
 693         struct xhci_trb_data data;
 694         /** Status stage TRB */
 695         struct xhci_trb_status status;
 696         /** Link TRB */
 697         struct xhci_trb_link link;
 698         /** Enable slot TRB */
 699         struct xhci_trb_enable_slot enable;
 700         /** Disable slot TRB */
 701         struct xhci_trb_disable_slot disable;
 702         /** Input context TRB */
 703         struct xhci_trb_context context;
 704         /** Reset endpoint TRB */
 705         struct xhci_trb_reset_endpoint reset;
 706         /** Stop endpoint TRB */
 707         struct xhci_trb_stop_endpoint stop;
 708         /** Set transfer ring dequeue pointer TRB */
 709         struct xhci_trb_set_tr_dequeue_pointer dequeue;
 710         /** Transfer event */
 711         struct xhci_trb_transfer transfer;
 712         /** Command completion event */
 713         struct xhci_trb_complete complete;
 714         /** Port status changed event */
 715         struct xhci_trb_port_status port;
 716         /** Host controller event */
 717         struct xhci_trb_host_controller host;
 718 } __attribute__ (( packed ));
 719
 720 /** An input control context */
 721 struct xhci_control_context {
 722         /** Drop context flags */
 723         uint32_t drop;
 724         /** Add context flags */
 725         uint32_t add;
 726         /** Reserved */
 727         uint32_t reserved_a[5];
 728         /** Configuration value */
 729         uint8_t config;
 730         /** Interface number */
 731         uint8_t intf;
 732         /** Alternate setting */
 733         uint8_t alt;
 734         /** Reserved */
 735         uint8_t reserved_b;
 736 } __attribute__ (( packed ));
 737
 738 /** A slot context */
 739 struct xhci_slot_context {
 740         /** Device info */
 741         uint32_t info;
 742         /** Maximum exit latency */
 743         uint16_t latency;
 744         /** Root hub port number */
 745         uint8_t port;
 746         /** Number of downstream ports */
 747         uint8_t ports;
 748         /** TT hub slot ID */
 749         uint8_t tt_id;
 750         /** TT port number */
 751         uint8_t tt_port;
 752         /** Interrupter target */
 753         uint16_t intr;
 754         /** USB address */
 755         uint8_t address;
 756         /** Reserved */
 757         uint16_t reserved_a;
 758         /** Slot state */
 759         uint8_t state;
 760         /** Reserved */
 761         uint32_t reserved_b[4];
 762 } __attribute__ (( packed ));
 763
 764 /** Construct slot context device info */
 765 #define XHCI_SLOT_INFO( entries, hub, speed, route ) \
 766         ( ( (entries) << 27 ) | ( (hub) << 26 ) | ( (speed) << 20 ) | (route) )
 767
 768 /** An endpoint context */
 769 struct xhci_endpoint_context {
 770         /** Endpoint state */
 771         uint8_t state;
 772         /** Stream configuration */
 773         uint8_t stream;
 774         /** Polling interval */
 775         uint8_t interval;
 776         /** Max ESIT payload high */
 777         uint8_t esit_high;
 778         /** Endpoint type */
 779         uint8_t type;
 780         /** Maximum burst size */
 781         uint8_t burst;
 782         /** Maximum packet size */
 783         uint16_t mtu;
 784         /** Transfer ring dequeue pointer */
 785         uint64_t dequeue;
 786         /** Average TRB length */
 787         uint16_t trb_len;
 788         /** Max ESIT payload low */
 789         uint16_t esit_low;
 790         /** Reserved */
 791         uint32_t reserved[3];
 792 } __attribute__ (( packed ));
 793
 794 /** Endpoint states */
 795 enum xhci_endpoint_state {
 796         /** Endpoint is disabled */
 797         XHCI_ENDPOINT_DISABLED = 0,
 798         /** Endpoint is running */
 799         XHCI_ENDPOINT_RUNNING = 1,
 800         /** Endpoint is halted due to a USB Halt condition */
 801         XHCI_ENDPOINT_HALTED = 2,
 802         /** Endpoint is stopped */
 803         XHCI_ENDPOINT_STOPPED = 3,
 804         /** Endpoint is halted due to a TRB error */
 805         XHCI_ENDPOINT_ERROR = 4,
 806 };
 807
 808 /** Endpoint state mask */
 809 #define XHCI_ENDPOINT_STATE_MASK 0x07
 810
 811 /** Endpoint type */
 812 #define XHCI_EP_TYPE(type) ( (type) << 3 )
 813
 814 /** Control endpoint type */
 815 #define XHCI_EP_TYPE_CONTROL XHCI_EP_TYPE ( 4 )
 816
 817 /** Input endpoint type */
 818 #define XHCI_EP_TYPE_IN XHCI_EP_TYPE ( 4 )
 819
 820 /** Periodic endpoint type */
 821 #define XHCI_EP_TYPE_PERIODIC XHCI_EP_TYPE ( 1 )
 822
 823 /** Endpoint dequeue cycle state */
 824 #define XHCI_EP_DCS 0x00000001UL
 825
 826 /** Control endpoint average TRB length */
 827 #define XHCI_EP0_TRB_LEN 8
 828
 829 /** An event ring segment */
 830 struct xhci_event_ring_segment {
 831         /** Base address */
 832         uint64_t base;
 833         /** Number of TRBs */
 834         uint32_t count;
 835         /** Reserved */
 836         uint32_t reserved;
 837 } __attribute__ (( packed ));
 838
 839 /** A transfer request block command/transfer ring */
 840 struct xhci_trb_ring {
 841         /** Producer counter */
 842         unsigned int prod;
 843         /** Consumer counter */
 844         unsigned int cons;
 845         /** Ring size (log2) */
 846         unsigned int shift;
 847         /** Ring counter mask */
 848         unsigned int mask;
 849
 850         /** I/O buffers */
 851         struct io_buffer **iobuf;
 852
 853         /** Transfer request blocks */
 854         union xhci_trb *trb;
 855         /** Length of transfer request blocks */
 856         size_t len;
 857         /** Link TRB (if applicable) */
 858         struct xhci_trb_link *link;
 859
 860         /** Doorbell register */
 861         void *db;
 862         /** Doorbell register value */
 863         uint32_t dbval;
 864 };
 865
 866 /** An event ring */
 867 struct xhci_event_ring {
 868         /** Consumer counter */
 869         unsigned int cons;
 870         /** Event ring segment table */
 871         struct xhci_event_ring_segment *segment;
 872         /** Transfer request blocks */
 873         union xhci_trb *trb;
 874 };
 875
 876 /**
 877  * Calculate doorbell register value
 878  *
 879  * @v target            Doorbell target
 880  * @v stream            Doorbell stream ID
 881  * @ret dbval           Doorbell register value
 882  */
 883 #define XHCI_DBVAL( target, stream ) ( (target) | ( (stream) << 16 ) )
 884
 885 /**
 886  * Calculate space used in TRB ring
 887  *
 888  * @v ring              TRB ring
 889  * @ret fill            Number of entries used
 890  */
 891 static inline __attribute__ (( always_inline )) unsigned int
 892 xhci_ring_fill ( struct xhci_trb_ring *ring ) {
 893
 894         return ( ring->prod - ring->cons );
 895 }
 896
 897 /**
 898  * Calculate space remaining in TRB ring
 899  *
 900  * @v ring              TRB ring
 901  * @ret remaining       Number of entries remaining
 902  *
 903  * xHCI does not allow us to completely fill a ring; there must be at
 904  * least one free entry (excluding the Link TRB).
 905  */
 906 static inline __attribute__ (( always_inline )) unsigned int
 907 xhci_ring_remaining ( struct xhci_trb_ring *ring ) {
 908         unsigned int fill = xhci_ring_fill ( ring );
 909
 910         /* We choose to utilise rings with ( 2^n + 1 ) entries, with
 911          * the final entry being a Link TRB.  The maximum fill level
 912          * is therefore
 913          *
 914          *   ( ( 2^n + 1 ) - 1 (Link TRB) - 1 (one slot always empty)
 915          *       == ( 2^n - 1 )
 916          *
 917          * which is therefore equal to the ring mask.
 918          */
 919         assert ( fill <= ring->mask );
 920         return ( ring->mask - fill );
 921 }
 922
 923 /**
 924  * Calculate physical address of most recently consumed TRB
 925  *
 926  * @v ring              TRB ring
 927  * @ret trb             TRB physical address
 928  */
 929 static inline __attribute__ (( always_inline )) physaddr_t
 930 xhci_ring_consumed ( struct xhci_trb_ring *ring ) {
 931         unsigned int index = ( ( ring->cons - 1 ) & ring->mask );
 932
 933         return virt_to_phys ( &ring->trb[index] );
 934 }
 935
 936 /** Slot context index */
 937 #define XHCI_CTX_SLOT 0
 938
 939 /** Calculate context index from USB endpoint address */
 940 #define XHCI_CTX(address)                                               \
 941         ( (address) ? ( ( ( (address) & 0x0f ) << 1 ) |                 \
 942                         ( ( (address) & 0x80 ) >> 7 ) ) : 1 )
 943
 944 /** Endpoint zero context index */
 945 #define XHCI_CTX_EP0 XHCI_CTX ( 0x00 )
 946
 947 /** End of contexts */
 948 #define XHCI_CTX_END 32
 949
 950 /** Device context index */
 951 #define XHCI_DCI(ctx) ( (ctx) + 0 )
 952
 953 /** Input context index */
 954 #define XHCI_ICI(ctx) ( (ctx) + 1 )
 955
 956 /** Number of TRBs (excluding Link TRB) in the command ring
 957  *
 958  * This is a policy decision.
 959  */
 960 #define XHCI_CMD_TRBS_LOG2 2
 961
 962 /** Number of TRBs in the event ring
 963  *
 964  * This is a policy decision.
 965  */
 966 #define XHCI_EVENT_TRBS_LOG2 6
 967
 968 /** Number of TRBs in a transfer ring
 969  *
 970  * This is a policy decision.
 971  */
 972 #define XHCI_TRANSFER_TRBS_LOG2 6
 973
 974 /** Maximum time to wait for BIOS to release ownership
 975  *
 976  * This is a policy decision.
 977  */
 978 #define XHCI_USBLEGSUP_MAX_WAIT_MS 100
 979
 980 /** Maximum time to wait for host controller to stop
 981  *
 982  * This is a policy decision.
 983  */
 984 #define XHCI_STOP_MAX_WAIT_MS 100
 985
 986 /** Maximum time to wait for reset to complete
 987  *
 988  * This is a policy decision.
 989  */
 990 #define XHCI_RESET_MAX_WAIT_MS 500
 991
 992 /** Maximum time to wait for a command to complete
 993  *
 994  * The "address device" command involves waiting for a response to a
 995  * USB control transaction, and so we must wait for up to the 5000ms
 996  * that USB allows for devices to respond to control transactions.
 997  */
 998 #define XHCI_COMMAND_MAX_WAIT_MS USB_CONTROL_MAX_WAIT_MS
 999
1000 /** Time to delay after aborting a command
1001  *
1002  * This is a policy decision
1003  */
1004 #define XHCI_COMMAND_ABORT_DELAY_MS 500
1005
1006 /** Maximum time to wait for a port reset to complete
1007  *
1008  * This is a policy decision.
1009  */
1010 #define XHCI_PORT_RESET_MAX_WAIT_MS 500
1011
1012 /** Intel PCH quirk */
1013 struct xhci_pch {
1014         /** USB2 port routing register original value */
1015         uint32_t xusb2pr;
1016         /** USB3 port SuperSpeed enable register original value */
1017         uint32_t usb3pssen;
1018 };
1019
1020 /** Intel PCH quirk flag */
1021 #define XHCI_PCH 0x0001
1022
1023 /** Intel PCH USB2 port routing register */
1024 #define XHCI_PCH_XUSB2PR 0xd0
1025
1026 /** Intel PCH USB2 port routing mask register */
1027 #define XHCI_PCH_XUSB2PRM 0xd4
1028
1029 /** Intel PCH SuperSpeed enable register */
1030 #define XHCI_PCH_USB3PSSEN 0xd8
1031
1032 /** Intel PCH USB3 port routing mask register */
1033 #define XHCI_PCH_USB3PRM 0xdc
1034
1035 /** Invalid protocol speed ID values quirk */
1036 #define XHCI_BAD_PSIV 0x0002
1037
1038 /** An xHCI device */
1039 struct xhci_device {
1040         /** Registers */
1041         void *regs;
1042         /** Name */
1043         const char *name;
1044         /** Quirks */
1045         unsigned int quirks;
1046
1047         /** Capability registers */
1048         void *cap;
1049         /** Operational registers */
1050         void *op;
1051         /** Runtime registers */
1052         void *run;
1053         /** Doorbell registers */
1054         void *db;
1055
1056         /** Number of device slots */
1057         unsigned int slots;
1058         /** Number of interrupters */
1059         unsigned int intrs;
1060         /** Number of ports */
1061         unsigned int ports;
1062
1063         /** Number of page-sized scratchpad buffers */
1064         unsigned int scratchpads;
1065
1066         /** 64-bit addressing capability */
1067         int addr64;
1068         /** Context size shift */
1069         unsigned int csz_shift;
1070         /** xHCI extended capabilities offset */
1071         unsigned int xecp;
1072
1073         /** Page size */
1074         size_t pagesize;
1075
1076         /** USB legacy support capability (if present and enabled) */
1077         unsigned int legacy;
1078
1079         /** Device context base address array */
1080         uint64_t *dcbaa;
1081
1082         /** Scratchpad buffer area */
1083         userptr_t scratchpad;
1084         /** Scratchpad buffer array */
1085         uint64_t *scratchpad_array;
1086
1087         /** Command ring */
1088         struct xhci_trb_ring command;
1089         /** Event ring */
1090         struct xhci_event_ring event;
1091         /** Current command (if any) */
1092         union xhci_trb *pending;
1093
1094         /** Device slots, indexed by slot ID */
1095         struct xhci_slot **slot;
1096
1097         /** USB bus */
1098         struct usb_bus *bus;
1099
1100         /** Intel PCH quirk */
1101         struct xhci_pch pch;
1102 };
1103
1104 /** An xHCI device slot */
1105 struct xhci_slot {
1106         /** xHCI device */
1107         struct xhci_device *xhci;
1108         /** USB device */
1109         struct usb_device *usb;
1110         /** Slot ID */
1111         unsigned int id;
1112         /** Slot context */
1113         struct xhci_slot_context *context;
1114         /** Route string */
1115         unsigned int route;
1116         /** Root hub port number */
1117         unsigned int port;
1118         /** Protocol speed ID */
1119         unsigned int psiv;
1120         /** Number of ports (if this device is a hub) */
1121         unsigned int ports;
1122         /** Transaction translator slot ID */
1123         unsigned int tt_id;
1124         /** Transaction translator port */
1125         unsigned int tt_port;
1126         /** Endpoints, indexed by context ID */
1127         struct xhci_endpoint *endpoint[XHCI_CTX_END];
1128 };
1129
1130 /** An xHCI endpoint */
1131 struct xhci_endpoint {
1132         /** xHCI device */
1133         struct xhci_device *xhci;
1134         /** xHCI slot */
1135         struct xhci_slot *slot;
1136         /** USB endpoint */
1137         struct usb_endpoint *ep;
1138         /** Context index */
1139         unsigned int ctx;
1140         /** Endpoint type */
1141         unsigned int type;
1142         /** Endpoint interval */
1143         unsigned int interval;
1144         /** Endpoint context */
1145         struct xhci_endpoint_context *context;
1146         /** Transfer ring */
1147         struct xhci_trb_ring ring;
1148 };
1149
1150 #endif /* _IPXE_XHCI_H */