[efi] Add a USB host controller driver based on EFI_USB_IO_PROTOCOL
[ipxe.git] / src / include / ipxe / usb.h
1 #ifndef _IPXE_USB_H
2 #define _IPXE_USB_H
3
4 /** @file
5 *
6 * Universal Serial Bus (USB)
7 *
8 */
9
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11
12 #include <byteswap.h>
13 #include <ipxe/list.h>
14 #include <ipxe/device.h>
15 #include <ipxe/process.h>
16 #include <ipxe/iobuf.h>
17 #include <ipxe/tables.h>
18
19 /** USB protocols */
20 enum usb_protocol {
21 /** USB 2.0 */
22 USB_PROTO_2_0 = 0x0200,
23 /** USB 3.0 */
24 USB_PROTO_3_0 = 0x0300,
25 /** USB 3.1 */
26 USB_PROTO_3_1 = 0x0301,
27 };
28
29 /** Define a USB speed
30 *
31 * @v mantissa Mantissa
32 * @v exponent Exponent (in engineering terms: 1=k, 2=M, 3=G)
33 * @ret speed USB speed
34 */
35 #define USB_SPEED( mantissa, exponent ) ( (exponent << 16) | (mantissa) )
36
37 /** Extract USB speed mantissa */
38 #define USB_SPEED_MANTISSA(speed) ( (speed) & 0xffff )
39
40 /** Extract USB speed exponent */
41 #define USB_SPEED_EXPONENT(speed) ( ( (speed) >> 16 ) & 0x3 )
42
43 /** USB device speeds */
44 enum usb_speed {
45 /** Not connected */
46 USB_SPEED_NONE = 0,
47 /** Low speed (1.5Mbps) */
48 USB_SPEED_LOW = USB_SPEED ( 1500, 1 ),
49 /** Full speed (12Mbps) */
50 USB_SPEED_FULL = USB_SPEED ( 12, 2 ),
51 /** High speed (480Mbps) */
52 USB_SPEED_HIGH = USB_SPEED ( 480, 2 ),
53 /** Super speed (5Gbps) */
54 USB_SPEED_SUPER = USB_SPEED ( 5, 3 ),
55 };
56
57 /** USB packet IDs */
58 enum usb_pid {
59 /** IN PID */
60 USB_PID_IN = 0x69,
61 /** OUT PID */
62 USB_PID_OUT = 0xe1,
63 /** SETUP PID */
64 USB_PID_SETUP = 0x2d,
65 };
66
67 /** A USB setup data packet */
68 struct usb_setup_packet {
69 /** Request */
70 uint16_t request;
71 /** Value parameter */
72 uint16_t value;
73 /** Index parameter */
74 uint16_t index;
75 /** Length of data stage */
76 uint16_t len;
77 } __attribute__ (( packed ));
78
79 /** Data transfer is from host to device */
80 #define USB_DIR_OUT ( 0 << 7 )
81
82 /** Data transfer is from device to host */
83 #define USB_DIR_IN ( 1 << 7 )
84
85 /** Standard request type */
86 #define USB_TYPE_STANDARD ( 0 << 5 )
87
88 /** Class-specific request type */
89 #define USB_TYPE_CLASS ( 1 << 5 )
90
91 /** Vendor-specific request type */
92 #define USB_TYPE_VENDOR ( 2 << 5 )
93
94 /** Request recipient mask */
95 #define USB_RECIP_MASK ( 0x1f << 0 )
96
97 /** Request recipient is the device */
98 #define USB_RECIP_DEVICE ( 0 << 0 )
99
100 /** Request recipient is an interface */
101 #define USB_RECIP_INTERFACE ( 1 << 0 )
102
103 /** Request recipient is an endpoint */
104 #define USB_RECIP_ENDPOINT ( 2 << 0 )
105
106 /** Construct USB request type */
107 #define USB_REQUEST_TYPE(type) ( (type) << 8 )
108
109 /** Get status */
110 #define USB_GET_STATUS ( USB_DIR_IN | USB_REQUEST_TYPE ( 0 ) )
111
112 /** Clear feature */
113 #define USB_CLEAR_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 1 ) )
114
115 /** Set feature */
116 #define USB_SET_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 3 ) )
117
118 /** Set address */
119 #define USB_SET_ADDRESS ( USB_DIR_OUT | USB_REQUEST_TYPE ( 5 ) )
120
121 /** Get descriptor */
122 #define USB_GET_DESCRIPTOR ( USB_DIR_IN | USB_REQUEST_TYPE ( 6 ) )
123
124 /** Set descriptor */
125 #define USB_SET_DESCRIPTOR ( USB_DIR_OUT | USB_REQUEST_TYPE ( 7 ) )
126
127 /** Get configuration */
128 #define USB_GET_CONFIGURATION ( USB_DIR_IN | USB_REQUEST_TYPE ( 8 ) )
129
130 /** Set configuration */
131 #define USB_SET_CONFIGURATION ( USB_DIR_OUT | USB_REQUEST_TYPE ( 9 ) )
132
133 /** Get interface */
134 #define USB_GET_INTERFACE \
135 ( USB_DIR_IN | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 10 ) )
136
137 /** Set interface */
138 #define USB_SET_INTERFACE \
139 ( USB_DIR_OUT | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 11 ) )
140
141 /** Endpoint halt feature */
142 #define USB_ENDPOINT_HALT 0
143
144 /** A USB class code tuple */
145 struct usb_class {
146 /** Class code */
147 uint8_t class;
148 /** Subclass code */
149 uint8_t subclass;
150 /** Protocol code */
151 uint8_t protocol;
152 } __attribute__ (( packed ));
153
154 /** Class code for USB hubs */
155 #define USB_CLASS_HUB 9
156
157 /** A USB descriptor header */
158 struct usb_descriptor_header {
159 /** Length of descriptor */
160 uint8_t len;
161 /** Descriptor type */
162 uint8_t type;
163 } __attribute__ (( packed ));
164
165 /** A USB device descriptor */
166 struct usb_device_descriptor {
167 /** Descriptor header */
168 struct usb_descriptor_header header;
169 /** USB specification release number in BCD */
170 uint16_t protocol;
171 /** Device class */
172 struct usb_class class;
173 /** Maximum packet size for endpoint zero */
174 uint8_t mtu;
175 /** Vendor ID */
176 uint16_t vendor;
177 /** Product ID */
178 uint16_t product;
179 /** Device release number in BCD */
180 uint16_t release;
181 /** Manufacturer string */
182 uint8_t manufacturer;
183 /** Product string */
184 uint8_t name;
185 /** Serial number string */
186 uint8_t serial;
187 /** Number of possible configurations */
188 uint8_t configurations;
189 } __attribute__ (( packed ));
190
191 /** A USB device descriptor */
192 #define USB_DEVICE_DESCRIPTOR 1
193
194 /** A USB configuration descriptor */
195 struct usb_configuration_descriptor {
196 /** Descriptor header */
197 struct usb_descriptor_header header;
198 /** Total length */
199 uint16_t len;
200 /** Number of interfaces */
201 uint8_t interfaces;
202 /** Configuration value */
203 uint8_t config;
204 /** Configuration string */
205 uint8_t name;
206 /** Attributes */
207 uint8_t attributes;
208 /** Maximum power consumption */
209 uint8_t power;
210 } __attribute__ (( packed ));
211
212 /** A USB configuration descriptor */
213 #define USB_CONFIGURATION_DESCRIPTOR 2
214
215 /** A USB string descriptor */
216 struct usb_string_descriptor {
217 /** Descriptor header */
218 struct usb_descriptor_header header;
219 /** String */
220 char string[0];
221 } __attribute__ (( packed ));
222
223 /** A USB string descriptor */
224 #define USB_STRING_DESCRIPTOR 3
225
226 /** A USB interface descriptor */
227 struct usb_interface_descriptor {
228 /** Descriptor header */
229 struct usb_descriptor_header header;
230 /** Interface number */
231 uint8_t interface;
232 /** Alternate setting */
233 uint8_t alternate;
234 /** Number of endpoints */
235 uint8_t endpoints;
236 /** Interface class */
237 struct usb_class class;
238 /** Interface name */
239 uint8_t name;
240 } __attribute__ (( packed ));
241
242 /** A USB interface descriptor */
243 #define USB_INTERFACE_DESCRIPTOR 4
244
245 /** A USB endpoint descriptor */
246 struct usb_endpoint_descriptor {
247 /** Descriptor header */
248 struct usb_descriptor_header header;
249 /** Endpoint address */
250 uint8_t endpoint;
251 /** Attributes */
252 uint8_t attributes;
253 /** Maximum packet size and burst size */
254 uint16_t sizes;
255 /** Polling interval */
256 uint8_t interval;
257 } __attribute__ (( packed ));
258
259 /** A USB endpoint descriptor */
260 #define USB_ENDPOINT_DESCRIPTOR 5
261
262 /** Endpoint attribute transfer type mask */
263 #define USB_ENDPOINT_ATTR_TYPE_MASK 0x03
264
265 /** Endpoint periodic type */
266 #define USB_ENDPOINT_ATTR_PERIODIC 0x01
267
268 /** Control endpoint transfer type */
269 #define USB_ENDPOINT_ATTR_CONTROL 0x00
270
271 /** Bulk endpoint transfer type */
272 #define USB_ENDPOINT_ATTR_BULK 0x02
273
274 /** Interrupt endpoint transfer type */
275 #define USB_ENDPOINT_ATTR_INTERRUPT 0x03
276
277 /** Bulk OUT endpoint (internal) type */
278 #define USB_BULK_OUT ( USB_ENDPOINT_ATTR_BULK | USB_DIR_OUT )
279
280 /** Bulk IN endpoint (internal) type */
281 #define USB_BULK_IN ( USB_ENDPOINT_ATTR_BULK | USB_DIR_IN )
282
283 /** Interrupt IN endpoint (internal) type */
284 #define USB_INTERRUPT_IN ( USB_ENDPOINT_ATTR_INTERRUPT | USB_DIR_IN )
285
286 /** Interrupt OUT endpoint (internal) type */
287 #define USB_INTERRUPT_OUT ( USB_ENDPOINT_ATTR_INTERRUPT | USB_DIR_OUT )
288
289 /** USB endpoint MTU */
290 #define USB_ENDPOINT_MTU(sizes) ( ( (sizes) >> 0 ) & 0x07ff )
291
292 /** USB endpoint maximum burst size */
293 #define USB_ENDPOINT_BURST(sizes) ( ( (sizes) >> 11 ) & 0x0003 )
294
295 /** A USB endpoint companion descriptor */
296 struct usb_endpoint_companion_descriptor {
297 /** Descriptor header */
298 struct usb_descriptor_header header;
299 /** Maximum burst size */
300 uint8_t burst;
301 /** Extended attributes */
302 uint8_t extended;
303 /** Number of bytes per service interval */
304 uint16_t periodic;
305 } __attribute__ (( packed ));
306
307 /** A USB endpoint companion descriptor */
308 #define USB_ENDPOINT_COMPANION_DESCRIPTOR 48
309
310 /** A USB interface association descriptor */
311 struct usb_interface_association_descriptor {
312 /** Descriptor header */
313 struct usb_descriptor_header header;
314 /** First interface number */
315 uint8_t first;
316 /** Interface count */
317 uint8_t count;
318 /** Association class */
319 struct usb_class class;
320 /** Association name */
321 uint8_t name;
322 } __attribute__ (( packed ));
323
324 /** A USB interface association descriptor */
325 #define USB_INTERFACE_ASSOCIATION_DESCRIPTOR 11
326
327 /** A class-specific interface descriptor */
328 #define USB_CS_INTERFACE_DESCRIPTOR 36
329
330 /** A class-specific endpoint descriptor */
331 #define USB_CS_ENDPOINT_DESCRIPTOR 37
332
333 /**
334 * Get next USB descriptor
335 *
336 * @v desc USB descriptor header
337 * @ret next Next USB descriptor header
338 */
339 static inline __attribute__ (( always_inline )) struct usb_descriptor_header *
340 usb_next_descriptor ( struct usb_descriptor_header *desc ) {
341
342 return ( ( ( void * ) desc ) + desc->len );
343 }
344
345 /**
346 * Check that descriptor lies within a configuration descriptor
347 *
348 * @v config Configuration descriptor
349 * @v desc Descriptor header
350 * @v is_within Descriptor is within the configuration descriptor
351 */
352 static inline __attribute__ (( always_inline )) int
353 usb_is_within_config ( struct usb_configuration_descriptor *config,
354 struct usb_descriptor_header *desc ) {
355 struct usb_descriptor_header *end =
356 ( ( ( void * ) config ) + le16_to_cpu ( config->len ) );
357
358 /* Check that descriptor starts within the configuration
359 * descriptor, and that the length does not exceed the
360 * configuration descriptor. This relies on the fact that
361 * usb_next_descriptor() needs to access only the first byte
362 * of the descriptor in order to determine the length.
363 */
364 return ( ( desc < end ) && ( usb_next_descriptor ( desc ) <= end ) );
365 }
366
367 /** Iterate over all configuration descriptors */
368 #define for_each_config_descriptor( desc, config ) \
369 for ( desc = container_of ( &(config)->header, \
370 typeof ( *desc ), header ) ; \
371 usb_is_within_config ( (config), &desc->header ) ; \
372 desc = container_of ( usb_next_descriptor ( &desc->header ), \
373 typeof ( *desc ), header ) )
374
375 /** Iterate over all configuration descriptors within an interface descriptor */
376 #define for_each_interface_descriptor( desc, config, interface ) \
377 for ( desc = container_of ( usb_next_descriptor ( &(interface)-> \
378 header ), \
379 typeof ( *desc ), header ) ; \
380 ( usb_is_within_config ( (config), &desc->header ) && \
381 ( desc->header.type != USB_INTERFACE_DESCRIPTOR ) ) ; \
382 desc = container_of ( usb_next_descriptor ( &desc->header ), \
383 typeof ( *desc ), header ) )
384
385 /** A USB endpoint */
386 struct usb_endpoint {
387 /** USB device */
388 struct usb_device *usb;
389 /** Endpoint address */
390 unsigned int address;
391 /** Attributes */
392 unsigned int attributes;
393 /** Maximum transfer size */
394 size_t mtu;
395 /** Maximum burst size */
396 unsigned int burst;
397 /** Interval (in microframes) */
398 unsigned int interval;
399
400 /** Endpoint is open */
401 int open;
402 /** Buffer fill level */
403 unsigned int fill;
404
405 /** List of halted endpoints */
406 struct list_head halted;
407
408 /** Host controller operations */
409 struct usb_endpoint_host_operations *host;
410 /** Host controller private data */
411 void *priv;
412 /** Driver operations */
413 struct usb_endpoint_driver_operations *driver;
414
415 /** Recycled I/O buffer list */
416 struct list_head recycled;
417 /** Refill buffer length */
418 size_t len;
419 /** Maximum fill level */
420 unsigned int max;
421 };
422
423 /** USB endpoint host controller operations */
424 struct usb_endpoint_host_operations {
425 /** Open endpoint
426 *
427 * @v ep USB endpoint
428 * @ret rc Return status code
429 */
430 int ( * open ) ( struct usb_endpoint *ep );
431 /** Close endpoint
432 *
433 * @v ep USB endpoint
434 */
435 void ( * close ) ( struct usb_endpoint *ep );
436 /**
437 * Reset endpoint
438 *
439 * @v ep USB endpoint
440 * @ret rc Return status code
441 */
442 int ( * reset ) ( struct usb_endpoint *ep );
443 /** Update MTU
444 *
445 * @v ep USB endpoint
446 * @ret rc Return status code
447 */
448 int ( * mtu ) ( struct usb_endpoint *ep );
449 /** Enqueue message transfer
450 *
451 * @v ep USB endpoint
452 * @v iobuf I/O buffer
453 * @ret rc Return status code
454 */
455 int ( * message ) ( struct usb_endpoint *ep,
456 struct io_buffer *iobuf );
457 /** Enqueue stream transfer
458 *
459 * @v ep USB endpoint
460 * @v iobuf I/O buffer
461 * @v terminate Terminate using a short packet
462 * @ret rc Return status code
463 */
464 int ( * stream ) ( struct usb_endpoint *ep, struct io_buffer *iobuf,
465 int terminate );
466 };
467
468 /** USB endpoint driver operations */
469 struct usb_endpoint_driver_operations {
470 /** Complete transfer
471 *
472 * @v ep USB endpoint
473 * @v iobuf I/O buffer
474 * @v rc Completion status code
475 */
476 void ( * complete ) ( struct usb_endpoint *ep,
477 struct io_buffer *iobuf, int rc );
478 };
479
480 /** Control endpoint address */
481 #define USB_EP0_ADDRESS 0x00
482
483 /** Control endpoint attributes */
484 #define USB_EP0_ATTRIBUTES 0x00
485
486 /** Calculate default MTU based on device speed
487 *
488 * @v speed Device speed
489 * @ret mtu Default MTU
490 */
491 #define USB_EP0_DEFAULT_MTU(speed) \
492 ( ( (speed) >= USB_SPEED_SUPER ) ? 512 : \
493 ( ( (speed) >= USB_SPEED_FULL ) ? 64 : 8 ) )
494
495 /** Control endpoint maximum burst size */
496 #define USB_EP0_BURST 0
497
498 /** Control endpoint interval */
499 #define USB_EP0_INTERVAL 0
500
501 /** Maximum endpoint number */
502 #define USB_ENDPOINT_MAX 0x0f
503
504 /** Endpoint direction is in */
505 #define USB_ENDPOINT_IN 0x80
506
507 /** Construct endpoint index from endpoint address */
508 #define USB_ENDPOINT_IDX(address) \
509 ( ( (address) & USB_ENDPOINT_MAX ) | \
510 ( ( (address) & USB_ENDPOINT_IN ) >> 3 ) )
511
512 /**
513 * Initialise USB endpoint
514 *
515 * @v ep USB endpoint
516 * @v usb USB device
517 * @v driver Driver operations
518 */
519 static inline __attribute__ (( always_inline )) void
520 usb_endpoint_init ( struct usb_endpoint *ep, struct usb_device *usb,
521 struct usb_endpoint_driver_operations *driver ) {
522
523 ep->usb = usb;
524 ep->driver = driver;
525 }
526
527 /**
528 * Describe USB endpoint
529 *
530 * @v ep USB endpoint
531 * @v address Endpoint address
532 * @v attributes Attributes
533 * @v mtu Maximum packet size
534 * @v burst Maximum burst size
535 * @v interval Interval (in microframes)
536 */
537 static inline __attribute__ (( always_inline )) void
538 usb_endpoint_describe ( struct usb_endpoint *ep, unsigned int address,
539 unsigned int attributes, size_t mtu,
540 unsigned int burst, unsigned int interval ) {
541
542 ep->address = address;
543 ep->attributes = attributes;
544 ep->mtu = mtu;
545 ep->burst = burst;
546 ep->interval = interval;
547 }
548
549 /**
550 * Set USB endpoint host controller private data
551 *
552 * @v ep USB endpoint
553 * @v priv Host controller private data
554 */
555 static inline __attribute__ (( always_inline )) void
556 usb_endpoint_set_hostdata ( struct usb_endpoint *ep, void *priv ) {
557 ep->priv = priv;
558 }
559
560 /**
561 * Get USB endpoint host controller private data
562 *
563 * @v ep USB endpoint
564 * @ret priv Host controller private data
565 */
566 static inline __attribute__ (( always_inline )) void *
567 usb_endpoint_get_hostdata ( struct usb_endpoint *ep ) {
568 return ep->priv;
569 }
570
571 extern const char * usb_endpoint_name ( struct usb_endpoint *ep );
572 extern int
573 usb_endpoint_described ( struct usb_endpoint *ep,
574 struct usb_configuration_descriptor *config,
575 struct usb_interface_descriptor *interface,
576 unsigned int type, unsigned int index );
577 extern int usb_endpoint_open ( struct usb_endpoint *ep );
578 extern void usb_endpoint_close ( struct usb_endpoint *ep );
579 extern int usb_message ( struct usb_endpoint *ep, unsigned int request,
580 unsigned int value, unsigned int index,
581 struct io_buffer *iobuf );
582 extern int usb_stream ( struct usb_endpoint *ep, struct io_buffer *iobuf,
583 int terminate );
584 extern void usb_complete_err ( struct usb_endpoint *ep,
585 struct io_buffer *iobuf, int rc );
586
587 /**
588 * Initialise USB endpoint refill
589 *
590 * @v ep USB endpoint
591 * @v len Refill buffer length (or zero to use endpoint's MTU)
592 * @v max Maximum fill level
593 */
594 static inline __attribute__ (( always_inline )) void
595 usb_refill_init ( struct usb_endpoint *ep, size_t len, unsigned int max ) {
596
597 INIT_LIST_HEAD ( &ep->recycled );
598 ep->len = len;
599 ep->max = max;
600 }
601
602 /**
603 * Recycle I/O buffer
604 *
605 * @v ep USB endpoint
606 * @v iobuf I/O buffer
607 */
608 static inline __attribute__ (( always_inline )) void
609 usb_recycle ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
610
611 list_add_tail ( &iobuf->list, &ep->recycled );
612 }
613
614 extern int usb_prefill ( struct usb_endpoint *ep );
615 extern int usb_refill ( struct usb_endpoint *ep );
616 extern void usb_flush ( struct usb_endpoint *ep );
617
618 /**
619 * A USB function
620 *
621 * A USB function represents an association of interfaces within a USB
622 * device.
623 */
624 struct usb_function {
625 /** Name */
626 const char *name;
627 /** USB device */
628 struct usb_device *usb;
629 /** Class */
630 struct usb_class class;
631 /** Number of interfaces */
632 unsigned int count;
633 /** Generic device */
634 struct device dev;
635 /** List of functions within this USB device */
636 struct list_head list;
637
638 /** Driver */
639 struct usb_driver *driver;
640 /** Driver private data */
641 void *priv;
642
643 /** List of interface numbers
644 *
645 * This must be the last field within the structure.
646 */
647 uint8_t interface[0];
648 };
649
650 /**
651 * Set USB function driver private data
652 *
653 * @v func USB function
654 * @v priv Driver private data
655 */
656 static inline __attribute__ (( always_inline )) void
657 usb_func_set_drvdata ( struct usb_function *func, void *priv ) {
658 func->priv = priv;
659 }
660
661 /**
662 * Get USB function driver private data
663 *
664 * @v function USB function
665 * @ret priv Driver private data
666 */
667 static inline __attribute__ (( always_inline )) void *
668 usb_func_get_drvdata ( struct usb_function *func ) {
669 return func->priv;
670 }
671
672 /** A USB device */
673 struct usb_device {
674 /** Name */
675 char name[32];
676 /** USB port */
677 struct usb_port *port;
678 /** List of devices on this bus */
679 struct list_head list;
680 /** Device address, if assigned */
681 unsigned int address;
682 /** Device descriptor */
683 struct usb_device_descriptor device;
684 /** List of functions */
685 struct list_head functions;
686
687 /** Host controller operations */
688 struct usb_device_host_operations *host;
689 /** Host controller private data */
690 void *priv;
691
692 /** Endpoint list */
693 struct usb_endpoint *ep[32];
694
695 /** Control endpoint */
696 struct usb_endpoint control;
697 /** Completed control transfers */
698 struct list_head complete;
699 };
700
701 /** USB device host controller operations */
702 struct usb_device_host_operations {
703 /** Open device
704 *
705 * @v usb USB device
706 * @ret rc Return status code
707 */
708 int ( * open ) ( struct usb_device *usb );
709 /** Close device
710 *
711 * @v usb USB device
712 */
713 void ( * close ) ( struct usb_device *usb );
714 /** Assign device address
715 *
716 * @v usb USB device
717 * @ret rc Return status code
718 */
719 int ( * address ) ( struct usb_device *usb );
720 };
721
722 /**
723 * Set USB device host controller private data
724 *
725 * @v usb USB device
726 * @v priv Host controller private data
727 */
728 static inline __attribute__ (( always_inline )) void
729 usb_set_hostdata ( struct usb_device *usb, void *priv ) {
730 usb->priv = priv;
731 }
732
733 /**
734 * Get USB device host controller private data
735 *
736 * @v usb USB device
737 * @ret priv Host controller private data
738 */
739 static inline __attribute__ (( always_inline )) void *
740 usb_get_hostdata ( struct usb_device *usb ) {
741 return usb->priv;
742 }
743
744 /**
745 * Get USB endpoint
746 *
747 * @v usb USB device
748 * @v address Endpoint address
749 * @ret ep USB endpoint, or NULL if not opened
750 */
751 static inline struct usb_endpoint * usb_endpoint ( struct usb_device *usb,
752 unsigned int address ) {
753
754 return usb->ep[ USB_ENDPOINT_IDX ( address ) ];
755 }
756
757 /** A USB port */
758 struct usb_port {
759 /** USB hub */
760 struct usb_hub *hub;
761 /** Port address */
762 unsigned int address;
763 /** Port protocol */
764 unsigned int protocol;
765 /** Port speed */
766 unsigned int speed;
767 /** Port disconnection has been detected
768 *
769 * This should be set whenever the underlying hardware reports
770 * a connection status change.
771 */
772 int disconnected;
773 /** Port has an attached device */
774 int attached;
775 /** Currently attached device (if in use)
776 *
777 * Note that this field will be NULL if the attached device
778 * has been freed (e.g. because there were no drivers found).
779 */
780 struct usb_device *usb;
781 /** List of changed ports */
782 struct list_head changed;
783 };
784
785 /** A USB hub */
786 struct usb_hub {
787 /** Name */
788 const char *name;
789 /** USB bus */
790 struct usb_bus *bus;
791 /** Underlying USB device, if any */
792 struct usb_device *usb;
793 /** Hub protocol */
794 unsigned int protocol;
795 /** Number of ports */
796 unsigned int ports;
797
798 /** List of hubs */
799 struct list_head list;
800
801 /** Host controller operations */
802 struct usb_hub_host_operations *host;
803 /** Driver operations */
804 struct usb_hub_driver_operations *driver;
805 /** Driver private data */
806 void *priv;
807
808 /** Port list
809 *
810 * This must be the last field within the structure.
811 */
812 struct usb_port port[0];
813 };
814
815 /** USB hub host controller operations */
816 struct usb_hub_host_operations {
817 /** Open hub
818 *
819 * @v hub USB hub
820 * @ret rc Return status code
821 */
822 int ( * open ) ( struct usb_hub *hub );
823 /** Close hub
824 *
825 * @v hub USB hub
826 */
827 void ( * close ) ( struct usb_hub *hub );
828 };
829
830 /** USB hub driver operations */
831 struct usb_hub_driver_operations {
832 /** Open hub
833 *
834 * @v hub USB hub
835 * @ret rc Return status code
836 */
837 int ( * open ) ( struct usb_hub *hub );
838 /** Close hub
839 *
840 * @v hub USB hub
841 */
842 void ( * close ) ( struct usb_hub *hub );
843 /** Enable port
844 *
845 * @v hub USB hub
846 * @v port USB port
847 * @ret rc Return status code
848 */
849 int ( * enable ) ( struct usb_hub *hub, struct usb_port *port );
850 /** Disable port
851 *
852 * @v hub USB hub
853 * @v port USB port
854 * @ret rc Return status code
855 */
856 int ( * disable ) ( struct usb_hub *hub, struct usb_port *port );
857 /** Update port speed
858 *
859 * @v hub USB hub
860 * @v port USB port
861 * @ret rc Return status code
862 */
863 int ( * speed ) ( struct usb_hub *hub, struct usb_port *port );
864 /** Clear transaction translator buffer
865 *
866 * @v hub USB hub
867 * @v port USB port
868 * @v ep USB endpoint
869 * @ret rc Return status code
870 */
871 int ( * clear_tt ) ( struct usb_hub *hub, struct usb_port *port,
872 struct usb_endpoint *ep );
873 };
874
875 /**
876 * Set USB hub driver private data
877 *
878 * @v hub USB hub
879 * @v priv Driver private data
880 */
881 static inline __attribute__ (( always_inline )) void
882 usb_hub_set_drvdata ( struct usb_hub *hub, void *priv ) {
883 hub->priv = priv;
884 }
885
886 /**
887 * Get USB hub driver private data
888 *
889 * @v hub USB hub
890 * @ret priv Driver private data
891 */
892 static inline __attribute__ (( always_inline )) void *
893 usb_hub_get_drvdata ( struct usb_hub *hub ) {
894 return hub->priv;
895 }
896
897 /**
898 * Get USB port
899 *
900 * @v hub USB hub
901 * @v address Port address
902 * @ret port USB port
903 */
904 static inline __attribute__ (( always_inline )) struct usb_port *
905 usb_port ( struct usb_hub *hub, unsigned int address ) {
906
907 return &hub->port[ address - 1 ];
908 }
909
910 /** A USB bus */
911 struct usb_bus {
912 /** Name */
913 const char *name;
914 /** Underlying hardware device */
915 struct device *dev;
916 /** Host controller operations set */
917 struct usb_host_operations *op;
918
919 /** Largest transfer allowed on the bus */
920 size_t mtu;
921 /** Address in-use mask
922 *
923 * This is used only by buses which perform manual address
924 * assignment. USB allows for addresses in the range [1,127].
925 * We use a simple bitmask which restricts us to the range
926 * [1,64]; this is unlikely to be a problem in practice. For
927 * comparison: controllers which perform autonomous address
928 * assignment (such as xHCI) typically allow for only 32
929 * devices per bus anyway.
930 */
931 unsigned long long addresses;
932
933 /** Root hub */
934 struct usb_hub *hub;
935
936 /** List of USB buses */
937 struct list_head list;
938 /** List of devices */
939 struct list_head devices;
940 /** List of hubs */
941 struct list_head hubs;
942
943 /** Host controller operations */
944 struct usb_bus_host_operations *host;
945 /** Host controller private data */
946 void *priv;
947 };
948
949 /** USB bus host controller operations */
950 struct usb_bus_host_operations {
951 /** Open bus
952 *
953 * @v bus USB bus
954 * @ret rc Return status code
955 */
956 int ( * open ) ( struct usb_bus *bus );
957 /** Close bus
958 *
959 * @v bus USB bus
960 */
961 void ( * close ) ( struct usb_bus *bus );
962 /** Poll bus
963 *
964 * @v bus USB bus
965 */
966 void ( * poll ) ( struct usb_bus *bus );
967 };
968
969 /** USB host controller operations */
970 struct usb_host_operations {
971 /** Endpoint operations */
972 struct usb_endpoint_host_operations endpoint;
973 /** Device operations */
974 struct usb_device_host_operations device;
975 /** Bus operations */
976 struct usb_bus_host_operations bus;
977 /** Hub operations */
978 struct usb_hub_host_operations hub;
979 /** Root hub operations */
980 struct usb_hub_driver_operations root;
981 };
982
983 /**
984 * Set USB bus host controller private data
985 *
986 * @v bus USB bus
987 * @v priv Host controller private data
988 */
989 static inline __attribute__ (( always_inline )) void
990 usb_bus_set_hostdata ( struct usb_bus *bus, void *priv ) {
991 bus->priv = priv;
992 }
993
994 /**
995 * Get USB bus host controller private data
996 *
997 * @v bus USB bus
998 * @ret priv Host controller private data
999 */
1000 static inline __attribute__ (( always_inline )) void *
1001 usb_bus_get_hostdata ( struct usb_bus *bus ) {
1002 return bus->priv;
1003 }
1004
1005 /**
1006 * Poll USB bus
1007 *
1008 * @v bus USB bus
1009 */
1010 static inline __attribute__ (( always_inline )) void
1011 usb_poll ( struct usb_bus *bus ) {
1012 bus->host->poll ( bus );
1013 }
1014
1015 /** Iterate over all USB buses */
1016 #define for_each_usb_bus( bus ) \
1017 list_for_each_entry ( (bus), &usb_buses, list )
1018
1019 /**
1020 * Complete transfer (without error)
1021 *
1022 * @v ep USB endpoint
1023 * @v iobuf I/O buffer
1024 */
1025 static inline __attribute__ (( always_inline )) void
1026 usb_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
1027 usb_complete_err ( ep, iobuf, 0 );
1028 }
1029
1030 extern int usb_control ( struct usb_device *usb, unsigned int request,
1031 unsigned int value, unsigned int index, void *data,
1032 size_t len );
1033 extern int usb_get_string_descriptor ( struct usb_device *usb,
1034 unsigned int index,
1035 unsigned int language,
1036 char *buf, size_t len );
1037
1038 /**
1039 * Get status
1040 *
1041 * @v usb USB device
1042 * @v type Request type
1043 * @v index Target index
1044 * @v data Status to fill in
1045 * @v len Length of status descriptor
1046 * @ret rc Return status code
1047 */
1048 static inline __attribute__ (( always_inline )) int
1049 usb_get_status ( struct usb_device *usb, unsigned int type, unsigned int index,
1050 void *data, size_t len ) {
1051
1052 return usb_control ( usb, ( USB_GET_STATUS | type ), 0, index,
1053 data, len );
1054 }
1055
1056 /**
1057 * Clear feature
1058 *
1059 * @v usb USB device
1060 * @v type Request type
1061 * @v feature Feature selector
1062 * @v index Target index
1063 * @ret rc Return status code
1064 */
1065 static inline __attribute__ (( always_inline )) int
1066 usb_clear_feature ( struct usb_device *usb, unsigned int type,
1067 unsigned int feature, unsigned int index ) {
1068
1069 return usb_control ( usb, ( USB_CLEAR_FEATURE | type ),
1070 feature, index, NULL, 0 );
1071 }
1072
1073 /**
1074 * Set feature
1075 *
1076 * @v usb USB device
1077 * @v type Request type
1078 * @v feature Feature selector
1079 * @v index Target index
1080 * @ret rc Return status code
1081 */
1082 static inline __attribute__ (( always_inline )) int
1083 usb_set_feature ( struct usb_device *usb, unsigned int type,
1084 unsigned int feature, unsigned int index ) {
1085
1086 return usb_control ( usb, ( USB_SET_FEATURE | type ),
1087 feature, index, NULL, 0 );
1088 }
1089
1090 /**
1091 * Set address
1092 *
1093 * @v usb USB device
1094 * @v address Device address
1095 * @ret rc Return status code
1096 */
1097 static inline __attribute__ (( always_inline )) int
1098 usb_set_address ( struct usb_device *usb, unsigned int address ) {
1099
1100 return usb_control ( usb, USB_SET_ADDRESS, address, 0, NULL, 0 );
1101 }
1102
1103 /**
1104 * Get USB descriptor
1105 *
1106 * @v usb USB device
1107 * @v type Request type
1108 * @v desc Descriptor type
1109 * @v index Descriptor index
1110 * @v language Language ID (for string descriptors)
1111 * @v data Descriptor to fill in
1112 * @v len Maximum length of descriptor
1113 * @ret rc Return status code
1114 */
1115 static inline __attribute__ (( always_inline )) int
1116 usb_get_descriptor ( struct usb_device *usb, unsigned int type,
1117 unsigned int desc, unsigned int index,
1118 unsigned int language, struct usb_descriptor_header *data,
1119 size_t len ) {
1120
1121 return usb_control ( usb, ( USB_GET_DESCRIPTOR | type ),
1122 ( ( desc << 8 ) | index ), language, data, len );
1123 }
1124
1125 /**
1126 * Get first part of USB device descriptor (up to and including MTU)
1127 *
1128 * @v usb USB device
1129 * @v data Device descriptor to (partially) fill in
1130 * @ret rc Return status code
1131 */
1132 static inline __attribute__ (( always_inline )) int
1133 usb_get_mtu ( struct usb_device *usb, struct usb_device_descriptor *data ) {
1134
1135 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1136 &data->header,
1137 ( offsetof ( typeof ( *data ), mtu ) +
1138 sizeof ( data->mtu ) ) );
1139 }
1140
1141 /**
1142 * Get USB device descriptor
1143 *
1144 * @v usb USB device
1145 * @v data Device descriptor to fill in
1146 * @ret rc Return status code
1147 */
1148 static inline __attribute__ (( always_inline )) int
1149 usb_get_device_descriptor ( struct usb_device *usb,
1150 struct usb_device_descriptor *data ) {
1151
1152 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1153 &data->header, sizeof ( *data ) );
1154 }
1155
1156 /**
1157 * Get USB configuration descriptor
1158 *
1159 * @v usb USB device
1160 * @v index Configuration index
1161 * @v data Configuration descriptor to fill in
1162 * @ret rc Return status code
1163 */
1164 static inline __attribute (( always_inline )) int
1165 usb_get_config_descriptor ( struct usb_device *usb, unsigned int index,
1166 struct usb_configuration_descriptor *data,
1167 size_t len ) {
1168
1169 return usb_get_descriptor ( usb, 0, USB_CONFIGURATION_DESCRIPTOR, index,
1170 0, &data->header, len );
1171 }
1172
1173 /**
1174 * Set USB configuration
1175 *
1176 * @v usb USB device
1177 * @v index Configuration index
1178 * @ret rc Return status code
1179 */
1180 static inline __attribute__ (( always_inline )) int
1181 usb_set_configuration ( struct usb_device *usb, unsigned int index ) {
1182
1183 return usb_control ( usb, USB_SET_CONFIGURATION, index, 0, NULL, 0 );
1184 }
1185
1186 /**
1187 * Set USB interface alternate setting
1188 *
1189 * @v usb USB device
1190 * @v interface Interface number
1191 * @v alternate Alternate setting
1192 * @ret rc Return status code
1193 */
1194 static inline __attribute__ (( always_inline )) int
1195 usb_set_interface ( struct usb_device *usb, unsigned int interface,
1196 unsigned int alternate ) {
1197
1198 return usb_control ( usb, USB_SET_INTERFACE, alternate, interface,
1199 NULL, 0 );
1200 }
1201
1202 extern struct list_head usb_buses;
1203
1204 extern struct usb_interface_descriptor *
1205 usb_interface_descriptor ( struct usb_configuration_descriptor *config,
1206 unsigned int interface, unsigned int alternate );
1207 extern struct usb_endpoint_descriptor *
1208 usb_endpoint_descriptor ( struct usb_configuration_descriptor *config,
1209 struct usb_interface_descriptor *interface,
1210 unsigned int type, unsigned int index );
1211 extern struct usb_endpoint_companion_descriptor *
1212 usb_endpoint_companion_descriptor ( struct usb_configuration_descriptor *config,
1213 struct usb_endpoint_descriptor *desc );
1214
1215 extern struct usb_hub * alloc_usb_hub ( struct usb_bus *bus,
1216 struct usb_device *usb,
1217 unsigned int ports,
1218 struct usb_hub_driver_operations *op );
1219 extern int register_usb_hub ( struct usb_hub *hub );
1220 extern void unregister_usb_hub ( struct usb_hub *hub );
1221 extern void free_usb_hub ( struct usb_hub *hub );
1222
1223 extern void usb_port_changed ( struct usb_port *port );
1224
1225 extern struct usb_bus * alloc_usb_bus ( struct device *dev,
1226 unsigned int ports, size_t mtu,
1227 struct usb_host_operations *op );
1228 extern int register_usb_bus ( struct usb_bus *bus );
1229 extern void unregister_usb_bus ( struct usb_bus *bus );
1230 extern void free_usb_bus ( struct usb_bus *bus );
1231 extern struct usb_bus * find_usb_bus_by_location ( unsigned int bus_type,
1232 unsigned int location );
1233
1234 extern int usb_alloc_address ( struct usb_bus *bus );
1235 extern void usb_free_address ( struct usb_bus *bus, unsigned int address );
1236 extern unsigned int usb_route_string ( struct usb_device *usb );
1237 extern unsigned int usb_depth ( struct usb_device *usb );
1238 extern struct usb_port * usb_root_hub_port ( struct usb_device *usb );
1239 extern struct usb_port * usb_transaction_translator ( struct usb_device *usb );
1240
1241 /** Minimum reset time
1242 *
1243 * Section 7.1.7.5 of the USB2 specification states that root hub
1244 * ports should assert reset signalling for at least 50ms.
1245 */
1246 #define USB_RESET_DELAY_MS 50
1247
1248 /** Reset recovery time
1249 *
1250 * Section 9.2.6.2 of the USB2 specification states that the
1251 * "recovery" interval after a port reset is 10ms.
1252 */
1253 #define USB_RESET_RECOVER_DELAY_MS 10
1254
1255 /** Maximum time to wait for a control transaction to complete
1256 *
1257 * Section 9.2.6.1 of the USB2 specification states that the upper
1258 * limit for commands to be processed is 5 seconds.
1259 */
1260 #define USB_CONTROL_MAX_WAIT_MS 5000
1261
1262 /** Set address recovery time
1263 *
1264 * Section 9.2.6.3 of the USB2 specification states that devices are
1265 * allowed a 2ms recovery interval after receiving a new address.
1266 */
1267 #define USB_SET_ADDRESS_RECOVER_DELAY_MS 2
1268
1269 /** Time to wait for ports to stabilise
1270 *
1271 * Section 7.1.7.3 of the USB specification states that we must allow
1272 * 100ms for devices to signal attachment, and an additional 100ms for
1273 * connection debouncing. (This delay is parallelised across all
1274 * ports on a hub; we do not delay separately for each port.)
1275 */
1276 #define USB_PORT_DELAY_MS 200
1277
1278 /** A USB device ID */
1279 struct usb_device_id {
1280 /** Name */
1281 const char *name;
1282 /** Vendor ID */
1283 uint16_t vendor;
1284 /** Product ID */
1285 uint16_t product;
1286 /** Class */
1287 struct usb_class class;
1288 };
1289
1290 /** Match-anything ID */
1291 #define USB_ANY_ID 0xffff
1292
1293 /** A USB driver */
1294 struct usb_driver {
1295 /** USB ID table */
1296 struct usb_device_id *ids;
1297 /** Number of entries in ID table */
1298 unsigned int id_count;
1299 /**
1300 * Probe device
1301 *
1302 * @v func USB function
1303 * @v config Configuration descriptor
1304 * @ret rc Return status code
1305 */
1306 int ( * probe ) ( struct usb_function *func,
1307 struct usb_configuration_descriptor *config );
1308 /**
1309 * Remove device
1310 *
1311 * @v func USB function
1312 */
1313 void ( * remove ) ( struct usb_function *func );
1314 };
1315
1316 /** USB driver table */
1317 #define USB_DRIVERS __table ( struct usb_driver, "usb_drivers" )
1318
1319 /** Declare a USB driver */
1320 #define __usb_driver __table_entry ( USB_DRIVERS, 01 )
1321
1322 extern struct usb_driver * usb_find_driver ( unsigned int vendor,
1323 unsigned int product,
1324 struct usb_class *class,
1325 struct usb_device_id **id );
1326
1327 #endif /* _IPXE_USB_H */