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

   1 #ifndef _IPXE_EHCI_H
   2 #define _IPXE_EHCI_H
   3
   4 /** @file
   5  *
   6  * USB Enhanced Host Controller Interface (EHCI) driver
   7  *
   8  */
   9
  10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  11
  12 #include <ipxe/pci.h>
  13 #include <ipxe/usb.h>
  14
  15 /** Minimum alignment required for data structures
  16  *
  17  * With the exception of the periodic frame list (which is
  18  * page-aligned), data structures used by EHCI generally require
  19  * 32-byte alignment and must not cross a 4kB page boundary.  We
  20  * simplify this requirement by aligning each structure on its own
  21  * size, with a minimum of a 32 byte alignment.
  22  */
  23 #define EHCI_MIN_ALIGN 32
  24
  25 /** Maximum transfer size
  26  *
  27  * EHCI allows for transfers of up to 20kB with page-alignment, or
  28  * 16kB with arbitrary alignment.
  29  */
  30 #define EHCI_MTU 16384
  31
  32 /** Page-alignment required for some data structures */
  33 #define EHCI_PAGE_ALIGN 4096
  34
  35 /** EHCI PCI BAR */
  36 #define EHCI_BAR PCI_BASE_ADDRESS_0
  37
  38 /** Capability register length */
  39 #define EHCI_CAP_CAPLENGTH 0x00
  40
  41 /** Host controller interface version number */
  42 #define EHCI_CAP_HCIVERSION 0x02
  43
  44 /** Structural parameters */
  45 #define EHCI_CAP_HCSPARAMS 0x04
  46
  47 /** Number of ports */
  48 #define EHCI_HCSPARAMS_PORTS(params) ( ( (params) >> 0 ) & 0x0f )
  49
  50 /** Capability parameters */
  51 #define EHCI_CAP_HCCPARAMS 0x08
  52
  53 /** 64-bit addressing capability */
  54 #define EHCI_HCCPARAMS_ADDR64(params) ( ( (params) >> 0 ) & 0x1 )
  55
  56 /** Programmable frame list flag */
  57 #define EHCI_HCCPARAMS_FLSIZE(params) ( ( (params) >> 1 ) & 0x1 )
  58
  59 /** EHCI extended capabilities pointer */
  60 #define EHCI_HCCPARAMS_EECP(params) ( ( ( (params) >> 8 ) & 0xff ) )
  61
  62 /** EHCI extended capability ID */
  63 #define EHCI_EECP_ID(eecp) ( ( (eecp) >> 0 ) & 0xff )
  64
  65 /** Next EHCI extended capability pointer */
  66 #define EHCI_EECP_NEXT(eecp) ( ( ( (eecp) >> 8 ) & 0xff ) )
  67
  68 /** USB legacy support extended capability */
  69 #define EHCI_EECP_ID_LEGACY 1
  70
  71 /** USB legacy support BIOS owned semaphore */
  72 #define EHCI_USBLEGSUP_BIOS 0x02
  73
  74 /** USB legacy support BIOS ownership flag */
  75 #define EHCI_USBLEGSUP_BIOS_OWNED 0x01
  76
  77 /** USB legacy support OS owned semaphore */
  78 #define EHCI_USBLEGSUP_OS 0x03
  79
  80 /** USB legacy support OS ownership flag */
  81 #define EHCI_USBLEGSUP_OS_OWNED 0x01
  82
  83 /** USB legacy support control/status */
  84 #define EHCI_USBLEGSUP_CTLSTS 0x04
  85
  86 /** USB command register */
  87 #define EHCI_OP_USBCMD 0x00
  88
  89 /** Run/stop */
  90 #define EHCI_USBCMD_RUN 0x00000001UL
  91
  92 /** Host controller reset */
  93 #define EHCI_USBCMD_HCRST 0x00000002UL
  94
  95 /** Frame list size */
  96 #define EHCI_USBCMD_FLSIZE(flsize) ( (flsize) << 2 )
  97
  98 /** Frame list size mask */
  99 #define EHCI_USBCMD_FLSIZE_MASK EHCI_USBCMD_FLSIZE ( 3 )
 100
 101 /** Default frame list size */
 102 #define EHCI_FLSIZE_DEFAULT 0
 103
 104 /** Smallest allowed frame list size */
 105 #define EHCI_FLSIZE_SMALL 2
 106
 107 /** Number of elements in frame list */
 108 #define EHCI_PERIODIC_FRAMES(flsize) ( 1024 >> (flsize) )
 109
 110 /** Periodic schedule enable */
 111 #define EHCI_USBCMD_PERIODIC 0x00000010UL
 112
 113 /** Asynchronous schedule enable */
 114 #define EHCI_USBCMD_ASYNC 0x00000020UL
 115
 116 /** Asyncchronous schedule advance doorbell */
 117 #define EHCI_USBCMD_ASYNC_ADVANCE 0x000040UL
 118
 119 /** USB status register */
 120 #define EHCI_OP_USBSTS 0x04
 121
 122 /** USB interrupt */
 123 #define EHCI_USBSTS_USBINT 0x00000001UL
 124
 125 /** USB error interrupt */
 126 #define EHCI_USBSTS_USBERRINT 0x00000002UL
 127
 128 /** Port change detect */
 129 #define EHCI_USBSTS_PORT 0x00000004UL
 130
 131 /** Frame list rollover */
 132 #define EHCI_USBSTS_ROLLOVER 0x00000008UL
 133
 134 /** Host system error */
 135 #define EHCI_USBSTS_SYSERR 0x00000010UL
 136
 137 /** Asynchronous schedule advanced */
 138 #define EHCI_USBSTS_ASYNC_ADVANCE 0x00000020UL
 139
 140 /** Periodic schedule enabled */
 141 #define EHCI_USBSTS_PERIODIC 0x00004000UL
 142
 143 /** Asynchronous schedule enabled */
 144 #define EHCI_USBSTS_ASYNC 0x00008000UL
 145
 146 /** Host controller halted */
 147 #define EHCI_USBSTS_HCH 0x00001000UL
 148
 149 /** USB status change mask */
 150 #define EHCI_USBSTS_CHANGE                                              \
 151         ( EHCI_USBSTS_USBINT | EHCI_USBSTS_USBERRINT |                  \
 152           EHCI_USBSTS_PORT | EHCI_USBSTS_ROLLOVER |                     \
 153           EHCI_USBSTS_SYSERR | EHCI_USBSTS_ASYNC_ADVANCE )
 154
 155 /** USB interrupt enable register */
 156 #define EHCI_OP_USBINTR 0x08
 157
 158 /** Frame index register */
 159 #define EHCI_OP_FRINDEX 0x0c
 160
 161 /** Control data structure segment register */
 162 #define EHCI_OP_CTRLDSSEGMENT 0x10
 163
 164 /** Periodic frame list base address register */
 165 #define EHCI_OP_PERIODICLISTBASE 0x14
 166
 167 /** Current asynchronous list address register */
 168 #define EHCI_OP_ASYNCLISTADDR 0x18
 169
 170 /** Configure flag register */
 171 #define EHCI_OP_CONFIGFLAG 0x40
 172
 173 /** Configure flag */
 174 #define EHCI_CONFIGFLAG_CF 0x00000001UL
 175
 176 /** Port status and control register */
 177 #define EHCI_OP_PORTSC(port) ( 0x40 + ( (port) << 2 ) )
 178
 179 /** Current connect status */
 180 #define EHCI_PORTSC_CCS 0x00000001UL
 181
 182 /** Connect status change */
 183 #define EHCI_PORTSC_CSC 0x00000002UL
 184
 185 /** Port enabled */
 186 #define EHCI_PORTSC_PED 0x00000004UL
 187
 188 /** Port enabled/disabled change */
 189 #define EHCI_PORTSC_PEC 0x00000008UL
 190
 191 /** Over-current change */
 192 #define EHCI_PORTSC_OCC 0x00000020UL
 193
 194 /** Port reset */
 195 #define EHCI_PORTSC_PR 0x00000100UL
 196
 197 /** Line status */
 198 #define EHCI_PORTSC_LINE_STATUS(portsc) ( ( (portsc) >> 10 ) & 0x3 )
 199
 200 /** Line status: low-speed device */
 201 #define EHCI_PORTSC_LINE_STATUS_LOW 0x1
 202
 203 /** Port power */
 204 #define EHCI_PORTSC_PP 0x00001000UL
 205
 206 /** Port owner */
 207 #define EHCI_PORTSC_OWNER 0x00002000UL
 208
 209 /** Port status change mask */
 210 #define EHCI_PORTSC_CHANGE \
 211         ( EHCI_PORTSC_CSC | EHCI_PORTSC_PEC | EHCI_PORTSC_OCC )
 212
 213 /** List terminator */
 214 #define EHCI_LINK_TERMINATE 0x00000001UL
 215
 216 /** Frame list type */
 217 #define EHCI_LINK_TYPE(type) ( (type) << 1 )
 218
 219 /** Queue head type */
 220 #define EHCI_LINK_TYPE_QH EHCI_LINK_TYPE ( 1 )
 221
 222 /** A periodic frame list entry */
 223 struct ehci_periodic_frame {
 224         /** First queue head */
 225         uint32_t link;
 226 } __attribute__ (( packed ));
 227
 228 /** A transfer descriptor */
 229 struct ehci_transfer_descriptor {
 230         /** Next transfer descriptor */
 231         uint32_t next;
 232         /** Alternate next transfer descriptor */
 233         uint32_t alt;
 234         /** Status */
 235         uint8_t status;
 236         /** Flags */
 237         uint8_t flags;
 238         /** Transfer length */
 239         uint16_t len;
 240         /** Buffer pointers (low 32 bits) */
 241         uint32_t low[5];
 242         /** Extended buffer pointers (high 32 bits) */
 243         uint32_t high[5];
 244         /** Reserved */
 245         uint8_t reserved[12];
 246 } __attribute__ (( packed ));
 247
 248 /** Transaction error */
 249 #define EHCI_STATUS_XACT_ERR 0x08
 250
 251 /** Babble detected */
 252 #define EHCI_STATUS_BABBLE 0x10
 253
 254 /** Data buffer error */
 255 #define EHCI_STATUS_BUFFER 0x20
 256
 257 /** Halted */
 258 #define EHCI_STATUS_HALTED 0x40
 259
 260 /** Active */
 261 #define EHCI_STATUS_ACTIVE 0x80
 262
 263 /** PID code */
 264 #define EHCI_FL_PID(code) ( (code) << 0 )
 265
 266 /** OUT token */
 267 #define EHCI_FL_PID_OUT EHCI_FL_PID ( 0 )
 268
 269 /** IN token */
 270 #define EHCI_FL_PID_IN EHCI_FL_PID ( 1 )
 271
 272 /** SETUP token */
 273 #define EHCI_FL_PID_SETUP EHCI_FL_PID ( 2 )
 274
 275 /** Error counter */
 276 #define EHCI_FL_CERR( count ) ( (count) << 2 )
 277
 278 /** Error counter maximum value */
 279 #define EHCI_FL_CERR_MAX EHCI_FL_CERR ( 3 )
 280
 281 /** Interrupt on completion */
 282 #define EHCI_FL_IOC 0x80
 283
 284 /** Length mask */
 285 #define EHCI_LEN_MASK 0x7fff
 286
 287 /** Data toggle */
 288 #define EHCI_LEN_TOGGLE 0x8000
 289
 290 /** A queue head */
 291 struct ehci_queue_head {
 292         /** Horizontal link pointer */
 293         uint32_t link;
 294         /** Endpoint characteristics */
 295         uint32_t chr;
 296         /** Endpoint capabilities */
 297         uint32_t cap;
 298         /** Current transfer descriptor */
 299         uint32_t current;
 300         /** Transfer descriptor cache */
 301         struct ehci_transfer_descriptor cache;
 302 } __attribute__ (( packed ));
 303
 304 /** Device address */
 305 #define EHCI_CHR_ADDRESS( address ) ( (address) << 0 )
 306
 307 /** Endpoint number */
 308 #define EHCI_CHR_ENDPOINT( address ) ( ( (address) & 0xf ) << 8 )
 309
 310 /** Endpoint speed */
 311 #define EHCI_CHR_EPS( eps ) ( (eps) << 12 )
 312
 313 /** Full-speed endpoint */
 314 #define EHCI_CHR_EPS_FULL EHCI_CHR_EPS ( 0 )
 315
 316 /** Low-speed endpoint */
 317 #define EHCI_CHR_EPS_LOW EHCI_CHR_EPS ( 1 )
 318
 319 /** High-speed endpoint */
 320 #define EHCI_CHR_EPS_HIGH EHCI_CHR_EPS ( 2 )
 321
 322 /** Explicit data toggles */
 323 #define EHCI_CHR_TOGGLE 0x00004000UL
 324
 325 /** Head of reclamation list flag */
 326 #define EHCI_CHR_HEAD 0x00008000UL
 327
 328 /** Maximum packet length */
 329 #define EHCI_CHR_MAX_LEN( len ) ( (len) << 16 )
 330
 331 /** Control endpoint flag */
 332 #define EHCI_CHR_CONTROL 0x08000000UL
 333
 334 /** Interrupt schedule mask */
 335 #define EHCI_CAP_INTR_SCHED( uframe ) ( 1 << ( (uframe) + 0 ) )
 336
 337 /** Split completion schedule mask */
 338 #define EHCI_CAP_SPLIT_SCHED( uframe ) ( 1 << ( (uframe) + 8 ) )
 339
 340 /** Default split completion schedule mask
 341  *
 342  * We schedule all split starts in microframe 0, on the assumption
 343  * that we will never have to deal with more than sixteen actively
 344  * interrupting devices via the same transaction translator.  We
 345  * schedule split completions for all remaining microframes after
 346  * microframe 1 (in which the low-speed or full-speed transaction is
 347  * assumed to execute).  This is a very crude approximation designed
 348  * to avoid the need for calculating exactly when low-speed and
 349  * full-speed transactions will execute.  Since we only ever deal with
 350  * interrupt endpoints (rather than isochronous endpoints), the volume
 351  * of periodic traffic is extremely low, and this approximation should
 352  * remain valid.
 353  */
 354 #define EHCI_CAP_SPLIT_SCHED_DEFAULT                                    \
 355         ( EHCI_CAP_SPLIT_SCHED ( 2 ) | EHCI_CAP_SPLIT_SCHED ( 3 ) |     \
 356           EHCI_CAP_SPLIT_SCHED ( 4 ) | EHCI_CAP_SPLIT_SCHED ( 5 ) |     \
 357           EHCI_CAP_SPLIT_SCHED ( 6 ) | EHCI_CAP_SPLIT_SCHED ( 7 ) )
 358
 359 /** Transaction translator hub address */
 360 #define EHCI_CAP_TT_HUB( address ) ( (address) << 16 )
 361
 362 /** Transaction translator port number */
 363 #define EHCI_CAP_TT_PORT( port ) ( (port) << 23 )
 364
 365 /** High-bandwidth pipe multiplier */
 366 #define EHCI_CAP_MULT( mult ) ( (mult) << 30 )
 367
 368 /** A transfer descriptor ring */
 369 struct ehci_ring {
 370         /** Producer counter */
 371         unsigned int prod;
 372         /** Consumer counter */
 373         unsigned int cons;
 374
 375         /** Residual untransferred data */
 376         size_t residual;
 377
 378         /** I/O buffers */
 379         struct io_buffer **iobuf;
 380
 381         /** Queue head */
 382         struct ehci_queue_head *head;
 383         /** Transfer descriptors */
 384         struct ehci_transfer_descriptor *desc;
 385 };
 386
 387 /** Number of transfer descriptors in a ring
 388  *
 389  * This is a policy decision.
 390  */
 391 #define EHCI_RING_COUNT 64
 392
 393 /**
 394  * Calculate space used in transfer descriptor ring
 395  *
 396  * @v ring              Transfer descriptor ring
 397  * @ret fill            Number of entries used
 398  */
 399 static inline __attribute__ (( always_inline )) unsigned int
 400 ehci_ring_fill ( struct ehci_ring *ring ) {
 401         unsigned int fill;
 402
 403         fill = ( ring->prod - ring->cons );
 404         assert ( fill <= EHCI_RING_COUNT );
 405         return fill;
 406 }
 407
 408 /**
 409  * Calculate space remaining in transfer descriptor ring
 410  *
 411  * @v ring              Transfer descriptor ring
 412  * @ret remaining       Number of entries remaining
 413  */
 414 static inline __attribute__ (( always_inline )) unsigned int
 415 ehci_ring_remaining ( struct ehci_ring *ring ) {
 416         unsigned int fill = ehci_ring_fill ( ring );
 417
 418         return ( EHCI_RING_COUNT - fill );
 419 }
 420
 421 /** Time to delay after enabling power to a port
 422  *
 423  * This is not mandated by EHCI; we use the value given for xHCI.
 424  */
 425 #define EHCI_PORT_POWER_DELAY_MS 20
 426
 427 /** Time to delay after releasing ownership of a port
 428  *
 429  * This is a policy decision.
 430  */
 431 #define EHCI_DISOWN_DELAY_MS 100
 432
 433 /** Maximum time to wait for BIOS to release ownership
 434  *
 435  * This is a policy decision.
 436  */
 437 #define EHCI_USBLEGSUP_MAX_WAIT_MS 100
 438
 439 /** Maximum time to wait for asynchronous schedule to advance
 440  *
 441  * This is a policy decision.
 442  */
 443 #define EHCI_ASYNC_ADVANCE_MAX_WAIT_MS 100
 444
 445 /** Maximum time to wait for host controller to stop
 446  *
 447  * This is a policy decision.
 448  */
 449 #define EHCI_STOP_MAX_WAIT_MS 100
 450
 451 /** Maximum time to wait for reset to complete
 452  *
 453  * This is a policy decision.
 454  */
 455 #define EHCI_RESET_MAX_WAIT_MS 500
 456
 457 /** Maximum time to wait for a port reset to complete
 458  *
 459  * This is a policy decision.
 460  */
 461 #define EHCI_PORT_RESET_MAX_WAIT_MS 500
 462
 463 /** An EHCI transfer */
 464 struct ehci_transfer {
 465         /** Data buffer */
 466         void *data;
 467         /** Length */
 468         size_t len;
 469         /** Flags
 470          *
 471          * This is the bitwise OR of zero or more EHCI_FL_XXX values.
 472          * The low 8 bits are copied to the flags byte within the
 473          * transfer descriptor; the remaining bits hold flags
 474          * meaningful only to our driver code.
 475          */
 476         unsigned int flags;
 477 };
 478
 479 /** Set initial data toggle */
 480 #define EHCI_FL_TOGGLE 0x8000
 481
 482 /** An EHCI device */
 483 struct ehci_device {
 484         /** Registers */
 485         void *regs;
 486         /** Name */
 487         const char *name;
 488
 489         /** Capability registers */
 490         void *cap;
 491         /** Operational registers */
 492         void *op;
 493
 494         /** Number of ports */
 495         unsigned int ports;
 496         /** 64-bit addressing capability */
 497         int addr64;
 498         /** Frame list size */
 499         unsigned int flsize;
 500         /** EHCI extended capabilities offset */
 501         unsigned int eecp;
 502
 503         /** USB legacy support capability (if present and enabled) */
 504         unsigned int legacy;
 505
 506         /** Control data structure segment */
 507         uint32_t ctrldssegment;
 508         /** Asynchronous queue head */
 509         struct ehci_queue_head *head;
 510         /** Periodic frame list */
 511         struct ehci_periodic_frame *frame;
 512
 513         /** List of all endpoints */
 514         struct list_head endpoints;
 515         /** Asynchronous schedule */
 516         struct list_head async;
 517         /** Periodic schedule
 518          *
 519          * Listed in decreasing order of endpoint interval.
 520          */
 521         struct list_head periodic;
 522
 523         /** USB bus */
 524         struct usb_bus *bus;
 525 };
 526
 527 /** An EHCI endpoint */
 528 struct ehci_endpoint {
 529         /** EHCI device */
 530         struct ehci_device *ehci;
 531         /** USB endpoint */
 532         struct usb_endpoint *ep;
 533         /** List of all endpoints */
 534         struct list_head list;
 535         /** Endpoint schedule */
 536         struct list_head schedule;
 537
 538         /** Transfer descriptor ring */
 539         struct ehci_ring ring;
 540 };
 541
 542 extern unsigned int ehci_companion ( struct pci_device *pci );
 543
 544 #endif /* _IPXE_EHCI_H */