[usb] Select preferred USB device configuration based on driver score
[ipxe.git] / src / drivers / bus / usb.c
1 /*
2 * Copyright (C) 2014 Michael Brown <mbrown@fensystems.co.uk>.
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License as
6 * published by the Free Software Foundation; either version 2 of the
7 * License, or (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 * 02110-1301, USA.
18 *
19 * You can also choose to distribute this program under the terms of
20 * the Unmodified Binary Distribution Licence (as given in the file
21 * COPYING.UBDL), provided that you have satisfied its requirements.
22 */
23
24 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
25
26 #include <stdlib.h>
27 #include <stdio.h>
28 #include <string.h>
29 #include <strings.h>
30 #include <unistd.h>
31 #include <errno.h>
32 #include <assert.h>
33 #include <byteswap.h>
34 #include <ipxe/usb.h>
35 #include <ipxe/cdc.h>
36
37 /** @file
38 *
39 * Universal Serial Bus (USB)
40 *
41 */
42
43 /** List of USB buses */
44 struct list_head usb_buses = LIST_HEAD_INIT ( usb_buses );
45
46 /** List of changed ports */
47 static struct list_head usb_changed = LIST_HEAD_INIT ( usb_changed );
48
49 /** List of halted endpoints */
50 static struct list_head usb_halted = LIST_HEAD_INIT ( usb_halted );
51
52 /******************************************************************************
53 *
54 * Utility functions
55 *
56 ******************************************************************************
57 */
58
59 /**
60 * Get USB speed name (for debugging)
61 *
62 * @v speed Speed
63 * @ret name Speed name
64 */
65 static inline const char * usb_speed_name ( unsigned int speed ) {
66 static const char *exponents[4] = { "", "k", "M", "G" };
67 static char buf[ 10 /* "xxxxxXbps" + NUL */ ];
68 unsigned int mantissa;
69 unsigned int exponent;
70
71 /* Extract mantissa and exponent */
72 mantissa = USB_SPEED_MANTISSA ( speed );
73 exponent = USB_SPEED_EXPONENT ( speed );
74
75 /* Name speed */
76 switch ( speed ) {
77 case USB_SPEED_NONE: return "DETACHED";
78 case USB_SPEED_LOW: return "low";
79 case USB_SPEED_FULL: return "full";
80 case USB_SPEED_HIGH: return "high";
81 case USB_SPEED_SUPER: return "super";
82 default:
83 snprintf ( buf, sizeof ( buf ), "%d%sbps",
84 mantissa, exponents[exponent] );
85 return buf;
86 }
87 }
88
89 /**
90 * Transcribe USB BCD-coded value (for debugging)
91 *
92 * @v bcd BCD-coded value
93 * @ret string Transcribed value
94 */
95 static inline const char * usb_bcd ( uint16_t bcd ) {
96 static char buf[ 6 /* "xx.xx" + NUL */ ];
97 uint8_t high = ( bcd >> 8 );
98 uint8_t low = ( bcd >> 0 );
99
100 snprintf ( buf, sizeof ( buf ), "%x.%02x", high, low );
101 return buf;
102 }
103
104 /******************************************************************************
105 *
106 * USB descriptors
107 *
108 ******************************************************************************
109 */
110
111 /**
112 * Locate USB interface association descriptor
113 *
114 * @v config Configuraton descriptor
115 * @v first First interface number
116 * @ret desc Interface association descriptor, or NULL if not found
117 */
118 static struct usb_interface_association_descriptor *
119 usb_interface_association_descriptor ( struct usb_configuration_descriptor
120 *config,
121 unsigned int first ) {
122 struct usb_interface_association_descriptor *desc;
123
124 /* Find a matching interface association descriptor */
125 for_each_config_descriptor ( desc, config ) {
126 if ( ( desc->header.type ==
127 USB_INTERFACE_ASSOCIATION_DESCRIPTOR ) &&
128 ( desc->first == first ) )
129 return desc;
130 }
131 return NULL;
132 }
133
134 /**
135 * Locate USB interface descriptor
136 *
137 * @v config Configuraton descriptor
138 * @v interface Interface number
139 * @v alternate Alternate setting
140 * @ret desc Interface descriptor, or NULL if not found
141 */
142 struct usb_interface_descriptor *
143 usb_interface_descriptor ( struct usb_configuration_descriptor *config,
144 unsigned int interface, unsigned int alternate ) {
145 struct usb_interface_descriptor *desc;
146
147 /* Find a matching interface descriptor */
148 for_each_config_descriptor ( desc, config ) {
149 if ( ( desc->header.type == USB_INTERFACE_DESCRIPTOR ) &&
150 ( desc->interface == interface ) &&
151 ( desc->alternate == alternate ) )
152 return desc;
153 }
154 return NULL;
155 }
156
157 /**
158 * Locate USB endpoint descriptor
159 *
160 * @v config Configuration descriptor
161 * @v interface Interface descriptor
162 * @v type Endpoint (internal) type
163 * @v index Endpoint index
164 * @ret desc Descriptor, or NULL if not found
165 */
166 struct usb_endpoint_descriptor *
167 usb_endpoint_descriptor ( struct usb_configuration_descriptor *config,
168 struct usb_interface_descriptor *interface,
169 unsigned int type, unsigned int index ) {
170 struct usb_endpoint_descriptor *desc;
171 unsigned int attributes = ( type & USB_ENDPOINT_ATTR_TYPE_MASK );
172 unsigned int direction = ( type & USB_DIR_IN );
173
174 /* Find a matching endpoint descriptor */
175 for_each_interface_descriptor ( desc, config, interface ) {
176 if ( ( desc->header.type == USB_ENDPOINT_DESCRIPTOR ) &&
177 ( ( desc->attributes &
178 USB_ENDPOINT_ATTR_TYPE_MASK ) == attributes ) &&
179 ( ( desc->endpoint & USB_DIR_IN ) == direction ) &&
180 ( index-- == 0 ) )
181 return desc;
182 }
183 return NULL;
184 }
185
186 /**
187 * Locate USB endpoint companion descriptor
188 *
189 * @v config Configuration descriptor
190 * @v desc Endpoint descriptor
191 * @ret descx Companion descriptor, or NULL if not found
192 */
193 struct usb_endpoint_companion_descriptor *
194 usb_endpoint_companion_descriptor ( struct usb_configuration_descriptor *config,
195 struct usb_endpoint_descriptor *desc ) {
196 struct usb_endpoint_companion_descriptor *descx;
197
198 /* Get companion descriptor, if present */
199 descx = container_of ( usb_next_descriptor ( &desc->header ),
200 struct usb_endpoint_companion_descriptor,
201 header );
202 return ( ( usb_is_within_config ( config, &descx->header ) &&
203 descx->header.type == USB_ENDPOINT_COMPANION_DESCRIPTOR )
204 ? descx : NULL );
205 }
206
207 /******************************************************************************
208 *
209 * USB endpoint
210 *
211 ******************************************************************************
212 */
213
214 /**
215 * Get USB endpoint name (for debugging)
216 *
217 * @v ep USB endpoint
218 * @ret name Endpoint name
219 */
220 const char * usb_endpoint_name ( struct usb_endpoint *ep ) {
221 static char buf[ 9 /* "EPxx OUT" + NUL */ ];
222 unsigned int address = ep->address;
223
224 snprintf ( buf, sizeof ( buf ), "EP%d%s",
225 ( address & USB_ENDPOINT_MAX ),
226 ( address ?
227 ( ( address & USB_ENDPOINT_IN ) ? " IN" : " OUT" ) : "" ));
228 return buf;
229 }
230
231 /**
232 * Describe USB endpoint from device configuration
233 *
234 * @v ep USB endpoint
235 * @v config Configuration descriptor
236 * @v interface Interface descriptor
237 * @v type Endpoint (internal) type
238 * @v index Endpoint index
239 * @ret rc Return status code
240 */
241 int usb_endpoint_described ( struct usb_endpoint *ep,
242 struct usb_configuration_descriptor *config,
243 struct usb_interface_descriptor *interface,
244 unsigned int type, unsigned int index ) {
245 struct usb_device *usb = ep->usb;
246 struct usb_port *port = usb->port;
247 struct usb_endpoint_descriptor *desc;
248 struct usb_endpoint_companion_descriptor *descx;
249 unsigned int sizes;
250 unsigned int burst;
251 unsigned int interval;
252 size_t mtu;
253
254 /* Locate endpoint descriptor */
255 desc = usb_endpoint_descriptor ( config, interface, type, index );
256 if ( ! desc )
257 return -ENOENT;
258
259 /* Locate companion descriptor, if any */
260 descx = usb_endpoint_companion_descriptor ( config, desc );
261
262 /* Calculate MTU and burst size */
263 sizes = le16_to_cpu ( desc->sizes );
264 mtu = USB_ENDPOINT_MTU ( sizes );
265 burst = ( descx ? descx->burst : USB_ENDPOINT_BURST ( sizes ) );
266
267 /* Calculate interval */
268 if ( ( type & USB_ENDPOINT_ATTR_TYPE_MASK ) ==
269 USB_ENDPOINT_ATTR_INTERRUPT ) {
270 if ( port->speed >= USB_SPEED_HIGH ) {
271 /* 2^(desc->interval-1) is a microframe count */
272 interval = ( 1 << ( desc->interval - 1 ) );
273 } else {
274 /* desc->interval is a (whole) frame count */
275 interval = ( desc->interval << 3 );
276 }
277 } else {
278 /* desc->interval is a microframe count */
279 interval = desc->interval;
280 }
281
282 /* Describe endpoint */
283 usb_endpoint_describe ( ep, desc->endpoint, desc->attributes,
284 mtu, burst, interval );
285 return 0;
286 }
287
288 /**
289 * Open USB endpoint
290 *
291 * @v ep USB endpoint
292 * @ret rc Return status code
293 */
294 int usb_endpoint_open ( struct usb_endpoint *ep ) {
295 struct usb_device *usb = ep->usb;
296 unsigned int idx = USB_ENDPOINT_IDX ( ep->address );
297 int rc;
298
299 /* Populate host controller operations */
300 ep->host = &usb->port->hub->bus->op->endpoint;
301
302 /* Add to endpoint list */
303 if ( usb->ep[idx] != NULL ) {
304 DBGC ( usb, "USB %s %s is already open\n",
305 usb->name, usb_endpoint_name ( ep ) );
306 rc = -EALREADY;
307 goto err_already;
308 }
309 usb->ep[idx] = ep;
310 INIT_LIST_HEAD ( &ep->halted );
311
312 /* Open endpoint */
313 if ( ( rc = ep->host->open ( ep ) ) != 0 ) {
314 DBGC ( usb, "USB %s %s could not open: %s\n", usb->name,
315 usb_endpoint_name ( ep ), strerror ( rc ) );
316 goto err_open;
317 }
318 ep->open = 1;
319
320 DBGC2 ( usb, "USB %s %s opened with MTU %zd, burst %d, interval %d\n",
321 usb->name, usb_endpoint_name ( ep ), ep->mtu, ep->burst,
322 ep->interval );
323 return 0;
324
325 ep->open = 0;
326 ep->host->close ( ep );
327 err_open:
328 usb->ep[idx] = NULL;
329 err_already:
330 if ( ep->max )
331 usb_flush ( ep );
332 return rc;
333 }
334
335 /**
336 * Clear transaction translator (if applicable)
337 *
338 * @v ep USB endpoint
339 * @ret rc Return status code
340 */
341 static int usb_endpoint_clear_tt ( struct usb_endpoint *ep ) {
342 struct usb_device *usb = ep->usb;
343 struct usb_port *tt;
344 int rc;
345
346 /* Do nothing if this is a periodic endpoint */
347 if ( ep->attributes & USB_ENDPOINT_ATTR_PERIODIC )
348 return 0;
349
350 /* Do nothing if this endpoint is not behind a transaction translator */
351 tt = usb_transaction_translator ( usb );
352 if ( ! tt )
353 return 0;
354
355 /* Clear transaction translator buffer */
356 if ( ( rc = tt->hub->driver->clear_tt ( tt->hub, tt, ep ) ) != 0 ) {
357 DBGC ( usb, "USB %s %s could not clear transaction translator: "
358 "%s\n", usb->name, usb_endpoint_name ( ep ),
359 strerror ( rc ) );
360 return rc;
361 }
362
363 return 0;
364 }
365
366 /**
367 * Close USB endpoint
368 *
369 * @v ep USB endpoint
370 */
371 void usb_endpoint_close ( struct usb_endpoint *ep ) {
372 struct usb_device *usb = ep->usb;
373 unsigned int idx = USB_ENDPOINT_IDX ( ep->address );
374
375 /* Sanity checks */
376 assert ( usb->ep[idx] == ep );
377
378 /* Close endpoint */
379 ep->open = 0;
380 ep->host->close ( ep );
381 assert ( ep->fill == 0 );
382
383 /* Remove from endpoint list */
384 usb->ep[idx] = NULL;
385 list_del ( &ep->halted );
386
387 /* Discard any recycled buffers, if applicable */
388 if ( ep->max )
389 usb_flush ( ep );
390
391 /* Clear transaction translator, if applicable */
392 usb_endpoint_clear_tt ( ep );
393 }
394
395 /**
396 * Reset USB endpoint
397 *
398 * @v ep USB endpoint
399 * @ret rc Return status code
400 */
401 static int usb_endpoint_reset ( struct usb_endpoint *ep ) {
402 struct usb_device *usb = ep->usb;
403 unsigned int type;
404 int rc;
405
406 /* Sanity check */
407 assert ( ! list_empty ( &ep->halted ) );
408
409 /* Reset endpoint */
410 if ( ( rc = ep->host->reset ( ep ) ) != 0 ) {
411 DBGC ( usb, "USB %s %s could not reset: %s\n",
412 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
413 return rc;
414 }
415
416 /* Clear transaction translator, if applicable */
417 if ( ( rc = usb_endpoint_clear_tt ( ep ) ) != 0 )
418 return rc;
419
420 /* Clear endpoint halt, if applicable */
421 type = ( ep->attributes & USB_ENDPOINT_ATTR_TYPE_MASK );
422 if ( ( type != USB_ENDPOINT_ATTR_CONTROL ) &&
423 ( ( rc = usb_clear_feature ( usb, USB_RECIP_ENDPOINT,
424 USB_ENDPOINT_HALT,
425 ep->address ) ) != 0 ) ) {
426 DBGC ( usb, "USB %s %s could not clear endpoint halt: %s\n",
427 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
428 return rc;
429 }
430
431 /* Remove from list of halted endpoints */
432 list_del ( &ep->halted );
433 INIT_LIST_HEAD ( &ep->halted );
434
435 DBGC ( usb, "USB %s %s reset\n",
436 usb->name, usb_endpoint_name ( ep ) );
437 return 0;
438 }
439
440 /**
441 * Update endpoint MTU
442 *
443 * @v ep USB endpoint
444 * @v mtu New MTU
445 * @ret rc Return status code
446 */
447 static int usb_endpoint_mtu ( struct usb_endpoint *ep, size_t mtu ) {
448 struct usb_device *usb = ep->usb;
449 int rc;
450
451 /* Update MTU */
452 ep->mtu = mtu;
453 if ( ( rc = ep->host->mtu ( ep ) ) != 0 ) {
454 DBGC ( usb, "USB %s %s could not update MTU: %s\n",
455 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
456 return rc;
457 }
458
459 return 0;
460 }
461
462 /**
463 * Enqueue USB message transfer
464 *
465 * @v ep USB endpoint
466 * @v request Request
467 * @v value Value parameter
468 * @v index Index parameter
469 * @v iobuf I/O buffer
470 * @ret rc Return status code
471 *
472 * The I/O buffer must have sufficient headroom to contain a setup
473 * packet.
474 */
475 int usb_message ( struct usb_endpoint *ep, unsigned int request,
476 unsigned int value, unsigned int index,
477 struct io_buffer *iobuf ) {
478 struct usb_device *usb = ep->usb;
479 struct usb_port *port = usb->port;
480 struct usb_setup_packet *packet;
481 size_t len = iob_len ( iobuf );
482 int rc;
483
484 /* Sanity check */
485 assert ( iob_headroom ( iobuf ) >= sizeof ( *packet ) );
486
487 /* Fail immediately if device has been unplugged */
488 if ( port->speed == USB_SPEED_NONE )
489 return -ENODEV;
490
491 /* Reset endpoint if required */
492 if ( ( ! list_empty ( &ep->halted ) ) &&
493 ( ( rc = usb_endpoint_reset ( ep ) ) != 0 ) )
494 return rc;
495
496 /* Zero input data buffer (if applicable) */
497 if ( request & USB_DIR_IN )
498 memset ( iobuf->data, 0, len );
499
500 /* Construct setup packet */
501 packet = iob_push ( iobuf, sizeof ( *packet ) );
502 packet->request = cpu_to_le16 ( request );
503 packet->value = cpu_to_le16 ( value );
504 packet->index = cpu_to_le16 ( index );
505 packet->len = cpu_to_le16 ( len );
506
507 /* Enqueue message transfer */
508 if ( ( rc = ep->host->message ( ep, iobuf ) ) != 0 ) {
509 DBGC ( usb, "USB %s %s could not enqueue message transfer: "
510 "%s\n", usb->name, usb_endpoint_name ( ep ),
511 strerror ( rc ) );
512 return rc;
513 }
514
515 /* Increment fill level */
516 ep->fill++;
517
518 return 0;
519 }
520
521 /**
522 * Enqueue USB stream transfer
523 *
524 * @v ep USB endpoint
525 * @v iobuf I/O buffer
526 * @v terminate Terminate using a short packet
527 * @ret rc Return status code
528 */
529 int usb_stream ( struct usb_endpoint *ep, struct io_buffer *iobuf,
530 int terminate ) {
531 struct usb_device *usb = ep->usb;
532 struct usb_port *port = usb->port;
533 int zlp;
534 int rc;
535
536 /* Fail immediately if device has been unplugged */
537 if ( port->speed == USB_SPEED_NONE )
538 return -ENODEV;
539
540 /* Reset endpoint if required */
541 if ( ( ! list_empty ( &ep->halted ) ) &&
542 ( ( rc = usb_endpoint_reset ( ep ) ) != 0 ) )
543 return rc;
544
545 /* Append a zero-length packet if necessary */
546 zlp = terminate;
547 if ( iob_len ( iobuf ) & ( ep->mtu - 1 ) )
548 zlp = 0;
549
550 /* Enqueue stream transfer */
551 if ( ( rc = ep->host->stream ( ep, iobuf, zlp ) ) != 0 ) {
552 DBGC ( usb, "USB %s %s could not enqueue stream transfer: %s\n",
553 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
554 return rc;
555 }
556
557 /* Increment fill level */
558 ep->fill++;
559
560 return 0;
561 }
562
563 /**
564 * Complete transfer (possibly with error)
565 *
566 * @v ep USB endpoint
567 * @v iobuf I/O buffer
568 * @v rc Completion status code
569 */
570 void usb_complete_err ( struct usb_endpoint *ep, struct io_buffer *iobuf,
571 int rc ) {
572 struct usb_device *usb = ep->usb;
573
574 /* Decrement fill level */
575 assert ( ep->fill > 0 );
576 ep->fill--;
577
578 /* Schedule reset, if applicable */
579 if ( ( rc != 0 ) && ep->open ) {
580 DBGC ( usb, "USB %s %s completion failed: %s\n",
581 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
582 list_del ( &ep->halted );
583 list_add_tail ( &ep->halted, &usb_halted );
584 }
585
586 /* Report completion */
587 ep->driver->complete ( ep, iobuf, rc );
588 }
589
590 /******************************************************************************
591 *
592 * Endpoint refilling
593 *
594 ******************************************************************************
595 */
596
597 /**
598 * Prefill endpoint recycled buffer list
599 *
600 * @v ep USB endpoint
601 * @ret rc Return status code
602 */
603 int usb_prefill ( struct usb_endpoint *ep ) {
604 struct io_buffer *iobuf;
605 size_t len = ( ep->len ? ep->len : ep->mtu );
606 unsigned int fill;
607 int rc;
608
609 /* Sanity checks */
610 assert ( ep->fill == 0 );
611 assert ( ep->max > 0 );
612 assert ( list_empty ( &ep->recycled ) );
613
614 /* Fill recycled buffer list */
615 for ( fill = 0 ; fill < ep->max ; fill++ ) {
616
617 /* Allocate I/O buffer */
618 iobuf = alloc_iob ( len );
619 if ( ! iobuf ) {
620 rc = -ENOMEM;
621 goto err_alloc;
622 }
623
624 /* Add to recycled buffer list */
625 list_add_tail ( &iobuf->list, &ep->recycled );
626 }
627
628 return 0;
629
630 err_alloc:
631 usb_flush ( ep );
632 return rc;
633 }
634
635 /**
636 * Refill endpoint
637 *
638 * @v ep USB endpoint
639 * @ret rc Return status code
640 */
641 int usb_refill ( struct usb_endpoint *ep ) {
642 struct io_buffer *iobuf;
643 size_t len = ( ep->len ? ep->len : ep->mtu );
644 int rc;
645
646 /* Sanity checks */
647 assert ( ep->open );
648 assert ( ep->max > 0 );
649
650 /* Refill endpoint */
651 while ( ep->fill < ep->max ) {
652
653 /* Get or allocate buffer */
654 if ( list_empty ( &ep->recycled ) ) {
655 /* Recycled buffer list is empty; allocate new buffer */
656 iobuf = alloc_iob ( len );
657 if ( ! iobuf )
658 return -ENOMEM;
659 } else {
660 /* Get buffer from recycled buffer list */
661 iobuf = list_first_entry ( &ep->recycled,
662 struct io_buffer, list );
663 assert ( iobuf != NULL );
664 list_del ( &iobuf->list );
665 }
666
667 /* Reset buffer to maximum size */
668 assert ( iob_len ( iobuf ) <= len );
669 iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
670
671 /* Enqueue buffer */
672 if ( ( rc = usb_stream ( ep, iobuf, 0 ) ) != 0 ) {
673 list_add ( &iobuf->list, &ep->recycled );
674 return rc;
675 }
676 }
677
678 return 0;
679 }
680
681 /**
682 * Discard endpoint recycled buffer list
683 *
684 * @v ep USB endpoint
685 */
686 void usb_flush ( struct usb_endpoint *ep ) {
687 struct io_buffer *iobuf;
688 struct io_buffer *tmp;
689
690 /* Sanity checks */
691 assert ( ! ep->open );
692 assert ( ep->max > 0 );
693
694 /* Free all I/O buffers */
695 list_for_each_entry_safe ( iobuf, tmp, &ep->recycled, list ) {
696 list_del ( &iobuf->list );
697 free_iob ( iobuf );
698 }
699 }
700
701 /******************************************************************************
702 *
703 * Control endpoint
704 *
705 ******************************************************************************
706 */
707
708 /** USB control transfer pseudo-header */
709 struct usb_control_pseudo_header {
710 /** Completion status */
711 int rc;
712 };
713
714 /**
715 * Complete USB control transfer
716 *
717 * @v ep USB endpoint
718 * @v iobuf I/O buffer
719 * @v rc Completion status code
720 */
721 static void usb_control_complete ( struct usb_endpoint *ep,
722 struct io_buffer *iobuf, int rc ) {
723 struct usb_device *usb = ep->usb;
724 struct usb_control_pseudo_header *pshdr;
725
726 /* Record completion status in buffer */
727 pshdr = iob_push ( iobuf, sizeof ( *pshdr ) );
728 pshdr->rc = rc;
729
730 /* Add to list of completed I/O buffers */
731 list_add_tail ( &iobuf->list, &usb->complete );
732 }
733
734 /** USB control endpoint driver operations */
735 static struct usb_endpoint_driver_operations usb_control_operations = {
736 .complete = usb_control_complete,
737 };
738
739 /**
740 * Issue USB control transaction
741 *
742 * @v usb USB device
743 * @v request Request
744 * @v value Value parameter
745 * @v index Index parameter
746 * @v data Data buffer (if any)
747 * @v len Length of data
748 * @ret rc Return status code
749 */
750 int usb_control ( struct usb_device *usb, unsigned int request,
751 unsigned int value, unsigned int index, void *data,
752 size_t len ) {
753 struct usb_bus *bus = usb->port->hub->bus;
754 struct usb_endpoint *ep = &usb->control;
755 struct io_buffer *iobuf;
756 struct io_buffer *cmplt;
757 union {
758 struct usb_setup_packet setup;
759 struct usb_control_pseudo_header pshdr;
760 } *headroom;
761 struct usb_control_pseudo_header *pshdr;
762 unsigned int i;
763 int rc;
764
765 /* Allocate I/O buffer */
766 iobuf = alloc_iob ( sizeof ( *headroom ) + len );
767 if ( ! iobuf ) {
768 rc = -ENOMEM;
769 goto err_alloc;
770 }
771 iob_reserve ( iobuf, sizeof ( *headroom ) );
772 iob_put ( iobuf, len );
773 if ( request & USB_DIR_IN ) {
774 memset ( data, 0, len );
775 } else {
776 memcpy ( iobuf->data, data, len );
777 }
778
779 /* Enqueue message */
780 if ( ( rc = usb_message ( ep, request, value, index, iobuf ) ) != 0 )
781 goto err_message;
782
783 /* Wait for completion */
784 for ( i = 0 ; i < USB_CONTROL_MAX_WAIT_MS ; i++ ) {
785
786 /* Poll bus */
787 usb_poll ( bus );
788
789 /* Check for completion */
790 while ( ( cmplt = list_first_entry ( &usb->complete,
791 struct io_buffer,
792 list ) ) ) {
793
794 /* Remove from completion list */
795 list_del ( &cmplt->list );
796
797 /* Extract and strip completion status */
798 pshdr = cmplt->data;
799 iob_pull ( cmplt, sizeof ( *pshdr ) );
800 rc = pshdr->rc;
801
802 /* Discard stale completions */
803 if ( cmplt != iobuf ) {
804 DBGC ( usb, "USB %s stale control completion: "
805 "%s\n", usb->name, strerror ( rc ) );
806 DBGC_HDA ( usb, 0, cmplt->data,
807 iob_len ( cmplt ) );
808 free_iob ( cmplt );
809 continue;
810 }
811
812 /* Fail immediately if completion was in error */
813 if ( rc != 0 ) {
814 DBGC ( usb, "USB %s control %04x:%04x:%04x "
815 "failed: %s\n", usb->name, request,
816 value, index, strerror ( rc ) );
817 free_iob ( cmplt );
818 return rc;
819 }
820
821 /* Copy completion to data buffer, if applicable */
822 assert ( iob_len ( cmplt ) <= len );
823 if ( request & USB_DIR_IN )
824 memcpy ( data, cmplt->data, iob_len ( cmplt ) );
825 free_iob ( cmplt );
826 return 0;
827 }
828
829 /* Delay */
830 mdelay ( 1 );
831 }
832
833 DBGC ( usb, "USB %s timed out waiting for control %04x:%04x:%04x\n",
834 usb->name, request, value, index );
835 return -ETIMEDOUT;
836
837 err_message:
838 free_iob ( iobuf );
839 err_alloc:
840 return rc;
841 }
842
843 /**
844 * Get USB string descriptor
845 *
846 * @v usb USB device
847 * @v index String index
848 * @v language Language ID
849 * @v buf Data buffer
850 * @v len Length of buffer
851 * @ret len String length (excluding NUL), or negative error
852 */
853 int usb_get_string_descriptor ( struct usb_device *usb, unsigned int index,
854 unsigned int language, char *buf, size_t len ) {
855 size_t max = ( len ? ( len - 1 /* NUL */ ) : 0 );
856 struct {
857 struct usb_descriptor_header header;
858 uint16_t character[max];
859 } __attribute__ (( packed )) *desc;
860 unsigned int actual;
861 unsigned int i;
862 int rc;
863
864 /* Allocate buffer for string */
865 desc = malloc ( sizeof ( *desc ) );
866 if ( ! desc ) {
867 rc = -ENOMEM;
868 goto err_alloc;
869 }
870
871 /* Get descriptor */
872 if ( ( rc = usb_get_descriptor ( usb, 0, USB_STRING_DESCRIPTOR, index,
873 language, &desc->header,
874 sizeof ( *desc ) ) ) != 0 )
875 goto err_get_descriptor;
876
877 /* Copy to buffer */
878 actual = ( ( desc->header.len - sizeof ( desc->header ) ) /
879 sizeof ( desc->character[0] ) );
880 for ( i = 0 ; ( ( i < actual ) && ( i < max ) ) ; i++ )
881 buf[i] = le16_to_cpu ( desc->character[i] );
882 if ( len )
883 buf[i] = '\0';
884
885 /* Free buffer */
886 free ( desc );
887
888 return actual;
889
890 err_get_descriptor:
891 free ( desc );
892 err_alloc:
893 return rc;
894 }
895
896 /******************************************************************************
897 *
898 * USB device driver
899 *
900 ******************************************************************************
901 */
902
903 /**
904 * Get USB configuration descriptor
905 *
906 * @v usb USB device
907 * @v index Configuration index
908 * @ret config Configuration descriptor
909 * @ret rc Return status code
910 *
911 * The configuration descriptor is dynamically allocated and must
912 * eventually be freed by the caller.
913 */
914 static int
915 usb_config_descriptor ( struct usb_device *usb, unsigned int index,
916 struct usb_configuration_descriptor **config ) {
917 struct usb_configuration_descriptor partial;
918 size_t len;
919 int rc;
920
921 /* Read first part of configuration descriptor to get size */
922 if ( ( rc = usb_get_config_descriptor ( usb, index, &partial,
923 sizeof ( partial ) ) ) != 0 ) {
924 DBGC ( usb, "USB %s could not get configuration descriptor %d: "
925 "%s\n", usb->name, index, strerror ( rc ) );
926 goto err_get_partial;
927 }
928 len = le16_to_cpu ( partial.len );
929 if ( len < sizeof ( partial ) ) {
930 DBGC ( usb, "USB %s underlength configuraton descriptor %d\n",
931 usb->name, index );
932 rc = -EINVAL;
933 goto err_partial_len;
934 }
935
936 /* Allocate buffer for whole configuration descriptor */
937 *config = malloc ( len );
938 if ( ! *config ) {
939 rc = -ENOMEM;
940 goto err_alloc_config;
941 }
942
943 /* Read whole configuration descriptor */
944 if ( ( rc = usb_get_config_descriptor ( usb, index, *config,
945 len ) ) != 0 ) {
946 DBGC ( usb, "USB %s could not get configuration descriptor %d: "
947 "%s\n", usb->name, index, strerror ( rc ) );
948 goto err_get_config_descriptor;
949 }
950 if ( (*config)->len != partial.len ) {
951 DBGC ( usb, "USB %s bad configuration descriptor %d length\n",
952 usb->name, index );
953 rc = -EINVAL;
954 goto err_config_len;
955 }
956
957 return 0;
958
959 err_config_len:
960 err_get_config_descriptor:
961 free ( *config );
962 err_alloc_config:
963 err_partial_len:
964 err_get_partial:
965 return rc;
966 }
967
968 /**
969 * Describe USB function
970 *
971 * @v usb USB device
972 * @v config Configuration descriptor
973 * @v first First interface number
974 * @v interfaces Interface list to fill in
975 * @v desc Function descriptor to fill in
976 * @ret rc Return status code
977 */
978 static int usb_describe ( struct usb_device *usb,
979 struct usb_configuration_descriptor *config,
980 unsigned int first, uint8_t *interfaces,
981 struct usb_function_descriptor *desc ) {
982 struct usb_interface_association_descriptor *association;
983 struct usb_interface_descriptor *interface;
984 struct cdc_union_descriptor *cdc_union;
985 unsigned int i;
986
987 /* Fill in vendor and product ID */
988 desc->vendor = le16_to_cpu ( usb->device.vendor );
989 desc->product = le16_to_cpu ( usb->device.product );
990
991 /* First, look for an interface association descriptor */
992 association = usb_interface_association_descriptor ( config, first );
993 if ( association ) {
994
995 /* Sanity check */
996 assert ( association->first == first );
997 if ( ( first + association->count ) > config->interfaces ) {
998 DBGC ( usb, "USB %s has invalid association [%d-%d)\n",
999 usb->name, first, ( first + association->count));
1000 return -ERANGE;
1001 }
1002
1003 /* Describe function */
1004 memcpy ( &desc->class, &association->class,
1005 sizeof ( desc->class ) );
1006 desc->count = association->count;
1007 for ( i = 0 ; i < association->count ; i++ )
1008 interfaces[i] = ( first + i );
1009 return 0;
1010 }
1011
1012 /* Next, look for an interface descriptor */
1013 interface = usb_interface_descriptor ( config, first, 0 );
1014 if ( ! interface ) {
1015 DBGC ( usb, "USB %s has no descriptor for interface %d\n",
1016 usb->name, first );
1017 return -ENOENT;
1018 }
1019
1020 /* Describe function */
1021 memcpy ( &desc->class, &interface->class, sizeof ( desc->class ) );
1022 desc->count = 1;
1023 interfaces[0] = first;
1024
1025 /* Look for a CDC union descriptor, if applicable */
1026 if ( ( desc->class.class == USB_CLASS_CDC ) &&
1027 ( cdc_union = cdc_union_descriptor ( config, interface ) ) ) {
1028
1029 /* Determine interface count */
1030 desc->count = ( ( cdc_union->header.len -
1031 offsetof ( typeof ( *cdc_union ),
1032 interface[0] ) ) /
1033 sizeof ( cdc_union->interface[0] ) );
1034 if ( desc->count > config->interfaces ) {
1035 DBGC ( usb, "USB %s has invalid union functional "
1036 "descriptor with %d interfaces\n",
1037 usb->name, desc->count );
1038 return -ERANGE;
1039 }
1040
1041 /* Describe function */
1042 for ( i = 0 ; i < desc->count ; i++ ) {
1043 if ( cdc_union->interface[i] >= config->interfaces ) {
1044 DBGC ( usb, "USB %s has invalid union "
1045 "functional descriptor covering "
1046 "interface %d\n", usb->name,
1047 cdc_union->interface[i] );
1048 return -ERANGE;
1049 }
1050 interfaces[i] = cdc_union->interface[i];
1051 }
1052
1053 return 0;
1054 }
1055
1056 return 0;
1057 }
1058
1059 /**
1060 * Update list of used interface
1061 *
1062 * @v usb USB device
1063 * @v count Number of interfaces
1064 * @v interface List of interfaces
1065 * @v used List of already-used interfaces
1066 * @ret rc Return status code
1067 */
1068 static int usb_used ( struct usb_device *usb, unsigned int count,
1069 uint8_t *interface, uint8_t *used ) {
1070 unsigned int i;
1071
1072 for ( i = 0 ; i < count ; i++ ) {
1073 if ( used[interface[i]] ) {
1074 DBGC ( usb, "USB %s interface %d already in use\n",
1075 usb->name, interface[i] );
1076 return -EINVAL;
1077 }
1078 used[interface[i]] = 1;
1079 }
1080 return 0;
1081 }
1082
1083 /**
1084 * Find USB device driver
1085 *
1086 * @v desc Function descriptor
1087 * @ret id USB device ID, or NULL
1088 * @ret driver USB device driver, or NULL
1089 */
1090 struct usb_driver * usb_find_driver ( struct usb_function_descriptor *desc,
1091 struct usb_device_id **id ) {
1092 struct usb_driver *driver;
1093 unsigned int i;
1094
1095 /* Look for a matching driver */
1096 for_each_table_entry ( driver, USB_DRIVERS ) {
1097 for ( i = 0 ; i < driver->id_count ; i++ ) {
1098
1099 /* Check for a matching ID */
1100 *id = &driver->ids[i];
1101 if ( ( ( (*id)->vendor == desc->vendor ) ||
1102 ( (*id)->vendor == USB_ANY_ID ) ) &&
1103 ( ( (*id)->product == desc->product ) ||
1104 ( (*id)->product == USB_ANY_ID ) ) &&
1105 ( (*id)->class.class == desc->class.class ) &&
1106 ( (*id)->class.subclass == desc->class.subclass )&&
1107 ( (*id)->class.protocol == desc->class.protocol ) )
1108 return driver;
1109 }
1110 }
1111
1112 /* Not found */
1113 *id = NULL;
1114 return NULL;
1115 }
1116
1117 /**
1118 * Get USB device configuration score
1119 *
1120 * @v usb USB device
1121 * @v config Configuration descriptor
1122 * @ret score Device configuration score, or negative error
1123 */
1124 static int usb_score ( struct usb_device *usb,
1125 struct usb_configuration_descriptor *config ) {
1126 uint8_t used[config->interfaces];
1127 uint8_t interface[config->interfaces];
1128 struct usb_function_descriptor desc;
1129 struct usb_driver *driver;
1130 struct usb_device_id *id;
1131 unsigned int first;
1132 unsigned int score = 0;
1133 int rc;
1134
1135 /* Identify each function in turn */
1136 memset ( used, 0, sizeof ( used ) );
1137 for ( first = 0 ; first < config->interfaces ; first++ ) {
1138
1139 /* Skip interfaces already used */
1140 if ( used[first] )
1141 continue;
1142
1143 /* Describe function */
1144 if ( ( rc = usb_describe ( usb, config, first, interface,
1145 &desc ) ) != 0 )
1146 return rc;
1147
1148 /* Update used interfaces */
1149 if ( ( rc = usb_used ( usb, desc.count, interface,
1150 used ) ) != 0 )
1151 return rc;
1152
1153 /* Look for a driver for this function */
1154 driver = usb_find_driver ( &desc, &id );
1155 if ( driver )
1156 score += driver->score;
1157 }
1158
1159 return score;
1160 }
1161
1162 /**
1163 * Probe USB device driver
1164 *
1165 * @v func USB function
1166 * @v config Configuration descriptor
1167 * @ret rc Return status code
1168 */
1169 static int usb_probe ( struct usb_function *func,
1170 struct usb_configuration_descriptor *config ) {
1171 struct usb_device *usb = func->usb;
1172 struct usb_driver *driver;
1173 struct usb_device_id *id;
1174 int rc;
1175
1176 /* Identify driver */
1177 driver = usb_find_driver ( &func->desc, &id );
1178 if ( ! driver ) {
1179 DBGC ( usb, "USB %s %04x:%04x class %d:%d:%d has no driver\n",
1180 func->name, func->desc.vendor, func->desc.product,
1181 func->desc.class.class, func->desc.class.subclass,
1182 func->desc.class.protocol );
1183 return -ENOENT;
1184 }
1185
1186 /* Probe driver */
1187 if ( ( rc = driver->probe ( func, config ) ) != 0 ) {
1188 DBGC ( usb, "USB %s failed to probe driver %s: %s\n",
1189 func->name, id->name, strerror ( rc ) );
1190 return rc;
1191 }
1192
1193 /* Record driver */
1194 func->driver = driver;
1195 func->dev.driver_name = id->name;
1196 return 0;
1197 }
1198
1199 /**
1200 * Remove USB device driver
1201 *
1202 * @v func USB function
1203 */
1204 static void usb_remove ( struct usb_function *func ) {
1205
1206 /* Remove driver */
1207 func->driver->remove ( func );
1208 }
1209
1210 /**
1211 * Probe all USB device drivers
1212 *
1213 * @v usb USB device
1214 * @v config Configuration descriptor
1215 */
1216 static void
1217 usb_probe_all ( struct usb_device *usb,
1218 struct usb_configuration_descriptor *config ) {
1219 struct usb_bus *bus = usb->port->hub->bus;
1220 struct usb_function *func;
1221 uint8_t used[config->interfaces];
1222 unsigned int first;
1223 unsigned int i;
1224 int rc;
1225
1226 /* Identify each function in turn */
1227 memset ( used, 0, sizeof ( used ) );
1228 for ( first = 0 ; first < config->interfaces ; first++ ) {
1229
1230 /* Skip interfaces already used */
1231 if ( used[first] )
1232 continue;
1233
1234 /* Allocate and initialise structure */
1235 func = zalloc ( sizeof ( *func ) +
1236 ( config->interfaces *
1237 sizeof ( func->interface[0] ) ) );
1238 if ( ! func )
1239 goto err_alloc;
1240 func->name = func->dev.name;
1241 func->usb = usb;
1242 func->dev.desc.bus_type = BUS_TYPE_USB;
1243 func->dev.desc.location = usb->address;
1244 func->dev.desc.vendor = le16_to_cpu ( usb->device.vendor );
1245 func->dev.desc.device = le16_to_cpu ( usb->device.product );
1246 snprintf ( func->dev.name, sizeof ( func->dev.name ),
1247 "%s-%d.%d", usb->name, config->config, first );
1248 INIT_LIST_HEAD ( &func->dev.children );
1249 func->dev.parent = bus->dev;
1250 list_add_tail ( &func->list, &usb->functions );
1251
1252 /* Identify function */
1253 if ( ( rc = usb_describe ( usb, config, first, func->interface,
1254 &func->desc ) ) != 0 )
1255 goto err_describe;
1256 assert ( func->desc.count <= config->interfaces );
1257
1258 /* Mark interfaces as used */
1259 if ( ( rc = usb_used ( usb, func->desc.count, func->interface,
1260 used ) ) != 0 )
1261 goto err_used;
1262
1263 /* Probe device driver */
1264 if ( ( rc = usb_probe ( func, config ) ) != 0 )
1265 goto err_probe;
1266 DBGC ( usb, "USB %s %04x:%04x class %d:%d:%d interfaces ",
1267 func->name, func->desc.vendor, func->desc.product,
1268 func->desc.class.class, func->desc.class.subclass,
1269 func->desc.class.protocol );
1270 for ( i = 0 ; i < func->desc.count ; i++ )
1271 DBGC ( usb, "%s%d", ( i ? "," : "" ),
1272 func->interface[i] );
1273 DBGC ( usb, " using driver %s\n", func->dev.driver_name );
1274
1275 /* Add to device hierarchy */
1276 list_add_tail ( &func->dev.siblings, &bus->dev->children );
1277
1278 continue;
1279
1280 list_del ( &func->dev.siblings );
1281 usb_remove ( func );
1282 err_probe:
1283 err_used:
1284 err_describe:
1285 list_del ( &func->list );
1286 free ( func );
1287 err_alloc:
1288 /* Continue registering other functions */
1289 continue;
1290 }
1291 }
1292
1293 /**
1294 * Remove all device drivers
1295 *
1296 * @v usb USB device
1297 */
1298 static void usb_remove_all ( struct usb_device *usb ) {
1299 struct usb_function *func;
1300 struct usb_function *tmp;
1301
1302 /* Remove all functions */
1303 list_for_each_entry_safe ( func, tmp, &usb->functions, list ) {
1304
1305 /* Remove device driver */
1306 usb_remove ( func );
1307
1308 /* Remove from device hierarchy */
1309 assert ( list_empty ( &func->dev.children ) );
1310 list_del ( &func->dev.siblings );
1311
1312 /* Remove from list of functions */
1313 list_del ( &func->list );
1314
1315 /* Free function */
1316 free ( func );
1317 }
1318 }
1319
1320 /**
1321 * Clear USB device configuration
1322 *
1323 * @v usb USB device
1324 */
1325 static void usb_deconfigure ( struct usb_device *usb ) {
1326 unsigned int i;
1327
1328 /* Remove device drivers */
1329 usb_remove_all ( usb );
1330
1331 /* Sanity checks */
1332 for ( i = 0 ; i < ( sizeof ( usb->ep ) / sizeof ( usb->ep[0] ) ) ; i++){
1333 if ( i != USB_ENDPOINT_IDX ( USB_EP0_ADDRESS ) )
1334 assert ( usb->ep[i] == NULL );
1335 }
1336
1337 /* Clear device configuration */
1338 usb_set_configuration ( usb, 0 );
1339 }
1340
1341 /**
1342 * Choose our preferred USB device configuration
1343 *
1344 * @v usb USB device
1345 * @ret rc Return status code
1346 */
1347 static int usb_autoconfigure ( struct usb_device *usb ) {
1348 struct usb_configuration_descriptor *config;
1349 unsigned int preferred = 0;
1350 unsigned int index;
1351 int score;
1352 int best = 0;
1353 int rc;
1354
1355 /* Calculate driver score for each configuration index */
1356 for ( index = 0 ; index < usb->device.configurations ; index++ ) {
1357
1358 /* Read configuration descriptor */
1359 if ( ( rc = usb_config_descriptor ( usb, index,
1360 &config ) ) != 0 )
1361 goto err_config;
1362
1363 /* Get score for this configuration */
1364 score = usb_score ( usb, config );
1365 if ( score < 0 ) {
1366 rc = score;
1367 goto err_score;
1368 }
1369 DBGC2 ( usb, "USB %s configuration %d score %d\n",
1370 usb->name, config->config, score );
1371
1372 /* Record as preferred configuration, if applicable */
1373 if ( score > best ) {
1374 best = score;
1375 preferred = index;
1376 }
1377
1378 /* Free configuration descriptor */
1379 free ( config );
1380 config = NULL;
1381 }
1382
1383 /* Read preferred configuration descriptor */
1384 if ( ( rc = usb_config_descriptor ( usb, preferred, &config ) ) != 0 )
1385 goto err_preferred;
1386
1387 /* Set configuration */
1388 if ( ( rc = usb_set_configuration ( usb, config->config ) ) != 0){
1389 DBGC ( usb, "USB %s could not set configuration %d: %s\n",
1390 usb->name, config->config, strerror ( rc ) );
1391 goto err_set_configuration;
1392 }
1393
1394 /* Probe USB device drivers */
1395 usb_probe_all ( usb, config );
1396
1397 /* Free configuration descriptor */
1398 free ( config );
1399
1400 return 0;
1401
1402 usb_remove_all ( usb );
1403 usb_set_configuration ( usb, 0 );
1404 err_set_configuration:
1405 free ( config );
1406 err_preferred:
1407 return rc;
1408
1409 err_score:
1410 free ( config );
1411 err_config:
1412 return rc;
1413 }
1414
1415 /******************************************************************************
1416 *
1417 * USB device
1418 *
1419 ******************************************************************************
1420 */
1421
1422 /**
1423 * Allocate USB device
1424 *
1425 * @v port USB port
1426 * @ret usb USB device, or NULL on allocation failure
1427 */
1428 static struct usb_device * alloc_usb ( struct usb_port *port ) {
1429 struct usb_hub *hub = port->hub;
1430 struct usb_bus *bus = hub->bus;
1431 struct usb_device *usb;
1432
1433 /* Allocate and initialise structure */
1434 usb = zalloc ( sizeof ( *usb ) );
1435 if ( ! usb )
1436 return NULL;
1437 snprintf ( usb->name, sizeof ( usb->name ), "%s%c%d", hub->name,
1438 ( hub->usb ? '.' : '-' ), port->address );
1439 usb->port = port;
1440 INIT_LIST_HEAD ( &usb->functions );
1441 usb->host = &bus->op->device;
1442 usb_endpoint_init ( &usb->control, usb, &usb_control_operations );
1443 INIT_LIST_HEAD ( &usb->complete );
1444
1445 return usb;
1446 }
1447
1448 /**
1449 * Register USB device
1450 *
1451 * @v usb USB device
1452 * @ret rc Return status code
1453 */
1454 static int register_usb ( struct usb_device *usb ) {
1455 struct usb_port *port = usb->port;
1456 struct usb_hub *hub = port->hub;
1457 struct usb_bus *bus = hub->bus;
1458 unsigned int protocol;
1459 size_t mtu;
1460 int rc;
1461
1462 /* Add to port */
1463 if ( port->usb != NULL ) {
1464 DBGC ( hub, "USB hub %s port %d is already registered to %s\n",
1465 hub->name, port->address, port->usb->name );
1466 rc = -EALREADY;
1467 goto err_already;
1468 }
1469 port->usb = usb;
1470
1471 /* Add to bus device list */
1472 list_add_tail ( &usb->list, &bus->devices );
1473
1474 /* Enable device */
1475 if ( ( rc = hub->driver->enable ( hub, port ) ) != 0 ) {
1476 DBGC ( hub, "USB hub %s port %d could not enable: %s\n",
1477 hub->name, port->address, strerror ( rc ) );
1478 goto err_enable;
1479 }
1480
1481 /* Allow recovery interval since port may have been reset */
1482 mdelay ( USB_RESET_RECOVER_DELAY_MS );
1483
1484 /* Get device speed */
1485 if ( ( rc = hub->driver->speed ( hub, port ) ) != 0 ) {
1486 DBGC ( hub, "USB hub %s port %d could not get speed: %s\n",
1487 hub->name, port->address, strerror ( rc ) );
1488 goto err_speed;
1489 }
1490 DBGC2 ( usb, "USB %s attached as %s-speed device\n",
1491 usb->name, usb_speed_name ( port->speed ) );
1492
1493 /* Open device */
1494 if ( ( rc = usb->host->open ( usb ) ) != 0 ) {
1495 DBGC ( usb, "USB %s could not open: %s\n",
1496 usb->name, strerror ( rc ) );
1497 goto err_open;
1498 }
1499
1500 /* Describe control endpoint */
1501 mtu = USB_EP0_DEFAULT_MTU ( port->speed );
1502 usb_endpoint_describe ( &usb->control, USB_EP0_ADDRESS,
1503 USB_EP0_ATTRIBUTES, mtu, USB_EP0_BURST,
1504 USB_EP0_INTERVAL );
1505
1506 /* Open control endpoint */
1507 if ( ( rc = usb_endpoint_open ( &usb->control ) ) != 0 )
1508 goto err_open_control;
1509 assert ( usb_endpoint ( usb, USB_EP0_ADDRESS ) == &usb->control );
1510
1511 /* Assign device address */
1512 if ( ( rc = usb->host->address ( usb ) ) != 0 ) {
1513 DBGC ( usb, "USB %s could not set address: %s\n",
1514 usb->name, strerror ( rc ) );
1515 goto err_address;
1516 }
1517 DBGC2 ( usb, "USB %s assigned address %d\n", usb->name, usb->address );
1518
1519 /* Allow recovery interval after Set Address command */
1520 mdelay ( USB_SET_ADDRESS_RECOVER_DELAY_MS );
1521
1522 /* Read first part of device descriptor to get EP0 MTU */
1523 if ( ( rc = usb_get_mtu ( usb, &usb->device ) ) != 0 ) {
1524 DBGC ( usb, "USB %s could not get MTU: %s\n",
1525 usb->name, strerror ( rc ) );
1526 goto err_get_mtu;
1527 }
1528
1529 /* Calculate EP0 MTU */
1530 protocol = le16_to_cpu ( usb->device.protocol );
1531 mtu = ( ( protocol < USB_PROTO_3_0 ) ?
1532 usb->device.mtu : ( 1 << usb->device.mtu ) );
1533 DBGC2 ( usb, "USB %s has control MTU %zd (guessed %zd)\n",
1534 usb->name, mtu, usb->control.mtu );
1535
1536 /* Update MTU */
1537 if ( ( rc = usb_endpoint_mtu ( &usb->control, mtu ) ) != 0 )
1538 goto err_mtu;
1539
1540 /* Read whole device descriptor */
1541 if ( ( rc = usb_get_device_descriptor ( usb, &usb->device ) ) != 0 ) {
1542 DBGC ( usb, "USB %s could not get device descriptor: %s\n",
1543 usb->name, strerror ( rc ) );
1544 goto err_get_device_descriptor;
1545 }
1546 DBGC ( usb, "USB %s addr %d %04x:%04x class %d:%d:%d (v%s, %s-speed, "
1547 "MTU %zd)\n", usb->name, usb->address,
1548 le16_to_cpu ( usb->device.vendor ),
1549 le16_to_cpu ( usb->device.product ), usb->device.class.class,
1550 usb->device.class.subclass, usb->device.class.protocol,
1551 usb_bcd ( le16_to_cpu ( usb->device.protocol ) ),
1552 usb_speed_name ( port->speed ), usb->control.mtu );
1553
1554 /* Configure device */
1555 if ( ( rc = usb_autoconfigure ( usb ) ) != 0 )
1556 goto err_autoconfigure;
1557
1558 return 0;
1559
1560 usb_deconfigure ( usb );
1561 err_autoconfigure:
1562 err_get_device_descriptor:
1563 err_mtu:
1564 err_get_mtu:
1565 err_address:
1566 usb_endpoint_close ( &usb->control );
1567 err_open_control:
1568 usb->host->close ( usb );
1569 err_open:
1570 err_speed:
1571 hub->driver->disable ( hub, port );
1572 err_enable:
1573 list_del ( &usb->list );
1574 port->usb = NULL;
1575 err_already:
1576 return rc;
1577 }
1578
1579 /**
1580 * Unregister USB device
1581 *
1582 * @v usb USB device
1583 */
1584 static void unregister_usb ( struct usb_device *usb ) {
1585 struct usb_port *port = usb->port;
1586 struct usb_hub *hub = port->hub;
1587 struct io_buffer *iobuf;
1588 struct io_buffer *tmp;
1589
1590 /* Sanity checks */
1591 assert ( port->usb == usb );
1592
1593 /* Clear device configuration */
1594 usb_deconfigure ( usb );
1595
1596 /* Close control endpoint */
1597 usb_endpoint_close ( &usb->control );
1598
1599 /* Discard any stale control completions */
1600 list_for_each_entry_safe ( iobuf, tmp, &usb->complete, list ) {
1601 list_del ( &iobuf->list );
1602 free_iob ( iobuf );
1603 }
1604
1605 /* Close device */
1606 usb->host->close ( usb );
1607
1608 /* Disable port */
1609 hub->driver->disable ( hub, port );
1610
1611 /* Remove from bus device list */
1612 list_del ( &usb->list );
1613
1614 /* Remove from port */
1615 port->usb = NULL;
1616 }
1617
1618 /**
1619 * Free USB device
1620 *
1621 * @v usb USB device
1622 */
1623 static void free_usb ( struct usb_device *usb ) {
1624 unsigned int i;
1625
1626 /* Sanity checks */
1627 for ( i = 0 ; i < ( sizeof ( usb->ep ) / sizeof ( usb->ep[0] ) ) ; i++ )
1628 assert ( usb->ep[i] == NULL );
1629 assert ( list_empty ( &usb->functions ) );
1630 assert ( list_empty ( &usb->complete ) );
1631
1632 /* Free device */
1633 free ( usb );
1634 }
1635
1636 /******************************************************************************
1637 *
1638 * USB device hotplug event handling
1639 *
1640 ******************************************************************************
1641 */
1642
1643 /**
1644 * Handle newly attached USB device
1645 *
1646 * @v port USB port
1647 * @ret rc Return status code
1648 */
1649 static int usb_attached ( struct usb_port *port ) {
1650 struct usb_device *usb;
1651 int rc;
1652
1653 /* Mark port as attached */
1654 port->attached = 1;
1655
1656 /* Sanity checks */
1657 assert ( port->usb == NULL );
1658
1659 /* Allocate USB device */
1660 usb = alloc_usb ( port );
1661 if ( ! usb ) {
1662 rc = -ENOMEM;
1663 goto err_alloc;
1664 }
1665
1666 /* Register USB device */
1667 if ( ( rc = register_usb ( usb ) ) != 0 )
1668 goto err_register;
1669
1670 return 0;
1671
1672 unregister_usb ( usb );
1673 err_register:
1674 free_usb ( usb );
1675 err_alloc:
1676 return rc;
1677 }
1678
1679 /**
1680 * Handle newly detached USB device
1681 *
1682 * @v port USB port
1683 */
1684 static void usb_detached ( struct usb_port *port ) {
1685 struct usb_device *usb = port->usb;
1686
1687 /* Mark port as detached */
1688 port->attached = 0;
1689
1690 /* Do nothing if we have no USB device */
1691 if ( ! usb )
1692 return;
1693
1694 /* Unregister USB device */
1695 unregister_usb ( usb );
1696
1697 /* Free USB device */
1698 free_usb ( usb );
1699 }
1700
1701 /**
1702 * Handle newly attached or detached USB device
1703 *
1704 * @v port USB port
1705 * @ret rc Return status code
1706 */
1707 static int usb_hotplugged ( struct usb_port *port ) {
1708 struct usb_hub *hub = port->hub;
1709 int rc;
1710
1711 /* Get current port speed */
1712 if ( ( rc = hub->driver->speed ( hub, port ) ) != 0 ) {
1713 DBGC ( hub, "USB hub %s port %d could not get speed: %s\n",
1714 hub->name, port->address, strerror ( rc ) );
1715 goto err_speed;
1716 }
1717
1718 /* Detach device, if applicable */
1719 if ( port->attached && ( port->disconnected || ! port->speed ) )
1720 usb_detached ( port );
1721
1722 /* Attach device, if applicable */
1723 if ( port->speed && ( ! port->attached ) &&
1724 ( ( rc = usb_attached ( port ) ) != 0 ) )
1725 goto err_attached;
1726
1727 err_attached:
1728 err_speed:
1729 /* Clear any recorded disconnections */
1730 port->disconnected = 0;
1731 return rc;
1732 }
1733
1734 /******************************************************************************
1735 *
1736 * USB process
1737 *
1738 ******************************************************************************
1739 */
1740
1741 /**
1742 * Report port status change
1743 *
1744 * @v port USB port
1745 */
1746 void usb_port_changed ( struct usb_port *port ) {
1747
1748 /* Record hub port status change */
1749 list_del ( &port->changed );
1750 list_add_tail ( &port->changed, &usb_changed );
1751 }
1752
1753 /**
1754 * Handle newly attached or detached USB device
1755 *
1756 */
1757 static void usb_hotplug ( void ) {
1758 struct usb_port *port;
1759
1760 /* Handle any changed ports, allowing for the fact that the
1761 * port list may change as we perform hotplug actions.
1762 */
1763 while ( ! list_empty ( &usb_changed ) ) {
1764
1765 /* Get first changed port */
1766 port = list_first_entry ( &usb_changed, struct usb_port,
1767 changed );
1768 assert ( port != NULL );
1769
1770 /* Remove from list of changed ports */
1771 list_del ( &port->changed );
1772 INIT_LIST_HEAD ( &port->changed );
1773
1774 /* Perform appropriate hotplug action */
1775 usb_hotplugged ( port );
1776 }
1777 }
1778
1779 /**
1780 * USB process
1781 *
1782 * @v process USB process
1783 */
1784 static void usb_step ( struct process *process __unused ) {
1785 struct usb_bus *bus;
1786 struct usb_endpoint *ep;
1787
1788 /* Poll all buses */
1789 for_each_usb_bus ( bus )
1790 usb_poll ( bus );
1791
1792 /* Attempt to reset first halted endpoint in list, if any. We
1793 * do not attempt to process the complete list, since this
1794 * would require extra code to allow for the facts that the
1795 * halted endpoint list may change as we do so, and that
1796 * resetting an endpoint may fail.
1797 */
1798 if ( ( ep = list_first_entry ( &usb_halted, struct usb_endpoint,
1799 halted ) ) != NULL )
1800 usb_endpoint_reset ( ep );
1801
1802 /* Handle any changed ports */
1803 usb_hotplug();
1804 }
1805
1806 /** USB process */
1807 PERMANENT_PROCESS ( usb_process, usb_step );
1808
1809 /******************************************************************************
1810 *
1811 * USB hub
1812 *
1813 ******************************************************************************
1814 */
1815
1816 /**
1817 * Allocate USB hub
1818 *
1819 * @v bus USB bus
1820 * @v usb Underlying USB device, if any
1821 * @v ports Number of ports
1822 * @v driver Hub driver operations
1823 * @ret hub USB hub, or NULL on allocation failure
1824 */
1825 struct usb_hub * alloc_usb_hub ( struct usb_bus *bus, struct usb_device *usb,
1826 unsigned int ports,
1827 struct usb_hub_driver_operations *driver ) {
1828 struct usb_hub *hub;
1829 struct usb_port *port;
1830 unsigned int i;
1831
1832 /* Allocate and initialise structure */
1833 hub = zalloc ( sizeof ( *hub ) + ( ports * sizeof ( hub->port[0] ) ) );
1834 if ( ! hub )
1835 return NULL;
1836 hub->name = ( usb ? usb->name : bus->name );
1837 hub->bus = bus;
1838 hub->usb = usb;
1839 if ( usb )
1840 hub->protocol = usb->port->protocol;
1841 hub->ports = ports;
1842 hub->driver = driver;
1843 hub->host = &bus->op->hub;
1844
1845 /* Initialise port list */
1846 for ( i = 1 ; i <= hub->ports ; i++ ) {
1847 port = usb_port ( hub, i );
1848 port->hub = hub;
1849 port->address = i;
1850 if ( usb )
1851 port->protocol = usb->port->protocol;
1852 INIT_LIST_HEAD ( &port->changed );
1853 }
1854
1855 return hub;
1856 }
1857
1858 /**
1859 * Register USB hub
1860 *
1861 * @v hub USB hub
1862 * @ret rc Return status code
1863 */
1864 int register_usb_hub ( struct usb_hub *hub ) {
1865 struct usb_bus *bus = hub->bus;
1866 struct usb_port *port;
1867 unsigned int i;
1868 int rc;
1869
1870 /* Add to hub list */
1871 list_add_tail ( &hub->list, &bus->hubs );
1872
1873 /* Open hub (host controller) */
1874 if ( ( rc = hub->host->open ( hub ) ) != 0 ) {
1875 DBGC ( hub, "USB hub %s could not open: %s\n",
1876 hub->name, strerror ( rc ) );
1877 goto err_host_open;
1878 }
1879
1880 /* Open hub (driver) */
1881 if ( ( rc = hub->driver->open ( hub ) ) != 0 ) {
1882 DBGC ( hub, "USB hub %s could not open: %s\n",
1883 hub->name, strerror ( rc ) );
1884 goto err_driver_open;
1885 }
1886
1887 /* Delay to allow ports to stabilise */
1888 mdelay ( USB_PORT_DELAY_MS );
1889
1890 /* Mark all ports as changed */
1891 for ( i = 1 ; i <= hub->ports ; i++ ) {
1892 port = usb_port ( hub, i );
1893 usb_port_changed ( port );
1894 }
1895
1896 /* Some hubs seem to defer reporting device connections until
1897 * their interrupt endpoint is polled for the first time.
1898 * Poll the bus once now in order to pick up any such
1899 * connections.
1900 */
1901 usb_poll ( bus );
1902
1903 return 0;
1904
1905 hub->driver->close ( hub );
1906 err_driver_open:
1907 hub->host->close ( hub );
1908 err_host_open:
1909 list_del ( &hub->list );
1910 return rc;
1911 }
1912
1913 /**
1914 * Unregister USB hub
1915 *
1916 * @v hub USB hub
1917 */
1918 void unregister_usb_hub ( struct usb_hub *hub ) {
1919 struct usb_port *port;
1920 unsigned int i;
1921
1922 /* Detach all devices */
1923 for ( i = 1 ; i <= hub->ports ; i++ ) {
1924 port = usb_port ( hub, i );
1925 if ( port->attached )
1926 usb_detached ( port );
1927 }
1928
1929 /* Close hub (driver) */
1930 hub->driver->close ( hub );
1931
1932 /* Close hub (host controller) */
1933 hub->host->close ( hub );
1934
1935 /* Cancel any pending port status changes */
1936 for ( i = 1 ; i <= hub->ports ; i++ ) {
1937 port = usb_port ( hub, i );
1938 list_del ( &port->changed );
1939 INIT_LIST_HEAD ( &port->changed );
1940 }
1941
1942 /* Remove from hub list */
1943 list_del ( &hub->list );
1944 }
1945
1946 /**
1947 * Free USB hub
1948 *
1949 * @v hub USB hub
1950 */
1951 void free_usb_hub ( struct usb_hub *hub ) {
1952 struct usb_port *port;
1953 unsigned int i;
1954
1955 /* Sanity checks */
1956 for ( i = 1 ; i <= hub->ports ; i++ ) {
1957 port = usb_port ( hub, i );
1958 assert ( ! port->attached );
1959 assert ( port->usb == NULL );
1960 assert ( list_empty ( &port->changed ) );
1961 }
1962
1963 /* Free hub */
1964 free ( hub );
1965 }
1966
1967 /******************************************************************************
1968 *
1969 * USB bus
1970 *
1971 ******************************************************************************
1972 */
1973
1974 /**
1975 * Allocate USB bus
1976 *
1977 * @v dev Underlying hardware device
1978 * @v ports Number of root hub ports
1979 * @v mtu Largest transfer allowed on the bus
1980 * @v op Host controller operations
1981 * @ret bus USB bus, or NULL on allocation failure
1982 */
1983 struct usb_bus * alloc_usb_bus ( struct device *dev, unsigned int ports,
1984 size_t mtu, struct usb_host_operations *op ) {
1985 struct usb_bus *bus;
1986
1987 /* Allocate and initialise structure */
1988 bus = zalloc ( sizeof ( *bus ) );
1989 if ( ! bus )
1990 goto err_alloc_bus;
1991 bus->name = dev->name;
1992 bus->dev = dev;
1993 bus->mtu = mtu;
1994 bus->op = op;
1995 INIT_LIST_HEAD ( &bus->devices );
1996 INIT_LIST_HEAD ( &bus->hubs );
1997 bus->host = &bus->op->bus;
1998
1999 /* Allocate root hub */
2000 bus->hub = alloc_usb_hub ( bus, NULL, ports, &op->root );
2001 if ( ! bus->hub )
2002 goto err_alloc_hub;
2003
2004 return bus;
2005
2006 free_usb_hub ( bus->hub );
2007 err_alloc_hub:
2008 free ( bus );
2009 err_alloc_bus:
2010 return NULL;
2011 }
2012
2013 /**
2014 * Register USB bus
2015 *
2016 * @v bus USB bus
2017 * @ret rc Return status code
2018 */
2019 int register_usb_bus ( struct usb_bus *bus ) {
2020 int rc;
2021
2022 /* Sanity checks */
2023 assert ( bus->hub != NULL );
2024
2025 /* Open bus */
2026 if ( ( rc = bus->host->open ( bus ) ) != 0 )
2027 goto err_open;
2028
2029 /* Add to list of USB buses */
2030 list_add_tail ( &bus->list, &usb_buses );
2031
2032 /* Register root hub */
2033 if ( ( rc = register_usb_hub ( bus->hub ) ) != 0 )
2034 goto err_register_hub;
2035
2036 /* Attach any devices already present */
2037 usb_hotplug();
2038
2039 return 0;
2040
2041 unregister_usb_hub ( bus->hub );
2042 err_register_hub:
2043 list_del ( &bus->list );
2044 bus->host->close ( bus );
2045 err_open:
2046 return rc;
2047 }
2048
2049 /**
2050 * Unregister USB bus
2051 *
2052 * @v bus USB bus
2053 */
2054 void unregister_usb_bus ( struct usb_bus *bus ) {
2055
2056 /* Sanity checks */
2057 assert ( bus->hub != NULL );
2058
2059 /* Unregister root hub */
2060 unregister_usb_hub ( bus->hub );
2061
2062 /* Remove from list of USB buses */
2063 list_del ( &bus->list );
2064
2065 /* Close bus */
2066 bus->host->close ( bus );
2067
2068 /* Sanity checks */
2069 assert ( list_empty ( &bus->devices ) );
2070 assert ( list_empty ( &bus->hubs ) );
2071 }
2072
2073 /**
2074 * Free USB bus
2075 *
2076 * @v bus USB bus
2077 */
2078 void free_usb_bus ( struct usb_bus *bus ) {
2079 struct usb_endpoint *ep;
2080 struct usb_port *port;
2081
2082 /* Sanity checks */
2083 assert ( list_empty ( &bus->devices ) );
2084 assert ( list_empty ( &bus->hubs ) );
2085 list_for_each_entry ( ep, &usb_halted, halted )
2086 assert ( ep->usb->port->hub->bus != bus );
2087 list_for_each_entry ( port, &usb_changed, changed )
2088 assert ( port->hub->bus != bus );
2089
2090 /* Free root hub */
2091 free_usb_hub ( bus->hub );
2092
2093 /* Free bus */
2094 free ( bus );
2095 }
2096
2097 /**
2098 * Find USB bus by device location
2099 *
2100 * @v bus_type Bus type
2101 * @v location Bus location
2102 * @ret bus USB bus, or NULL
2103 */
2104 struct usb_bus * find_usb_bus_by_location ( unsigned int bus_type,
2105 unsigned int location ) {
2106 struct usb_bus *bus;
2107
2108 for_each_usb_bus ( bus ) {
2109 if ( ( bus->dev->desc.bus_type == bus_type ) &&
2110 ( bus->dev->desc.location == location ) )
2111 return bus;
2112 }
2113
2114 return NULL;
2115 }
2116
2117 /******************************************************************************
2118 *
2119 * USB address assignment
2120 *
2121 ******************************************************************************
2122 */
2123
2124 /**
2125 * Allocate device address
2126 *
2127 * @v bus USB bus
2128 * @ret address Device address, or negative error
2129 */
2130 int usb_alloc_address ( struct usb_bus *bus ) {
2131 unsigned int address;
2132
2133 /* Find first free device address */
2134 address = ffsll ( ~bus->addresses );
2135 if ( ! address )
2136 return -ENOENT;
2137
2138 /* Mark address as used */
2139 bus->addresses |= ( 1ULL << ( address - 1 ) );
2140
2141 return address;
2142 }
2143
2144 /**
2145 * Free device address
2146 *
2147 * @v bus USB bus
2148 * @v address Device address
2149 */
2150 void usb_free_address ( struct usb_bus *bus, unsigned int address ) {
2151
2152 /* Sanity check */
2153 assert ( address > 0 );
2154 assert ( bus->addresses & ( 1ULL << ( address - 1 ) ) );
2155
2156 /* Mark address as free */
2157 bus->addresses &= ~( 1ULL << ( address - 1 ) );
2158 }
2159
2160 /******************************************************************************
2161 *
2162 * USB bus topology
2163 *
2164 ******************************************************************************
2165 */
2166
2167 /**
2168 * Get USB route string
2169 *
2170 * @v usb USB device
2171 * @ret route USB route string
2172 */
2173 unsigned int usb_route_string ( struct usb_device *usb ) {
2174 struct usb_device *parent;
2175 unsigned int route;
2176
2177 /* Navigate up to root hub, constructing route string as we go */
2178 for ( route = 0 ; ( parent = usb->port->hub->usb ) ; usb = parent ) {
2179 route <<= 4;
2180 route |= ( ( usb->port->address > 0xf ) ?
2181 0xf : usb->port->address );
2182 }
2183
2184 return route;
2185 }
2186
2187 /**
2188 * Get USB depth
2189 *
2190 * @v usb USB device
2191 * @ret depth Hub depth
2192 */
2193 unsigned int usb_depth ( struct usb_device *usb ) {
2194 struct usb_device *parent;
2195 unsigned int depth;
2196
2197 /* Navigate up to root hub, constructing depth as we go */
2198 for ( depth = 0 ; ( parent = usb->port->hub->usb ) ; usb = parent )
2199 depth++;
2200
2201 return depth;
2202 }
2203
2204 /**
2205 * Get USB root hub port
2206 *
2207 * @v usb USB device
2208 * @ret port Root hub port
2209 */
2210 struct usb_port * usb_root_hub_port ( struct usb_device *usb ) {
2211 struct usb_device *parent;
2212
2213 /* Navigate up to root hub */
2214 while ( ( parent = usb->port->hub->usb ) )
2215 usb = parent;
2216
2217 return usb->port;
2218 }
2219
2220 /**
2221 * Get USB transaction translator
2222 *
2223 * @v usb USB device
2224 * @ret port Transaction translator port, or NULL
2225 */
2226 struct usb_port * usb_transaction_translator ( struct usb_device *usb ) {
2227 struct usb_device *parent;
2228
2229 /* Navigate up to root hub. If we find a low-speed or
2230 * full-speed port with a higher-speed parent device, then
2231 * that port is the transaction translator.
2232 */
2233 for ( ; ( parent = usb->port->hub->usb ) ; usb = parent ) {
2234 if ( ( usb->port->speed <= USB_SPEED_FULL ) &&
2235 ( parent->port->speed > USB_SPEED_FULL ) )
2236 return usb->port;
2237 }
2238
2239 return NULL;
2240 }
2241
2242 /* Drag in objects via register_usb_bus() */
2243 REQUIRING_SYMBOL ( register_usb_bus );
2244
2245 /* Drag in USB configuration */
2246 REQUIRE_OBJECT ( config_usb );
2247
2248 /* Drag in hub driver */
2249 REQUIRE_OBJECT ( usbhub );