[pci] Add support for PCI MSI-X interrupts
[ipxe.git] / 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 */