iPXE
ehci.h
Go to the documentation of this file.
00001 #ifndef _IPXE_EHCI_H
00002 #define _IPXE_EHCI_H
00003 
00004 /** @file
00005  *
00006  * USB Enhanced Host Controller Interface (EHCI) driver
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <ipxe/pci.h>
00013 #include <ipxe/usb.h>
00014 
00015 /** Minimum alignment required for data structures
00016  *
00017  * With the exception of the periodic frame list (which is
00018  * page-aligned), data structures used by EHCI generally require
00019  * 32-byte alignment and must not cross a 4kB page boundary.  We
00020  * simplify this requirement by aligning each structure on its own
00021  * size, with a minimum of a 32 byte alignment.
00022  */
00023 #define EHCI_MIN_ALIGN 32
00024 
00025 /** Maximum transfer size
00026  *
00027  * EHCI allows for transfers of up to 20kB with page-alignment, or
00028  * 16kB with arbitrary alignment.
00029  */
00030 #define EHCI_MTU 16384
00031 
00032 /** Page-alignment required for some data structures */
00033 #define EHCI_PAGE_ALIGN 4096
00034 
00035 /** EHCI PCI BAR */
00036 #define EHCI_BAR PCI_BASE_ADDRESS_0
00037 
00038 /** Capability register length */
00039 #define EHCI_CAP_CAPLENGTH 0x00
00040 
00041 /** Host controller interface version number */
00042 #define EHCI_CAP_HCIVERSION 0x02
00043 
00044 /** Structural parameters */
00045 #define EHCI_CAP_HCSPARAMS 0x04
00046 
00047 /** Number of ports */
00048 #define EHCI_HCSPARAMS_PORTS(params) ( ( (params) >> 0 ) & 0x0f )
00049 
00050 /** Capability parameters */
00051 #define EHCI_CAP_HCCPARAMS 0x08
00052 
00053 /** 64-bit addressing capability */
00054 #define EHCI_HCCPARAMS_ADDR64(params) ( ( (params) >> 0 ) & 0x1 )
00055 
00056 /** Programmable frame list flag */
00057 #define EHCI_HCCPARAMS_FLSIZE(params) ( ( (params) >> 1 ) & 0x1 )
00058 
00059 /** EHCI extended capabilities pointer */
00060 #define EHCI_HCCPARAMS_EECP(params) ( ( ( (params) >> 8 ) & 0xff ) )
00061 
00062 /** EHCI extended capability ID */
00063 #define EHCI_EECP_ID(eecp) ( ( (eecp) >> 0 ) & 0xff )
00064 
00065 /** Next EHCI extended capability pointer */
00066 #define EHCI_EECP_NEXT(eecp) ( ( ( (eecp) >> 8 ) & 0xff ) )
00067 
00068 /** USB legacy support extended capability */
00069 #define EHCI_EECP_ID_LEGACY 1
00070 
00071 /** USB legacy support BIOS owned semaphore */
00072 #define EHCI_USBLEGSUP_BIOS 0x02
00073 
00074 /** USB legacy support BIOS ownership flag */
00075 #define EHCI_USBLEGSUP_BIOS_OWNED 0x01
00076 
00077 /** USB legacy support OS owned semaphore */
00078 #define EHCI_USBLEGSUP_OS 0x03
00079 
00080 /** USB legacy support OS ownership flag */
00081 #define EHCI_USBLEGSUP_OS_OWNED 0x01
00082 
00083 /** USB legacy support control/status */
00084 #define EHCI_USBLEGSUP_CTLSTS 0x04
00085 
00086 /** USB command register */
00087 #define EHCI_OP_USBCMD 0x00
00088 
00089 /** Run/stop */
00090 #define EHCI_USBCMD_RUN 0x00000001UL
00091 
00092 /** Host controller reset */
00093 #define EHCI_USBCMD_HCRST 0x00000002UL
00094 
00095 /** Frame list size */
00096 #define EHCI_USBCMD_FLSIZE(flsize) ( (flsize) << 2 )
00097 
00098 /** Frame list size mask */
00099 #define EHCI_USBCMD_FLSIZE_MASK EHCI_USBCMD_FLSIZE ( 3 )
00100 
00101 /** Default frame list size */
00102 #define EHCI_FLSIZE_DEFAULT 0
00103 
00104 /** Smallest allowed frame list size */
00105 #define EHCI_FLSIZE_SMALL 2
00106 
00107 /** Number of elements in frame list */
00108 #define EHCI_PERIODIC_FRAMES(flsize) ( 1024 >> (flsize) )
00109 
00110 /** Periodic schedule enable */
00111 #define EHCI_USBCMD_PERIODIC 0x00000010UL
00112 
00113 /** Asynchronous schedule enable */
00114 #define EHCI_USBCMD_ASYNC 0x00000020UL
00115 
00116 /** Asyncchronous schedule advance doorbell */
00117 #define EHCI_USBCMD_ASYNC_ADVANCE 0x000040UL
00118 
00119 /** USB status register */
00120 #define EHCI_OP_USBSTS 0x04
00121 
00122 /** USB interrupt */
00123 #define EHCI_USBSTS_USBINT 0x00000001UL
00124 
00125 /** USB error interrupt */
00126 #define EHCI_USBSTS_USBERRINT 0x00000002UL
00127 
00128 /** Port change detect */
00129 #define EHCI_USBSTS_PORT 0x00000004UL
00130 
00131 /** Frame list rollover */
00132 #define EHCI_USBSTS_ROLLOVER 0x00000008UL
00133 
00134 /** Host system error */
00135 #define EHCI_USBSTS_SYSERR 0x00000010UL
00136 
00137 /** Asynchronous schedule advanced */
00138 #define EHCI_USBSTS_ASYNC_ADVANCE 0x00000020UL
00139 
00140 /** Periodic schedule enabled */
00141 #define EHCI_USBSTS_PERIODIC 0x00004000UL
00142 
00143 /** Asynchronous schedule enabled */
00144 #define EHCI_USBSTS_ASYNC 0x00008000UL
00145 
00146 /** Host controller halted */
00147 #define EHCI_USBSTS_HCH 0x00001000UL
00148 
00149 /** USB status change mask */
00150 #define EHCI_USBSTS_CHANGE                                              \
00151         ( EHCI_USBSTS_USBINT | EHCI_USBSTS_USBERRINT |                  \
00152           EHCI_USBSTS_PORT | EHCI_USBSTS_ROLLOVER |                     \
00153           EHCI_USBSTS_SYSERR | EHCI_USBSTS_ASYNC_ADVANCE )
00154 
00155 /** USB interrupt enable register */
00156 #define EHCI_OP_USBINTR 0x08
00157 
00158 /** Frame index register */
00159 #define EHCI_OP_FRINDEX 0x0c
00160 
00161 /** Control data structure segment register */
00162 #define EHCI_OP_CTRLDSSEGMENT 0x10
00163 
00164 /** Periodic frame list base address register */
00165 #define EHCI_OP_PERIODICLISTBASE 0x14
00166 
00167 /** Current asynchronous list address register */
00168 #define EHCI_OP_ASYNCLISTADDR 0x18
00169 
00170 /** Configure flag register */
00171 #define EHCI_OP_CONFIGFLAG 0x40
00172 
00173 /** Configure flag */
00174 #define EHCI_CONFIGFLAG_CF 0x00000001UL
00175 
00176 /** Port status and control register */
00177 #define EHCI_OP_PORTSC(port) ( 0x40 + ( (port) << 2 ) )
00178 
00179 /** Current connect status */
00180 #define EHCI_PORTSC_CCS 0x00000001UL
00181 
00182 /** Connect status change */
00183 #define EHCI_PORTSC_CSC 0x00000002UL
00184 
00185 /** Port enabled */
00186 #define EHCI_PORTSC_PED 0x00000004UL
00187 
00188 /** Port enabled/disabled change */
00189 #define EHCI_PORTSC_PEC 0x00000008UL
00190 
00191 /** Over-current change */
00192 #define EHCI_PORTSC_OCC 0x00000020UL
00193 
00194 /** Port reset */
00195 #define EHCI_PORTSC_PR 0x00000100UL
00196 
00197 /** Line status */
00198 #define EHCI_PORTSC_LINE_STATUS(portsc) ( ( (portsc) >> 10 ) & 0x3 )
00199 
00200 /** Line status: low-speed device */
00201 #define EHCI_PORTSC_LINE_STATUS_LOW 0x1
00202 
00203 /** Port power */
00204 #define EHCI_PORTSC_PP 0x00001000UL
00205 
00206 /** Port owner */
00207 #define EHCI_PORTSC_OWNER 0x00002000UL
00208 
00209 /** Port status change mask */
00210 #define EHCI_PORTSC_CHANGE \
00211         ( EHCI_PORTSC_CSC | EHCI_PORTSC_PEC | EHCI_PORTSC_OCC )
00212 
00213 /** List terminator */
00214 #define EHCI_LINK_TERMINATE 0x00000001UL
00215 
00216 /** Frame list type */
00217 #define EHCI_LINK_TYPE(type) ( (type) << 1 )
00218 
00219 /** Queue head type */
00220 #define EHCI_LINK_TYPE_QH EHCI_LINK_TYPE ( 1 )
00221 
00222 /** A periodic frame list entry */
00223 struct ehci_periodic_frame {
00224         /** First queue head */
00225         uint32_t link;
00226 } __attribute__ (( packed ));
00227 
00228 /** A transfer descriptor */
00229 struct ehci_transfer_descriptor {
00230         /** Next transfer descriptor */
00231         uint32_t next;
00232         /** Alternate next transfer descriptor */
00233         uint32_t alt;
00234         /** Status */
00235         uint8_t status;
00236         /** Flags */
00237         uint8_t flags;
00238         /** Transfer length */
00239         uint16_t len;
00240         /** Buffer pointers (low 32 bits) */
00241         uint32_t low[5];
00242         /** Extended buffer pointers (high 32 bits) */
00243         uint32_t high[5];
00244         /** Reserved */
00245         uint8_t reserved[12];
00246 } __attribute__ (( packed ));
00247 
00248 /** Transaction error */
00249 #define EHCI_STATUS_XACT_ERR 0x08
00250 
00251 /** Babble detected */
00252 #define EHCI_STATUS_BABBLE 0x10
00253 
00254 /** Data buffer error */
00255 #define EHCI_STATUS_BUFFER 0x20
00256 
00257 /** Halted */
00258 #define EHCI_STATUS_HALTED 0x40
00259 
00260 /** Active */
00261 #define EHCI_STATUS_ACTIVE 0x80
00262 
00263 /** PID code */
00264 #define EHCI_FL_PID(code) ( (code) << 0 )
00265 
00266 /** OUT token */
00267 #define EHCI_FL_PID_OUT EHCI_FL_PID ( 0 )
00268 
00269 /** IN token */
00270 #define EHCI_FL_PID_IN EHCI_FL_PID ( 1 )
00271 
00272 /** SETUP token */
00273 #define EHCI_FL_PID_SETUP EHCI_FL_PID ( 2 )
00274 
00275 /** Error counter */
00276 #define EHCI_FL_CERR( count ) ( (count) << 2 )
00277 
00278 /** Error counter maximum value */
00279 #define EHCI_FL_CERR_MAX EHCI_FL_CERR ( 3 )
00280 
00281 /** Interrupt on completion */
00282 #define EHCI_FL_IOC 0x80
00283 
00284 /** Length mask */
00285 #define EHCI_LEN_MASK 0x7fff
00286 
00287 /** Data toggle */
00288 #define EHCI_LEN_TOGGLE 0x8000
00289 
00290 /** A queue head */
00291 struct ehci_queue_head {
00292         /** Horizontal link pointer */
00293         uint32_t link;
00294         /** Endpoint characteristics */
00295         uint32_t chr;
00296         /** Endpoint capabilities */
00297         uint32_t cap;
00298         /** Current transfer descriptor */
00299         uint32_t current;
00300         /** Transfer descriptor cache */
00301         struct ehci_transfer_descriptor cache;
00302 } __attribute__ (( packed ));
00303 
00304 /** Device address */
00305 #define EHCI_CHR_ADDRESS( address ) ( (address) << 0 )
00306 
00307 /** Endpoint number */
00308 #define EHCI_CHR_ENDPOINT( address ) ( ( (address) & 0xf ) << 8 )
00309 
00310 /** Endpoint speed */
00311 #define EHCI_CHR_EPS( eps ) ( (eps) << 12 )
00312 
00313 /** Full-speed endpoint */
00314 #define EHCI_CHR_EPS_FULL EHCI_CHR_EPS ( 0 )
00315 
00316 /** Low-speed endpoint */
00317 #define EHCI_CHR_EPS_LOW EHCI_CHR_EPS ( 1 )
00318 
00319 /** High-speed endpoint */
00320 #define EHCI_CHR_EPS_HIGH EHCI_CHR_EPS ( 2 )
00321 
00322 /** Explicit data toggles */
00323 #define EHCI_CHR_TOGGLE 0x00004000UL
00324 
00325 /** Head of reclamation list flag */
00326 #define EHCI_CHR_HEAD 0x00008000UL
00327 
00328 /** Maximum packet length */
00329 #define EHCI_CHR_MAX_LEN( len ) ( (len) << 16 )
00330 
00331 /** Control endpoint flag */
00332 #define EHCI_CHR_CONTROL 0x08000000UL
00333 
00334 /** Interrupt schedule mask */
00335 #define EHCI_CAP_INTR_SCHED( uframe ) ( 1 << ( (uframe) + 0 ) )
00336 
00337 /** Split completion schedule mask */
00338 #define EHCI_CAP_SPLIT_SCHED( uframe ) ( 1 << ( (uframe) + 8 ) )
00339 
00340 /** Default split completion schedule mask
00341  *
00342  * We schedule all split starts in microframe 0, on the assumption
00343  * that we will never have to deal with more than sixteen actively
00344  * interrupting devices via the same transaction translator.  We
00345  * schedule split completions for all remaining microframes after
00346  * microframe 1 (in which the low-speed or full-speed transaction is
00347  * assumed to execute).  This is a very crude approximation designed
00348  * to avoid the need for calculating exactly when low-speed and
00349  * full-speed transactions will execute.  Since we only ever deal with
00350  * interrupt endpoints (rather than isochronous endpoints), the volume
00351  * of periodic traffic is extremely low, and this approximation should
00352  * remain valid.
00353  */
00354 #define EHCI_CAP_SPLIT_SCHED_DEFAULT                                    \
00355         ( EHCI_CAP_SPLIT_SCHED ( 2 ) | EHCI_CAP_SPLIT_SCHED ( 3 ) |     \
00356           EHCI_CAP_SPLIT_SCHED ( 4 ) | EHCI_CAP_SPLIT_SCHED ( 5 ) |     \
00357           EHCI_CAP_SPLIT_SCHED ( 6 ) | EHCI_CAP_SPLIT_SCHED ( 7 ) )
00358 
00359 /** Transaction translator hub address */
00360 #define EHCI_CAP_TT_HUB( address ) ( (address) << 16 )
00361 
00362 /** Transaction translator port number */
00363 #define EHCI_CAP_TT_PORT( port ) ( (port) << 23 )
00364 
00365 /** High-bandwidth pipe multiplier */
00366 #define EHCI_CAP_MULT( mult ) ( (mult) << 30 )
00367 
00368 /** A transfer descriptor ring */
00369 struct ehci_ring {
00370         /** Producer counter */
00371         unsigned int prod;
00372         /** Consumer counter */
00373         unsigned int cons;
00374 
00375         /** Residual untransferred data */
00376         size_t residual;
00377 
00378         /** I/O buffers */
00379         struct io_buffer **iobuf;
00380 
00381         /** Queue head */
00382         struct ehci_queue_head *head;
00383         /** Transfer descriptors */
00384         struct ehci_transfer_descriptor *desc;
00385 };
00386 
00387 /** Number of transfer descriptors in a ring
00388  *
00389  * This is a policy decision.
00390  */
00391 #define EHCI_RING_COUNT 64
00392 
00393 /**
00394  * Calculate space used in transfer descriptor ring
00395  *
00396  * @v ring              Transfer descriptor ring
00397  * @ret fill            Number of entries used
00398  */
00399 static inline __attribute__ (( always_inline )) unsigned int
00400 ehci_ring_fill ( struct ehci_ring *ring ) {
00401         unsigned int fill;
00402 
00403         fill = ( ring->prod - ring->cons );
00404         assert ( fill <= EHCI_RING_COUNT );
00405         return fill;
00406 }
00407 
00408 /**
00409  * Calculate space remaining in transfer descriptor ring
00410  *
00411  * @v ring              Transfer descriptor ring
00412  * @ret remaining       Number of entries remaining
00413  */
00414 static inline __attribute__ (( always_inline )) unsigned int
00415 ehci_ring_remaining ( struct ehci_ring *ring ) {
00416         unsigned int fill = ehci_ring_fill ( ring );
00417 
00418         return ( EHCI_RING_COUNT - fill );
00419 }
00420 
00421 /** Time to delay after enabling power to a port
00422  *
00423  * This is not mandated by EHCI; we use the value given for xHCI.
00424  */
00425 #define EHCI_PORT_POWER_DELAY_MS 20
00426 
00427 /** Time to delay after releasing ownership of a port
00428  *
00429  * This is a policy decision.
00430  */
00431 #define EHCI_DISOWN_DELAY_MS 100
00432 
00433 /** Maximum time to wait for BIOS to release ownership
00434  *
00435  * This is a policy decision.
00436  */
00437 #define EHCI_USBLEGSUP_MAX_WAIT_MS 100
00438 
00439 /** Maximum time to wait for asynchronous schedule to advance
00440  *
00441  * This is a policy decision.
00442  */
00443 #define EHCI_ASYNC_ADVANCE_MAX_WAIT_MS 100
00444 
00445 /** Maximum time to wait for host controller to stop
00446  *
00447  * This is a policy decision.
00448  */
00449 #define EHCI_STOP_MAX_WAIT_MS 100
00450 
00451 /** Maximum time to wait for reset to complete
00452  *
00453  * This is a policy decision.
00454  */
00455 #define EHCI_RESET_MAX_WAIT_MS 500
00456 
00457 /** Maximum time to wait for a port reset to complete
00458  *
00459  * This is a policy decision.
00460  */
00461 #define EHCI_PORT_RESET_MAX_WAIT_MS 500
00462 
00463 /** An EHCI transfer */
00464 struct ehci_transfer {
00465         /** Data buffer */
00466         void *data;
00467         /** Length */
00468         size_t len;
00469         /** Flags
00470          *
00471          * This is the bitwise OR of zero or more EHCI_FL_XXX values.
00472          * The low 8 bits are copied to the flags byte within the
00473          * transfer descriptor; the remaining bits hold flags
00474          * meaningful only to our driver code.
00475          */
00476         unsigned int flags;
00477 };
00478 
00479 /** Set initial data toggle */
00480 #define EHCI_FL_TOGGLE 0x8000
00481 
00482 /** An EHCI device */
00483 struct ehci_device {
00484         /** Registers */
00485         void *regs;
00486         /** Name */
00487         const char *name;
00488 
00489         /** Capability registers */
00490         void *cap;
00491         /** Operational registers */
00492         void *op;
00493 
00494         /** Number of ports */
00495         unsigned int ports;
00496         /** 64-bit addressing capability */
00497         int addr64;
00498         /** Frame list size */
00499         unsigned int flsize;
00500         /** EHCI extended capabilities offset */
00501         unsigned int eecp;
00502 
00503         /** USB legacy support capability (if present and enabled) */
00504         unsigned int legacy;
00505 
00506         /** Control data structure segment */
00507         uint32_t ctrldssegment;
00508         /** Asynchronous queue head */
00509         struct ehci_queue_head *head;
00510         /** Periodic frame list */
00511         struct ehci_periodic_frame *frame;
00512 
00513         /** List of all endpoints */
00514         struct list_head endpoints;
00515         /** Asynchronous schedule */
00516         struct list_head async;
00517         /** Periodic schedule
00518          *
00519          * Listed in decreasing order of endpoint interval.
00520          */
00521         struct list_head periodic;
00522 
00523         /** USB bus */
00524         struct usb_bus *bus;
00525 };
00526 
00527 /** An EHCI endpoint */
00528 struct ehci_endpoint {
00529         /** EHCI device */
00530         struct ehci_device *ehci;
00531         /** USB endpoint */
00532         struct usb_endpoint *ep;
00533         /** List of all endpoints */
00534         struct list_head list;
00535         /** Endpoint schedule */
00536         struct list_head schedule;
00537 
00538         /** Transfer descriptor ring */
00539         struct ehci_ring ring;
00540 };
00541 
00542 extern unsigned int ehci_companion ( struct pci_device *pci );
00543 
00544 #endif /* _IPXE_EHCI_H */