[efi] Implement the EFI_PXE_BASE_CODE_PROTOCOL
[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 rc;
534
535 /* Fail immediately if device has been unplugged */
536 if ( port->speed == USB_SPEED_NONE )
537 return -ENODEV;
538
539 /* Reset endpoint if required */
540 if ( ( ! list_empty ( &ep->halted ) ) &&
541 ( ( rc = usb_endpoint_reset ( ep ) ) != 0 ) )
542 return rc;
543
544 /* Enqueue stream transfer */
545 if ( ( rc = ep->host->stream ( ep, iobuf, terminate ) ) != 0 ) {
546 DBGC ( usb, "USB %s %s could not enqueue stream transfer: %s\n",
547 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
548 return rc;
549 }
550
551 /* Increment fill level */
552 ep->fill++;
553
554 return 0;
555 }
556
557 /**
558 * Complete transfer (possibly with error)
559 *
560 * @v ep USB endpoint
561 * @v iobuf I/O buffer
562 * @v rc Completion status code
563 */
564 void usb_complete_err ( struct usb_endpoint *ep, struct io_buffer *iobuf,
565 int rc ) {
566 struct usb_device *usb = ep->usb;
567
568 /* Decrement fill level */
569 assert ( ep->fill > 0 );
570 ep->fill--;
571
572 /* Schedule reset, if applicable */
573 if ( ( rc != 0 ) && ep->open ) {
574 DBGC ( usb, "USB %s %s completion failed: %s\n",
575 usb->name, usb_endpoint_name ( ep ), strerror ( rc ) );
576 list_del ( &ep->halted );
577 list_add_tail ( &ep->halted, &usb_halted );
578 }
579
580 /* Report completion */
581 ep->driver->complete ( ep, iobuf, rc );
582 }
583
584 /******************************************************************************
585 *
586 * Endpoint refilling
587 *
588 ******************************************************************************
589 */
590
591 /**
592 * Prefill endpoint recycled buffer list
593 *
594 * @v ep USB endpoint
595 * @ret rc Return status code
596 */
597 int usb_prefill ( struct usb_endpoint *ep ) {
598 struct io_buffer *iobuf;
599 size_t len = ( ep->len ? ep->len : ep->mtu );
600 unsigned int fill;
601 int rc;
602
603 /* Sanity checks */
604 assert ( ep->fill == 0 );
605 assert ( ep->max > 0 );
606 assert ( list_empty ( &ep->recycled ) );
607
608 /* Fill recycled buffer list */
609 for ( fill = 0 ; fill < ep->max ; fill++ ) {
610
611 /* Allocate I/O buffer */
612 iobuf = alloc_iob ( len );
613 if ( ! iobuf ) {
614 rc = -ENOMEM;
615 goto err_alloc;
616 }
617
618 /* Add to recycled buffer list */
619 list_add_tail ( &iobuf->list, &ep->recycled );
620 }
621
622 return 0;
623
624 err_alloc:
625 usb_flush ( ep );
626 return rc;
627 }
628
629 /**
630 * Refill endpoint
631 *
632 * @v ep USB endpoint
633 * @ret rc Return status code
634 */
635 int usb_refill ( struct usb_endpoint *ep ) {
636 struct io_buffer *iobuf;
637 size_t len = ( ep->len ? ep->len : ep->mtu );
638 int rc;
639
640 /* Sanity checks */
641 assert ( ep->open );
642 assert ( ep->max > 0 );
643
644 /* Refill endpoint */
645 while ( ep->fill < ep->max ) {
646
647 /* Get or allocate buffer */
648 if ( list_empty ( &ep->recycled ) ) {
649 /* Recycled buffer list is empty; allocate new buffer */
650 iobuf = alloc_iob ( len );
651 if ( ! iobuf )
652 return -ENOMEM;
653 } else {
654 /* Get buffer from recycled buffer list */
655 iobuf = list_first_entry ( &ep->recycled,
656 struct io_buffer, list );
657 assert ( iobuf != NULL );
658 list_del ( &iobuf->list );
659 }
660
661 /* Reset buffer to maximum size */
662 assert ( iob_len ( iobuf ) <= len );
663 iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
664
665 /* Enqueue buffer */
666 if ( ( rc = usb_stream ( ep, iobuf, 0 ) ) != 0 ) {
667 list_add ( &iobuf->list, &ep->recycled );
668 return rc;
669 }
670 }
671
672 return 0;
673 }
674
675 /**
676 * Discard endpoint recycled buffer list
677 *
678 * @v ep USB endpoint
679 */
680 void usb_flush ( struct usb_endpoint *ep ) {
681 struct io_buffer *iobuf;
682 struct io_buffer *tmp;
683
684 /* Sanity checks */
685 assert ( ! ep->open );
686 assert ( ep->max > 0 );
687
688 /* Free all I/O buffers */
689 list_for_each_entry_safe ( iobuf, tmp, &ep->recycled, list ) {
690 list_del ( &iobuf->list );
691 free_iob ( iobuf );
692 }
693 }
694
695 /******************************************************************************
696 *
697 * Control endpoint
698 *
699 ******************************************************************************
700 */
701
702 /** USB control transfer pseudo-header */
703 struct usb_control_pseudo_header {
704 /** Completion status */
705 int rc;
706 };
707
708 /**
709 * Complete USB control transfer
710 *
711 * @v ep USB endpoint
712 * @v iobuf I/O buffer
713 * @v rc Completion status code
714 */
715 static void usb_control_complete ( struct usb_endpoint *ep,
716 struct io_buffer *iobuf, int rc ) {
717 struct usb_device *usb = ep->usb;
718 struct usb_control_pseudo_header *pshdr;
719
720 /* Record completion status in buffer */
721 pshdr = iob_push ( iobuf, sizeof ( *pshdr ) );
722 pshdr->rc = rc;
723
724 /* Add to list of completed I/O buffers */
725 list_add_tail ( &iobuf->list, &usb->complete );
726 }
727
728 /** USB control endpoint driver operations */
729 static struct usb_endpoint_driver_operations usb_control_operations = {
730 .complete = usb_control_complete,
731 };
732
733 /**
734 * Issue USB control transaction
735 *
736 * @v usb USB device
737 * @v request Request
738 * @v value Value parameter
739 * @v index Index parameter
740 * @v data Data buffer (if any)
741 * @v len Length of data
742 * @ret rc Return status code
743 */
744 int usb_control ( struct usb_device *usb, unsigned int request,
745 unsigned int value, unsigned int index, void *data,
746 size_t len ) {
747 struct usb_bus *bus = usb->port->hub->bus;
748 struct usb_endpoint *ep = &usb->control;
749 struct io_buffer *iobuf;
750 struct io_buffer *cmplt;
751 union {
752 struct usb_setup_packet setup;
753 struct usb_control_pseudo_header pshdr;
754 } *headroom;
755 struct usb_control_pseudo_header *pshdr;
756 unsigned int i;
757 int rc;
758
759 /* Allocate I/O buffer */
760 iobuf = alloc_iob ( sizeof ( *headroom ) + len );
761 if ( ! iobuf ) {
762 rc = -ENOMEM;
763 goto err_alloc;
764 }
765 iob_reserve ( iobuf, sizeof ( *headroom ) );
766 iob_put ( iobuf, len );
767 if ( request & USB_DIR_IN ) {
768 memset ( data, 0, len );
769 } else {
770 memcpy ( iobuf->data, data, len );
771 }
772
773 /* Enqueue message */
774 if ( ( rc = usb_message ( ep, request, value, index, iobuf ) ) != 0 )
775 goto err_message;
776
777 /* Wait for completion */
778 for ( i = 0 ; i < USB_CONTROL_MAX_WAIT_MS ; i++ ) {
779
780 /* Poll bus */
781 usb_poll ( bus );
782
783 /* Check for completion */
784 while ( ( cmplt = list_first_entry ( &usb->complete,
785 struct io_buffer,
786 list ) ) ) {
787
788 /* Remove from completion list */
789 list_del ( &cmplt->list );
790
791 /* Extract and strip completion status */
792 pshdr = cmplt->data;
793 iob_pull ( cmplt, sizeof ( *pshdr ) );
794 rc = pshdr->rc;
795
796 /* Discard stale completions */
797 if ( cmplt != iobuf ) {
798 DBGC ( usb, "USB %s stale control completion: "
799 "%s\n", usb->name, strerror ( rc ) );
800 DBGC_HDA ( usb, 0, cmplt->data,
801 iob_len ( cmplt ) );
802 free_iob ( cmplt );
803 continue;
804 }
805
806 /* Fail immediately if completion was in error */
807 if ( rc != 0 ) {
808 DBGC ( usb, "USB %s control %04x:%04x:%04x "
809 "failed: %s\n", usb->name, request,
810 value, index, strerror ( rc ) );
811 free_iob ( cmplt );
812 return rc;
813 }
814
815 /* Copy completion to data buffer, if applicable */
816 assert ( iob_len ( cmplt ) <= len );
817 if ( request & USB_DIR_IN )
818 memcpy ( data, cmplt->data, iob_len ( cmplt ) );
819 free_iob ( cmplt );
820 return 0;
821 }
822
823 /* Delay */
824 mdelay ( 1 );
825 }
826
827 DBGC ( usb, "USB %s timed out waiting for control %04x:%04x:%04x\n",
828 usb->name, request, value, index );
829 return -ETIMEDOUT;
830
831 err_message:
832 free_iob ( iobuf );
833 err_alloc:
834 return rc;
835 }
836
837 /**
838 * Get USB string descriptor
839 *
840 * @v usb USB device
841 * @v index String index
842 * @v language Language ID
843 * @v buf Data buffer
844 * @v len Length of buffer
845 * @ret len String length (excluding NUL), or negative error
846 */
847 int usb_get_string_descriptor ( struct usb_device *usb, unsigned int index,
848 unsigned int language, char *buf, size_t len ) {
849 size_t max = ( len ? ( len - 1 /* NUL */ ) : 0 );
850 struct {
851 struct usb_descriptor_header header;
852 uint16_t character[max];
853 } __attribute__ (( packed )) *desc;
854 unsigned int actual;
855 unsigned int i;
856 int rc;
857
858 /* Allocate buffer for string */
859 desc = malloc ( sizeof ( *desc ) );
860 if ( ! desc ) {
861 rc = -ENOMEM;
862 goto err_alloc;
863 }
864
865 /* Get descriptor */
866 if ( ( rc = usb_get_descriptor ( usb, 0, USB_STRING_DESCRIPTOR, index,
867 language, &desc->header,
868 sizeof ( *desc ) ) ) != 0 )
869 goto err_get_descriptor;
870
871 /* Copy to buffer */
872 actual = ( ( desc->header.len - sizeof ( desc->header ) ) /
873 sizeof ( desc->character[0] ) );
874 for ( i = 0 ; ( ( i < actual ) && ( i < max ) ) ; i++ )
875 buf[i] = le16_to_cpu ( desc->character[i] );
876 if ( len )
877 buf[i] = '\0';
878
879 /* Free buffer */
880 free ( desc );
881
882 return actual;
883
884 err_get_descriptor:
885 free ( desc );
886 err_alloc:
887 return rc;
888 }
889
890 /******************************************************************************
891 *
892 * USB device driver
893 *
894 ******************************************************************************
895 */
896
897 /**
898 * Describe USB function
899 *
900 * @v func USB function
901 * @v config Configuration descriptor
902 * @v first First interface number
903 * @ret rc Return status code
904 */
905 static int usb_function ( struct usb_function *func,
906 struct usb_configuration_descriptor *config,
907 unsigned int first ) {
908 struct usb_device *usb = func->usb;
909 struct usb_interface_association_descriptor *association;
910 struct usb_interface_descriptor *interface;
911 struct cdc_union_descriptor *cdc_union;
912 unsigned int i;
913
914 /* First, look for an interface association descriptor */
915 association = usb_interface_association_descriptor ( config, first );
916 if ( association ) {
917
918 /* Sanity check */
919 if ( association->count > config->interfaces ) {
920 DBGC ( usb, "USB %s has invalid association [%d-%d)\n",
921 func->name, association->first,
922 ( association->first + association->count ) );
923 return -ERANGE;
924 }
925
926 /* Describe function */
927 memcpy ( &func->class, &association->class,
928 sizeof ( func->class ) );
929 func->count = association->count;
930 for ( i = 0 ; i < association->count ; i++ )
931 func->interface[i] = ( association->first + i );
932 return 0;
933 }
934
935 /* Next, look for an interface descriptor */
936 interface = usb_interface_descriptor ( config, first, 0 );
937 if ( ! interface ) {
938 DBGC ( usb, "USB %s has no interface descriptor\n",
939 func->name );
940 return -ENOENT;
941 }
942
943 /* Describe function */
944 memcpy ( &func->class, &interface->class, sizeof ( func->class ) );
945 func->count = 1;
946 func->interface[0] = first;
947
948 /* Look for a CDC union descriptor, if applicable */
949 if ( ( func->class.class == USB_CLASS_CDC ) &&
950 ( cdc_union = cdc_union_descriptor ( config, interface ) ) ) {
951
952 /* Determine interface count */
953 func->count = ( ( cdc_union->header.len -
954 offsetof ( typeof ( *cdc_union ),
955 interface[0] ) ) /
956 sizeof ( cdc_union->interface[0] ) );
957 if ( func->count > config->interfaces ) {
958 DBGC ( usb, "USB %s has invalid union functional "
959 "descriptor with %d interfaces\n",
960 func->name, func->count );
961 return -ERANGE;
962 }
963
964 /* Describe function */
965 for ( i = 0 ; i < func->count ; i++ )
966 func->interface[i] = cdc_union->interface[i];
967
968 return 0;
969 }
970
971 return 0;
972 }
973
974 /**
975 * Check for a USB device ID match
976 *
977 * @v func USB function
978 * @v id Device ID
979 * @ret matches Device ID matches
980 */
981 static int
982 usb_device_id_matches ( struct usb_function *func, struct usb_device_id *id ) {
983
984 return ( ( ( id->vendor == func->dev.desc.vendor ) ||
985 ( id->vendor == USB_ANY_ID ) ) &&
986 ( ( id->product == func->dev.desc.device ) ||
987 ( id->product == USB_ANY_ID ) ) &&
988 ( id->class.class == func->class.class ) &&
989 ( id->class.subclass == func->class.subclass ) &&
990 ( id->class.protocol == func->class.protocol ) );
991 }
992
993 /**
994 * Probe USB device driver
995 *
996 * @v func USB function
997 * @v config Configuration descriptor
998 * @ret rc Return status code
999 */
1000 static int usb_probe ( struct usb_function *func,
1001 struct usb_configuration_descriptor *config ) {
1002 struct usb_device *usb = func->usb;
1003 struct usb_driver *driver;
1004 struct usb_device_id *id;
1005 unsigned int i;
1006 int rc;
1007
1008 /* Look for a matching driver */
1009 for_each_table_entry ( driver, USB_DRIVERS ) {
1010 for ( i = 0 ; i < driver->id_count ; i++ ) {
1011
1012 /* Check for a matching ID */
1013 id = &driver->ids[i];
1014 if ( ! usb_device_id_matches ( func, id ) )
1015 continue;
1016
1017 /* Probe driver */
1018 if ( ( rc = driver->probe ( func, config ) ) != 0 ) {
1019 DBGC ( usb, "USB %s failed to probe driver %s: "
1020 "%s\n", func->name, id->name,
1021 strerror ( rc ) );
1022 /* Continue trying other drivers */
1023 continue;
1024 }
1025
1026 /* Record driver */
1027 func->driver = driver;
1028 func->dev.driver_name = id->name;
1029 return 0;
1030 }
1031 }
1032
1033 /* No driver found */
1034 DBGC ( usb, "USB %s %04x:%04x class %d:%d:%d has no driver\n",
1035 func->name, func->dev.desc.vendor, func->dev.desc.device,
1036 func->class.class, func->class.subclass, func->class.protocol );
1037 return -ENOENT;
1038 }
1039
1040 /**
1041 * Remove USB device driver
1042 *
1043 * @v func USB function
1044 */
1045 static void usb_remove ( struct usb_function *func ) {
1046
1047 /* Remove driver */
1048 func->driver->remove ( func );
1049 }
1050
1051 /**
1052 * Probe all USB device drivers
1053 *
1054 * @v usb USB device
1055 * @v config Configuration descriptor
1056 */
1057 static void
1058 usb_probe_all ( struct usb_device *usb,
1059 struct usb_configuration_descriptor *config ) {
1060 struct usb_bus *bus = usb->port->hub->bus;
1061 struct usb_function *func;
1062 uint8_t used[config->interfaces];
1063 unsigned int first;
1064 unsigned int i;
1065 int rc;
1066
1067 /* Identify each function in turn */
1068 memset ( used, 0, sizeof ( used ) );
1069 for ( first = 0 ; first < config->interfaces ; first++ ) {
1070
1071 /* Skip interfaces already used */
1072 if ( used[first] )
1073 continue;
1074
1075 /* Allocate and initialise structure */
1076 func = zalloc ( sizeof ( *func ) +
1077 ( config->interfaces *
1078 sizeof ( func->interface[0] ) ) );
1079 if ( ! func )
1080 goto err_alloc;
1081 func->name = func->dev.name;
1082 func->usb = usb;
1083 func->dev.desc.bus_type = BUS_TYPE_USB;
1084 func->dev.desc.location = usb->address;
1085 func->dev.desc.vendor = le16_to_cpu ( usb->device.vendor );
1086 func->dev.desc.device = le16_to_cpu ( usb->device.product );
1087 snprintf ( func->dev.name, sizeof ( func->dev.name ),
1088 "%s-%d.%d", usb->name, config->config, first );
1089 INIT_LIST_HEAD ( &func->dev.children );
1090 func->dev.parent = bus->dev;
1091
1092 /* Identify function */
1093 if ( ( rc = usb_function ( func, config, first ) ) != 0 )
1094 goto err_function;
1095 assert ( func->count <= config->interfaces );
1096
1097 /* Mark interfaces as used */
1098 for ( i = 0 ; i < func->count ; i++ ) {
1099 if ( func->interface[i] >= config->interfaces ) {
1100 DBGC ( usb, "USB %s has invalid interface %d\n",
1101 func->name, func->interface[i] );
1102 goto err_interface;
1103 }
1104 used[ func->interface[i] ] = 1;
1105 }
1106
1107 /* Probe device driver */
1108 if ( ( rc = usb_probe ( func, config ) ) != 0 )
1109 goto err_probe;
1110 DBGC ( usb, "USB %s %04x:%04x class %d:%d:%d interfaces ",
1111 func->name, func->dev.desc.vendor, func->dev.desc.device,
1112 func->class.class, func->class.subclass,
1113 func->class.protocol );
1114 for ( i = 0 ; i < func->count ; i++ )
1115 DBGC ( usb, "%s%d", ( i ? "," : "" ),
1116 func->interface[i] );
1117 DBGC ( usb, " using driver %s\n", func->dev.driver_name );
1118
1119 /* Add to list of functions */
1120 list_add ( &func->list, &usb->functions );
1121
1122 /* Add to device hierarchy */
1123 list_add_tail ( &func->dev.siblings, &bus->dev->children );
1124
1125 continue;
1126
1127 list_del ( &func->dev.siblings );
1128 list_del ( &func->list );
1129 usb_remove ( func );
1130 err_probe:
1131 free ( func );
1132 err_alloc:
1133 err_interface:
1134 err_function:
1135 /* Continue registering other functions */
1136 continue;
1137 }
1138 }
1139
1140 /**
1141 * Remove all device drivers
1142 *
1143 * @v usb USB device
1144 */
1145 static void usb_remove_all ( struct usb_device *usb ) {
1146 struct usb_function *func;
1147 struct usb_function *tmp;
1148
1149 /* Remove all functions */
1150 list_for_each_entry_safe ( func, tmp, &usb->functions, list ) {
1151
1152 /* Remove device driver */
1153 usb_remove ( func );
1154
1155 /* Remove from device hierarchy */
1156 assert ( list_empty ( &func->dev.children ) );
1157 list_del ( &func->dev.siblings );
1158
1159 /* Remove from list of functions */
1160 list_del ( &func->list );
1161
1162 /* Free function */
1163 free ( func );
1164 }
1165 }
1166
1167 /**
1168 * Select USB device configuration
1169 *
1170 * @v usb USB device
1171 * @v index Configuration index
1172 * @ret rc Return status code
1173 */
1174 static int usb_configure ( struct usb_device *usb, unsigned int index ) {
1175 struct usb_configuration_descriptor partial;
1176 struct usb_configuration_descriptor *config;
1177 size_t len;
1178 int rc;
1179
1180 /* Read first part of configuration descriptor to get size */
1181 if ( ( rc = usb_get_config_descriptor ( usb, index, &partial,
1182 sizeof ( partial ) ) ) != 0 ) {
1183 DBGC ( usb, "USB %s could not get configuration descriptor %d: "
1184 "%s\n", usb->name, index, strerror ( rc ) );
1185 goto err_get_partial;
1186 }
1187 len = le16_to_cpu ( partial.len );
1188 if ( len < sizeof ( partial ) ) {
1189 DBGC ( usb, "USB %s underlength configuraton descriptor %d\n",
1190 usb->name, index );
1191 rc = -EINVAL;
1192 goto err_partial_len;
1193 }
1194
1195 /* Allocate buffer for whole configuration descriptor */
1196 config = malloc ( len );
1197 if ( ! config ) {
1198 rc = -ENOMEM;
1199 goto err_alloc_config;
1200 }
1201
1202 /* Read whole configuration descriptor */
1203 if ( ( rc = usb_get_config_descriptor ( usb, index, config,
1204 len ) ) != 0 ) {
1205 DBGC ( usb, "USB %s could not get configuration descriptor %d: "
1206 "%s\n", usb->name, index, strerror ( rc ) );
1207 goto err_get_config_descriptor;
1208 }
1209 if ( config->len != partial.len ) {
1210 DBGC ( usb, "USB %s bad configuration descriptor %d length\n",
1211 usb->name, index );
1212 rc = -EINVAL;
1213 goto err_config_len;
1214 }
1215
1216 /* Set configuration */
1217 if ( ( rc = usb_set_configuration ( usb, config->config ) ) != 0){
1218 DBGC ( usb, "USB %s could not set configuration %d: %s\n",
1219 usb->name, config->config, strerror ( rc ) );
1220 goto err_set_configuration;
1221 }
1222
1223 /* Probe USB device drivers */
1224 usb_probe_all ( usb, config );
1225
1226 /* Free configuration descriptor */
1227 free ( config );
1228
1229 return 0;
1230
1231 usb_remove_all ( usb );
1232 usb_set_configuration ( usb, 0 );
1233 err_set_configuration:
1234 err_config_len:
1235 err_get_config_descriptor:
1236 free ( config );
1237 err_alloc_config:
1238 err_partial_len:
1239 err_get_partial:
1240 return rc;
1241 }
1242
1243 /**
1244 * Clear USB device configuration
1245 *
1246 * @v usb USB device
1247 */
1248 static void usb_deconfigure ( struct usb_device *usb ) {
1249 unsigned int i;
1250
1251 /* Remove device drivers */
1252 usb_remove_all ( usb );
1253
1254 /* Sanity checks */
1255 for ( i = 0 ; i < ( sizeof ( usb->ep ) / sizeof ( usb->ep[0] ) ) ; i++){
1256 if ( i != USB_ENDPOINT_IDX ( USB_EP0_ADDRESS ) )
1257 assert ( usb->ep[i] == NULL );
1258 }
1259
1260 /* Clear device configuration */
1261 usb_set_configuration ( usb, 0 );
1262 }
1263
1264 /**
1265 * Find and select a supported USB device configuration
1266 *
1267 * @v usb USB device
1268 * @ret rc Return status code
1269 */
1270 static int usb_configure_any ( struct usb_device *usb ) {
1271 unsigned int index;
1272 int rc = -ENOENT;
1273
1274 /* Attempt all configuration indexes */
1275 for ( index = 0 ; index < usb->device.configurations ; index++ ) {
1276
1277 /* Attempt this configuration index */
1278 if ( ( rc = usb_configure ( usb, index ) ) != 0 )
1279 continue;
1280
1281 /* If we have no drivers, then try the next configuration */
1282 if ( list_empty ( &usb->functions ) ) {
1283 rc = -ENOTSUP;
1284 usb_deconfigure ( usb );
1285 continue;
1286 }
1287
1288 return 0;
1289 }
1290
1291 return rc;
1292 }
1293
1294 /******************************************************************************
1295 *
1296 * USB device
1297 *
1298 ******************************************************************************
1299 */
1300
1301 /**
1302 * Allocate USB device
1303 *
1304 * @v port USB port
1305 * @ret usb USB device, or NULL on allocation failure
1306 */
1307 static struct usb_device * alloc_usb ( struct usb_port *port ) {
1308 struct usb_hub *hub = port->hub;
1309 struct usb_bus *bus = hub->bus;
1310 struct usb_device *usb;
1311
1312 /* Allocate and initialise structure */
1313 usb = zalloc ( sizeof ( *usb ) );
1314 if ( ! usb )
1315 return NULL;
1316 snprintf ( usb->name, sizeof ( usb->name ), "%s%c%d", hub->name,
1317 ( hub->usb ? '.' : '-' ), port->address );
1318 usb->port = port;
1319 INIT_LIST_HEAD ( &usb->functions );
1320 usb->host = &bus->op->device;
1321 usb_endpoint_init ( &usb->control, usb, &usb_control_operations );
1322 INIT_LIST_HEAD ( &usb->complete );
1323
1324 return usb;
1325 }
1326
1327 /**
1328 * Register USB device
1329 *
1330 * @v usb USB device
1331 * @ret rc Return status code
1332 */
1333 static int register_usb ( struct usb_device *usb ) {
1334 struct usb_port *port = usb->port;
1335 struct usb_hub *hub = port->hub;
1336 struct usb_bus *bus = hub->bus;
1337 unsigned int protocol;
1338 size_t mtu;
1339 int rc;
1340
1341 /* Add to port */
1342 if ( port->usb != NULL ) {
1343 DBGC ( hub, "USB hub %s port %d is already registered to %s\n",
1344 hub->name, port->address, port->usb->name );
1345 rc = -EALREADY;
1346 goto err_already;
1347 }
1348 port->usb = usb;
1349
1350 /* Add to bus device list */
1351 list_add_tail ( &usb->list, &bus->devices );
1352
1353 /* Enable device */
1354 if ( ( rc = hub->driver->enable ( hub, port ) ) != 0 ) {
1355 DBGC ( hub, "USB hub %s port %d could not enable: %s\n",
1356 hub->name, port->address, strerror ( rc ) );
1357 goto err_enable;
1358 }
1359
1360 /* Allow recovery interval since port may have been reset */
1361 mdelay ( USB_RESET_RECOVER_DELAY_MS );
1362
1363 /* Get device speed */
1364 if ( ( rc = hub->driver->speed ( hub, port ) ) != 0 ) {
1365 DBGC ( hub, "USB hub %s port %d could not get speed: %s\n",
1366 hub->name, port->address, strerror ( rc ) );
1367 goto err_speed;
1368 }
1369 DBGC2 ( usb, "USB %s attached as %s-speed device\n",
1370 usb->name, usb_speed_name ( port->speed ) );
1371
1372 /* Open device */
1373 if ( ( rc = usb->host->open ( usb ) ) != 0 ) {
1374 DBGC ( usb, "USB %s could not open: %s\n",
1375 usb->name, strerror ( rc ) );
1376 goto err_open;
1377 }
1378
1379 /* Describe control endpoint */
1380 mtu = USB_EP0_DEFAULT_MTU ( port->speed );
1381 usb_endpoint_describe ( &usb->control, USB_EP0_ADDRESS,
1382 USB_EP0_ATTRIBUTES, mtu, USB_EP0_BURST,
1383 USB_EP0_INTERVAL );
1384
1385 /* Open control endpoint */
1386 if ( ( rc = usb_endpoint_open ( &usb->control ) ) != 0 )
1387 goto err_open_control;
1388 assert ( usb_endpoint ( usb, USB_EP0_ADDRESS ) == &usb->control );
1389
1390 /* Assign device address */
1391 if ( ( rc = usb->host->address ( usb ) ) != 0 ) {
1392 DBGC ( usb, "USB %s could not set address: %s\n",
1393 usb->name, strerror ( rc ) );
1394 goto err_address;
1395 }
1396 DBGC2 ( usb, "USB %s assigned address %d\n", usb->name, usb->address );
1397
1398 /* Allow recovery interval after Set Address command */
1399 mdelay ( USB_SET_ADDRESS_RECOVER_DELAY_MS );
1400
1401 /* Read first part of device descriptor to get EP0 MTU */
1402 if ( ( rc = usb_get_mtu ( usb, &usb->device ) ) != 0 ) {
1403 DBGC ( usb, "USB %s could not get MTU: %s\n",
1404 usb->name, strerror ( rc ) );
1405 goto err_get_mtu;
1406 }
1407
1408 /* Calculate EP0 MTU */
1409 protocol = le16_to_cpu ( usb->device.protocol );
1410 mtu = ( ( protocol < USB_PROTO_3_0 ) ?
1411 usb->device.mtu : ( 1 << usb->device.mtu ) );
1412 DBGC2 ( usb, "USB %s has control MTU %zd (guessed %zd)\n",
1413 usb->name, mtu, usb->control.mtu );
1414
1415 /* Update MTU */
1416 if ( ( rc = usb_endpoint_mtu ( &usb->control, mtu ) ) != 0 )
1417 goto err_mtu;
1418
1419 /* Read whole device descriptor */
1420 if ( ( rc = usb_get_device_descriptor ( usb, &usb->device ) ) != 0 ) {
1421 DBGC ( usb, "USB %s could not get device descriptor: %s\n",
1422 usb->name, strerror ( rc ) );
1423 goto err_get_device_descriptor;
1424 }
1425 DBGC ( usb, "USB %s addr %d %04x:%04x class %d:%d:%d (v%s, %s-speed, "
1426 "MTU %zd)\n", usb->name, usb->address,
1427 le16_to_cpu ( usb->device.vendor ),
1428 le16_to_cpu ( usb->device.product ), usb->device.class.class,
1429 usb->device.class.subclass, usb->device.class.protocol,
1430 usb_bcd ( le16_to_cpu ( usb->device.protocol ) ),
1431 usb_speed_name ( port->speed ), usb->control.mtu );
1432
1433 /* Configure device */
1434 if ( ( rc = usb_configure_any ( usb ) ) != 0 )
1435 goto err_configure_any;
1436
1437 return 0;
1438
1439 usb_deconfigure ( usb );
1440 err_configure_any:
1441 err_get_device_descriptor:
1442 err_mtu:
1443 err_get_mtu:
1444 err_address:
1445 usb_endpoint_close ( &usb->control );
1446 err_open_control:
1447 usb->host->close ( usb );
1448 err_open:
1449 err_speed:
1450 hub->driver->disable ( hub, port );
1451 err_enable:
1452 list_del ( &usb->list );
1453 port->usb = NULL;
1454 err_already:
1455 return rc;
1456 }
1457
1458 /**
1459 * Unregister USB device
1460 *
1461 * @v usb USB device
1462 */
1463 static void unregister_usb ( struct usb_device *usb ) {
1464 struct usb_port *port = usb->port;
1465 struct usb_hub *hub = port->hub;
1466 struct io_buffer *iobuf;
1467 struct io_buffer *tmp;
1468
1469 /* Sanity checks */
1470 assert ( port->usb == usb );
1471
1472 /* Clear device configuration */
1473 usb_deconfigure ( usb );
1474
1475 /* Close control endpoint */
1476 usb_endpoint_close ( &usb->control );
1477
1478 /* Discard any stale control completions */
1479 list_for_each_entry_safe ( iobuf, tmp, &usb->complete, list ) {
1480 list_del ( &iobuf->list );
1481 free_iob ( iobuf );
1482 }
1483
1484 /* Close device */
1485 usb->host->close ( usb );
1486
1487 /* Disable port */
1488 hub->driver->disable ( hub, port );
1489
1490 /* Remove from bus device list */
1491 list_del ( &usb->list );
1492
1493 /* Remove from port */
1494 port->usb = NULL;
1495 }
1496
1497 /**
1498 * Free USB device
1499 *
1500 * @v usb USB device
1501 */
1502 static void free_usb ( struct usb_device *usb ) {
1503 unsigned int i;
1504
1505 /* Sanity checks */
1506 for ( i = 0 ; i < ( sizeof ( usb->ep ) / sizeof ( usb->ep[0] ) ) ; i++ )
1507 assert ( usb->ep[i] == NULL );
1508 assert ( list_empty ( &usb->functions ) );
1509 assert ( list_empty ( &usb->complete ) );
1510
1511 /* Free device */
1512 free ( usb );
1513 }
1514
1515 /******************************************************************************
1516 *
1517 * USB device hotplug event handling
1518 *
1519 ******************************************************************************
1520 */
1521
1522 /**
1523 * Handle newly attached USB device
1524 *
1525 * @v port USB port
1526 * @ret rc Return status code
1527 */
1528 static int usb_attached ( struct usb_port *port ) {
1529 struct usb_device *usb;
1530 int rc;
1531
1532 /* Mark port as attached */
1533 port->attached = 1;
1534
1535 /* Sanity checks */
1536 assert ( port->usb == NULL );
1537
1538 /* Allocate USB device */
1539 usb = alloc_usb ( port );
1540 if ( ! usb ) {
1541 rc = -ENOMEM;
1542 goto err_alloc;
1543 }
1544
1545 /* Register USB device */
1546 if ( ( rc = register_usb ( usb ) ) != 0 )
1547 goto err_register;
1548
1549 return 0;
1550
1551 unregister_usb ( usb );
1552 err_register:
1553 free_usb ( usb );
1554 err_alloc:
1555 return rc;
1556 }
1557
1558 /**
1559 * Handle newly detached USB device
1560 *
1561 * @v port USB port
1562 */
1563 static void usb_detached ( struct usb_port *port ) {
1564 struct usb_device *usb = port->usb;
1565
1566 /* Mark port as detached */
1567 port->attached = 0;
1568
1569 /* Do nothing if we have no USB device */
1570 if ( ! usb )
1571 return;
1572
1573 /* Unregister USB device */
1574 unregister_usb ( usb );
1575
1576 /* Free USB device */
1577 free_usb ( usb );
1578 }
1579
1580 /**
1581 * Handle newly attached or detached USB device
1582 *
1583 * @v port USB port
1584 * @ret rc Return status code
1585 */
1586 static int usb_hotplugged ( struct usb_port *port ) {
1587 struct usb_hub *hub = port->hub;
1588 int rc;
1589
1590 /* Get current port speed */
1591 if ( ( rc = hub->driver->speed ( hub, port ) ) != 0 ) {
1592 DBGC ( hub, "USB hub %s port %d could not get speed: %s\n",
1593 hub->name, port->address, strerror ( rc ) );
1594 goto err_speed;
1595 }
1596
1597 /* Detach device, if applicable */
1598 if ( port->attached && ( port->disconnected || ! port->speed ) )
1599 usb_detached ( port );
1600
1601 /* Attach device, if applicable */
1602 if ( port->speed && ( ! port->attached ) &&
1603 ( ( rc = usb_attached ( port ) ) != 0 ) )
1604 goto err_attached;
1605
1606 err_attached:
1607 err_speed:
1608 /* Clear any recorded disconnections */
1609 port->disconnected = 0;
1610 return rc;
1611 }
1612
1613 /******************************************************************************
1614 *
1615 * USB process
1616 *
1617 ******************************************************************************
1618 */
1619
1620 /**
1621 * Report port status change
1622 *
1623 * @v port USB port
1624 */
1625 void usb_port_changed ( struct usb_port *port ) {
1626
1627 /* Record hub port status change */
1628 list_del ( &port->changed );
1629 list_add_tail ( &port->changed, &usb_changed );
1630 }
1631
1632 /**
1633 * Handle newly attached or detached USB device
1634 *
1635 */
1636 static void usb_hotplug ( void ) {
1637 struct usb_port *port;
1638
1639 /* Handle any changed ports, allowing for the fact that the
1640 * port list may change as we perform hotplug actions.
1641 */
1642 while ( ! list_empty ( &usb_changed ) ) {
1643
1644 /* Get first changed port */
1645 port = list_first_entry ( &usb_changed, struct usb_port,
1646 changed );
1647 assert ( port != NULL );
1648
1649 /* Remove from list of changed ports */
1650 list_del ( &port->changed );
1651 INIT_LIST_HEAD ( &port->changed );
1652
1653 /* Perform appropriate hotplug action */
1654 usb_hotplugged ( port );
1655 }
1656 }
1657
1658 /**
1659 * USB process
1660 *
1661 * @v process USB process
1662 */
1663 static void usb_step ( struct process *process __unused ) {
1664 struct usb_bus *bus;
1665 struct usb_endpoint *ep;
1666
1667 /* Poll all buses */
1668 for_each_usb_bus ( bus )
1669 usb_poll ( bus );
1670
1671 /* Attempt to reset first halted endpoint in list, if any. We
1672 * do not attempt to process the complete list, since this
1673 * would require extra code to allow for the facts that the
1674 * halted endpoint list may change as we do so, and that
1675 * resetting an endpoint may fail.
1676 */
1677 if ( ( ep = list_first_entry ( &usb_halted, struct usb_endpoint,
1678 halted ) ) != NULL )
1679 usb_endpoint_reset ( ep );
1680
1681 /* Handle any changed ports */
1682 usb_hotplug();
1683 }
1684
1685 /** USB process */
1686 PERMANENT_PROCESS ( usb_process, usb_step );
1687
1688 /******************************************************************************
1689 *
1690 * USB hub
1691 *
1692 ******************************************************************************
1693 */
1694
1695 /**
1696 * Allocate USB hub
1697 *
1698 * @v bus USB bus
1699 * @v usb Underlying USB device, if any
1700 * @v ports Number of ports
1701 * @v driver Hub driver operations
1702 * @ret hub USB hub, or NULL on allocation failure
1703 */
1704 struct usb_hub * alloc_usb_hub ( struct usb_bus *bus, struct usb_device *usb,
1705 unsigned int ports,
1706 struct usb_hub_driver_operations *driver ) {
1707 struct usb_hub *hub;
1708 struct usb_port *port;
1709 unsigned int i;
1710
1711 /* Allocate and initialise structure */
1712 hub = zalloc ( sizeof ( *hub ) + ( ports * sizeof ( hub->port[0] ) ) );
1713 if ( ! hub )
1714 return NULL;
1715 hub->name = ( usb ? usb->name : bus->name );
1716 hub->bus = bus;
1717 hub->usb = usb;
1718 if ( usb )
1719 hub->protocol = usb->port->protocol;
1720 hub->ports = ports;
1721 hub->driver = driver;
1722 hub->host = &bus->op->hub;
1723
1724 /* Initialise port list */
1725 for ( i = 1 ; i <= hub->ports ; i++ ) {
1726 port = usb_port ( hub, i );
1727 port->hub = hub;
1728 port->address = i;
1729 if ( usb )
1730 port->protocol = usb->port->protocol;
1731 INIT_LIST_HEAD ( &port->changed );
1732 }
1733
1734 return hub;
1735 }
1736
1737 /**
1738 * Register USB hub
1739 *
1740 * @v hub USB hub
1741 * @ret rc Return status code
1742 */
1743 int register_usb_hub ( struct usb_hub *hub ) {
1744 struct usb_bus *bus = hub->bus;
1745 struct usb_port *port;
1746 unsigned int i;
1747 int rc;
1748
1749 /* Add to hub list */
1750 list_add_tail ( &hub->list, &bus->hubs );
1751
1752 /* Open hub (host controller) */
1753 if ( ( rc = hub->host->open ( hub ) ) != 0 ) {
1754 DBGC ( hub, "USB hub %s could not open: %s\n",
1755 hub->name, strerror ( rc ) );
1756 goto err_host_open;
1757 }
1758
1759 /* Open hub (driver) */
1760 if ( ( rc = hub->driver->open ( hub ) ) != 0 ) {
1761 DBGC ( hub, "USB hub %s could not open: %s\n",
1762 hub->name, strerror ( rc ) );
1763 goto err_driver_open;
1764 }
1765
1766 /* Delay to allow ports to stabilise */
1767 mdelay ( USB_PORT_DELAY_MS );
1768
1769 /* Mark all ports as changed */
1770 for ( i = 1 ; i <= hub->ports ; i++ ) {
1771 port = usb_port ( hub, i );
1772 usb_port_changed ( port );
1773 }
1774
1775 /* Some hubs seem to defer reporting device connections until
1776 * their interrupt endpoint is polled for the first time.
1777 * Poll the bus once now in order to pick up any such
1778 * connections.
1779 */
1780 usb_poll ( bus );
1781
1782 return 0;
1783
1784 hub->driver->close ( hub );
1785 err_driver_open:
1786 hub->host->close ( hub );
1787 err_host_open:
1788 list_del ( &hub->list );
1789 return rc;
1790 }
1791
1792 /**
1793 * Unregister USB hub
1794 *
1795 * @v hub USB hub
1796 */
1797 void unregister_usb_hub ( struct usb_hub *hub ) {
1798 struct usb_port *port;
1799 unsigned int i;
1800
1801 /* Detach all devices */
1802 for ( i = 1 ; i <= hub->ports ; i++ ) {
1803 port = usb_port ( hub, i );
1804 if ( port->attached )
1805 usb_detached ( port );
1806 }
1807
1808 /* Close hub (driver) */
1809 hub->driver->close ( hub );
1810
1811 /* Close hub (host controller) */
1812 hub->host->close ( hub );
1813
1814 /* Cancel any pending port status changes */
1815 for ( i = 1 ; i <= hub->ports ; i++ ) {
1816 port = usb_port ( hub, i );
1817 list_del ( &port->changed );
1818 INIT_LIST_HEAD ( &port->changed );
1819 }
1820
1821 /* Remove from hub list */
1822 list_del ( &hub->list );
1823 }
1824
1825 /**
1826 * Free USB hub
1827 *
1828 * @v hub USB hub
1829 */
1830 void free_usb_hub ( struct usb_hub *hub ) {
1831 struct usb_port *port;
1832 unsigned int i;
1833
1834 /* Sanity checks */
1835 for ( i = 1 ; i <= hub->ports ; i++ ) {
1836 port = usb_port ( hub, i );
1837 assert ( ! port->attached );
1838 assert ( port->usb == NULL );
1839 assert ( list_empty ( &port->changed ) );
1840 }
1841
1842 /* Free hub */
1843 free ( hub );
1844 }
1845
1846 /******************************************************************************
1847 *
1848 * USB bus
1849 *
1850 ******************************************************************************
1851 */
1852
1853 /**
1854 * Allocate USB bus
1855 *
1856 * @v dev Underlying hardware device
1857 * @v ports Number of root hub ports
1858 * @v mtu Largest transfer allowed on the bus
1859 * @v op Host controller operations
1860 * @ret bus USB bus, or NULL on allocation failure
1861 */
1862 struct usb_bus * alloc_usb_bus ( struct device *dev, unsigned int ports,
1863 size_t mtu, struct usb_host_operations *op ) {
1864 struct usb_bus *bus;
1865
1866 /* Allocate and initialise structure */
1867 bus = zalloc ( sizeof ( *bus ) );
1868 if ( ! bus )
1869 goto err_alloc_bus;
1870 bus->name = dev->name;
1871 bus->dev = dev;
1872 bus->mtu = mtu;
1873 bus->op = op;
1874 INIT_LIST_HEAD ( &bus->devices );
1875 INIT_LIST_HEAD ( &bus->hubs );
1876 bus->host = &bus->op->bus;
1877
1878 /* Allocate root hub */
1879 bus->hub = alloc_usb_hub ( bus, NULL, ports, &op->root );
1880 if ( ! bus->hub )
1881 goto err_alloc_hub;
1882
1883 return bus;
1884
1885 free_usb_hub ( bus->hub );
1886 err_alloc_hub:
1887 free ( bus );
1888 err_alloc_bus:
1889 return NULL;
1890 }
1891
1892 /**
1893 * Register USB bus
1894 *
1895 * @v bus USB bus
1896 * @ret rc Return status code
1897 */
1898 int register_usb_bus ( struct usb_bus *bus ) {
1899 int rc;
1900
1901 /* Sanity checks */
1902 assert ( bus->hub != NULL );
1903
1904 /* Open bus */
1905 if ( ( rc = bus->host->open ( bus ) ) != 0 )
1906 goto err_open;
1907
1908 /* Add to list of USB buses */
1909 list_add_tail ( &bus->list, &usb_buses );
1910
1911 /* Register root hub */
1912 if ( ( rc = register_usb_hub ( bus->hub ) ) != 0 )
1913 goto err_register_hub;
1914
1915 /* Attach any devices already present */
1916 usb_hotplug();
1917
1918 return 0;
1919
1920 unregister_usb_hub ( bus->hub );
1921 err_register_hub:
1922 list_del ( &bus->list );
1923 bus->host->close ( bus );
1924 err_open:
1925 return rc;
1926 }
1927
1928 /**
1929 * Unregister USB bus
1930 *
1931 * @v bus USB bus
1932 */
1933 void unregister_usb_bus ( struct usb_bus *bus ) {
1934
1935 /* Sanity checks */
1936 assert ( bus->hub != NULL );
1937
1938 /* Unregister root hub */
1939 unregister_usb_hub ( bus->hub );
1940
1941 /* Remove from list of USB buses */
1942 list_del ( &bus->list );
1943
1944 /* Close bus */
1945 bus->host->close ( bus );
1946
1947 /* Sanity checks */
1948 assert ( list_empty ( &bus->devices ) );
1949 assert ( list_empty ( &bus->hubs ) );
1950 }
1951
1952 /**
1953 * Free USB bus
1954 *
1955 * @v bus USB bus
1956 */
1957 void free_usb_bus ( struct usb_bus *bus ) {
1958 struct usb_endpoint *ep;
1959 struct usb_port *port;
1960
1961 /* Sanity checks */
1962 assert ( list_empty ( &bus->devices ) );
1963 assert ( list_empty ( &bus->hubs ) );
1964 list_for_each_entry ( ep, &usb_halted, halted )
1965 assert ( ep->usb->port->hub->bus != bus );
1966 list_for_each_entry ( port, &usb_changed, changed )
1967 assert ( port->hub->bus != bus );
1968
1969 /* Free root hub */
1970 free_usb_hub ( bus->hub );
1971
1972 /* Free bus */
1973 free ( bus );
1974 }
1975
1976 /**
1977 * Find USB bus by device location
1978 *
1979 * @v bus_type Bus type
1980 * @v location Bus location
1981 * @ret bus USB bus, or NULL
1982 */
1983 struct usb_bus * find_usb_bus_by_location ( unsigned int bus_type,
1984 unsigned int location ) {
1985 struct usb_bus *bus;
1986
1987 for_each_usb_bus ( bus ) {
1988 if ( ( bus->dev->desc.bus_type == bus_type ) &&
1989 ( bus->dev->desc.location == location ) )
1990 return bus;
1991 }
1992
1993 return NULL;
1994 }
1995
1996 /******************************************************************************
1997 *
1998 * USB address assignment
1999 *
2000 ******************************************************************************
2001 */
2002
2003 /**
2004 * Allocate device address
2005 *
2006 * @v bus USB bus
2007 * @ret address Device address, or negative error
2008 */
2009 int usb_alloc_address ( struct usb_bus *bus ) {
2010 unsigned int address;
2011
2012 /* Find first free device address */
2013 address = ffsll ( ~bus->addresses );
2014 if ( ! address )
2015 return -ENOENT;
2016
2017 /* Mark address as used */
2018 bus->addresses |= ( 1ULL << ( address - 1 ) );
2019
2020 return address;
2021 }
2022
2023 /**
2024 * Free device address
2025 *
2026 * @v bus USB bus
2027 * @v address Device address
2028 */
2029 void usb_free_address ( struct usb_bus *bus, unsigned int address ) {
2030
2031 /* Sanity check */
2032 assert ( address > 0 );
2033 assert ( bus->addresses & ( 1ULL << ( address - 1 ) ) );
2034
2035 /* Mark address as free */
2036 bus->addresses &= ~( 1ULL << ( address - 1 ) );
2037 }
2038
2039 /******************************************************************************
2040 *
2041 * USB bus topology
2042 *
2043 ******************************************************************************
2044 */
2045
2046 /**
2047 * Get USB route string
2048 *
2049 * @v usb USB device
2050 * @ret route USB route string
2051 */
2052 unsigned int usb_route_string ( struct usb_device *usb ) {
2053 struct usb_device *parent;
2054 unsigned int route;
2055
2056 /* Navigate up to root hub, constructing route string as we go */
2057 for ( route = 0 ; ( parent = usb->port->hub->usb ) ; usb = parent ) {
2058 route <<= 4;
2059 route |= ( ( usb->port->address > 0xf ) ?
2060 0xf : usb->port->address );
2061 }
2062
2063 return route;
2064 }
2065
2066 /**
2067 * Get USB depth
2068 *
2069 * @v usb USB device
2070 * @ret depth Hub depth
2071 */
2072 unsigned int usb_depth ( struct usb_device *usb ) {
2073 struct usb_device *parent;
2074 unsigned int depth;
2075
2076 /* Navigate up to root hub, constructing depth as we go */
2077 for ( depth = 0 ; ( parent = usb->port->hub->usb ) ; usb = parent )
2078 depth++;
2079
2080 return depth;
2081 }
2082
2083 /**
2084 * Get USB root hub port
2085 *
2086 * @v usb USB device
2087 * @ret port Root hub port
2088 */
2089 struct usb_port * usb_root_hub_port ( struct usb_device *usb ) {
2090 struct usb_device *parent;
2091
2092 /* Navigate up to root hub */
2093 while ( ( parent = usb->port->hub->usb ) )
2094 usb = parent;
2095
2096 return usb->port;
2097 }
2098
2099 /**
2100 * Get USB transaction translator
2101 *
2102 * @v usb USB device
2103 * @ret port Transaction translator port, or NULL
2104 */
2105 struct usb_port * usb_transaction_translator ( struct usb_device *usb ) {
2106 struct usb_device *parent;
2107
2108 /* Navigate up to root hub. If we find a low-speed or
2109 * full-speed port with a higher-speed parent device, then
2110 * that port is the transaction translator.
2111 */
2112 for ( ; ( parent = usb->port->hub->usb ) ; usb = parent ) {
2113 if ( ( usb->port->speed <= USB_SPEED_FULL ) &&
2114 ( parent->port->speed > USB_SPEED_FULL ) )
2115 return usb->port;
2116 }
2117
2118 return NULL;
2119 }
2120
2121 /* Drag in objects via register_usb_bus() */
2122 REQUIRING_SYMBOL ( register_usb_bus );
2123
2124 /* Drag in USB configuration */
2125 REQUIRE_OBJECT ( config_usb );
2126
2127 /* Drag in hub driver */
2128 REQUIRE_OBJECT ( usbhub );