iPXE
ehci.h
Go to the documentation of this file.
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 */
224  /** First queue head */
226 } __attribute__ (( packed ));
227 
228 /** A transfer descriptor */
230  /** Next transfer descriptor */
232  /** Alternate next transfer descriptor */
234  /** Status */
236  /** Flags */
238  /** Transfer length */
240  /** Buffer pointers (low 32 bits) */
242  /** Extended buffer pointers (high 32 bits) */
244  /** Reserved */
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 */
292  /** Horizontal link pointer */
294  /** Endpoint characteristics */
296  /** Endpoint capabilities */
298  /** Current transfer descriptor */
300  /** 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 */
383  /** Transfer descriptors */
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 */
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 */
508  /** Asynchronous queue head */
510  /** Periodic frame list */
512 
513  /** List of all endpoints */
515  /** Asynchronous schedule */
516  struct list_head async;
517  /** Periodic schedule
518  *
519  * Listed in decreasing order of endpoint interval.
520  */
522 
523  /** USB bus */
524  struct usb_bus *bus;
525 };
526 
527 /** An 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 */
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 */
unsigned int cons
Consumer counter.
Definition: ehci.h:373
#define __attribute__(x)
Definition: compiler.h:10
unsigned short uint16_t
Definition: stdint.h:11
unsigned int ports
Number of ports.
Definition: ehci.h:495
uint32_t high[5]
Extended buffer pointers (high 32 bits)
Definition: ehci.h:243
A transfer descriptor ring.
Definition: ehci.h:369
struct list_head periodic
Periodic schedule.
Definition: ehci.h:521
void * op
Operational registers.
Definition: ehci.h:492
uint32_t ctrldssegment
Control data structure segment.
Definition: ehci.h:507
size_t residual
Residual untransferred data.
Definition: ehci.h:376
uint16_t len
Transfer length.
Definition: ehci.h:239
An EHCI endpoint.
Definition: ehci.h:528
struct usb_bus * bus
USB bus.
Definition: ehci.h:524
uint32_t link
First queue head.
Definition: ehci.h:225
struct list_head schedule
Endpoint schedule.
Definition: ehci.h:536
uint32_t low[5]
Buffer pointers (low 32 bits)
Definition: ehci.h:241
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
uint32_t next
Next transfer descriptor.
Definition: ehci.h:231
An EHCI transfer.
Definition: ehci.h:464
A doubly-linked list entry (or list head)
Definition: list.h:18
struct ehci_queue_head * head
Queue head.
Definition: ehci.h:382
struct ehci_queue_head * head
Asynchronous queue head.
Definition: ehci.h:509
struct io_buffer ** iobuf
I/O buffers.
Definition: ehci.h:379
unsigned int legacy
USB legacy support capability (if present and enabled)
Definition: ehci.h:504
A USB endpoint.
Definition: usb.h:389
uint32_t alt
Alternate next transfer descriptor.
Definition: ehci.h:233
struct ehci_device * ehci
EHCI device.
Definition: ehci.h:530
int addr64
64-bit addressing capability
Definition: ehci.h:497
unsigned int prod
Producer counter.
Definition: ehci.h:371
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
struct usb_endpoint * ep
USB endpoint.
Definition: ehci.h:532
void * cap
Capability registers.
Definition: ehci.h:490
unsigned int flsize
Frame list size.
Definition: ehci.h:499
struct ehci_transfer_descriptor cache
Transfer descriptor cache.
Definition: ehci.h:301
const char * name
Name.
Definition: ehci.h:487
struct ehci_ring ring
Transfer descriptor ring.
Definition: ehci.h:539
A queue head.
Definition: ehci.h:291
uint8_t flags
Flags.
Definition: ehci.h:237
size_t len
Length.
Definition: ehci.h:468
PCI bus.
A PCI device.
Definition: pci.h:187
static unsigned int ehci_ring_remaining(struct ehci_ring *ring)
Calculate space remaining in transfer descriptor ring.
Definition: ehci.h:415
unsigned char uint8_t
Definition: stdint.h:10
A periodic frame list entry.
Definition: ehci.h:223
struct ehci_periodic_frame * frame
Periodic frame list.
Definition: ehci.h:511
unsigned int flags
Flags.
Definition: ehci.h:476
unsigned int uint32_t
Definition: stdint.h:12
unsigned int ehci_companion(struct pci_device *pci)
Locate EHCI companion controller.
Definition: ehci.c:420
uint8_t status
Status.
Definition: ehci.h:235
struct list_head endpoints
List of all endpoints.
Definition: ehci.h:514
uint8_t reserved[12]
Reserved.
Definition: ehci.h:245
Universal Serial Bus (USB)
unsigned int eecp
EHCI extended capabilities offset.
Definition: ehci.h:501
uint32_t link
Horizontal link pointer.
Definition: ehci.h:293
uint8_t fill
Length pair.
Definition: deflate.h:12
A transfer descriptor.
Definition: ehci.h:229
static unsigned int ehci_ring_fill(struct ehci_ring *ring)
Calculate space used in transfer descriptor ring.
Definition: ehci.h:400
uint32_t cap
Endpoint capabilities.
Definition: ehci.h:297
uint32_t current
Current transfer descriptor.
Definition: ehci.h:299
void * regs
Registers.
Definition: ehci.h:485
void * data
Data buffer.
Definition: ehci.h:466
struct list_head async
Asynchronous schedule.
Definition: ehci.h:516
#define EHCI_RING_COUNT
Number of transfer descriptors in a ring.
Definition: ehci.h:391
struct list_head list
List of all endpoints.
Definition: ehci.h:534
A USB bus.
Definition: usb.h:949
struct ehci_transfer_descriptor * desc
Transfer descriptors.
Definition: ehci.h:384
uint32_t chr
Endpoint characteristics.
Definition: ehci.h:295
An EHCI device.
Definition: ehci.h:483
A persistent I/O buffer.
Definition: iobuf.h:32