iPXE
usbio.c
Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2015 Michael Brown <mbrown@fensystems.co.uk>.
00003  *
00004  * This program is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU General Public License as
00006  * published by the Free Software Foundation; either version 2 of the
00007  * License, or (at your option) any later version.
00008  *
00009  * This program is distributed in the hope that it will be useful, but
00010  * WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU General Public License
00015  * along with this program; if not, write to the Free Software
00016  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
00017  * 02110-1301, USA.
00018  *
00019  * You can also choose to distribute this program under the terms of
00020  * the Unmodified Binary Distribution Licence (as given in the file
00021  * COPYING.UBDL), provided that you have satisfied its requirements.
00022  */
00023 
00024 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00025 
00026 #include <stdlib.h>
00027 #include <string.h>
00028 #include <errno.h>
00029 #include <assert.h>
00030 #include <ipxe/efi/efi.h>
00031 #include <ipxe/efi/efi_driver.h>
00032 #include <ipxe/efi/efi_utils.h>
00033 #include <ipxe/efi/Protocol/UsbIo.h>
00034 #include <ipxe/usb.h>
00035 #include "usbio.h"
00036 
00037 /** @file
00038  *
00039  * EFI_USB_IO_PROTOCOL pseudo Host Controller Interface driver
00040  *
00041  *
00042  * The EFI_USB_IO_PROTOCOL is an almost unbelievably poorly designed
00043  * abstraction of a USB device.  It would be just about forgivable for
00044  * an API to support only synchronous operation for bulk OUT
00045  * endpoints.  It is imbecilic to support only synchronous operation
00046  * for bulk IN endpoints.  This apparently intern-designed API
00047  * throttles a typical NIC down to 1.5% of its maximum throughput.
00048  * That isn't a typo.  It really is that slow.
00049  *
00050  * We can't even work around this stupidity by talking to the host
00051  * controller abstraction directly, because an identical limitation
00052  * exists in the EFI_USB2_HC_PROTOCOL.
00053  *
00054  * Unless you derive therapeutic value from watching download progress
00055  * indicators lethargically creep through every single integer from 0
00056  * to 100, you should use iPXE's native USB host controller drivers
00057  * instead.  (Or just upgrade from UEFI to "legacy" BIOS, which will
00058  * produce a similar speed increase.)
00059  *
00060  *
00061  * For added excitement, the EFI_USB_IO_PROTOCOL makes the
00062  * (demonstrably incorrect) assumption that a USB driver needs to
00063  * attach to exactly one interface within a USB device, and provides a
00064  * helper method to retrieve "the" interface descriptor.  Since pretty
00065  * much every USB network device requires binding to a pair of
00066  * control+data interfaces, this aspect of EFI_USB_IO_PROTOCOL is of
00067  * no use to us.
00068  *
00069  * We have our own existing code for reading USB descriptors, so we
00070  * don't actually care that the UsbGetInterfaceDescriptor() method
00071  * provided by EFI_USB_IO_PROTOCOL is useless for network devices.  We
00072  * can read the descriptors ourselves (via UsbControlTransfer()) and
00073  * get all of the information we need this way.  We can even work
00074  * around the fact that EFI_USB_IO_PROTOCOL provides separate handles
00075  * for each of the two interfaces comprising our network device.
00076  *
00077  * However, if we discover that we need to select an alternative
00078  * device configuration (e.g. for devices exposing both RNDIS and
00079  * ECM), then all hell breaks loose.  EFI_USB_IO_PROTOCOL starts to
00080  * panic because its cached interface and endpoint descriptors will no
00081  * longer be valid.  As mentioned above, the cached descriptors are
00082  * useless for network devices anyway so we _really_ don't care about
00083  * this, but EFI_USB_IO_PROTOCOL certainly cares.  It prints out a
00084  * manic warning message containing no fewer than six exclamation
00085  * marks and then literally commits seppuku in the middle of the
00086  * UsbControlTransfer() method by attempting to uninstall itself.
00087  * Quite how the caller is supposed to react when asked to stop using
00088  * the EFI_USB_IO_PROTOCOL instance while in the middle of an
00089  * uninterruptible call to said instance is left as an exercise for
00090  * the interested reader.
00091  *
00092  * There is no sensible way to work around this, so we just
00093  * preemptively fail if asked to change the device configuration, on
00094  * the basis that reporting a sarcastic error message is often
00095  * preferable to jumping through a NULL pointer and crashing the
00096  * system.
00097  */
00098 
00099 /* Disambiguate the various error causes */
00100 #define ENOTSUP_MORONIC_SPECIFICATION                                   \
00101         __einfo_error ( EINFO_ENOTSUP_MORONIC_SPECIFICATION )
00102 #define EINFO_ENOTSUP_MORONIC_SPECIFICATION                             \
00103         __einfo_uniqify ( EINFO_ENOTSUP, 0x01,                          \
00104                           "EFI_USB_IO_PROTOCOL was designed by morons" )
00105 
00106 /******************************************************************************
00107  *
00108  * Device model
00109  *
00110  ******************************************************************************
00111  */
00112 
00113 /**
00114  * Determine endpoint interface number
00115  *
00116  * @v usbio             USB I/O device
00117  * @v ep                USB Endpoint
00118  * @ret interface       Interface number, or negative error
00119  */
00120 static int usbio_interface ( struct usbio_device *usbio,
00121                              struct usb_endpoint *ep ) {
00122         EFI_HANDLE handle = usbio->handle;
00123         struct usb_device *usb = ep->usb;
00124         struct usb_configuration_descriptor *config;
00125         struct usb_interface_descriptor *interface;
00126         struct usb_endpoint_descriptor *endpoint;
00127         struct usb_function *func;
00128         unsigned int i;
00129 
00130         /* The control endpoint is not part of a described interface */
00131         if ( ep->address == USB_EP0_ADDRESS )
00132                 return 0;
00133 
00134         /* Iterate over all interface descriptors looking for a match */
00135         config = usbio->config;
00136         for_each_config_descriptor ( interface, config ) {
00137 
00138                 /* Skip non-interface descriptors */
00139                 if ( interface->header.type != USB_INTERFACE_DESCRIPTOR )
00140                         continue;
00141 
00142                 /* Iterate over all endpoint descriptors looking for a match */
00143                 for_each_interface_descriptor ( endpoint, config, interface ) {
00144 
00145                         /* Skip non-endpoint descriptors */
00146                         if ( endpoint->header.type != USB_ENDPOINT_DESCRIPTOR )
00147                                 continue;
00148 
00149                         /* Check endpoint address */
00150                         if ( endpoint->endpoint != ep->address )
00151                                 continue;
00152 
00153                         /* Check interface belongs to this function */
00154                         list_for_each_entry ( func, &usb->functions, list ) {
00155 
00156                                 /* Skip non-matching functions */
00157                                 if ( func->interface[0] != usbio->first )
00158                                         continue;
00159 
00160                                 /* Iterate over all interfaces for a match */
00161                                 for ( i = 0 ; i < func->desc.count ; i++ ) {
00162                                         if ( interface->interface ==
00163                                              func->interface[i] )
00164                                                 return interface->interface;
00165                                 }
00166                         }
00167                 }
00168         }
00169 
00170         DBGC ( usbio, "USBIO %s cannot find interface for %s",
00171                efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00172         return -ENOENT;
00173 }
00174 
00175 /**
00176  * Open USB I/O interface
00177  *
00178  * @v usbio             USB I/O device
00179  * @v interface         Interface number
00180  * @ret rc              Return status code
00181  */
00182 static int usbio_open ( struct usbio_device *usbio, unsigned int interface ) {
00183         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
00184         EFI_HANDLE handle = usbio->handle;
00185         struct usbio_interface *intf = &usbio->interface[interface];
00186         EFI_DEVICE_PATH_PROTOCOL *path;
00187         EFI_DEVICE_PATH_PROTOCOL *end;
00188         USB_DEVICE_PATH *usbpath;
00189         union {
00190                 void *interface;
00191                 EFI_USB_IO_PROTOCOL *io;
00192         } u;
00193         EFI_STATUS efirc;
00194         int rc;
00195 
00196         /* Sanity check */
00197         assert ( interface < usbio->config->interfaces );
00198 
00199         /* If interface is already open, just increment the usage count */
00200         if ( intf->count ) {
00201                 intf->count++;
00202                 return 0;
00203         }
00204 
00205         /* Construct device path for this interface */
00206         path = usbio->path;
00207         usbpath = usbio->usbpath;
00208         usbpath->InterfaceNumber = interface;
00209         end = efi_devpath_end ( path );
00210 
00211         /* Locate handle for this endpoint's interface */
00212         if ( ( efirc = bs->LocateDevicePath ( &efi_usb_io_protocol_guid, &path,
00213                                               &intf->handle ) ) != 0 ) {
00214                 rc = -EEFI ( efirc );
00215                 DBGC ( usbio, "USBIO %s could not locate ",
00216                        efi_handle_name ( handle ) );
00217                 DBGC ( usbio, "%s: %s\n",
00218                        efi_devpath_text ( usbio->path ), strerror ( rc ) );
00219                 return rc;
00220         }
00221 
00222         /* Check that expected path was located */
00223         if ( path != end ) {
00224                 DBGC ( usbio, "USBIO %s located incomplete ",
00225                        efi_handle_name ( handle ) );
00226                 DBGC ( usbio, "%s\n", efi_handle_name ( intf->handle ) );
00227                 return -EXDEV;
00228         }
00229 
00230         /* Open USB I/O protocol on this handle */
00231         if ( ( efirc = bs->OpenProtocol ( intf->handle,
00232                                           &efi_usb_io_protocol_guid,
00233                                           &u.interface, efi_image_handle,
00234                                           intf->handle,
00235                                           ( EFI_OPEN_PROTOCOL_BY_DRIVER |
00236                                             EFI_OPEN_PROTOCOL_EXCLUSIVE )))!=0){
00237                 rc = -EEFI ( efirc );
00238                 DBGC ( usbio, "USBIO %s cannot open ",
00239                        efi_handle_name ( handle ) );
00240                 DBGC ( usbio, "%s: %s\n",
00241                        efi_handle_name ( intf->handle ), strerror ( rc ) );
00242                 DBGC_EFI_OPENERS ( usbio, intf->handle,
00243                                    &efi_usb_io_protocol_guid );
00244                 return rc;
00245         }
00246         intf->io = u.io;
00247 
00248         /* Increment usage count */
00249         intf->count++;
00250 
00251         return 0;
00252 }
00253 
00254 /**
00255  * Close USB I/O interface
00256  *
00257  * @v usbio             USB I/O device
00258  * @v interface         Interface number
00259  */
00260 static void usbio_close ( struct usbio_device *usbio, unsigned int interface ) {
00261         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
00262         struct usbio_interface *intf = &usbio->interface[interface];
00263 
00264         /* Sanity checks */
00265         assert ( interface < usbio->config->interfaces );
00266         assert ( intf->count > 0 );
00267 
00268         /* Decrement usage count */
00269         intf->count--;
00270 
00271         /* Do nothing if interface is still in use */
00272         if ( intf->count )
00273                 return;
00274 
00275         /* Close USB I/O protocol */
00276         bs->CloseProtocol ( intf->handle, &efi_usb_io_protocol_guid,
00277                             efi_image_handle, intf->handle );
00278 }
00279 
00280 /******************************************************************************
00281  *
00282  * Control endpoints
00283  *
00284  ******************************************************************************
00285  */
00286 
00287 /**
00288  * Open control endpoint
00289  *
00290  * @v endpoint          Endpoint
00291  * @ret rc              Return status code
00292  */
00293 static int usbio_control_open ( struct usbio_endpoint *endpoint __unused ) {
00294 
00295         /* Nothing to do */
00296         return 0;
00297 }
00298 
00299 /**
00300  * Close control endpoint
00301  *
00302  * @v endpoint          Endpoint
00303  */
00304 static void usbio_control_close ( struct usbio_endpoint *endpoint __unused ) {
00305 
00306         /* Nothing to do */
00307 }
00308 
00309 /**
00310  * Poll control endpoint
00311  *
00312  * @v endpoint          Endpoint
00313  */
00314 static void usbio_control_poll ( struct usbio_endpoint *endpoint ) {
00315         struct usbio_device *usbio = endpoint->usbio;
00316         struct usb_endpoint *ep = endpoint->ep;
00317         EFI_HANDLE handle = usbio->handle;
00318         EFI_USB_IO_PROTOCOL *io;
00319         union {
00320                 struct usb_setup_packet setup;
00321                 EFI_USB_DEVICE_REQUEST efi;
00322         } *msg;
00323         EFI_USB_DATA_DIRECTION direction;
00324         struct io_buffer *iobuf;
00325         unsigned int index;
00326         unsigned int flags;
00327         unsigned int recipient;
00328         unsigned int interface;
00329         uint16_t request;
00330         void *data;
00331         size_t len;
00332         UINT32 status;
00333         EFI_STATUS efirc;
00334         int rc;
00335 
00336         /* Do nothing if ring is empty */
00337         if ( endpoint->cons == endpoint->prod )
00338                 return;
00339 
00340         /* Consume next transfer */
00341         index = ( endpoint->cons++ % USBIO_RING_COUNT );
00342         iobuf = endpoint->iobuf[index];
00343         flags = endpoint->flags[index];
00344 
00345         /* Sanity check */
00346         if ( ! ( flags & USBIO_MESSAGE ) ) {
00347                 DBGC ( usbio, "USBIO %s %s non-message transfer\n",
00348                        efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00349                 rc = -ENOTSUP;
00350                 goto err_not_message;
00351         }
00352 
00353         /* Construct transfer */
00354         assert ( iob_len ( iobuf ) >= sizeof ( *msg ) );
00355         msg = iobuf->data;
00356         iob_pull ( iobuf, sizeof ( *msg ) );
00357         request = le16_to_cpu ( msg->setup.request );
00358         len = iob_len ( iobuf );
00359         if ( len ) {
00360                 data = iobuf->data;
00361                 direction = ( ( request & USB_DIR_IN ) ?
00362                               EfiUsbDataIn : EfiUsbDataOut );
00363         } else {
00364                 data = NULL;
00365                 direction = EfiUsbNoData;
00366         }
00367 
00368         /* Determine interface for this transfer */
00369         recipient = ( request & USB_RECIP_MASK );
00370         if ( recipient == USB_RECIP_INTERFACE ) {
00371                 /* Recipient is an interface: use interface number directly */
00372                 interface = le16_to_cpu ( msg->setup.index );
00373         } else {
00374                 /* Route all other requests through the first interface */
00375                 interface = 0;
00376         }
00377 
00378         /* Open interface */
00379         if ( ( rc = usbio_open ( usbio, interface ) ) != 0 )
00380                 goto err_open;
00381         io = usbio->interface[interface].io;
00382 
00383         /* Due to the design of EFI_USB_IO_PROTOCOL, attempting to set
00384          * the configuration to a non-default value is basically a
00385          * self-destruct button.
00386          */
00387         if ( ( request == USB_SET_CONFIGURATION ) &&
00388              ( le16_to_cpu ( msg->setup.value ) != usbio->config->config ) ) {
00389                 rc = -ENOTSUP_MORONIC_SPECIFICATION;
00390                 DBGC ( usbio, "USBIO %s cannot change configuration: %s\n",
00391                        efi_handle_name ( handle ), strerror ( rc ) );
00392                 goto err_moronic_specification;
00393         }
00394 
00395         /* Submit transfer */
00396         if ( ( efirc = io->UsbControlTransfer ( io, &msg->efi, direction, 0,
00397                                                 data, len, &status ) ) != 0 ) {
00398                 rc = -EEFI ( efirc );
00399                 DBGC ( usbio, "USBIO %s %s could not submit control transfer ",
00400                        efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00401                 DBGC ( usbio, "via %s: %s (status %04x)\n",
00402                        efi_handle_name ( usbio->interface[interface].handle ),
00403                        strerror ( rc ), status );
00404                 goto err_transfer;
00405         }
00406 
00407         /* Close interface */
00408         usbio_close ( usbio, interface );
00409 
00410         /* Complete transfer */
00411         usb_complete ( ep, iobuf );
00412 
00413         return;
00414 
00415  err_transfer:
00416  err_moronic_specification:
00417         usbio_close ( usbio, interface );
00418  err_open:
00419  err_not_message:
00420         usb_complete_err ( ep, iobuf, rc );
00421 }
00422 
00423 /** Control endpoint operations */
00424 static struct usbio_operations usbio_control_operations = {
00425         .open   = usbio_control_open,
00426         .close  = usbio_control_close,
00427         .poll   = usbio_control_poll,
00428 };
00429 
00430 /******************************************************************************
00431  *
00432  * Bulk IN endpoints
00433  *
00434  ******************************************************************************
00435  */
00436 
00437 /**
00438  * Open bulk IN endpoint
00439  *
00440  * @v endpoint          Endpoint
00441  * @ret rc              Return status code
00442  */
00443 static int usbio_bulk_in_open ( struct usbio_endpoint *endpoint __unused ) {
00444 
00445         /* Nothing to do */
00446         return 0;
00447 }
00448 
00449 /**
00450  * Close bulk IN endpoint
00451  *
00452  * @v endpoint          Endpoint
00453  */
00454 static void usbio_bulk_in_close ( struct usbio_endpoint *endpoint __unused ) {
00455 
00456         /* Nothing to do */
00457 }
00458 
00459 /**
00460  * Poll bulk IN endpoint
00461  *
00462  * @v endpoint          Endpoint
00463  */
00464 static void usbio_bulk_in_poll ( struct usbio_endpoint *endpoint ) {
00465         struct usbio_device *usbio = endpoint->usbio;
00466         struct usb_endpoint *ep = endpoint->ep;
00467         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00468         EFI_HANDLE handle = usbio->handle;
00469         struct io_buffer *iobuf;
00470         unsigned int index;
00471         UINTN len;
00472         UINT32 status;
00473         EFI_STATUS efirc;
00474         int rc;
00475 
00476         /* Do nothing if ring is empty */
00477         if ( endpoint->cons == endpoint->prod )
00478                 return;
00479 
00480         /* Attempt (but do not yet consume) next transfer */
00481         index = ( endpoint->cons % USBIO_RING_COUNT );
00482         iobuf = endpoint->iobuf[index];
00483 
00484         /* Construct transfer */
00485         len = iob_len ( iobuf );
00486 
00487         /* Upon being turned on, the EFI_USB_IO_PROTOCOL did nothing
00488          * for several minutes before firing a small ARP packet a few
00489          * millimetres into the ether.
00490          */
00491         efirc = io->UsbBulkTransfer ( io, ep->address, iobuf->data,
00492                                       &len, 1, &status );
00493         if ( efirc == EFI_TIMEOUT )
00494                 return;
00495 
00496         /* Consume transfer */
00497         endpoint->cons++;
00498 
00499         /* Check for failure */
00500         if ( efirc != 0 ) {
00501                 rc = -EEFI ( efirc );
00502                 DBGC2 ( usbio, "USBIO %s %s could not submit bulk IN transfer: "
00503                         "%s (status %04x)\n", efi_handle_name ( handle ),
00504                         usb_endpoint_name ( ep ), strerror ( rc ), status );
00505                 usb_complete_err ( ep, iobuf, rc );
00506                 return;
00507         }
00508 
00509         /* Update length */
00510         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00511 
00512         /* Complete transfer */
00513         usb_complete ( ep, iobuf );
00514 }
00515 
00516 /** Bulk endpoint operations */
00517 static struct usbio_operations usbio_bulk_in_operations = {
00518         .open   = usbio_bulk_in_open,
00519         .close  = usbio_bulk_in_close,
00520         .poll   = usbio_bulk_in_poll,
00521 };
00522 
00523 /******************************************************************************
00524  *
00525  * Bulk OUT endpoints
00526  *
00527  ******************************************************************************
00528  */
00529 
00530 /**
00531  * Open bulk OUT endpoint
00532  *
00533  * @v endpoint          Endpoint
00534  * @ret rc              Return status code
00535  */
00536 static int usbio_bulk_out_open ( struct usbio_endpoint *endpoint __unused ) {
00537 
00538         /* Nothing to do */
00539         return 0;
00540 }
00541 
00542 /**
00543  * Close bulk OUT endpoint
00544  *
00545  * @v endpoint          Endpoint
00546  */
00547 static void usbio_bulk_out_close ( struct usbio_endpoint *endpoint __unused ) {
00548 
00549         /* Nothing to do */
00550 }
00551 
00552 /**
00553  * Poll bulk OUT endpoint
00554  *
00555  * @v endpoint          Endpoint
00556  */
00557 static void usbio_bulk_out_poll ( struct usbio_endpoint *endpoint ) {
00558         struct usbio_device *usbio = endpoint->usbio;
00559         struct usb_endpoint *ep = endpoint->ep;
00560         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00561         EFI_HANDLE handle = usbio->handle;
00562         struct io_buffer *iobuf;
00563         unsigned int index;
00564         unsigned int flags;
00565         UINTN len;
00566         UINT32 status;
00567         EFI_STATUS efirc;
00568         int rc;
00569 
00570         /* Do nothing if ring is empty */
00571         if ( endpoint->cons == endpoint->prod )
00572                 return;
00573 
00574         /* Consume next transfer */
00575         index = ( endpoint->cons++ % USBIO_RING_COUNT );
00576         iobuf = endpoint->iobuf[index];
00577         flags = endpoint->flags[index];
00578 
00579         /* Construct transfer */
00580         len = iob_len ( iobuf );
00581 
00582         /* Submit transfer */
00583         if ( ( efirc = io->UsbBulkTransfer ( io, ep->address, iobuf->data,
00584                                              &len, 0, &status ) ) != 0 ) {
00585                 rc = -EEFI ( efirc );
00586                 DBGC ( usbio, "USBIO %s %s could not submit bulk OUT transfer: "
00587                        "%s (status %04x)\n", efi_handle_name ( handle ),
00588                        usb_endpoint_name ( ep ), strerror ( rc ), status );
00589                 goto err;
00590         }
00591 
00592         /* Update length */
00593         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00594 
00595         /* Submit zero-length transfer if required */
00596         len = 0;
00597         if ( ( flags & USBIO_ZLEN ) &&
00598              ( efirc = io->UsbBulkTransfer ( io, ep->address, NULL, &len, 0,
00599                                              &status ) ) != 0 ) {
00600                 rc = -EEFI ( efirc );
00601                 DBGC ( usbio, "USBIO %s %s could not submit zero-length "
00602                        "transfer: %s (status %04x)\n",
00603                        efi_handle_name ( handle ), usb_endpoint_name ( ep ),
00604                        strerror ( rc ), status );
00605                 goto err;
00606         }
00607 
00608         /* Complete transfer */
00609         usb_complete ( ep, iobuf );
00610 
00611         return;
00612 
00613  err:
00614         usb_complete_err ( ep, iobuf, rc );
00615 }
00616 
00617 /** Bulk endpoint operations */
00618 static struct usbio_operations usbio_bulk_out_operations = {
00619         .open   = usbio_bulk_out_open,
00620         .close  = usbio_bulk_out_close,
00621         .poll   = usbio_bulk_out_poll,
00622 };
00623 
00624 /******************************************************************************
00625  *
00626  * Interrupt endpoints
00627  *
00628  ******************************************************************************
00629  *
00630  * The EFI_USB_IO_PROTOCOL provides two ways to interact with
00631  * interrupt endpoints, neither of which naturally model the hardware
00632  * interaction.  The UsbSyncInterruptTransfer() method allows imposes
00633  * a 1ms overhead for every interrupt transfer (which could result in
00634  * up to a 50% decrease in overall throughput for the device).  The
00635  * UsbAsyncInterruptTransfer() method provides no way for us to
00636  * prevent transfers when no I/O buffers are available.
00637  *
00638  * We work around this design by utilising a small, fixed ring buffer
00639  * into which the interrupt callback delivers the data.  This aims to
00640  * provide buffer space even if no I/O buffers have yet been enqueued.
00641  * The scheme is not guaranteed since the fixed ring buffer may also
00642  * become full.  However:
00643  *
00644  *   - devices which send a constant stream of interrupts (and which
00645  *     therefore might exhaust the fixed ring buffer) tend to be
00646  *     responding to every interrupt request, and can tolerate lost
00647  *     packets, and
00648  *
00649  *   - devices which cannot tolerate lost interrupt packets tend to send
00650  *     only a few small messages.
00651  *
00652  * The scheme should therefore work in practice.
00653  */
00654 
00655 /**
00656  * Interrupt endpoint callback
00657  *
00658  * @v data              Received data
00659  * @v len               Length of received data
00660  * @v context           Callback context
00661  * @v status            Transfer status
00662  * @ret efirc           EFI status code
00663  */
00664 static EFI_STATUS EFIAPI usbio_interrupt_callback ( VOID *data, UINTN len,
00665                                                     VOID *context,
00666                                                     UINT32 status ) {
00667         struct usbio_interrupt_ring *intr = context;
00668         struct usbio_endpoint *endpoint = intr->endpoint;
00669         struct usbio_device *usbio = endpoint->usbio;
00670         struct usb_endpoint *ep = endpoint->ep;
00671         EFI_HANDLE handle = usbio->handle;
00672         unsigned int fill;
00673         unsigned int index;
00674 
00675         /* Sanity check */
00676         assert ( len <= ep->mtu );
00677 
00678         /* Do nothing if ring is empty */
00679         fill = ( intr->prod - intr->cons );
00680         if ( fill >= USBIO_INTR_COUNT ) {
00681                 DBGC ( usbio, "USBIO %s %s dropped interrupt completion\n",
00682                        efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00683                 return 0;
00684         }
00685 
00686         /* Do nothing if transfer was unsuccessful */
00687         if ( status != 0 ) {
00688                 DBGC ( usbio, "USBIO %s %s interrupt completion status %04x\n",
00689                        efi_handle_name ( handle ), usb_endpoint_name ( ep ),
00690                        status );
00691                 return 0; /* Unclear what failure actually means here */
00692         }
00693 
00694         /* Copy data to buffer and increment producer counter */
00695         index = ( intr->prod % USBIO_INTR_COUNT );
00696         memcpy ( intr->data[index], data, len );
00697         intr->len[index] = len;
00698         intr->prod++;
00699 
00700         return 0;
00701 }
00702 
00703 /**
00704  * Open interrupt endpoint
00705  *
00706  * @v endpoint          Endpoint
00707  * @ret rc              Return status code
00708  */
00709 static int usbio_interrupt_open ( struct usbio_endpoint *endpoint ) {
00710         struct usbio_device *usbio = endpoint->usbio;
00711         struct usbio_interrupt_ring *intr;
00712         struct usb_endpoint *ep = endpoint->ep;
00713         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00714         EFI_HANDLE handle = usbio->handle;
00715         unsigned int interval;
00716         unsigned int i;
00717         void *data;
00718         EFI_STATUS efirc;
00719         int rc;
00720 
00721         /* Allocate interrupt ring buffer */
00722         intr = zalloc ( sizeof ( *intr ) + ( USBIO_INTR_COUNT * ep->mtu ) );
00723         if ( ! intr ) {
00724                 rc = -ENOMEM;
00725                 goto err_alloc;
00726         }
00727         endpoint->intr = intr;
00728         intr->endpoint = endpoint;
00729         data = ( ( ( void * ) intr ) + sizeof ( *intr ) );
00730         for ( i = 0 ; i < USBIO_INTR_COUNT ; i++ ) {
00731                 intr->data[i] = data;
00732                 data += ep->mtu;
00733         }
00734 
00735         /* Determine polling interval */
00736         interval = ( ep->interval >> 3 /* microframes -> milliseconds */ );
00737         if ( ! interval )
00738                 interval = 1; /* May not be zero */
00739 
00740         /* Add to periodic schedule */
00741         if ( ( efirc = io->UsbAsyncInterruptTransfer ( io, ep->address, TRUE,
00742                                                        interval, ep->mtu,
00743                                                        usbio_interrupt_callback,
00744                                                        intr ) ) != 0 ) {
00745                 rc = -EEFI ( efirc );
00746                 DBGC ( usbio, "USBIO %s %s could not schedule interrupt "
00747                        "transfer: %s\n", efi_handle_name ( handle ),
00748                        usb_endpoint_name ( ep ), strerror ( rc ) );
00749                 goto err_schedule;
00750         }
00751 
00752         return 0;
00753 
00754         io->UsbAsyncInterruptTransfer ( io, ep->address, FALSE, 0, 0,
00755                                         NULL, NULL );
00756  err_schedule:
00757         free ( intr );
00758  err_alloc:
00759         return rc;
00760 }
00761 
00762 /**
00763  * Close interrupt endpoint
00764  *
00765  * @v endpoint          Endpoint
00766  */
00767 static void usbio_interrupt_close ( struct usbio_endpoint *endpoint ) {
00768         struct usb_endpoint *ep = endpoint->ep;
00769         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00770 
00771         /* Remove from periodic schedule */
00772         io->UsbAsyncInterruptTransfer ( io, ep->address, FALSE, 0, 0,
00773                                         NULL, NULL );
00774 
00775         /* Free interrupt ring buffer */
00776         free ( endpoint->intr );
00777 }
00778 
00779 /**
00780  * Poll interrupt endpoint
00781  *
00782  * @v endpoint          Endpoint
00783  */
00784 static void usbio_interrupt_poll ( struct usbio_endpoint *endpoint ) {
00785         struct usbio_interrupt_ring *intr = endpoint->intr;
00786         struct usb_endpoint *ep = endpoint->ep;
00787         struct io_buffer *iobuf;
00788         unsigned int index;
00789         unsigned int intr_index;
00790         size_t len;
00791 
00792         /* Do nothing if ring is empty */
00793         if ( endpoint->cons == endpoint->prod )
00794                 return;
00795 
00796         /* Do nothing if interrupt ring is empty */
00797         if ( intr->cons == intr->prod )
00798                 return;
00799 
00800         /* Consume next transfer */
00801         index = ( endpoint->cons++ % USBIO_RING_COUNT );
00802         iobuf = endpoint->iobuf[index];
00803 
00804         /* Populate I/O buffer */
00805         intr_index = ( intr->cons++ % USBIO_INTR_COUNT );
00806         len = intr->len[intr_index];
00807         assert ( len <= iob_len ( iobuf ) );
00808         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00809         memcpy ( iobuf->data, intr->data[intr_index], len );
00810 
00811         /* Complete transfer */
00812         usb_complete ( ep, iobuf );
00813 }
00814 
00815 /** Interrupt endpoint operations */
00816 static struct usbio_operations usbio_interrupt_operations = {
00817         .open   = usbio_interrupt_open,
00818         .close  = usbio_interrupt_close,
00819         .poll   = usbio_interrupt_poll,
00820 };
00821 
00822 /******************************************************************************
00823  *
00824  * Endpoint operations
00825  *
00826  ******************************************************************************
00827  */
00828 
00829 /**
00830  * Open endpoint
00831  *
00832  * @v ep                USB endpoint
00833  * @ret rc              Return status code
00834  */
00835 static int usbio_endpoint_open ( struct usb_endpoint *ep ) {
00836         struct usb_bus *bus = ep->usb->port->hub->bus;
00837         struct usbio_device *usbio = usb_bus_get_hostdata ( bus );
00838         struct usbio_endpoint *endpoint;
00839         EFI_HANDLE handle = usbio->handle;
00840         unsigned int attr = ( ep->attributes & USB_ENDPOINT_ATTR_TYPE_MASK );
00841         int interface;
00842         int rc;
00843 
00844         /* Allocate and initialise structure */
00845         endpoint = zalloc ( sizeof ( *endpoint ) );
00846         if ( ! endpoint ) {
00847                 rc = -ENOMEM;
00848                 goto err_alloc;
00849         }
00850         usb_endpoint_set_hostdata ( ep, endpoint );
00851         endpoint->usbio = usbio;
00852         endpoint->ep = ep;
00853 
00854         /* Identify endpoint operations */
00855         if ( attr == USB_ENDPOINT_ATTR_CONTROL ) {
00856                 endpoint->op = &usbio_control_operations;
00857         } else if ( attr == USB_ENDPOINT_ATTR_BULK ) {
00858                 endpoint->op = ( ( ep->address & USB_DIR_IN ) ?
00859                                  &usbio_bulk_in_operations :
00860                                  &usbio_bulk_out_operations );
00861         } else if ( attr == USB_ENDPOINT_ATTR_INTERRUPT ) {
00862                 endpoint->op = &usbio_interrupt_operations;
00863         } else {
00864                 rc = -ENOTSUP;
00865                 goto err_operations;
00866         }
00867 
00868         /* Identify interface for this endpoint */
00869         interface = usbio_interface ( usbio, ep );
00870         if ( interface < 0 ) {
00871                 rc = interface;
00872                 goto err_interface;
00873         }
00874         endpoint->interface = interface;
00875 
00876         /* Open interface */
00877         if ( ( rc = usbio_open ( usbio, interface ) ) != 0 )
00878                 goto err_open_interface;
00879         endpoint->handle = usbio->interface[interface].handle;
00880         endpoint->io = usbio->interface[interface].io;
00881         DBGC ( usbio, "USBIO %s %s using ",
00882                efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00883         DBGC ( usbio, "%s\n", efi_handle_name ( endpoint->handle ) );
00884 
00885         /* Open endpoint */
00886         if ( ( rc = endpoint->op->open ( endpoint ) ) != 0 )
00887                 goto err_open_endpoint;
00888 
00889         /* Add to list of endpoints */
00890         list_add_tail ( &endpoint->list, &usbio->endpoints );
00891 
00892         return 0;
00893 
00894         list_del ( &endpoint->list );
00895         endpoint->op->close ( endpoint );
00896  err_open_endpoint:
00897         usbio_close ( usbio, interface );
00898  err_open_interface:
00899  err_interface:
00900  err_operations:
00901         free ( endpoint );
00902  err_alloc:
00903         return rc;
00904 }
00905 
00906 /**
00907  * Close endpoint
00908  *
00909  * @v ep                USB endpoint
00910  */
00911 static void usbio_endpoint_close ( struct usb_endpoint *ep ) {
00912         struct usbio_endpoint *endpoint = usb_endpoint_get_hostdata ( ep );
00913         struct usbio_device *usbio = endpoint->usbio;
00914         struct io_buffer *iobuf;
00915         unsigned int index;
00916 
00917         /* Remove from list of endpoints */
00918         list_del ( &endpoint->list );
00919 
00920         /* Close endpoint */
00921         endpoint->op->close ( endpoint );
00922 
00923         /* Close interface */
00924         usbio_close ( usbio, endpoint->interface );
00925 
00926         /* Cancel any incomplete transfers */
00927         while ( endpoint->cons != endpoint->prod ) {
00928                 index = ( endpoint->cons++ % USBIO_RING_COUNT );
00929                 iobuf = endpoint->iobuf[index];
00930                 usb_complete_err ( ep, iobuf, -ECANCELED );
00931         }
00932 
00933         /* Free endpoint */
00934         free ( endpoint );
00935 }
00936 
00937 /**
00938  * Reset endpoint
00939  *
00940  * @v ep                USB endpoint
00941  * @ret rc              Return status code
00942  */
00943 static int usbio_endpoint_reset ( struct usb_endpoint *ep __unused ) {
00944 
00945         /* Nothing to do */
00946         return 0;
00947 }
00948 
00949 /**
00950  * Update MTU
00951  *
00952  * @v ep                USB endpoint
00953  * @ret rc              Return status code
00954  */
00955 static int usbio_endpoint_mtu ( struct usb_endpoint *ep __unused ) {
00956 
00957         /* Nothing to do */
00958         return 0;
00959 }
00960 
00961 /**
00962  * Enqueue transfer
00963  *
00964  * @v ep                USB endpoint
00965  * @v iobuf             I/O buffer
00966  * @v flags             Transfer flags
00967  * @ret rc              Return status code
00968  */
00969 static int usbio_endpoint_enqueue ( struct usb_endpoint *ep,
00970                                     struct io_buffer *iobuf,
00971                                     unsigned int flags ) {
00972         struct usbio_endpoint *endpoint = usb_endpoint_get_hostdata ( ep );
00973         unsigned int fill;
00974         unsigned int index;
00975 
00976         /* Fail if transfer ring is full */
00977         fill = ( endpoint->prod - endpoint->cons );
00978         if ( fill >= USBIO_RING_COUNT )
00979                 return -ENOBUFS;
00980 
00981         /* Add to ring */
00982         index = ( endpoint->prod++ % USBIO_RING_COUNT );
00983         endpoint->iobuf[index] = iobuf;
00984         endpoint->flags[index] = flags;
00985 
00986         return 0;
00987 }
00988 
00989 /**
00990  * Enqueue message transfer
00991  *
00992  * @v ep                USB endpoint
00993  * @v iobuf             I/O buffer
00994  * @ret rc              Return status code
00995  */
00996 static int usbio_endpoint_message ( struct usb_endpoint *ep,
00997                                     struct io_buffer *iobuf ) {
00998 
00999         /* Enqueue transfer */
01000         return usbio_endpoint_enqueue ( ep, iobuf, USBIO_MESSAGE );
01001 }
01002 
01003 /**
01004  * Enqueue stream transfer
01005  *
01006  * @v ep                USB endpoint
01007  * @v iobuf             I/O buffer
01008  * @v zlp               Append a zero-length packet
01009  * @ret rc              Return status code
01010  */
01011 static int usbio_endpoint_stream ( struct usb_endpoint *ep,
01012                                    struct io_buffer *iobuf, int zlp ) {
01013 
01014         /* Enqueue transfer */
01015         return usbio_endpoint_enqueue ( ep, iobuf, ( zlp ? USBIO_ZLEN : 0 ) );
01016 }
01017 
01018 /**
01019  * Poll for completions
01020  *
01021  * @v endpoint          Endpoint
01022  */
01023 static void usbio_endpoint_poll ( struct usbio_endpoint *endpoint ) {
01024 
01025         /* Poll endpoint */
01026         endpoint->op->poll ( endpoint );
01027 }
01028 
01029 /******************************************************************************
01030  *
01031  * Device operations
01032  *
01033  ******************************************************************************
01034  */
01035 
01036 /**
01037  * Open device
01038  *
01039  * @v usb               USB device
01040  * @ret rc              Return status code
01041  */
01042 static int usbio_device_open ( struct usb_device *usb ) {
01043         struct usbio_device *usbio =
01044                 usb_bus_get_hostdata ( usb->port->hub->bus );
01045 
01046         usb_set_hostdata ( usb, usbio );
01047         return 0;
01048 }
01049 
01050 /**
01051  * Close device
01052  *
01053  * @v usb               USB device
01054  */
01055 static void usbio_device_close ( struct usb_device *usb __unused ) {
01056 
01057         /* Nothing to do */
01058 }
01059 
01060 /**
01061  * Assign device address
01062  *
01063  * @v usb               USB device
01064  * @ret rc              Return status code
01065  */
01066 static int usbio_device_address ( struct usb_device *usb __unused ) {
01067 
01068         /* Nothing to do */
01069         return 0;
01070 }
01071 
01072 /******************************************************************************
01073  *
01074  * Hub operations
01075  *
01076  ******************************************************************************
01077  */
01078 
01079 /**
01080  * Open hub
01081  *
01082  * @v hub               USB hub
01083  * @ret rc              Return status code
01084  */
01085 static int usbio_hub_open ( struct usb_hub *hub ) {
01086 
01087         /* Disallow non-root hubs */
01088         if ( hub->usb )
01089                 return -ENOTSUP;
01090 
01091         /* Nothing to do */
01092         return 0;
01093 }
01094 
01095 /**
01096  * Close hub
01097  *
01098  * @v hub               USB hub
01099  */
01100 static void usbio_hub_close ( struct usb_hub *hub __unused ) {
01101 
01102         /* Nothing to do */
01103 }
01104 
01105 /******************************************************************************
01106  *
01107  * Root hub operations
01108  *
01109  ******************************************************************************
01110  */
01111 
01112 /**
01113  * Open root hub
01114  *
01115  * @v hub               USB hub
01116  * @ret rc              Return status code
01117  */
01118 static int usbio_root_open ( struct usb_hub *hub __unused ) {
01119 
01120         /* Nothing to do */
01121         return 0;
01122 }
01123 
01124 /**
01125  * Close root hub
01126  *
01127  * @v hub               USB hub
01128  */
01129 static void usbio_root_close ( struct usb_hub *hub __unused ) {
01130 
01131         /* Nothing to do */
01132 }
01133 
01134 /**
01135  * Enable port
01136  *
01137  * @v hub               USB hub
01138  * @v port              USB port
01139  * @ret rc              Return status code
01140  */
01141 static int usbio_root_enable ( struct usb_hub *hub __unused,
01142                                struct usb_port *port __unused ) {
01143 
01144         /* Nothing to do */
01145         return 0;
01146 }
01147 
01148 /**
01149  * Disable port
01150  *
01151  * @v hub               USB hub
01152  * @v port              USB port
01153  * @ret rc              Return status code
01154  */
01155 static int usbio_root_disable ( struct usb_hub *hub __unused,
01156                                 struct usb_port *port __unused ) {
01157 
01158         /* Nothing to do */
01159         return 0;
01160 }
01161 
01162 /**
01163  * Update root hub port speed
01164  *
01165  * @v hub               USB hub
01166  * @v port              USB port
01167  * @ret rc              Return status code
01168  */
01169 static int usbio_root_speed ( struct usb_hub *hub __unused,
01170                               struct usb_port *port ) {
01171 
01172         /* Not actually exposed via EFI_USB_IO_PROTOCOL */
01173         port->speed = USB_SPEED_HIGH;
01174         return 0;
01175 }
01176 
01177 /**
01178  * Clear transaction translator buffer
01179  *
01180  * @v hub               USB hub
01181  * @v port              USB port
01182  * @v ep                USB endpoint
01183  * @ret rc              Return status code
01184  */
01185 static int usbio_root_clear_tt ( struct usb_hub *hub __unused,
01186                                  struct usb_port *port __unused,
01187                                  struct usb_endpoint *ep __unused ) {
01188 
01189         /* Should never be called; this is a root hub */
01190         return -ENOTSUP;
01191 }
01192 
01193 /******************************************************************************
01194  *
01195  * Bus operations
01196  *
01197  ******************************************************************************
01198  */
01199 
01200 /**
01201  * Open USB bus
01202  *
01203  * @v bus               USB bus
01204  * @ret rc              Return status code
01205  */
01206 static int usbio_bus_open ( struct usb_bus *bus __unused ) {
01207 
01208         /* Nothing to do */
01209         return 0;
01210 }
01211 
01212 /**
01213  * Close USB bus
01214  *
01215  * @v bus               USB bus
01216  */
01217 static void usbio_bus_close ( struct usb_bus *bus __unused ) {
01218 
01219         /* Nothing to do */
01220 }
01221 
01222 /**
01223  * Poll USB bus
01224  *
01225  * @v bus               USB bus
01226  */
01227 static void usbio_bus_poll ( struct usb_bus *bus ) {
01228         struct usbio_device *usbio = usb_bus_get_hostdata ( bus );
01229         struct usbio_endpoint *endpoint;
01230 
01231         /* Poll all endpoints.  We trust that completion handlers are
01232          * minimal and will not do anything that could plausibly
01233          * affect the endpoint list itself.
01234          */
01235         list_for_each_entry ( endpoint, &usbio->endpoints, list )
01236                 usbio_endpoint_poll ( endpoint );
01237 }
01238 
01239 /******************************************************************************
01240  *
01241  * EFI driver interface
01242  *
01243  ******************************************************************************
01244  */
01245 
01246 /** USB I/O host controller driver operations */
01247 static struct usb_host_operations usbio_operations = {
01248         .endpoint = {
01249                 .open = usbio_endpoint_open,
01250                 .close = usbio_endpoint_close,
01251                 .reset = usbio_endpoint_reset,
01252                 .mtu = usbio_endpoint_mtu,
01253                 .message = usbio_endpoint_message,
01254                 .stream = usbio_endpoint_stream,
01255         },
01256         .device = {
01257                 .open = usbio_device_open,
01258                 .close = usbio_device_close,
01259                 .address = usbio_device_address,
01260         },
01261         .bus = {
01262                 .open = usbio_bus_open,
01263                 .close = usbio_bus_close,
01264                 .poll = usbio_bus_poll,
01265         },
01266         .hub = {
01267                 .open = usbio_hub_open,
01268                 .close = usbio_hub_close,
01269         },
01270         .root = {
01271                 .open = usbio_root_open,
01272                 .close = usbio_root_close,
01273                 .enable = usbio_root_enable,
01274                 .disable = usbio_root_disable,
01275                 .speed = usbio_root_speed,
01276                 .clear_tt = usbio_root_clear_tt,
01277         },
01278 };
01279 
01280 /**
01281  * Check to see if driver supports a device
01282  *
01283  * @v handle            EFI device handle
01284  * @ret rc              Return status code
01285  */
01286 static int usbio_supported ( EFI_HANDLE handle ) {
01287         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01288         EFI_USB_DEVICE_DESCRIPTOR device;
01289         EFI_USB_INTERFACE_DESCRIPTOR interface;
01290         struct usb_function_descriptor desc;
01291         struct usb_driver *driver;
01292         struct usb_device_id *id;
01293         union {
01294                 void *interface;
01295                 EFI_USB_IO_PROTOCOL *io;
01296         } usb;
01297         EFI_STATUS efirc;
01298         int rc;
01299 
01300         /* Get protocol */
01301         if ( ( efirc = bs->OpenProtocol ( handle, &efi_usb_io_protocol_guid,
01302                                           &usb.interface, efi_image_handle,
01303                                           handle,
01304                                           EFI_OPEN_PROTOCOL_GET_PROTOCOL ))!=0){
01305                 rc = -EEFI ( efirc );
01306                 DBGCP ( handle, "USB %s is not a USB device\n",
01307                         efi_handle_name ( handle ) );
01308                 goto err_open_protocol;
01309         }
01310 
01311         /* Get device descriptor */
01312         if ( ( efirc = usb.io->UsbGetDeviceDescriptor ( usb.io,
01313                                                         &device ) ) != 0 ) {
01314                 rc = -EEFI ( efirc );
01315                 DBGC ( handle, "USB %s could not get device descriptor: "
01316                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01317                 goto err_get_device_descriptor;
01318         }
01319         memset ( &desc, 0, sizeof ( desc ) );
01320         desc.vendor = device.IdVendor;
01321         desc.product = device.IdProduct;
01322 
01323         /* Get interface descriptor */
01324         if ( ( efirc = usb.io->UsbGetInterfaceDescriptor ( usb.io,
01325                                                            &interface ) ) !=0){
01326                 rc = -EEFI ( efirc );
01327                 DBGC ( handle, "USB %s could not get interface descriptor: "
01328                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01329                 goto err_get_interface_descriptor;
01330         }
01331         desc.class.class.class = interface.InterfaceClass;
01332         desc.class.class.subclass = interface.InterfaceSubClass;
01333         desc.class.class.protocol = interface.InterfaceProtocol;
01334 
01335         /* Look for a driver for this interface */
01336         driver = usb_find_driver ( &desc, &id );
01337         if ( ! driver ) {
01338                 rc = -ENOTSUP;
01339                 goto err_unsupported;
01340         }
01341 
01342         /* Success */
01343         rc = 0;
01344 
01345  err_unsupported:
01346  err_get_interface_descriptor:
01347  err_get_device_descriptor:
01348         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01349                             efi_image_handle, handle );
01350  err_open_protocol:
01351         return rc;
01352 }
01353 
01354 /**
01355  * Fetch configuration descriptor
01356  *
01357  * @v usbio             USB I/O device
01358  * @ret rc              Return status code
01359  */
01360 static int usbio_config ( struct usbio_device *usbio ) {
01361         EFI_HANDLE handle = usbio->handle;
01362         EFI_USB_IO_PROTOCOL *io = usbio->io;
01363         EFI_USB_DEVICE_DESCRIPTOR device;
01364         EFI_USB_CONFIG_DESCRIPTOR partial;
01365         union {
01366                 struct usb_setup_packet setup;
01367                 EFI_USB_DEVICE_REQUEST efi;
01368         } msg;
01369         UINT32 status;
01370         size_t len;
01371         unsigned int count;
01372         unsigned int value;
01373         unsigned int i;
01374         EFI_STATUS efirc;
01375         int rc;
01376 
01377         /* Get device descriptor */
01378         if ( ( efirc = io->UsbGetDeviceDescriptor ( io, &device ) ) != 0 ) {
01379                 rc = -EEFI ( efirc );
01380                 DBGC ( usbio, "USB %s could not get device descriptor: "
01381                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01382                 goto err_get_device_descriptor;
01383         }
01384         count = device.NumConfigurations;
01385 
01386         /* Get current partial configuration descriptor */
01387         if ( ( efirc = io->UsbGetConfigDescriptor ( io, &partial ) ) != 0 ) {
01388                 rc = -EEFI ( efirc );
01389                 DBGC ( usbio, "USB %s could not get partial configuration "
01390                        "descriptor: %s\n", efi_handle_name ( handle ),
01391                        strerror ( rc ) );
01392                 goto err_get_configuration_descriptor;
01393         }
01394         len = le16_to_cpu ( partial.TotalLength );
01395 
01396         /* Allocate configuration descriptor */
01397         usbio->config = malloc ( len );
01398         if ( ! usbio->config ) {
01399                 rc = -ENOMEM;
01400                 goto err_alloc;
01401         }
01402 
01403         /* There is, naturally, no way to retrieve the entire device
01404          * configuration descriptor via EFI_USB_IO_PROTOCOL.  Worse,
01405          * there is no way to even retrieve the index of the current
01406          * configuration descriptor.  We have to iterate over all
01407          * possible configuration descriptors looking for the
01408          * descriptor that matches the current configuration value.
01409          */
01410         for ( i = 0 ; i < count ; i++ ) {
01411 
01412                 /* Construct request */
01413                 msg.setup.request = cpu_to_le16 ( USB_GET_DESCRIPTOR );
01414                 value = ( ( USB_CONFIGURATION_DESCRIPTOR << 8 ) | i );
01415                 msg.setup.value = cpu_to_le16 ( value );
01416                 msg.setup.index = 0;
01417                 msg.setup.len = cpu_to_le16 ( len );
01418 
01419                 /* Get full configuration descriptor */
01420                 if ( ( efirc = io->UsbControlTransfer ( io, &msg.efi,
01421                                                         EfiUsbDataIn, 0,
01422                                                         usbio->config, len,
01423                                                         &status ) ) != 0 ) {
01424                         rc = -EEFI ( efirc );
01425                         DBGC ( usbio, "USB %s could not get configuration %d "
01426                                "descriptor: %s\n", efi_handle_name ( handle ),
01427                                i, strerror ( rc ) );
01428                         goto err_control_transfer;
01429                 }
01430 
01431                 /* Ignore unless this is the current configuration */
01432                 if ( usbio->config->config != partial.ConfigurationValue )
01433                         continue;
01434 
01435                 /* Check length */
01436                 if ( le16_to_cpu ( usbio->config->len ) != len ) {
01437                         DBGC ( usbio, "USB %s configuration descriptor length "
01438                                "mismatch\n", efi_handle_name ( handle ) );
01439                         rc = -EINVAL;
01440                         goto err_len;
01441                 }
01442 
01443                 return 0;
01444         }
01445 
01446         /* No match found */
01447         DBGC ( usbio, "USB %s could not find current configuration "
01448                "descriptor\n", efi_handle_name ( handle ) );
01449         rc = -ENOENT;
01450 
01451  err_len:
01452  err_control_transfer:
01453         free ( usbio->config );
01454  err_alloc:
01455  err_get_configuration_descriptor:
01456  err_get_device_descriptor:
01457         return rc;
01458 }
01459 
01460 /**
01461  * Construct device path for opening other interfaces
01462  *
01463  * @v usbio             USB I/O device
01464  * @ret rc              Return status code
01465  */
01466 static int usbio_path ( struct usbio_device *usbio ) {
01467         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01468         EFI_HANDLE handle = usbio->handle;
01469         EFI_DEVICE_PATH_PROTOCOL *path;
01470         EFI_DEVICE_PATH_PROTOCOL *end;
01471         USB_DEVICE_PATH *usbpath;
01472         union {
01473                 void *interface;
01474                 EFI_DEVICE_PATH_PROTOCOL *path;
01475         } u;
01476         size_t len;
01477         EFI_STATUS efirc;
01478         int rc;
01479 
01480         /* Open device path protocol */
01481         if ( ( efirc = bs->OpenProtocol ( handle,
01482                                           &efi_device_path_protocol_guid,
01483                                           &u.interface, efi_image_handle,
01484                                           handle,
01485                                           EFI_OPEN_PROTOCOL_GET_PROTOCOL ))!=0){
01486                 rc = -EEFI ( efirc );
01487                 DBGC ( usbio, "USBIO %s cannot open device path protocol: "
01488                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01489                 goto err_open_protocol;
01490         }
01491         path = u.interface;
01492 
01493         /* Locate end of device path and sanity check */
01494         len = efi_devpath_len ( path );
01495         if ( len < sizeof ( *usbpath ) ) {
01496                 DBGC ( usbio, "USBIO %s underlength device path\n",
01497                        efi_handle_name ( handle ) );
01498                 rc = -EINVAL;
01499                 goto err_underlength;
01500         }
01501         usbpath = ( ( ( void * ) path ) + len - sizeof ( *usbpath ) );
01502         if ( ! ( ( usbpath->Header.Type == MESSAGING_DEVICE_PATH ) &&
01503                  ( usbpath->Header.SubType == MSG_USB_DP ) ) ) {
01504                 DBGC ( usbio, "USBIO %s not a USB device path: ",
01505                        efi_handle_name ( handle ) );
01506                 DBGC ( usbio, "%s\n", efi_devpath_text ( path ) );
01507                 rc = -EINVAL;
01508                 goto err_non_usb;
01509         }
01510 
01511         /* Allocate copy of device path */
01512         usbio->path = malloc ( len + sizeof ( *end ) );
01513         if ( ! usbio->path ) {
01514                 rc = -ENOMEM;
01515                 goto err_alloc;
01516         }
01517         memcpy ( usbio->path, path, ( len + sizeof ( *end ) ) );
01518         usbio->usbpath = ( ( ( void * ) usbio->path ) + len -
01519                            sizeof ( *usbpath ) );
01520 
01521         /* Close protocol */
01522         bs->CloseProtocol ( handle, &efi_device_path_protocol_guid,
01523                             efi_image_handle, handle );
01524 
01525         return 0;
01526 
01527         free ( usbio->path );
01528  err_alloc:
01529  err_non_usb:
01530  err_underlength:
01531         bs->CloseProtocol ( handle, &efi_device_path_protocol_guid,
01532                             efi_image_handle, handle );
01533  err_open_protocol:
01534         return rc;
01535 }
01536 
01537 /**
01538  * Construct interface list
01539  *
01540  * @v usbio             USB I/O device
01541  * @ret rc              Return status code
01542  */
01543 static int usbio_interfaces ( struct usbio_device *usbio ) {
01544         EFI_HANDLE handle = usbio->handle;
01545         EFI_USB_IO_PROTOCOL *io = usbio->io;
01546         EFI_USB_INTERFACE_DESCRIPTOR interface;
01547         unsigned int first;
01548         unsigned int count;
01549         EFI_STATUS efirc;
01550         int rc;
01551 
01552         /* Get interface descriptor */
01553         if ( ( efirc = io->UsbGetInterfaceDescriptor ( io, &interface ) ) != 0){
01554                 rc = -EEFI ( efirc );
01555                 DBGC ( usbio, "USB %s could not get interface descriptor: "
01556                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01557                 goto err_get_interface_descriptor;
01558         }
01559 
01560         /* Record first interface number */
01561         first = interface.InterfaceNumber;
01562         count = usbio->config->interfaces;
01563         assert ( first < count );
01564         usbio->first = first;
01565 
01566         /* Allocate interface list */
01567         usbio->interface = zalloc ( count * sizeof ( usbio->interface[0] ) );
01568         if ( ! usbio->interface ) {
01569                 rc = -ENOMEM;
01570                 goto err_alloc;
01571         }
01572 
01573         /* Use already-opened protocol for control transfers and for
01574          * the first interface.
01575          */
01576         usbio->interface[0].handle = handle;
01577         usbio->interface[0].io = io;
01578         usbio->interface[0].count = 1;
01579         usbio->interface[first].handle = handle;
01580         usbio->interface[first].io = io;
01581         usbio->interface[first].count = 1;
01582 
01583         return 0;
01584 
01585         free ( usbio->interface );
01586  err_alloc:
01587  err_get_interface_descriptor:
01588         return rc;
01589 }
01590 
01591 /**
01592  * Attach driver to device
01593  *
01594  * @v efidev            EFI device
01595  * @ret rc              Return status code
01596  */
01597 static int usbio_start ( struct efi_device *efidev ) {
01598         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01599         EFI_HANDLE handle = efidev->device;
01600         struct usbio_device *usbio;
01601         struct usb_port *port;
01602         union {
01603                 void *interface;
01604                 EFI_USB_IO_PROTOCOL *io;
01605         } u;
01606         EFI_STATUS efirc;
01607         int rc;
01608 
01609         /* Allocate and initialise structure */
01610         usbio = zalloc ( sizeof ( *usbio ) );
01611         if ( ! usbio ) {
01612                 rc = -ENOMEM;
01613                 goto err_alloc;
01614         }
01615         efidev_set_drvdata ( efidev, usbio );
01616         usbio->handle = handle;
01617         INIT_LIST_HEAD ( &usbio->endpoints );
01618 
01619         /* Open USB I/O protocol */
01620         if ( ( efirc = bs->OpenProtocol ( handle, &efi_usb_io_protocol_guid,
01621                                           &u.interface, efi_image_handle,
01622                                           handle,
01623                                           ( EFI_OPEN_PROTOCOL_BY_DRIVER |
01624                                             EFI_OPEN_PROTOCOL_EXCLUSIVE )))!=0){
01625                 rc = -EEFI ( efirc );
01626                 DBGC ( usbio, "USBIO %s cannot open USB I/O protocol: %s\n",
01627                        efi_handle_name ( handle ), strerror ( rc ) );
01628                 DBGC_EFI_OPENERS ( usbio, handle, &efi_usb_io_protocol_guid );
01629                 goto err_open_usbio;
01630         }
01631         usbio->io = u.io;
01632 
01633         /* Describe generic device */
01634         efi_device_info ( handle, "USB", &usbio->dev );
01635         usbio->dev.parent = &efidev->dev;
01636         list_add ( &usbio->dev.siblings, &efidev->dev.children );
01637         INIT_LIST_HEAD ( &usbio->dev.children );
01638 
01639         /* Fetch configuration descriptor */
01640         if ( ( rc = usbio_config ( usbio ) ) != 0 )
01641                 goto err_config;
01642 
01643         /* Construct device path */
01644         if ( ( rc = usbio_path ( usbio ) ) != 0 )
01645                 goto err_path;
01646 
01647         /* Construct interface list */
01648         if ( ( rc = usbio_interfaces ( usbio ) ) != 0 )
01649                 goto err_interfaces;
01650 
01651         /* Allocate USB bus */
01652         usbio->bus = alloc_usb_bus ( &usbio->dev, 1 /* single "port" */,
01653                                      USBIO_MTU, &usbio_operations );
01654         if ( ! usbio->bus ) {
01655                 rc = -ENOMEM;
01656                 goto err_alloc_bus;
01657         }
01658         usb_bus_set_hostdata ( usbio->bus, usbio );
01659         usb_hub_set_drvdata ( usbio->bus->hub, usbio );
01660 
01661         /* Set port protocol */
01662         port = usb_port ( usbio->bus->hub, 1 );
01663         port->protocol = USB_PROTO_2_0;
01664 
01665         /* Register USB bus */
01666         if ( ( rc = register_usb_bus ( usbio->bus ) ) != 0 )
01667                 goto err_register;
01668 
01669         return 0;
01670 
01671         unregister_usb_bus ( usbio->bus );
01672  err_register:
01673         free_usb_bus ( usbio->bus );
01674  err_alloc_bus:
01675         free ( usbio->interface );
01676  err_interfaces:
01677         free ( usbio->path );
01678  err_path:
01679         free ( usbio->config );
01680  err_config:
01681         list_del ( &usbio->dev.siblings );
01682         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01683                             efi_image_handle, handle );
01684  err_open_usbio:
01685         free ( usbio );
01686  err_alloc:
01687         return rc;
01688 }
01689 
01690 /**
01691  * Detach driver from device
01692  *
01693  * @v efidev            EFI device
01694  */
01695 static void usbio_stop ( struct efi_device *efidev ) {
01696         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01697         EFI_HANDLE handle = efidev->device;
01698         struct usbio_device *usbio = efidev_get_drvdata ( efidev );
01699 
01700         unregister_usb_bus ( usbio->bus );
01701         free_usb_bus ( usbio->bus );
01702         free ( usbio->interface );
01703         free ( usbio->path );
01704         free ( usbio->config );
01705         list_del ( &usbio->dev.siblings );
01706         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01707                             efi_image_handle, handle );
01708         free ( usbio );
01709 }
01710 
01711 /** EFI USB I/O driver */
01712 struct efi_driver usbio_driver __efi_driver ( EFI_DRIVER_NORMAL ) = {
01713         .name = "USBIO",
01714         .supported = usbio_supported,
01715         .start = usbio_start,
01716         .stop = usbio_stop,
01717 };