[usb] Try multiple USB device configurations
[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 );
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 /** A USB setup data packet */
58 struct usb_setup_packet {
59 /** Request */
60 uint16_t request;
61 /** Value paramer */
62 uint16_t value;
63 /** Index parameter */
64 uint16_t index;
65 /** Length of data stage */
66 uint16_t len;
67 } __attribute__ (( packed ));
68
69 /** Data transfer is from host to device */
70 #define USB_DIR_OUT ( 0 << 7 )
71
72 /** Data transfer is from device to host */
73 #define USB_DIR_IN ( 1 << 7 )
74
75 /** Standard request type */
76 #define USB_TYPE_STANDARD ( 0 << 5 )
77
78 /** Class-specific request type */
79 #define USB_TYPE_CLASS ( 1 << 5 )
80
81 /** Request recipient is the device */
82 #define USB_RECIP_DEVICE ( 0 << 0 )
83
84 /** Request recipient is an interface */
85 #define USB_RECIP_INTERFACE ( 1 << 0 )
86
87 /** Request recipient is an endpoint */
88 #define USB_RECIP_ENDPOINT ( 2 << 0 )
89
90 /** Construct USB request type */
91 #define USB_REQUEST_TYPE(type) ( (type) << 8 )
92
93 /** Get status */
94 #define USB_GET_STATUS ( USB_DIR_IN | USB_REQUEST_TYPE ( 0 ) )
95
96 /** Clear feature */
97 #define USB_CLEAR_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 1 ) )
98
99 /** Set feature */
100 #define USB_SET_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 3 ) )
101
102 /** Set address */
103 #define USB_SET_ADDRESS ( USB_DIR_OUT | USB_REQUEST_TYPE ( 5 ) )
104
105 /** Get descriptor */
106 #define USB_GET_DESCRIPTOR ( USB_DIR_IN | USB_REQUEST_TYPE ( 6 ) )
107
108 /** Set descriptor */
109 #define USB_SET_DESCRIPTOR ( USB_DIR_OUT | USB_REQUEST_TYPE ( 7 ) )
110
111 /** Get configuration */
112 #define USB_GET_CONFIGURATION ( USB_DIR_IN | USB_REQUEST_TYPE ( 8 ) )
113
114 /** Set configuration */
115 #define USB_SET_CONFIGURATION ( USB_DIR_OUT | USB_REQUEST_TYPE ( 9 ) )
116
117 /** Get interface */
118 #define USB_GET_INTERFACE \
119 ( USB_DIR_IN | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 10 ) )
120
121 /** Set interface */
122 #define USB_SET_INTERFACE \
123 ( USB_DIR_OUT | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 11 ) )
124
125 /** Endpoint halt feature */
126 #define USB_ENDPOINT_HALT 0
127
128 /** A USB class code tuple */
129 struct usb_class {
130 /** Class code */
131 uint8_t class;
132 /** Subclass code */
133 uint8_t subclass;
134 /** Protocol code */
135 uint8_t protocol;
136 } __attribute__ (( packed ));
137
138 /** Class code for USB hubs */
139 #define USB_CLASS_HUB 9
140
141 /** A USB descriptor header */
142 struct usb_descriptor_header {
143 /** Length of descriptor */
144 uint8_t len;
145 /** Descriptor type */
146 uint8_t type;
147 } __attribute__ (( packed ));
148
149 /** A USB device descriptor */
150 struct usb_device_descriptor {
151 /** Descriptor header */
152 struct usb_descriptor_header header;
153 /** USB specification release number in BCD */
154 uint16_t protocol;
155 /** Device class */
156 struct usb_class class;
157 /** Maximum packet size for endpoint zero */
158 uint8_t mtu;
159 /** Vendor ID */
160 uint16_t vendor;
161 /** Product ID */
162 uint16_t product;
163 /** Device release number in BCD */
164 uint16_t release;
165 /** Manufacturer string */
166 uint8_t manufacturer;
167 /** Product string */
168 uint8_t name;
169 /** Serial number string */
170 uint8_t serial;
171 /** Number of possible configurations */
172 uint8_t configurations;
173 } __attribute__ (( packed ));
174
175 /** A USB device descriptor */
176 #define USB_DEVICE_DESCRIPTOR 1
177
178 /** A USB configuration descriptor */
179 struct usb_configuration_descriptor {
180 /** Descriptor header */
181 struct usb_descriptor_header header;
182 /** Total length */
183 uint16_t len;
184 /** Number of interfaces */
185 uint8_t interfaces;
186 /** Configuration value */
187 uint8_t config;
188 /** Configuration string */
189 uint8_t name;
190 /** Attributes */
191 uint8_t attributes;
192 /** Maximum power consumption */
193 uint8_t power;
194 } __attribute__ (( packed ));
195
196 /** A USB configuration descriptor */
197 #define USB_CONFIGURATION_DESCRIPTOR 2
198
199 /** A USB string descriptor */
200 struct usb_string_descriptor {
201 /** Descriptor header */
202 struct usb_descriptor_header header;
203 /** String */
204 char string[0];
205 } __attribute__ (( packed ));
206
207 /** A USB string descriptor */
208 #define USB_STRING_DESCRIPTOR 3
209
210 /** A USB interface descriptor */
211 struct usb_interface_descriptor {
212 /** Descriptor header */
213 struct usb_descriptor_header header;
214 /** Interface number */
215 uint8_t interface;
216 /** Alternate setting */
217 uint8_t alternate;
218 /** Number of endpoints */
219 uint8_t endpoints;
220 /** Interface class */
221 struct usb_class class;
222 /** Interface name */
223 uint8_t name;
224 } __attribute__ (( packed ));
225
226 /** A USB interface descriptor */
227 #define USB_INTERFACE_DESCRIPTOR 4
228
229 /** A USB endpoint descriptor */
230 struct usb_endpoint_descriptor {
231 /** Descriptor header */
232 struct usb_descriptor_header header;
233 /** Endpoint address */
234 uint8_t endpoint;
235 /** Attributes */
236 uint8_t attributes;
237 /** Maximum packet size and burst size */
238 uint16_t sizes;
239 /** Polling interval */
240 uint8_t interval;
241 } __attribute__ (( packed ));
242
243 /** A USB endpoint descriptor */
244 #define USB_ENDPOINT_DESCRIPTOR 5
245
246 /** Endpoint attribute transfer type mask */
247 #define USB_ENDPOINT_ATTR_TYPE_MASK 0x03
248
249 /** Control endpoint transfer type */
250 #define USB_ENDPOINT_ATTR_CONTROL 0x00
251
252 /** Bulk endpoint transfer type */
253 #define USB_ENDPOINT_ATTR_BULK 0x02
254
255 /** Interrupt endpoint transfer type */
256 #define USB_ENDPOINT_ATTR_INTERRUPT 0x03
257
258 /** Bulk OUT endpoint (internal) type */
259 #define USB_BULK_OUT ( USB_ENDPOINT_ATTR_BULK | USB_DIR_OUT )
260
261 /** Bulk IN endpoint (internal) type */
262 #define USB_BULK_IN ( USB_ENDPOINT_ATTR_BULK | USB_DIR_IN )
263
264 /** Interrupt endpoint (internal) type */
265 #define USB_INTERRUPT ( USB_ENDPOINT_ATTR_INTERRUPT | USB_DIR_IN )
266
267 /** USB endpoint MTU */
268 #define USB_ENDPOINT_MTU(sizes) ( ( (sizes) >> 0 ) & 0x07ff )
269
270 /** USB endpoint maximum burst size */
271 #define USB_ENDPOINT_BURST(sizes) ( ( (sizes) >> 11 ) & 0x0003 )
272
273 /** A USB endpoint companion descriptor */
274 struct usb_endpoint_companion_descriptor {
275 /** Descriptor header */
276 struct usb_descriptor_header header;
277 /** Maximum burst size */
278 uint8_t burst;
279 /** Extended attributes */
280 uint8_t extended;
281 /** Number of bytes per service interval */
282 uint16_t periodic;
283 } __attribute__ (( packed ));
284
285 /** A USB endpoint companion descriptor */
286 #define USB_ENDPOINT_COMPANION_DESCRIPTOR 48
287
288 /** A USB interface association descriptor */
289 struct usb_interface_association_descriptor {
290 /** Descriptor header */
291 struct usb_descriptor_header header;
292 /** First interface number */
293 uint8_t first;
294 /** Interface count */
295 uint8_t count;
296 /** Association class */
297 struct usb_class class;
298 /** Association name */
299 uint8_t name;
300 } __attribute__ (( packed ));
301
302 /** A USB interface association descriptor */
303 #define USB_INTERFACE_ASSOCIATION_DESCRIPTOR 11
304
305 /** A class-specific interface descriptor */
306 #define USB_CS_INTERFACE_DESCRIPTOR 36
307
308 /** A class-specific endpoint descriptor */
309 #define USB_CS_ENDPOINT_DESCRIPTOR 37
310
311 /**
312 * Get next USB descriptor
313 *
314 * @v desc USB descriptor header
315 * @ret next Next USB descriptor header
316 */
317 static inline __attribute__ (( always_inline )) struct usb_descriptor_header *
318 usb_next_descriptor ( struct usb_descriptor_header *desc ) {
319
320 return ( ( ( void * ) desc ) + desc->len );
321 }
322
323 /**
324 * Check that descriptor lies within a configuration descriptor
325 *
326 * @v config Configuration descriptor
327 * @v desc Descriptor header
328 * @v is_within Descriptor is within the configuration descriptor
329 */
330 static inline __attribute__ (( always_inline )) int
331 usb_is_within_config ( struct usb_configuration_descriptor *config,
332 struct usb_descriptor_header *desc ) {
333 struct usb_descriptor_header *end =
334 ( ( ( void * ) config ) + le16_to_cpu ( config->len ) );
335
336 /* Check that descriptor starts within the configuration
337 * descriptor, and that the length does not exceed the
338 * configuration descriptor. This relies on the fact that
339 * usb_next_descriptor() needs to access only the first byte
340 * of the descriptor in order to determine the length.
341 */
342 return ( ( desc < end ) && ( usb_next_descriptor ( desc ) <= end ) );
343 }
344
345 /** Iterate over all configuration descriptors */
346 #define for_each_config_descriptor( desc, config ) \
347 for ( desc = container_of ( &(config)->header, \
348 typeof ( *desc ), header ) ; \
349 usb_is_within_config ( (config), &desc->header ) ; \
350 desc = container_of ( usb_next_descriptor ( &desc->header ), \
351 typeof ( *desc ), header ) )
352
353 /** Iterate over all configuration descriptors within an interface descriptor */
354 #define for_each_interface_descriptor( desc, config, interface ) \
355 for ( desc = container_of ( usb_next_descriptor ( &(interface)-> \
356 header ), \
357 typeof ( *desc ), header ) ; \
358 ( usb_is_within_config ( (config), &desc->header ) && \
359 ( desc->header.type != USB_INTERFACE_DESCRIPTOR ) ) ; \
360 desc = container_of ( usb_next_descriptor ( &desc->header ), \
361 typeof ( *desc ), header ) )
362
363 /** A USB endpoint */
364 struct usb_endpoint {
365 /** USB device */
366 struct usb_device *usb;
367 /** Endpoint address */
368 unsigned int address;
369 /** Attributes */
370 unsigned int attributes;
371 /** Maximum transfer size */
372 size_t mtu;
373 /** Maximum burst size */
374 unsigned int burst;
375
376 /** Endpoint is open */
377 int open;
378 /** Current failure state (if any) */
379 int rc;
380
381 /** Host controller operations */
382 struct usb_endpoint_host_operations *host;
383 /** Host controller private data */
384 void *priv;
385 /** Driver operations */
386 struct usb_endpoint_driver_operations *driver;
387 };
388
389 /** USB endpoint host controller operations */
390 struct usb_endpoint_host_operations {
391 /** Open endpoint
392 *
393 * @v ep USB endpoint
394 * @ret rc Return status code
395 */
396 int ( * open ) ( struct usb_endpoint *ep );
397 /** Close endpoint
398 *
399 * @v ep USB endpoint
400 */
401 void ( * close ) ( struct usb_endpoint *ep );
402 /**
403 * Reset endpoint
404 *
405 * @v ep USB endpoint
406 * @ret rc Return status code
407 */
408 int ( * reset ) ( struct usb_endpoint *ep );
409 /** Update MTU
410 *
411 * @v ep USB endpoint
412 * @ret rc Return status code
413 */
414 int ( * mtu ) ( struct usb_endpoint *ep );
415 /** Enqueue message transfer
416 *
417 * @v ep USB endpoint
418 * @v packet Setup packet
419 * @v iobuf I/O buffer (if any)
420 * @ret rc Return status code
421 */
422 int ( * message ) ( struct usb_endpoint *ep,
423 struct usb_setup_packet *setup,
424 struct io_buffer *iobuf );
425 /** Enqueue stream transfer
426 *
427 * @v ep USB endpoint
428 * @v iobuf I/O buffer
429 * @ret rc Return status code
430 */
431 int ( * stream ) ( struct usb_endpoint *ep,
432 struct io_buffer *iobuf );
433 };
434
435 /** USB endpoint driver operations */
436 struct usb_endpoint_driver_operations {
437 /** Complete transfer
438 *
439 * @v ep USB endpoint
440 * @v iobuf I/O buffer
441 * @v rc Completion status code
442 */
443 void ( * complete ) ( struct usb_endpoint *ep,
444 struct io_buffer *iobuf, int rc );
445 };
446
447 /** Control endpoint address */
448 #define USB_EP0_ADDRESS 0x00
449
450 /** Control endpoint attributes */
451 #define USB_EP0_ATTRIBUTES 0x00
452
453 /** Calculate default MTU based on device speed
454 *
455 * @v speed Device speed
456 * @ret mtu Default MTU
457 */
458 #define USB_EP0_DEFAULT_MTU(speed) \
459 ( ( (speed) >= USB_SPEED_SUPER ) ? 512 : \
460 ( ( (speed) >= USB_SPEED_FULL ) ? 64 : 8 ) )
461
462 /** Control endpoint maximum burst size */
463 #define USB_EP0_BURST 0
464
465 /** Maximum endpoint number */
466 #define USB_ENDPOINT_MAX 0x0f
467
468 /** Endpoint direction is in */
469 #define USB_ENDPOINT_IN 0x80
470
471 /** Construct endpoint index from endpoint address */
472 #define USB_ENDPOINT_IDX(address) \
473 ( ( (address) & USB_ENDPOINT_MAX ) | \
474 ( ( (address) & USB_ENDPOINT_IN ) >> 3 ) )
475
476 /**
477 * Initialise USB endpoint
478 *
479 * @v ep USB endpoint
480 * @v usb USB device
481 * @v driver Driver operations
482 */
483 static inline __attribute__ (( always_inline )) void
484 usb_endpoint_init ( struct usb_endpoint *ep, struct usb_device *usb,
485 struct usb_endpoint_driver_operations *driver ) {
486
487 ep->usb = usb;
488 ep->driver = driver;
489 }
490
491 /**
492 * Describe USB endpoint
493 *
494 * @v ep USB endpoint
495 * @v address Endpoint address
496 * @v attributes Attributes
497 * @v mtu Maximum packet size
498 * @v burst Maximum burst size
499 */
500 static inline __attribute__ (( always_inline )) void
501 usb_endpoint_describe ( struct usb_endpoint *ep, unsigned int address,
502 unsigned int attributes, size_t mtu,
503 unsigned int burst ) {
504
505 ep->address = address;
506 ep->attributes = attributes;
507 ep->mtu = mtu;
508 ep->burst = burst;
509 }
510
511 /**
512 * Set USB endpoint host controller private data
513 *
514 * @v ep USB endpoint
515 * @v priv Host controller private data
516 */
517 static inline __attribute__ (( always_inline )) void
518 usb_endpoint_set_hostdata ( struct usb_endpoint *ep, void *priv ) {
519 ep->priv = priv;
520 }
521
522 /**
523 * Get USB endpoint host controller private data
524 *
525 * @v ep USB endpoint
526 * @ret priv Host controller private data
527 */
528 static inline __attribute__ (( always_inline )) void *
529 usb_endpoint_get_hostdata ( struct usb_endpoint *ep ) {
530 return ep->priv;
531 }
532
533 extern int
534 usb_endpoint_described ( struct usb_endpoint *ep,
535 struct usb_configuration_descriptor *config,
536 struct usb_interface_descriptor *interface,
537 unsigned int type, unsigned int index );
538 extern int usb_endpoint_open ( struct usb_endpoint *ep );
539 extern void usb_endpoint_close ( struct usb_endpoint *ep );
540 extern int usb_message ( struct usb_endpoint *ep, unsigned int request,
541 unsigned int value, unsigned int index,
542 struct io_buffer *iobuf );
543 extern int usb_stream ( struct usb_endpoint *ep, struct io_buffer *iobuf );
544 extern void usb_complete_err ( struct usb_endpoint *ep,
545 struct io_buffer *iobuf, int rc );
546
547 /**
548 * A USB function
549 *
550 * A USB function represents an association of interfaces within a USB
551 * device.
552 */
553 struct usb_function {
554 /** Name */
555 const char *name;
556 /** USB device */
557 struct usb_device *usb;
558 /** Class */
559 struct usb_class class;
560 /** Number of interfaces */
561 unsigned int count;
562 /** Generic device */
563 struct device dev;
564 /** List of functions within this USB device */
565 struct list_head list;
566
567 /** Driver */
568 struct usb_driver *driver;
569 /** Driver private data */
570 void *priv;
571
572 /** List of interface numbers
573 *
574 * This must be the last field within the structure.
575 */
576 uint8_t interface[0];
577 };
578
579 /**
580 * Set USB function driver private data
581 *
582 * @v func USB function
583 * @v priv Driver private data
584 */
585 static inline __attribute__ (( always_inline )) void
586 usb_func_set_drvdata ( struct usb_function *func, void *priv ) {
587 func->priv = priv;
588 }
589
590 /**
591 * Get USB function driver private data
592 *
593 * @v function USB function
594 * @ret priv Driver private data
595 */
596 static inline __attribute__ (( always_inline )) void *
597 usb_func_get_drvdata ( struct usb_function *func ) {
598 return func->priv;
599 }
600
601 /** A USB device */
602 struct usb_device {
603 /** Name */
604 char name[32];
605 /** USB port */
606 struct usb_port *port;
607 /** List of devices on this bus */
608 struct list_head list;
609 /** Device address, if assigned */
610 unsigned int address;
611 /** Device descriptor */
612 struct usb_device_descriptor device;
613 /** List of functions */
614 struct list_head functions;
615
616 /** Host controller operations */
617 struct usb_device_host_operations *host;
618 /** Host controller private data */
619 void *priv;
620
621 /** Endpoint list */
622 struct usb_endpoint *ep[32];
623
624 /** Control endpoint */
625 struct usb_endpoint control;
626 /** Completed control transfers */
627 struct list_head complete;
628 };
629
630 /** USB device host controller operations */
631 struct usb_device_host_operations {
632 /** Open device
633 *
634 * @v usb USB device
635 * @ret rc Return status code
636 */
637 int ( * open ) ( struct usb_device *usb );
638 /** Close device
639 *
640 * @v usb USB device
641 */
642 void ( * close ) ( struct usb_device *usb );
643 /** Assign device address
644 *
645 * @v usb USB device
646 * @ret rc Return status code
647 */
648 int ( * address ) ( struct usb_device *usb );
649 };
650
651 /**
652 * Set USB device host controller private data
653 *
654 * @v usb USB device
655 * @v priv Host controller private data
656 */
657 static inline __attribute__ (( always_inline )) void
658 usb_set_hostdata ( struct usb_device *usb, void *priv ) {
659 usb->priv = priv;
660 }
661
662 /**
663 * Get USB device host controller private data
664 *
665 * @v usb USB device
666 * @ret priv Host controller private data
667 */
668 static inline __attribute__ (( always_inline )) void *
669 usb_get_hostdata ( struct usb_device *usb ) {
670 return usb->priv;
671 }
672
673 /**
674 * Get USB endpoint
675 *
676 * @v usb USB device
677 * @v address Endpoint address
678 * @ret ep USB endpoint, or NULL if not opened
679 */
680 static inline struct usb_endpoint * usb_endpoint ( struct usb_device *usb,
681 unsigned int address ) {
682
683 return usb->ep[ USB_ENDPOINT_IDX ( address ) ];
684 }
685
686 /** A USB port */
687 struct usb_port {
688 /** USB hub */
689 struct usb_hub *hub;
690 /** Port address */
691 unsigned int address;
692 /** Port protocol */
693 unsigned int protocol;
694 /** Port speed */
695 unsigned int speed;
696 /** Currently attached device (if any) */
697 struct usb_device *usb;
698 /** List of changed ports */
699 struct list_head list;
700 };
701
702 /** A USB hub */
703 struct usb_hub {
704 /** Name */
705 const char *name;
706 /** USB bus */
707 struct usb_bus *bus;
708 /** Underlying USB device, if any */
709 struct usb_device *usb;
710 /** Hub protocol */
711 unsigned int protocol;
712 /** Number of ports */
713 unsigned int ports;
714
715 /** List of hubs */
716 struct list_head list;
717
718 /** Driver operations */
719 struct usb_hub_driver_operations *driver;
720 /** Driver private data */
721 void *priv;
722
723 /** Port list
724 *
725 * This must be the last field within the structure.
726 */
727 struct usb_port port[0];
728 };
729
730 /** USB hub operations */
731 struct usb_hub_driver_operations {
732 /** Open hub
733 *
734 * @v hub USB hub
735 * @ret rc Return status code
736 */
737 int ( * open ) ( struct usb_hub *hub );
738 /** Close hub
739 *
740 * @v hub USB hub
741 */
742 void ( * close ) ( struct usb_hub *hub );
743 /** Enable port
744 *
745 * @v hub USB hub
746 * @v port USB port
747 * @ret rc Return status code
748 */
749 int ( * enable ) ( struct usb_hub *hub, struct usb_port *port );
750 /** Disable port
751 *
752 * @v hub USB hub
753 * @v port USB port
754 * @ret rc Return status code
755 */
756 int ( * disable ) ( struct usb_hub *hub, struct usb_port *port );
757 /** Update port speed
758 *
759 * @v hub USB hub
760 * @v port USB port
761 * @ret rc Return status code
762 */
763 int ( * speed ) ( struct usb_hub *hub, struct usb_port *port );
764 };
765
766 /**
767 * Set USB hub driver private data
768 *
769 * @v hub USB hub
770 * @v priv Driver private data
771 */
772 static inline __attribute__ (( always_inline )) void
773 usb_hub_set_drvdata ( struct usb_hub *hub, void *priv ) {
774 hub->priv = priv;
775 }
776
777 /**
778 * Get USB hub driver private data
779 *
780 * @v hub USB hub
781 * @ret priv Driver private data
782 */
783 static inline __attribute__ (( always_inline )) void *
784 usb_hub_get_drvdata ( struct usb_hub *hub ) {
785 return hub->priv;
786 }
787
788 /**
789 * Get USB port
790 *
791 * @v hub USB hub
792 * @v address Port address
793 * @ret port USB port
794 */
795 static inline __attribute__ (( always_inline )) struct usb_port *
796 usb_port ( struct usb_hub *hub, unsigned int address ) {
797
798 return &hub->port[ address - 1 ];
799 }
800
801 /** A USB bus */
802 struct usb_bus {
803 /** Name */
804 const char *name;
805 /** Underlying hardware device */
806 struct device *dev;
807 /** Host controller operations set */
808 struct usb_host_operations *op;
809
810 /** Root hub */
811 struct usb_hub *hub;
812
813 /** List of devices */
814 struct list_head devices;
815 /** List of hubs */
816 struct list_head hubs;
817 /** List of changed ports */
818 struct list_head changed;
819 /** Process */
820 struct process process;
821
822 /** Host controller operations */
823 struct usb_bus_host_operations *host;
824 /** Host controller private data */
825 void *priv;
826 };
827
828 /** USB bus host controller operations */
829 struct usb_bus_host_operations {
830 /** Open bus
831 *
832 * @v bus USB bus
833 * @ret rc Return status code
834 */
835 int ( * open ) ( struct usb_bus *bus );
836 /** Close bus
837 *
838 * @v bus USB bus
839 */
840 void ( * close ) ( struct usb_bus *bus );
841 /** Poll bus
842 *
843 * @v bus USB bus
844 */
845 void ( * poll ) ( struct usb_bus *bus );
846 };
847
848 /** USB host controller operations */
849 struct usb_host_operations {
850 /** Endpoint operations */
851 struct usb_endpoint_host_operations endpoint;
852 /** Device operations */
853 struct usb_device_host_operations device;
854 /** Bus operations */
855 struct usb_bus_host_operations bus;
856 /** Root hub operations */
857 struct usb_hub_driver_operations hub;
858 };
859
860 /**
861 * Set USB bus host controller private data
862 *
863 * @v bus USB bus
864 * @v priv Host controller private data
865 */
866 static inline __attribute__ (( always_inline )) void
867 usb_bus_set_hostdata ( struct usb_bus *bus, void *priv ) {
868 bus->priv = priv;
869 }
870
871 /**
872 * Get USB bus host controller private data
873 *
874 * @v bus USB bus
875 * @ret priv Host controller private data
876 */
877 static inline __attribute__ (( always_inline )) void *
878 usb_bus_get_hostdata ( struct usb_bus *bus ) {
879 return bus->priv;
880 }
881
882 /**
883 * Poll USB bus
884 *
885 * @v bus USB bus
886 */
887 static inline __attribute__ (( always_inline )) void
888 usb_poll ( struct usb_bus *bus ) {
889 bus->host->poll ( bus );
890 }
891
892 /**
893 * Complete transfer (without error)
894 *
895 * @v ep USB endpoint
896 * @v iobuf I/O buffer
897 */
898 static inline __attribute__ (( always_inline )) void
899 usb_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
900 usb_complete_err ( ep, iobuf, 0 );
901 }
902
903 extern int usb_control ( struct usb_device *usb, unsigned int request,
904 unsigned int value, unsigned int index, void *data,
905 size_t len );
906 extern int usb_get_string_descriptor ( struct usb_device *usb,
907 unsigned int index,
908 unsigned int language,
909 char *buf, size_t len );
910
911 /**
912 * Get status
913 *
914 * @v usb USB device
915 * @v type Request type
916 * @v index Target index
917 * @v data Status to fill in
918 * @v len Length of status descriptor
919 * @ret rc Return status code
920 */
921 static inline __attribute__ (( always_inline )) int
922 usb_get_status ( struct usb_device *usb, unsigned int type, unsigned int index,
923 void *data, size_t len ) {
924
925 return usb_control ( usb, ( USB_GET_STATUS | type ), 0, index,
926 data, len );
927 }
928
929 /**
930 * Clear feature
931 *
932 * @v usb USB device
933 * @v type Request type
934 * @v feature Feature selector
935 * @v index Target index
936 * @ret rc Return status code
937 */
938 static inline __attribute__ (( always_inline )) int
939 usb_clear_feature ( struct usb_device *usb, unsigned int type,
940 unsigned int feature, unsigned int index ) {
941
942 return usb_control ( usb, ( USB_CLEAR_FEATURE | type ),
943 feature, index, NULL, 0 );
944 }
945
946 /**
947 * Set feature
948 *
949 * @v usb USB device
950 * @v type Request type
951 * @v feature Feature selector
952 * @v index Target index
953 * @ret rc Return status code
954 */
955 static inline __attribute__ (( always_inline )) int
956 usb_set_feature ( struct usb_device *usb, unsigned int type,
957 unsigned int feature, unsigned int index ) {
958
959 return usb_control ( usb, ( USB_SET_FEATURE | type ),
960 feature, index, NULL, 0 );
961 }
962
963 /**
964 * Get USB descriptor
965 *
966 * @v usb USB device
967 * @v type Request type
968 * @v desc Descriptor type
969 * @v index Descriptor index
970 * @v language Language ID (for string descriptors)
971 * @v data Descriptor to fill in
972 * @v len Maximum length of descriptor
973 * @ret rc Return status code
974 */
975 static inline __attribute__ (( always_inline )) int
976 usb_get_descriptor ( struct usb_device *usb, unsigned int type,
977 unsigned int desc, unsigned int index,
978 unsigned int language, struct usb_descriptor_header *data,
979 size_t len ) {
980
981 return usb_control ( usb, ( USB_GET_DESCRIPTOR | type ),
982 ( ( desc << 8 ) | index ), language, data, len );
983 }
984
985 /**
986 * Get first part of USB device descriptor (up to and including MTU)
987 *
988 * @v usb USB device
989 * @v data Device descriptor to (partially) fill in
990 * @ret rc Return status code
991 */
992 static inline __attribute__ (( always_inline )) int
993 usb_get_mtu ( struct usb_device *usb, struct usb_device_descriptor *data ) {
994
995 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
996 &data->header,
997 ( offsetof ( typeof ( *data ), mtu ) +
998 sizeof ( data->mtu ) ) );
999 }
1000
1001 /**
1002 * Get USB device descriptor
1003 *
1004 * @v usb USB device
1005 * @v data Device descriptor to fill in
1006 * @ret rc Return status code
1007 */
1008 static inline __attribute__ (( always_inline )) int
1009 usb_get_device_descriptor ( struct usb_device *usb,
1010 struct usb_device_descriptor *data ) {
1011
1012 return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1013 &data->header, sizeof ( *data ) );
1014 }
1015
1016 /**
1017 * Get USB configuration descriptor
1018 *
1019 * @v usb USB device
1020 * @v index Configuration index
1021 * @v data Configuration descriptor to fill in
1022 * @ret rc Return status code
1023 */
1024 static inline __attribute (( always_inline )) int
1025 usb_get_config_descriptor ( struct usb_device *usb, unsigned int index,
1026 struct usb_configuration_descriptor *data,
1027 size_t len ) {
1028
1029 return usb_get_descriptor ( usb, 0, USB_CONFIGURATION_DESCRIPTOR, index,
1030 0, &data->header, len );
1031 }
1032
1033 /**
1034 * Set USB configuration
1035 *
1036 * @v usb USB device
1037 * @v index Configuration index
1038 * @ret rc Return status code
1039 */
1040 static inline __attribute__ (( always_inline )) int
1041 usb_set_configuration ( struct usb_device *usb, unsigned int index ) {
1042
1043 return usb_control ( usb, USB_SET_CONFIGURATION, index, 0, NULL, 0 );
1044 }
1045
1046 /**
1047 * Set USB interface alternate setting
1048 *
1049 * @v usb USB device
1050 * @v interface Interface number
1051 * @v alternate Alternate setting
1052 * @ret rc Return status code
1053 */
1054 static inline __attribute__ (( always_inline )) int
1055 usb_set_interface ( struct usb_device *usb, unsigned int interface,
1056 unsigned int alternate ) {
1057
1058 return usb_control ( usb, USB_SET_INTERFACE, alternate, interface,
1059 NULL, 0 );
1060 }
1061
1062 extern struct usb_interface_descriptor *
1063 usb_interface_descriptor ( struct usb_configuration_descriptor *config,
1064 unsigned int interface, unsigned int alternate );
1065 extern struct usb_endpoint_descriptor *
1066 usb_endpoint_descriptor ( struct usb_configuration_descriptor *config,
1067 struct usb_interface_descriptor *interface,
1068 unsigned int type, unsigned int index );
1069 extern struct usb_endpoint_companion_descriptor *
1070 usb_endpoint_companion_descriptor ( struct usb_configuration_descriptor *config,
1071 struct usb_endpoint_descriptor *desc );
1072
1073 extern struct usb_hub * alloc_usb_hub ( struct usb_bus *bus,
1074 struct usb_device *usb,
1075 unsigned int ports,
1076 struct usb_hub_driver_operations *op );
1077 extern int register_usb_hub ( struct usb_hub *hub );
1078 extern void unregister_usb_hub ( struct usb_hub *hub );
1079 extern void free_usb_hub ( struct usb_hub *hub );
1080
1081 extern void usb_port_changed ( struct usb_port *port );
1082
1083 extern struct usb_bus * alloc_usb_bus ( struct device *dev, unsigned int ports,
1084 struct usb_host_operations *op );
1085 extern int register_usb_bus ( struct usb_bus *bus );
1086 extern void unregister_usb_bus ( struct usb_bus *bus );
1087 extern void free_usb_bus ( struct usb_bus *bus );
1088
1089 extern unsigned int usb_route_string ( struct usb_device *usb );
1090 extern unsigned int usb_depth ( struct usb_device *usb );
1091 extern struct usb_port * usb_root_hub_port ( struct usb_device *usb );
1092
1093 /** Maximum time to wait for a control transaction to complete
1094 *
1095 * This is a policy decision.
1096 */
1097 #define USB_CONTROL_MAX_WAIT_MS 100
1098
1099 /** Time to wait for ports to stabilise
1100 *
1101 * This is a policy decision.
1102 */
1103 #define USB_PORT_DELAY_MS 100
1104
1105 /** A USB device ID */
1106 struct usb_device_id {
1107 /** Name */
1108 const char *name;
1109 /** Vendor ID */
1110 uint16_t vendor;
1111 /** Product ID */
1112 uint16_t product;
1113 /** Class */
1114 struct usb_class class;
1115 };
1116
1117 /** Match-anything ID */
1118 #define USB_ANY_ID 0xffff
1119
1120 /** A USB driver */
1121 struct usb_driver {
1122 /** USB ID table */
1123 struct usb_device_id *ids;
1124 /** Number of entries in ID table */
1125 unsigned int id_count;
1126 /**
1127 * Probe device
1128 *
1129 * @v func USB function
1130 * @v config Configuration descriptor
1131 * @ret rc Return status code
1132 */
1133 int ( * probe ) ( struct usb_function *func,
1134 struct usb_configuration_descriptor *config );
1135 /**
1136 * Remove device
1137 *
1138 * @v func USB function
1139 */
1140 void ( * remove ) ( struct usb_function *func );
1141 };
1142
1143 /** USB driver table */
1144 #define USB_DRIVERS __table ( struct usb_driver, "usb_drivers" )
1145
1146 /** Declare a USB driver */
1147 #define __usb_driver __table_entry ( USB_DRIVERS, 01 )
1148
1149 #endif /* _IPXE_USB_H */