[usb] Select preferred USB device configuration based on driver score
[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 zlp Append a zero-length packet
462 * @ret rc Return status code
463 */
464 int ( * stream ) ( struct usb_endpoint *ep, struct io_buffer *iobuf,
465 int zlp );
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 descriptor
620 *
621 * This is an internal descriptor used to represent an association of
622 * interfaces within a USB device.
623 */
624 struct usb_function_descriptor {
625 /** Vendor ID */
626 uint16_t vendor;
627 /** Product ID */
628 uint16_t product;
629 /** Class */
630 struct usb_class class;
631 /** Number of interfaces */
632 unsigned int count;
633 };
634
635 /**
636 * A USB function
637 *
638 * A USB function represents an association of interfaces within a USB
639 * device.
640 */
641 struct usb_function {
642 /** Name */
643 const char *name;
644 /** USB device */
645 struct usb_device *usb;
646 /** Function descriptor */
647 struct usb_function_descriptor desc;
648 /** Generic device */
649 struct device dev;
650 /** List of functions within this USB device */
651 struct list_head list;
652
653 /** Driver */
654 struct usb_driver *driver;
655 /** Driver private data */
656 void *priv;
657
658 /** List of interface numbers
659 *
660 * This must be the last field within the structure.
661 */
662 uint8_t interface[0];
663 };
664
665 /**
666 * Set USB function driver private data
667 *
668 * @v func USB function
669 * @v priv Driver private data
670 */
671 static inline __attribute__ (( always_inline )) void
672 usb_func_set_drvdata ( struct usb_function *func, void *priv ) {
673 func->priv = priv;
674 }
675
676 /**
677 * Get USB function driver private data
678 *
679 * @v function USB function
680 * @ret priv Driver private data
681 */
682 static inline __attribute__ (( always_inline )) void *
683 usb_func_get_drvdata ( struct usb_function *func ) {
684 return func->priv;
685 }
686
687 /** A USB device */
688 struct usb_device {
689 /** Name */
690 char name[32];
691 /** USB port */
692 struct usb_port *port;
693 /** List of devices on this bus */
694 struct list_head list;
695 /** Device address, if assigned */
696 unsigned int address;
697 /** Device descriptor */
698 struct usb_device_descriptor device;
699 /** List of functions */
700 struct list_head functions;
701
702 /** Host controller operations */
703 struct usb_device_host_operations *host;
704 /** Host controller private data */
705 void *priv;
706
707 /** Endpoint list */
708 struct usb_endpoint *ep[32];
709
710 /** Control endpoint */
711 struct usb_endpoint control;
712 /** Completed control transfers */
713 struct list_head complete;
714 };
715
716 /** USB device host controller operations */
717 struct usb_device_host_operations {
718 /** Open device
719 *
720 * @v usb USB device
721 * @ret rc Return status code
722 */
723 int ( * open ) ( struct usb_device *usb );
724 /** Close device
725 *
726 * @v usb USB device
727 */
728 void ( * close ) ( struct usb_device *usb );
729 /** Assign device address
730 *
731 * @v usb USB device
732 * @ret rc Return status code
733 */
734 int ( * address ) ( struct usb_device *usb );
735 };
736
737 /**
738 * Set USB device host controller private data
739 *
740 * @v usb USB device
741 * @v priv Host controller private data
742 */
743 static inline __attribute__ (( always_inline )) void
744 usb_set_hostdata ( struct usb_device *usb, void *priv ) {
745 usb->priv = priv;
746 }
747
748 /**
749 * Get USB device host controller private data
750 *
751 * @v usb USB device
752 * @ret priv Host controller private data
753 */
754 static inline __attribute__ (( always_inline )) void *
755 usb_get_hostdata ( struct usb_device *usb ) {
756 return usb->priv;
757 }
758
759 /**
760 * Get USB endpoint
761 *
762 * @v usb USB device
763 * @v address Endpoint address
764 * @ret ep USB endpoint, or NULL if not opened
765 */
766 static inline struct usb_endpoint * usb_endpoint ( struct usb_device *usb,
767 unsigned int address ) {
768
769 return usb->ep[ USB_ENDPOINT_IDX ( address ) ];
770 }
771
772 /** A USB port */
773 struct usb_port {
774 /** USB hub */
775 struct usb_hub *hub;
776 /** Port address */
777 unsigned int address;
778 /** Port protocol */
779 unsigned int protocol;
780 /** Port speed */
781 unsigned int speed;
782 /** Port disconnection has been detected
783 *
784 * This should be set whenever the underlying hardware reports
785 * a connection status change.
786 */
787 int disconnected;
788 /** Port has an attached device */
789 int attached;
790 /** Currently attached device (if in use)
791 *
792 * Note that this field will be NULL if the attached device
793 * has been freed (e.g. because there were no drivers found).
794 */
795 struct usb_device *usb;
796 /** List of changed ports */
797 struct list_head changed;
798 };
799
800 /** A USB hub */
801 struct usb_hub {
802 /** Name */
803 const char *name;
804 /** USB bus */
805 struct usb_bus *bus;
806 /** Underlying USB device, if any */
807 struct usb_device *usb;
808 /** Hub protocol */
809 unsigned int protocol;
810 /** Number of ports */
811 unsigned int ports;
812
813 /** List of hubs */
814 struct list_head list;
815
816 /** Host controller operations */
817 struct usb_hub_host_operations *host;
818 /** Driver operations */
819 struct usb_hub_driver_operations *driver;
820 /** Driver private data */
821 void *priv;
822
823 /** Port list
824 *
825 * This must be the last field within the structure.
826 */
827 struct usb_port port[0];
828 };
829
830 /** USB hub host controller operations */
831 struct usb_hub_host_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 };
844
845 /** USB hub driver operations */
846 struct usb_hub_driver_operations {
847 /** Open hub
848 *
849 * @v hub USB hub
850 * @ret rc Return status code
851 */
852 int ( * open ) ( struct usb_hub *hub );
853 /** Close hub
854 *
855 * @v hub USB hub
856 */
857 void ( * close ) ( struct usb_hub *hub );
858 /** Enable port
859 *
860 * @v hub USB hub
861 * @v port USB port
862 * @ret rc Return status code
863 */
864 int ( * enable ) ( struct usb_hub *hub, struct usb_port *port );
865 /** Disable port
866 *
867 * @v hub USB hub
868 * @v port USB port
869 * @ret rc Return status code
870 */
871 int ( * disable ) ( struct usb_hub *hub, struct usb_port *port );
872 /** Update port speed
873 *
874 * @v hub USB hub
875 * @v port USB port
876 * @ret rc Return status code
877 */
878 int ( * speed ) ( struct usb_hub *hub, struct usb_port *port );
879 /** Clear transaction translator buffer
880 *
881 * @v hub USB hub
882 * @v port USB port
883 * @v ep USB endpoint
884 * @ret rc Return status code
885 */
886 int ( * clear_tt ) ( struct usb_hub *hub, struct usb_port *port,
887 struct usb_endpoint *ep );
888 };
889
890 /**
891 * Set USB hub driver private data
892 *
893 * @v hub USB hub
894 * @v priv Driver private data
895 */
896 static inline __attribute__ (( always_inline )) void
897 usb_hub_set_drvdata ( struct usb_hub *hub, void *priv ) {
898 hub->priv = priv;
899 }
900
901 /**
902 * Get USB hub driver private data
903 *
904 * @v hub USB hub
905 * @ret priv Driver private data
906 */
907 static inline __attribute__ (( always_inline )) void *
908 usb_hub_get_drvdata ( struct usb_hub *hub ) {
909 return hub->priv;
910 }
911
912 /**
913 * Get USB port
914 *
915 * @v hub USB hub
916 * @v address Port address
917 * @ret port USB port
918 */
919 static inline __attribute__ (( always_inline )) struct usb_port *
920 usb_port ( struct usb_hub *hub, unsigned int address ) {
921
922 return &hub->port[ address - 1 ];
923 }
924
925 /** A USB bus */
926 struct usb_bus {
927 /** Name */
928 const char *name;
929 /** Underlying hardware device */
930 struct device *dev;
931 /** Host controller operations set */
932 struct usb_host_operations *op;
933
934 /** Largest transfer allowed on the bus */
935 size_t mtu;
936 /** Address in-use mask
937 *
938 * This is used only by buses which perform manual address
939 * assignment. USB allows for addresses in the range [1,127].
940 * We use a simple bitmask which restricts us to the range
941 * [1,64]; this is unlikely to be a problem in practice. For
942 * comparison: controllers which perform autonomous address
943 * assignment (such as xHCI) typically allow for only 32
944 * devices per bus anyway.
945 */
946 unsigned long long addresses;
947
948 /** Root hub */
949 struct usb_hub *hub;
950
951 /** List of USB buses */
952 struct list_head list;
953 /** List of devices */
954 struct list_head devices;
955 /** List of hubs */
956 struct list_head hubs;
957
958 /** Host controller operations */
959 struct usb_bus_host_operations *host;
960 /** Host controller private data */
961 void *priv;
962 };
963
964 /** USB bus host controller operations */
965 struct usb_bus_host_operations {
966 /** Open bus
967 *
968 * @v bus USB bus
969 * @ret rc Return status code
970 */
971 int ( * open ) ( struct usb_bus *bus );
972 /** Close bus
973 *
974 * @v bus USB bus
975 */
976 void ( * close ) ( struct usb_bus *bus );
977 /** Poll bus
978 *
979 * @v bus USB bus
980 */
981 void ( * poll ) ( struct usb_bus *bus );
982 };
983
984 /** USB host controller operations */
985 struct usb_host_operations {
986 /** Endpoint operations */
987 struct usb_endpoint_host_operations endpoint;
988 /** Device operations */
989 struct usb_device_host_operations device;
990 /** Bus operations */
991 struct usb_bus_host_operations bus;
992 /** Hub operations */
993 struct usb_hub_host_operations hub;
994 /** Root hub operations */
995 struct usb_hub_driver_operations root;
996 };
997
998 /**
999 * Set USB bus host controller private data
1000 *
1001 * @v bus USB bus
1002 * @v priv Host controller private data
1003 */
1004 static inline __attribute__ (( always_inline )) void
1005 usb_bus_set_hostdata ( struct usb_bus *bus, void *priv ) {
1006 bus->priv = priv;
1007 }
1008
1009 /**
1010 * Get USB bus host controller private data
1011 *
1012 * @v bus USB bus
1013 * @ret priv Host controller private data
1014 */
1015 static inline __attribute__ (( always_inline )) void *
1016 usb_bus_get_hostdata ( struct usb_bus *bus ) {
1017 return bus->priv;
1018 }
1019
1020 /**
1021 * Poll USB bus
1022 *
1023 * @v bus USB bus
1024 */
1025 static inline __attribute__ (( always_inline )) void
1026 usb_poll ( struct usb_bus *bus ) {
1027 bus->host->poll ( bus );
1028 }
1029
1030 /** Iterate over all USB buses */
1031 #define for_each_usb_bus( bus ) \
1032 list_for_each_entry ( (bus), &usb_buses, list )
1033
1034 /**
1035 * Complete transfer (without error)
1036 *
1037 * @v ep USB endpoint
1038 * @v iobuf I/O buffer
1039 */
1040 static inline __attribute__ (( always_inline )) void
1041 usb_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
1042 usb_complete_err ( ep, iobuf, 0 );
1043 }
1044
1045 extern int usb_control ( struct usb_device *usb, unsigned int request,
1046 unsigned int value, unsigned int index, void *data,
1047 size_t len );
1048 extern int usb_get_string_descriptor ( struct usb_device *usb,
1049 unsigned int index,
1050 unsigned int language,
1051 char *buf, size_t len );
1052
1053 /**
1054 * Get status
1055 *
1056 * @v usb USB device
1057 * @v type Request type
1058 * @v index Target index
1059 * @v data Status to fill in
1060 * @v len Length of status descriptor
1061 * @ret rc Return status code
1062 */
1063 static inline __attribute__ (( always_inline )) int
1064 usb_get_status ( struct usb_device *usb, unsigned int type, unsigned int index,
1065 void *data, size_t len ) {
1066
1067 return usb_control ( usb, ( USB_GET_STATUS | type ), 0, index,
1068 data, len );
1069 }
1070
1071 /**
1072 * Clear feature
1073 *
1074 * @v usb USB device
1075 * @v type Request type
1076 * @v feature Feature selector
1077 * @v index Target index
1078 * @ret rc Return status code
1079 */
1080 static inline __attribute__ (( always_inline )) int
1081 usb_clear_feature ( struct usb_device *usb, unsigned int type,
1082 unsigned int feature, unsigned int index ) {
1083
1084 return usb_control ( usb, ( USB_CLEAR_FEATURE | type ),
1085 feature, index, NULL, 0 );
1086 }
1087
1088 /**
1089 * Set feature
1090 *
1091 * @v usb USB device
1092 * @v type Request type
1093 * @v feature Feature selector
1094 * @v index Target index
1095 * @ret rc Return status code
1096 */
1097 static inline __attribute__ (( always_inline )) int
1098 usb_set_feature ( struct usb_device *usb, unsigned int type,
1099 unsigned int feature, unsigned int index ) {
1100
1101 return usb_control ( usb, ( USB_SET_FEATURE | type ),
1102 feature, index, NULL, 0 );
1103 }
1104
1105 /**
1106 * Set address
1107 *
1108 * @v usb USB device
1109 * @v address Device address
1110 * @ret rc Return status code
1111 */
1112 static inline __attribute__ (( always_inline )) int
1113 usb_set_address ( struct usb_device *usb, unsigned int address ) {
1114
1115 return usb_control ( usb, USB_SET_ADDRESS, address, 0, NULL, 0 );
1116 }
1117
1118 /**
1119 * Get USB descriptor
1120 *
1121 * @v usb USB device
1122 * @v type Request type
1123 * @v desc Descriptor type
1124 * @v index Descriptor index
1125 * @v language Language ID (for string descriptors)
1126 * @v data Descriptor to fill in
1127 * @v len Maximum length of descriptor
1128 * @ret rc Return status code
1129 */
1130 static inline __attribute__ (( always_inline )) int
1131 usb_get_descriptor ( struct usb_device *usb, unsigned int type,
1132 unsigned int desc, unsigned int index,
1133 unsigned int language, struct usb_descriptor_header *data,
1134 size_t len ) {
1135
1136 return usb_control ( usb, ( USB_GET_DESCRIPTOR | type ),
1137 ( ( desc << 8 ) | index ), language, data, len );
1138 }
1139
1140 /**
1141 * Get first part of USB device descriptor (up to and including MTU)
1142 *
1143 * @v usb USB device
1144 * @v data Device descriptor to (partially) fill in
1145 * @ret rc Return status code
1146 */
1147 static inline __attribute__ (( always_inline )) int
1148 usb_get_mtu ( struct usb_device *usb, struct usb_device_descriptor *data ) {
1149
1150 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1151 &data->header,
1152 ( offsetof ( typeof ( *data ), mtu ) +
1153 sizeof ( data->mtu ) ) );
1154 }
1155
1156 /**
1157 * Get USB device descriptor
1158 *
1159 * @v usb USB device
1160 * @v data Device descriptor to fill in
1161 * @ret rc Return status code
1162 */
1163 static inline __attribute__ (( always_inline )) int
1164 usb_get_device_descriptor ( struct usb_device *usb,
1165 struct usb_device_descriptor *data ) {
1166
1167 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1168 &data->header, sizeof ( *data ) );
1169 }
1170
1171 /**
1172 * Get USB configuration descriptor
1173 *
1174 * @v usb USB device
1175 * @v index Configuration index
1176 * @v data Configuration descriptor to fill in
1177 * @ret rc Return status code
1178 */
1179 static inline __attribute__ (( always_inline )) int
1180 usb_get_config_descriptor ( struct usb_device *usb, unsigned int index,
1181 struct usb_configuration_descriptor *data,
1182 size_t len ) {
1183
1184 return usb_get_descriptor ( usb, 0, USB_CONFIGURATION_DESCRIPTOR, index,
1185 0, &data->header, len );
1186 }
1187
1188 /**
1189 * Set USB configuration
1190 *
1191 * @v usb USB device
1192 * @v index Configuration index
1193 * @ret rc Return status code
1194 */
1195 static inline __attribute__ (( always_inline )) int
1196 usb_set_configuration ( struct usb_device *usb, unsigned int index ) {
1197
1198 return usb_control ( usb, USB_SET_CONFIGURATION, index, 0, NULL, 0 );
1199 }
1200
1201 /**
1202 * Set USB interface alternate setting
1203 *
1204 * @v usb USB device
1205 * @v interface Interface number
1206 * @v alternate Alternate setting
1207 * @ret rc Return status code
1208 */
1209 static inline __attribute__ (( always_inline )) int
1210 usb_set_interface ( struct usb_device *usb, unsigned int interface,
1211 unsigned int alternate ) {
1212
1213 return usb_control ( usb, USB_SET_INTERFACE, alternate, interface,
1214 NULL, 0 );
1215 }
1216
1217 extern struct list_head usb_buses;
1218
1219 extern struct usb_interface_descriptor *
1220 usb_interface_descriptor ( struct usb_configuration_descriptor *config,
1221 unsigned int interface, unsigned int alternate );
1222 extern struct usb_endpoint_descriptor *
1223 usb_endpoint_descriptor ( struct usb_configuration_descriptor *config,
1224 struct usb_interface_descriptor *interface,
1225 unsigned int type, unsigned int index );
1226 extern struct usb_endpoint_companion_descriptor *
1227 usb_endpoint_companion_descriptor ( struct usb_configuration_descriptor *config,
1228 struct usb_endpoint_descriptor *desc );
1229
1230 extern struct usb_hub * alloc_usb_hub ( struct usb_bus *bus,
1231 struct usb_device *usb,
1232 unsigned int ports,
1233 struct usb_hub_driver_operations *op );
1234 extern int register_usb_hub ( struct usb_hub *hub );
1235 extern void unregister_usb_hub ( struct usb_hub *hub );
1236 extern void free_usb_hub ( struct usb_hub *hub );
1237
1238 extern void usb_port_changed ( struct usb_port *port );
1239
1240 extern struct usb_bus * alloc_usb_bus ( struct device *dev,
1241 unsigned int ports, size_t mtu,
1242 struct usb_host_operations *op );
1243 extern int register_usb_bus ( struct usb_bus *bus );
1244 extern void unregister_usb_bus ( struct usb_bus *bus );
1245 extern void free_usb_bus ( struct usb_bus *bus );
1246 extern struct usb_bus * find_usb_bus_by_location ( unsigned int bus_type,
1247 unsigned int location );
1248
1249 extern int usb_alloc_address ( struct usb_bus *bus );
1250 extern void usb_free_address ( struct usb_bus *bus, unsigned int address );
1251 extern unsigned int usb_route_string ( struct usb_device *usb );
1252 extern unsigned int usb_depth ( struct usb_device *usb );
1253 extern struct usb_port * usb_root_hub_port ( struct usb_device *usb );
1254 extern struct usb_port * usb_transaction_translator ( struct usb_device *usb );
1255
1256 /** Minimum reset time
1257 *
1258 * Section 7.1.7.5 of the USB2 specification states that root hub
1259 * ports should assert reset signalling for at least 50ms.
1260 */
1261 #define USB_RESET_DELAY_MS 50
1262
1263 /** Reset recovery time
1264 *
1265 * Section 9.2.6.2 of the USB2 specification states that the
1266 * "recovery" interval after a port reset is 10ms.
1267 */
1268 #define USB_RESET_RECOVER_DELAY_MS 10
1269
1270 /** Maximum time to wait for a control transaction to complete
1271 *
1272 * Section 9.2.6.1 of the USB2 specification states that the upper
1273 * limit for commands to be processed is 5 seconds.
1274 */
1275 #define USB_CONTROL_MAX_WAIT_MS 5000
1276
1277 /** Set address recovery time
1278 *
1279 * Section 9.2.6.3 of the USB2 specification states that devices are
1280 * allowed a 2ms recovery interval after receiving a new address.
1281 */
1282 #define USB_SET_ADDRESS_RECOVER_DELAY_MS 2
1283
1284 /** Time to wait for ports to stabilise
1285 *
1286 * Section 7.1.7.3 of the USB specification states that we must allow
1287 * 100ms for devices to signal attachment, and an additional 100ms for
1288 * connection debouncing. (This delay is parallelised across all
1289 * ports on a hub; we do not delay separately for each port.)
1290 */
1291 #define USB_PORT_DELAY_MS 200
1292
1293 /** A USB device ID */
1294 struct usb_device_id {
1295 /** Name */
1296 const char *name;
1297 /** Vendor ID */
1298 uint16_t vendor;
1299 /** Product ID */
1300 uint16_t product;
1301 /** Class */
1302 struct usb_class class;
1303 };
1304
1305 /** Match-anything ID */
1306 #define USB_ANY_ID 0xffff
1307
1308 /** A USB driver */
1309 struct usb_driver {
1310 /** USB ID table */
1311 struct usb_device_id *ids;
1312 /** Number of entries in ID table */
1313 unsigned int id_count;
1314 /** Driver score
1315 *
1316 * This is used to determine the preferred configuration for a
1317 * USB device.
1318 */
1319 unsigned int score;
1320 /**
1321 * Probe device
1322 *
1323 * @v func USB function
1324 * @v config Configuration descriptor
1325 * @ret rc Return status code
1326 */
1327 int ( * probe ) ( struct usb_function *func,
1328 struct usb_configuration_descriptor *config );
1329 /**
1330 * Remove device
1331 *
1332 * @v func USB function
1333 */
1334 void ( * remove ) ( struct usb_function *func );
1335 };
1336
1337 /** USB driver table */
1338 #define USB_DRIVERS __table ( struct usb_driver, "usb_drivers" )
1339
1340 /** Declare a USB driver */
1341 #define __usb_driver __table_entry ( USB_DRIVERS, 01 )
1342
1343 /** USB driver scores */
1344 enum usb_driver_score {
1345 /** Fallback driver (has no effect on overall score) */
1346 USB_SCORE_FALLBACK = 0,
1347 /** Deprecated driver */
1348 USB_SCORE_DEPRECATED = 1,
1349 /** Normal driver */
1350 USB_SCORE_NORMAL = 2,
1351 };
1352
1353 extern struct usb_driver *
1354 usb_find_driver ( struct usb_function_descriptor *desc,
1355 struct usb_device_id **id );
1356
1357 #endif /* _IPXE_USB_H */