6 * USB Enhanced Host Controller Interface (EHCI) driver
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
15 /** Minimum alignment required for data structures
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.
23 #define EHCI_MIN_ALIGN 32
25 /** Maximum transfer size
27 * EHCI allows for transfers of up to 20kB with page-alignment, or
28 * 16kB with arbitrary alignment.
30 #define EHCI_MTU 16384
32 /** Page-alignment required for some data structures */
33 #define EHCI_PAGE_ALIGN 4096
36 #define EHCI_BAR PCI_BASE_ADDRESS_0
38 /** Capability register length */
39 #define EHCI_CAP_CAPLENGTH 0x00
41 /** Host controller interface version number */
42 #define EHCI_CAP_HCIVERSION 0x02
44 /** Structural parameters */
45 #define EHCI_CAP_HCSPARAMS 0x04
47 /** Number of ports */
48 #define EHCI_HCSPARAMS_PORTS(params) ( ( (params) >> 0 ) & 0x0f )
50 /** Capability parameters */
51 #define EHCI_CAP_HCCPARAMS 0x08
53 /** 64-bit addressing capability */
54 #define EHCI_HCCPARAMS_ADDR64(params) ( ( (params) >> 0 ) & 0x1 )
56 /** Programmable frame list flag */
57 #define EHCI_HCCPARAMS_FLSIZE(params) ( ( (params) >> 1 ) & 0x1 )
59 /** EHCI extended capabilities pointer */
60 #define EHCI_HCCPARAMS_EECP(params) ( ( ( (params) >> 8 ) & 0xff ) )
62 /** EHCI extended capability ID */
63 #define EHCI_EECP_ID(eecp) ( ( (eecp) >> 0 ) & 0xff )
65 /** Next EHCI extended capability pointer */
66 #define EHCI_EECP_NEXT(eecp) ( ( ( (eecp) >> 8 ) & 0xff ) )
68 /** USB legacy support extended capability */
69 #define EHCI_EECP_ID_LEGACY 1
71 /** USB legacy support BIOS owned semaphore */
72 #define EHCI_USBLEGSUP_BIOS 0x02
74 /** USB legacy support BIOS ownership flag */
75 #define EHCI_USBLEGSUP_BIOS_OWNED 0x01
77 /** USB legacy support OS owned semaphore */
78 #define EHCI_USBLEGSUP_OS 0x03
80 /** USB legacy support OS ownership flag */
81 #define EHCI_USBLEGSUP_OS_OWNED 0x01
83 /** USB legacy support control/status */
84 #define EHCI_USBLEGSUP_CTLSTS 0x04
86 /** USB command register */
87 #define EHCI_OP_USBCMD 0x00
90 #define EHCI_USBCMD_RUN 0x00000001UL
92 /** Host controller reset */
93 #define EHCI_USBCMD_HCRST 0x00000002UL
95 /** Frame list size */
96 #define EHCI_USBCMD_FLSIZE(flsize) ( (flsize) << 2 )
98 /** Frame list size mask */
99 #define EHCI_USBCMD_FLSIZE_MASK EHCI_USBCMD_FLSIZE ( 3 )
101 /** Default frame list size */
102 #define EHCI_FLSIZE_DEFAULT 0
104 /** Smallest allowed frame list size */
105 #define EHCI_FLSIZE_SMALL 2
107 /** Number of elements in frame list */
108 #define EHCI_PERIODIC_FRAMES(flsize) ( 1024 >> (flsize) )
110 /** Periodic schedule enable */
111 #define EHCI_USBCMD_PERIODIC 0x00000010UL
113 /** Asynchronous schedule enable */
114 #define EHCI_USBCMD_ASYNC 0x00000020UL
116 /** Asyncchronous schedule advance doorbell */
117 #define EHCI_USBCMD_ASYNC_ADVANCE 0x000040UL
119 /** USB status register */
120 #define EHCI_OP_USBSTS 0x04
123 #define EHCI_USBSTS_USBINT 0x00000001UL
125 /** USB error interrupt */
126 #define EHCI_USBSTS_USBERRINT 0x00000002UL
128 /** Port change detect */
129 #define EHCI_USBSTS_PORT 0x00000004UL
131 /** Frame list rollover */
132 #define EHCI_USBSTS_ROLLOVER 0x00000008UL
134 /** Host system error */
135 #define EHCI_USBSTS_SYSERR 0x00000010UL
137 /** Asynchronous schedule advanced */
138 #define EHCI_USBSTS_ASYNC_ADVANCE 0x00000020UL
140 /** Periodic schedule enabled */
141 #define EHCI_USBSTS_PERIODIC 0x00004000UL
143 /** Asynchronous schedule enabled */
144 #define EHCI_USBSTS_ASYNC 0x00008000UL
146 /** Host controller halted */
147 #define EHCI_USBSTS_HCH 0x00001000UL
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 )
155 /** USB interrupt enable register */
156 #define EHCI_OP_USBINTR 0x08
158 /** Frame index register */
159 #define EHCI_OP_FRINDEX 0x0c
161 /** Control data structure segment register */
162 #define EHCI_OP_CTRLDSSEGMENT 0x10
164 /** Periodic frame list base address register */
165 #define EHCI_OP_PERIODICLISTBASE 0x14
167 /** Current asynchronous list address register */
168 #define EHCI_OP_ASYNCLISTADDR 0x18
170 /** Configure flag register */
171 #define EHCI_OP_CONFIGFLAG 0x40
173 /** Configure flag */
174 #define EHCI_CONFIGFLAG_CF 0x00000001UL
176 /** Port status and control register */
177 #define EHCI_OP_PORTSC(port) ( 0x40 + ( (port) << 2 ) )
179 /** Current connect status */
180 #define EHCI_PORTSC_CCS 0x00000001UL
182 /** Connect status change */
183 #define EHCI_PORTSC_CSC 0x00000002UL
186 #define EHCI_PORTSC_PED 0x00000004UL
188 /** Port enabled/disabled change */
189 #define EHCI_PORTSC_PEC 0x00000008UL
191 /** Over-current change */
192 #define EHCI_PORTSC_OCC 0x00000020UL
195 #define EHCI_PORTSC_PR 0x00000100UL
198 #define EHCI_PORTSC_LINE_STATUS(portsc) ( ( (portsc) >> 10 ) & 0x3 )
200 /** Line status: low-speed device */
201 #define EHCI_PORTSC_LINE_STATUS_LOW 0x1
204 #define EHCI_PORTSC_PP 0x00001000UL
207 #define EHCI_PORTSC_OWNER 0x00002000UL
209 /** Port status change mask */
210 #define EHCI_PORTSC_CHANGE \
211 ( EHCI_PORTSC_CSC | EHCI_PORTSC_PEC | EHCI_PORTSC_OCC )
213 /** List terminator */
214 #define EHCI_LINK_TERMINATE 0x00000001UL
216 /** Frame list type */
217 #define EHCI_LINK_TYPE(type) ( (type) << 1 )
219 /** Queue head type */
220 #define EHCI_LINK_TYPE_QH EHCI_LINK_TYPE ( 1 )
222 /** A periodic frame list entry */
223 struct ehci_periodic_frame {
224 /** First queue head */
226 } __attribute__ (( packed ));
228 /** A transfer descriptor */
229 struct ehci_transfer_descriptor {
230 /** Next transfer descriptor */
232 /** Alternate next transfer descriptor */
238 /** Transfer length */
240 /** Buffer pointers (low 32 bits) */
242 /** Extended buffer pointers (high 32 bits) */
245 uint8_t reserved[12];
246 } __attribute__ (( packed ));
248 /** Transaction error */
249 #define EHCI_STATUS_XACT_ERR 0x08
251 /** Babble detected */
252 #define EHCI_STATUS_BABBLE 0x10
254 /** Data buffer error */
255 #define EHCI_STATUS_BUFFER 0x20
258 #define EHCI_STATUS_HALTED 0x40
261 #define EHCI_STATUS_ACTIVE 0x80
264 #define EHCI_FL_PID(code) ( (code) << 0 )
267 #define EHCI_FL_PID_OUT EHCI_FL_PID ( 0 )
270 #define EHCI_FL_PID_IN EHCI_FL_PID ( 1 )
273 #define EHCI_FL_PID_SETUP EHCI_FL_PID ( 2 )
276 #define EHCI_FL_CERR( count ) ( (count) << 2 )
278 /** Error counter maximum value */
279 #define EHCI_FL_CERR_MAX EHCI_FL_CERR ( 3 )
281 /** Interrupt on completion */
282 #define EHCI_FL_IOC 0x80
285 #define EHCI_LEN_MASK 0x7fff
288 #define EHCI_LEN_TOGGLE 0x8000
291 struct ehci_queue_head {
292 /** Horizontal link pointer */
294 /** Endpoint characteristics */
296 /** Endpoint capabilities */
298 /** Current transfer descriptor */
300 /** Transfer descriptor cache */
301 struct ehci_transfer_descriptor cache;
302 } __attribute__ (( packed ));
304 /** Device address */
305 #define EHCI_CHR_ADDRESS( address ) ( (address) << 0 )
307 /** Endpoint number */
308 #define EHCI_CHR_ENDPOINT( address ) ( ( (address) & 0xf ) << 8 )
310 /** Endpoint speed */
311 #define EHCI_CHR_EPS( eps ) ( (eps) << 12 )
313 /** Full-speed endpoint */
314 #define EHCI_CHR_EPS_FULL EHCI_CHR_EPS ( 0 )
316 /** Low-speed endpoint */
317 #define EHCI_CHR_EPS_LOW EHCI_CHR_EPS ( 1 )
319 /** High-speed endpoint */
320 #define EHCI_CHR_EPS_HIGH EHCI_CHR_EPS ( 2 )
322 /** Explicit data toggles */
323 #define EHCI_CHR_TOGGLE 0x00004000UL
325 /** Head of reclamation list flag */
326 #define EHCI_CHR_HEAD 0x00008000UL
328 /** Maximum packet length */
329 #define EHCI_CHR_MAX_LEN( len ) ( (len) << 16 )
331 /** Control endpoint flag */
332 #define EHCI_CHR_CONTROL 0x08000000UL
334 /** Interrupt schedule mask */
335 #define EHCI_CAP_INTR_SCHED( uframe ) ( 1 << ( (uframe) + 0 ) )
337 /** Split completion schedule mask */
338 #define EHCI_CAP_SPLIT_SCHED( uframe ) ( 1 << ( (uframe) + 8 ) )
340 /** Default split completion schedule mask
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
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 ) )
359 /** Transaction translator hub address */
360 #define EHCI_CAP_TT_HUB( address ) ( (address) << 16 )
362 /** Transaction translator port number */
363 #define EHCI_CAP_TT_PORT( port ) ( (port) << 23 )
365 /** High-bandwidth pipe multiplier */
366 #define EHCI_CAP_MULT( mult ) ( (mult) << 30 )
368 /** A transfer descriptor ring */
370 /** Producer counter */
372 /** Consumer counter */
375 /** Residual untransferred data */
379 struct io_buffer **iobuf;
382 struct ehci_queue_head *head;
383 /** Transfer descriptors */
384 struct ehci_transfer_descriptor *desc;
387 /** Number of transfer descriptors in a ring
389 * This is a policy decision.
391 #define EHCI_RING_COUNT 64
394 * Calculate space used in transfer descriptor ring
396 * @v ring Transfer descriptor ring
397 * @ret fill Number of entries used
399 static inline __attribute__ (( always_inline )) unsigned int
400 ehci_ring_fill ( struct ehci_ring *ring ) {
403 fill = ( ring->prod - ring->cons );
404 assert ( fill <= EHCI_RING_COUNT );
409 * Calculate space remaining in transfer descriptor ring
411 * @v ring Transfer descriptor ring
412 * @ret remaining Number of entries remaining
414 static inline __attribute__ (( always_inline )) unsigned int
415 ehci_ring_remaining ( struct ehci_ring *ring ) {
416 unsigned int fill = ehci_ring_fill ( ring );
418 return ( EHCI_RING_COUNT - fill );
421 /** Time to delay after enabling power to a port
423 * This is not mandated by EHCI; we use the value given for xHCI.
425 #define EHCI_PORT_POWER_DELAY_MS 20
427 /** Time to delay after releasing ownership of a port
429 * This is a policy decision.
431 #define EHCI_DISOWN_DELAY_MS 100
433 /** Maximum time to wait for BIOS to release ownership
435 * This is a policy decision.
437 #define EHCI_USBLEGSUP_MAX_WAIT_MS 100
439 /** Maximum time to wait for asynchronous schedule to advance
441 * This is a policy decision.
443 #define EHCI_ASYNC_ADVANCE_MAX_WAIT_MS 100
445 /** Maximum time to wait for host controller to stop
447 * This is a policy decision.
449 #define EHCI_STOP_MAX_WAIT_MS 100
451 /** Maximum time to wait for reset to complete
453 * This is a policy decision.
455 #define EHCI_RESET_MAX_WAIT_MS 500
457 /** Maximum time to wait for a port reset to complete
459 * This is a policy decision.
461 #define EHCI_PORT_RESET_MAX_WAIT_MS 500
463 /** An EHCI transfer */
464 struct ehci_transfer {
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.
479 /** Set initial data toggle */
480 #define EHCI_FL_TOGGLE 0x8000
482 /** An EHCI device */
489 /** Capability registers */
491 /** Operational registers */
494 /** Number of ports */
496 /** 64-bit addressing capability */
498 /** Frame list size */
500 /** EHCI extended capabilities offset */
503 /** USB legacy support capability (if present and enabled) */
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;
513 /** List of all endpoints */
514 struct list_head endpoints;
515 /** Asynchronous schedule */
516 struct list_head async;
517 /** Periodic schedule
519 * Listed in decreasing order of endpoint interval.
521 struct list_head periodic;
527 /** An EHCI endpoint */
528 struct ehci_endpoint {
530 struct ehci_device *ehci;
532 struct usb_endpoint *ep;
533 /** List of all endpoints */
534 struct list_head list;
535 /** Endpoint schedule */
536 struct list_head schedule;
538 /** Transfer descriptor ring */
539 struct ehci_ring ring;
542 extern unsigned int ehci_companion ( struct pci_device *pci );
544 #endif /* _IPXE_EHCI_H */