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         msg = iob_push ( iobuf, sizeof ( *msg ) );
00355         iob_pull ( iobuf, sizeof ( *msg ) );
00356         request = le16_to_cpu ( msg->setup.request );
00357         len = iob_len ( iobuf );
00358         if ( len ) {
00359                 data = iobuf->data;
00360                 direction = ( ( request & USB_DIR_IN ) ?
00361                               EfiUsbDataIn : EfiUsbDataOut );
00362         } else {
00363                 data = NULL;
00364                 direction = EfiUsbNoData;
00365         }
00366 
00367         /* Determine interface for this transfer */
00368         recipient = ( request & USB_RECIP_MASK );
00369         if ( recipient == USB_RECIP_INTERFACE ) {
00370                 /* Recipient is an interface: use interface number directly */
00371                 interface = le16_to_cpu ( msg->setup.index );
00372         } else {
00373                 /* Route all other requests through the first interface */
00374                 interface = 0;
00375         }
00376 
00377         /* Open interface */
00378         if ( ( rc = usbio_open ( usbio, interface ) ) != 0 )
00379                 goto err_open;
00380         io = usbio->interface[interface].io;
00381 
00382         /* Due to the design of EFI_USB_IO_PROTOCOL, attempting to set
00383          * the configuration to a non-default value is basically a
00384          * self-destruct button.
00385          */
00386         if ( ( request == USB_SET_CONFIGURATION ) &&
00387              ( le16_to_cpu ( msg->setup.value ) != usbio->config->config ) ) {
00388                 rc = -ENOTSUP_MORONIC_SPECIFICATION;
00389                 DBGC ( usbio, "USBIO %s cannot change configuration: %s\n",
00390                        efi_handle_name ( handle ), strerror ( rc ) );
00391                 goto err_moronic_specification;
00392         }
00393 
00394         /* Submit transfer */
00395         if ( ( efirc = io->UsbControlTransfer ( io, &msg->efi, direction, 0,
00396                                                 data, len, &status ) ) != 0 ) {
00397                 rc = -EEFI ( efirc );
00398                 DBGC ( usbio, "USBIO %s %s could not submit control transfer ",
00399                        efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00400                 DBGC ( usbio, "via %s: %s (status %04x)\n",
00401                        efi_handle_name ( usbio->interface[interface].handle ),
00402                        strerror ( rc ), status );
00403                 goto err_transfer;
00404         }
00405 
00406         /* Close interface */
00407         usbio_close ( usbio, interface );
00408 
00409         /* Complete transfer */
00410         usb_complete ( ep, iobuf );
00411 
00412         return;
00413 
00414  err_transfer:
00415  err_moronic_specification:
00416         usbio_close ( usbio, interface );
00417  err_open:
00418  err_not_message:
00419         usb_complete_err ( ep, iobuf, rc );
00420 }
00421 
00422 /** Control endpoint operations */
00423 static struct usbio_operations usbio_control_operations = {
00424         .open   = usbio_control_open,
00425         .close  = usbio_control_close,
00426         .poll   = usbio_control_poll,
00427 };
00428 
00429 /******************************************************************************
00430  *
00431  * Bulk IN endpoints
00432  *
00433  ******************************************************************************
00434  */
00435 
00436 /**
00437  * Open bulk IN endpoint
00438  *
00439  * @v endpoint          Endpoint
00440  * @ret rc              Return status code
00441  */
00442 static int usbio_bulk_in_open ( struct usbio_endpoint *endpoint __unused ) {
00443 
00444         /* Nothing to do */
00445         return 0;
00446 }
00447 
00448 /**
00449  * Close bulk IN endpoint
00450  *
00451  * @v endpoint          Endpoint
00452  */
00453 static void usbio_bulk_in_close ( struct usbio_endpoint *endpoint __unused ) {
00454 
00455         /* Nothing to do */
00456 }
00457 
00458 /**
00459  * Poll bulk IN endpoint
00460  *
00461  * @v endpoint          Endpoint
00462  */
00463 static void usbio_bulk_in_poll ( struct usbio_endpoint *endpoint ) {
00464         struct usbio_device *usbio = endpoint->usbio;
00465         struct usb_endpoint *ep = endpoint->ep;
00466         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00467         EFI_HANDLE handle = usbio->handle;
00468         struct io_buffer *iobuf;
00469         unsigned int index;
00470         UINTN len;
00471         UINT32 status;
00472         EFI_STATUS efirc;
00473         int rc;
00474 
00475         /* Do nothing if ring is empty */
00476         if ( endpoint->cons == endpoint->prod )
00477                 return;
00478 
00479         /* Attempt (but do not yet consume) next transfer */
00480         index = ( endpoint->cons % USBIO_RING_COUNT );
00481         iobuf = endpoint->iobuf[index];
00482 
00483         /* Construct transfer */
00484         len = iob_len ( iobuf );
00485 
00486         /* Upon being turned on, the EFI_USB_IO_PROTOCOL did nothing
00487          * for several minutes before firing a small ARP packet a few
00488          * millimetres into the ether.
00489          */
00490         efirc = io->UsbBulkTransfer ( io, ep->address, iobuf->data,
00491                                       &len, 1, &status );
00492         if ( efirc == EFI_TIMEOUT )
00493                 return;
00494 
00495         /* Consume transfer */
00496         endpoint->cons++;
00497 
00498         /* Check for failure */
00499         if ( efirc != 0 ) {
00500                 rc = -EEFI ( efirc );
00501                 DBGC2 ( usbio, "USBIO %s %s could not submit bulk IN transfer: "
00502                         "%s (status %04x)\n", efi_handle_name ( handle ),
00503                         usb_endpoint_name ( ep ), strerror ( rc ), status );
00504                 usb_complete_err ( ep, iobuf, rc );
00505                 return;
00506         }
00507 
00508         /* Update length */
00509         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00510 
00511         /* Complete transfer */
00512         usb_complete ( ep, iobuf );
00513 }
00514 
00515 /** Bulk endpoint operations */
00516 static struct usbio_operations usbio_bulk_in_operations = {
00517         .open   = usbio_bulk_in_open,
00518         .close  = usbio_bulk_in_close,
00519         .poll   = usbio_bulk_in_poll,
00520 };
00521 
00522 /******************************************************************************
00523  *
00524  * Bulk OUT endpoints
00525  *
00526  ******************************************************************************
00527  */
00528 
00529 /**
00530  * Open bulk OUT endpoint
00531  *
00532  * @v endpoint          Endpoint
00533  * @ret rc              Return status code
00534  */
00535 static int usbio_bulk_out_open ( struct usbio_endpoint *endpoint __unused ) {
00536 
00537         /* Nothing to do */
00538         return 0;
00539 }
00540 
00541 /**
00542  * Close bulk OUT endpoint
00543  *
00544  * @v endpoint          Endpoint
00545  */
00546 static void usbio_bulk_out_close ( struct usbio_endpoint *endpoint __unused ) {
00547 
00548         /* Nothing to do */
00549 }
00550 
00551 /**
00552  * Poll bulk OUT endpoint
00553  *
00554  * @v endpoint          Endpoint
00555  */
00556 static void usbio_bulk_out_poll ( struct usbio_endpoint *endpoint ) {
00557         struct usbio_device *usbio = endpoint->usbio;
00558         struct usb_endpoint *ep = endpoint->ep;
00559         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00560         EFI_HANDLE handle = usbio->handle;
00561         struct io_buffer *iobuf;
00562         unsigned int index;
00563         unsigned int flags;
00564         UINTN len;
00565         UINT32 status;
00566         EFI_STATUS efirc;
00567         int rc;
00568 
00569         /* Do nothing if ring is empty */
00570         if ( endpoint->cons == endpoint->prod )
00571                 return;
00572 
00573         /* Consume next transfer */
00574         index = ( endpoint->cons++ % USBIO_RING_COUNT );
00575         iobuf = endpoint->iobuf[index];
00576         flags = endpoint->flags[index];
00577 
00578         /* Construct transfer */
00579         len = iob_len ( iobuf );
00580 
00581         /* Submit transfer */
00582         if ( ( efirc = io->UsbBulkTransfer ( io, ep->address, iobuf->data,
00583                                              &len, 0, &status ) ) != 0 ) {
00584                 rc = -EEFI ( efirc );
00585                 DBGC ( usbio, "USBIO %s %s could not submit bulk OUT transfer: "
00586                        "%s (status %04x)\n", efi_handle_name ( handle ),
00587                        usb_endpoint_name ( ep ), strerror ( rc ), status );
00588                 goto err;
00589         }
00590 
00591         /* Update length */
00592         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00593 
00594         /* Submit zero-length transfer if required */
00595         len = 0;
00596         if ( ( flags & USBIO_ZLEN ) &&
00597              ( efirc = io->UsbBulkTransfer ( io, ep->address, NULL, &len, 0,
00598                                              &status ) ) != 0 ) {
00599                 rc = -EEFI ( efirc );
00600                 DBGC ( usbio, "USBIO %s %s could not submit zero-length "
00601                        "transfer: %s (status %04x)\n",
00602                        efi_handle_name ( handle ), usb_endpoint_name ( ep ),
00603                        strerror ( rc ), status );
00604                 goto err;
00605         }
00606 
00607         /* Complete transfer */
00608         usb_complete ( ep, iobuf );
00609 
00610         return;
00611 
00612  err:
00613         usb_complete_err ( ep, iobuf, rc );
00614 }
00615 
00616 /** Bulk endpoint operations */
00617 static struct usbio_operations usbio_bulk_out_operations = {
00618         .open   = usbio_bulk_out_open,
00619         .close  = usbio_bulk_out_close,
00620         .poll   = usbio_bulk_out_poll,
00621 };
00622 
00623 /******************************************************************************
00624  *
00625  * Interrupt endpoints
00626  *
00627  ******************************************************************************
00628  *
00629  * The EFI_USB_IO_PROTOCOL provides two ways to interact with
00630  * interrupt endpoints, neither of which naturally model the hardware
00631  * interaction.  The UsbSyncInterruptTransfer() method allows imposes
00632  * a 1ms overhead for every interrupt transfer (which could result in
00633  * up to a 50% decrease in overall throughput for the device).  The
00634  * UsbAsyncInterruptTransfer() method provides no way for us to
00635  * prevent transfers when no I/O buffers are available.
00636  *
00637  * We work around this design by utilising a small, fixed ring buffer
00638  * into which the interrupt callback delivers the data.  This aims to
00639  * provide buffer space even if no I/O buffers have yet been enqueued.
00640  * The scheme is not guaranteed since the fixed ring buffer may also
00641  * become full.  However:
00642  *
00643  *   - devices which send a constant stream of interrupts (and which
00644  *     therefore might exhaust the fixed ring buffer) tend to be
00645  *     responding to every interrupt request, and can tolerate lost
00646  *     packets, and
00647  *
00648  *   - devices which cannot tolerate lost interrupt packets tend to send
00649  *     only a few small messages.
00650  *
00651  * The scheme should therefore work in practice.
00652  */
00653 
00654 /**
00655  * Interrupt endpoint callback
00656  *
00657  * @v data              Received data
00658  * @v len               Length of received data
00659  * @v context           Callback context
00660  * @v status            Transfer status
00661  * @ret efirc           EFI status code
00662  */
00663 static EFI_STATUS EFIAPI usbio_interrupt_callback ( VOID *data, UINTN len,
00664                                                     VOID *context,
00665                                                     UINT32 status ) {
00666         struct usbio_interrupt_ring *intr = context;
00667         struct usbio_endpoint *endpoint = intr->endpoint;
00668         struct usbio_device *usbio = endpoint->usbio;
00669         struct usb_endpoint *ep = endpoint->ep;
00670         EFI_HANDLE handle = usbio->handle;
00671         unsigned int fill;
00672         unsigned int index;
00673 
00674         /* Sanity check */
00675         assert ( len <= ep->mtu );
00676 
00677         /* Do nothing if ring is empty */
00678         fill = ( intr->prod - intr->cons );
00679         if ( fill >= USBIO_INTR_COUNT ) {
00680                 DBGC ( usbio, "USBIO %s %s dropped interrupt completion\n",
00681                        efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00682                 return 0;
00683         }
00684 
00685         /* Do nothing if transfer was unsuccessful */
00686         if ( status != 0 ) {
00687                 DBGC ( usbio, "USBIO %s %s interrupt completion status %04x\n",
00688                        efi_handle_name ( handle ), usb_endpoint_name ( ep ),
00689                        status );
00690                 return 0; /* Unclear what failure actually means here */
00691         }
00692 
00693         /* Copy data to buffer and increment producer counter */
00694         index = ( intr->prod % USBIO_INTR_COUNT );
00695         memcpy ( intr->data[index], data, len );
00696         intr->len[index] = len;
00697         intr->prod++;
00698 
00699         return 0;
00700 }
00701 
00702 /**
00703  * Open interrupt endpoint
00704  *
00705  * @v endpoint          Endpoint
00706  * @ret rc              Return status code
00707  */
00708 static int usbio_interrupt_open ( struct usbio_endpoint *endpoint ) {
00709         struct usbio_device *usbio = endpoint->usbio;
00710         struct usbio_interrupt_ring *intr;
00711         struct usb_endpoint *ep = endpoint->ep;
00712         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00713         EFI_HANDLE handle = usbio->handle;
00714         unsigned int interval;
00715         unsigned int i;
00716         void *data;
00717         EFI_STATUS efirc;
00718         int rc;
00719 
00720         /* Allocate interrupt ring buffer */
00721         intr = zalloc ( sizeof ( *intr ) + ( USBIO_INTR_COUNT * ep->mtu ) );
00722         if ( ! intr ) {
00723                 rc = -ENOMEM;
00724                 goto err_alloc;
00725         }
00726         endpoint->intr = intr;
00727         intr->endpoint = endpoint;
00728         data = ( ( ( void * ) intr ) + sizeof ( *intr ) );
00729         for ( i = 0 ; i < USBIO_INTR_COUNT ; i++ ) {
00730                 intr->data[i] = data;
00731                 data += ep->mtu;
00732         }
00733 
00734         /* Determine polling interval */
00735         interval = ( ep->interval >> 3 /* microframes -> milliseconds */ );
00736         if ( ! interval )
00737                 interval = 1; /* May not be zero */
00738 
00739         /* Add to periodic schedule */
00740         if ( ( efirc = io->UsbAsyncInterruptTransfer ( io, ep->address, TRUE,
00741                                                        interval, ep->mtu,
00742                                                        usbio_interrupt_callback,
00743                                                        intr ) ) != 0 ) {
00744                 rc = -EEFI ( efirc );
00745                 DBGC ( usbio, "USBIO %s %s could not schedule interrupt "
00746                        "transfer: %s\n", efi_handle_name ( handle ),
00747                        usb_endpoint_name ( ep ), strerror ( rc ) );
00748                 goto err_schedule;
00749         }
00750 
00751         return 0;
00752 
00753         io->UsbAsyncInterruptTransfer ( io, ep->address, FALSE, 0, 0,
00754                                         NULL, NULL );
00755  err_schedule:
00756         free ( intr );
00757  err_alloc:
00758         return rc;
00759 }
00760 
00761 /**
00762  * Close interrupt endpoint
00763  *
00764  * @v endpoint          Endpoint
00765  */
00766 static void usbio_interrupt_close ( struct usbio_endpoint *endpoint ) {
00767         struct usb_endpoint *ep = endpoint->ep;
00768         EFI_USB_IO_PROTOCOL *io = endpoint->io;
00769 
00770         /* Remove from periodic schedule */
00771         io->UsbAsyncInterruptTransfer ( io, ep->address, FALSE, 0, 0,
00772                                         NULL, NULL );
00773 
00774         /* Free interrupt ring buffer */
00775         free ( endpoint->intr );
00776 }
00777 
00778 /**
00779  * Poll interrupt endpoint
00780  *
00781  * @v endpoint          Endpoint
00782  */
00783 static void usbio_interrupt_poll ( struct usbio_endpoint *endpoint ) {
00784         struct usbio_interrupt_ring *intr = endpoint->intr;
00785         struct usb_endpoint *ep = endpoint->ep;
00786         struct io_buffer *iobuf;
00787         unsigned int index;
00788         unsigned int intr_index;
00789         size_t len;
00790 
00791         /* Do nothing if ring is empty */
00792         if ( endpoint->cons == endpoint->prod )
00793                 return;
00794 
00795         /* Do nothing if interrupt ring is empty */
00796         if ( intr->cons == intr->prod )
00797                 return;
00798 
00799         /* Consume next transfer */
00800         index = ( endpoint->cons++ % USBIO_RING_COUNT );
00801         iobuf = endpoint->iobuf[index];
00802 
00803         /* Populate I/O buffer */
00804         intr_index = ( intr->cons++ % USBIO_INTR_COUNT );
00805         len = intr->len[intr_index];
00806         assert ( len <= iob_len ( iobuf ) );
00807         iob_put ( iobuf, ( len - iob_len ( iobuf ) ) );
00808         memcpy ( iobuf->data, intr->data[intr_index], len );
00809 
00810         /* Complete transfer */
00811         usb_complete ( ep, iobuf );
00812 }
00813 
00814 /** Interrupt endpoint operations */
00815 static struct usbio_operations usbio_interrupt_operations = {
00816         .open   = usbio_interrupt_open,
00817         .close  = usbio_interrupt_close,
00818         .poll   = usbio_interrupt_poll,
00819 };
00820 
00821 /******************************************************************************
00822  *
00823  * Endpoint operations
00824  *
00825  ******************************************************************************
00826  */
00827 
00828 /**
00829  * Open endpoint
00830  *
00831  * @v ep                USB endpoint
00832  * @ret rc              Return status code
00833  */
00834 static int usbio_endpoint_open ( struct usb_endpoint *ep ) {
00835         struct usb_bus *bus = ep->usb->port->hub->bus;
00836         struct usbio_device *usbio = usb_bus_get_hostdata ( bus );
00837         struct usbio_endpoint *endpoint;
00838         EFI_HANDLE handle = usbio->handle;
00839         unsigned int attr = ( ep->attributes & USB_ENDPOINT_ATTR_TYPE_MASK );
00840         int interface;
00841         int rc;
00842 
00843         /* Allocate and initialise structure */
00844         endpoint = zalloc ( sizeof ( *endpoint ) );
00845         if ( ! endpoint ) {
00846                 rc = -ENOMEM;
00847                 goto err_alloc;
00848         }
00849         usb_endpoint_set_hostdata ( ep, endpoint );
00850         endpoint->usbio = usbio;
00851         endpoint->ep = ep;
00852 
00853         /* Identify endpoint operations */
00854         if ( attr == USB_ENDPOINT_ATTR_CONTROL ) {
00855                 endpoint->op = &usbio_control_operations;
00856         } else if ( attr == USB_ENDPOINT_ATTR_BULK ) {
00857                 endpoint->op = ( ( ep->address & USB_DIR_IN ) ?
00858                                  &usbio_bulk_in_operations :
00859                                  &usbio_bulk_out_operations );
00860         } else if ( attr == USB_ENDPOINT_ATTR_INTERRUPT ) {
00861                 endpoint->op = &usbio_interrupt_operations;
00862         } else {
00863                 rc = -ENOTSUP;
00864                 goto err_operations;
00865         }
00866 
00867         /* Identify interface for this endpoint */
00868         interface = usbio_interface ( usbio, ep );
00869         if ( interface < 0 ) {
00870                 rc = interface;
00871                 goto err_interface;
00872         }
00873         endpoint->interface = interface;
00874 
00875         /* Open interface */
00876         if ( ( rc = usbio_open ( usbio, interface ) ) != 0 )
00877                 goto err_open_interface;
00878         endpoint->handle = usbio->interface[interface].handle;
00879         endpoint->io = usbio->interface[interface].io;
00880         DBGC ( usbio, "USBIO %s %s using ",
00881                efi_handle_name ( handle ), usb_endpoint_name ( ep ) );
00882         DBGC ( usbio, "%s\n", efi_handle_name ( endpoint->handle ) );
00883 
00884         /* Open endpoint */
00885         if ( ( rc = endpoint->op->open ( endpoint ) ) != 0 )
00886                 goto err_open_endpoint;
00887 
00888         /* Add to list of endpoints */
00889         list_add_tail ( &endpoint->list, &usbio->endpoints );
00890 
00891         return 0;
00892 
00893         list_del ( &endpoint->list );
00894         endpoint->op->close ( endpoint );
00895  err_open_endpoint:
00896         usbio_close ( usbio, interface );
00897  err_open_interface:
00898  err_interface:
00899  err_operations:
00900         free ( endpoint );
00901  err_alloc:
00902         return rc;
00903 }
00904 
00905 /**
00906  * Close endpoint
00907  *
00908  * @v ep                USB endpoint
00909  */
00910 static void usbio_endpoint_close ( struct usb_endpoint *ep ) {
00911         struct usbio_endpoint *endpoint = usb_endpoint_get_hostdata ( ep );
00912         struct usbio_device *usbio = endpoint->usbio;
00913         struct io_buffer *iobuf;
00914         unsigned int index;
00915 
00916         /* Remove from list of endpoints */
00917         list_del ( &endpoint->list );
00918 
00919         /* Close endpoint */
00920         endpoint->op->close ( endpoint );
00921 
00922         /* Close interface */
00923         usbio_close ( usbio, endpoint->interface );
00924 
00925         /* Cancel any incomplete transfers */
00926         while ( endpoint->cons != endpoint->prod ) {
00927                 index = ( endpoint->cons++ % USBIO_RING_COUNT );
00928                 iobuf = endpoint->iobuf[index];
00929                 usb_complete_err ( ep, iobuf, -ECANCELED );
00930         }
00931 
00932         /* Free endpoint */
00933         free ( endpoint );
00934 }
00935 
00936 /**
00937  * Reset endpoint
00938  *
00939  * @v ep                USB endpoint
00940  * @ret rc              Return status code
00941  */
00942 static int usbio_endpoint_reset ( struct usb_endpoint *ep __unused ) {
00943 
00944         /* Nothing to do */
00945         return 0;
00946 }
00947 
00948 /**
00949  * Update MTU
00950  *
00951  * @v ep                USB endpoint
00952  * @ret rc              Return status code
00953  */
00954 static int usbio_endpoint_mtu ( struct usb_endpoint *ep __unused ) {
00955 
00956         /* Nothing to do */
00957         return 0;
00958 }
00959 
00960 /**
00961  * Enqueue transfer
00962  *
00963  * @v ep                USB endpoint
00964  * @v iobuf             I/O buffer
00965  * @v flags             Transfer flags
00966  * @ret rc              Return status code
00967  */
00968 static int usbio_endpoint_enqueue ( struct usb_endpoint *ep,
00969                                     struct io_buffer *iobuf,
00970                                     unsigned int flags ) {
00971         struct usbio_endpoint *endpoint = usb_endpoint_get_hostdata ( ep );
00972         unsigned int fill;
00973         unsigned int index;
00974 
00975         /* Fail if shutdown is in progress */
00976         if ( efi_shutdown_in_progress )
00977                 return -ECANCELED;
00978 
00979         /* Fail if transfer ring is full */
00980         fill = ( endpoint->prod - endpoint->cons );
00981         if ( fill >= USBIO_RING_COUNT )
00982                 return -ENOBUFS;
00983 
00984         /* Add to ring */
00985         index = ( endpoint->prod++ % USBIO_RING_COUNT );
00986         endpoint->iobuf[index] = iobuf;
00987         endpoint->flags[index] = flags;
00988 
00989         return 0;
00990 }
00991 
00992 /**
00993  * Enqueue message transfer
00994  *
00995  * @v ep                USB endpoint
00996  * @v iobuf             I/O buffer
00997  * @ret rc              Return status code
00998  */
00999 static int usbio_endpoint_message ( struct usb_endpoint *ep,
01000                                     struct io_buffer *iobuf ) {
01001         struct usb_setup_packet *setup;
01002 
01003         /* Adjust I/O buffer to start of data payload */
01004         assert ( iob_len ( iobuf ) >= sizeof ( *setup ) );
01005         iob_pull ( iobuf, sizeof ( *setup ) );
01006 
01007         /* Enqueue transfer */
01008         return usbio_endpoint_enqueue ( ep, iobuf, USBIO_MESSAGE );
01009 }
01010 
01011 /**
01012  * Enqueue stream transfer
01013  *
01014  * @v ep                USB endpoint
01015  * @v iobuf             I/O buffer
01016  * @v zlp               Append a zero-length packet
01017  * @ret rc              Return status code
01018  */
01019 static int usbio_endpoint_stream ( struct usb_endpoint *ep,
01020                                    struct io_buffer *iobuf, int zlp ) {
01021 
01022         /* Enqueue transfer */
01023         return usbio_endpoint_enqueue ( ep, iobuf, ( zlp ? USBIO_ZLEN : 0 ) );
01024 }
01025 
01026 /**
01027  * Poll for completions
01028  *
01029  * @v endpoint          Endpoint
01030  */
01031 static void usbio_endpoint_poll ( struct usbio_endpoint *endpoint ) {
01032 
01033         /* Do nothing if shutdown is in progress */
01034         if ( efi_shutdown_in_progress )
01035                 return;
01036 
01037         /* Poll endpoint */
01038         endpoint->op->poll ( endpoint );
01039 }
01040 
01041 /******************************************************************************
01042  *
01043  * Device operations
01044  *
01045  ******************************************************************************
01046  */
01047 
01048 /**
01049  * Open device
01050  *
01051  * @v usb               USB device
01052  * @ret rc              Return status code
01053  */
01054 static int usbio_device_open ( struct usb_device *usb ) {
01055         struct usbio_device *usbio =
01056                 usb_bus_get_hostdata ( usb->port->hub->bus );
01057 
01058         usb_set_hostdata ( usb, usbio );
01059         return 0;
01060 }
01061 
01062 /**
01063  * Close device
01064  *
01065  * @v usb               USB device
01066  */
01067 static void usbio_device_close ( struct usb_device *usb __unused ) {
01068 
01069         /* Nothing to do */
01070 }
01071 
01072 /**
01073  * Assign device address
01074  *
01075  * @v usb               USB device
01076  * @ret rc              Return status code
01077  */
01078 static int usbio_device_address ( struct usb_device *usb __unused ) {
01079 
01080         /* Nothing to do */
01081         return 0;
01082 }
01083 
01084 /******************************************************************************
01085  *
01086  * Hub operations
01087  *
01088  ******************************************************************************
01089  */
01090 
01091 /**
01092  * Open hub
01093  *
01094  * @v hub               USB hub
01095  * @ret rc              Return status code
01096  */
01097 static int usbio_hub_open ( struct usb_hub *hub ) {
01098 
01099         /* Disallow non-root hubs */
01100         if ( hub->usb )
01101                 return -ENOTSUP;
01102 
01103         /* Nothing to do */
01104         return 0;
01105 }
01106 
01107 /**
01108  * Close hub
01109  *
01110  * @v hub               USB hub
01111  */
01112 static void usbio_hub_close ( struct usb_hub *hub __unused ) {
01113 
01114         /* Nothing to do */
01115 }
01116 
01117 /******************************************************************************
01118  *
01119  * Root hub operations
01120  *
01121  ******************************************************************************
01122  */
01123 
01124 /**
01125  * Open root hub
01126  *
01127  * @v hub               USB hub
01128  * @ret rc              Return status code
01129  */
01130 static int usbio_root_open ( struct usb_hub *hub __unused ) {
01131 
01132         /* Nothing to do */
01133         return 0;
01134 }
01135 
01136 /**
01137  * Close root hub
01138  *
01139  * @v hub               USB hub
01140  */
01141 static void usbio_root_close ( struct usb_hub *hub __unused ) {
01142 
01143         /* Nothing to do */
01144 }
01145 
01146 /**
01147  * Enable port
01148  *
01149  * @v hub               USB hub
01150  * @v port              USB port
01151  * @ret rc              Return status code
01152  */
01153 static int usbio_root_enable ( struct usb_hub *hub __unused,
01154                                struct usb_port *port __unused ) {
01155 
01156         /* Nothing to do */
01157         return 0;
01158 }
01159 
01160 /**
01161  * Disable port
01162  *
01163  * @v hub               USB hub
01164  * @v port              USB port
01165  * @ret rc              Return status code
01166  */
01167 static int usbio_root_disable ( struct usb_hub *hub __unused,
01168                                 struct usb_port *port __unused ) {
01169 
01170         /* Nothing to do */
01171         return 0;
01172 }
01173 
01174 /**
01175  * Update root hub port speed
01176  *
01177  * @v hub               USB hub
01178  * @v port              USB port
01179  * @ret rc              Return status code
01180  */
01181 static int usbio_root_speed ( struct usb_hub *hub __unused,
01182                               struct usb_port *port ) {
01183 
01184         /* Not actually exposed via EFI_USB_IO_PROTOCOL */
01185         port->speed = USB_SPEED_HIGH;
01186         return 0;
01187 }
01188 
01189 /**
01190  * Clear transaction translator buffer
01191  *
01192  * @v hub               USB hub
01193  * @v port              USB port
01194  * @v ep                USB endpoint
01195  * @ret rc              Return status code
01196  */
01197 static int usbio_root_clear_tt ( struct usb_hub *hub __unused,
01198                                  struct usb_port *port __unused,
01199                                  struct usb_endpoint *ep __unused ) {
01200 
01201         /* Should never be called; this is a root hub */
01202         return -ENOTSUP;
01203 }
01204 
01205 /******************************************************************************
01206  *
01207  * Bus operations
01208  *
01209  ******************************************************************************
01210  */
01211 
01212 /**
01213  * Open USB bus
01214  *
01215  * @v bus               USB bus
01216  * @ret rc              Return status code
01217  */
01218 static int usbio_bus_open ( struct usb_bus *bus __unused ) {
01219 
01220         /* Nothing to do */
01221         return 0;
01222 }
01223 
01224 /**
01225  * Close USB bus
01226  *
01227  * @v bus               USB bus
01228  */
01229 static void usbio_bus_close ( struct usb_bus *bus __unused ) {
01230 
01231         /* Nothing to do */
01232 }
01233 
01234 /**
01235  * Poll USB bus
01236  *
01237  * @v bus               USB bus
01238  */
01239 static void usbio_bus_poll ( struct usb_bus *bus ) {
01240         struct usbio_device *usbio = usb_bus_get_hostdata ( bus );
01241         struct usbio_endpoint *endpoint;
01242 
01243         /* Poll all endpoints.  We trust that completion handlers are
01244          * minimal and will not do anything that could plausibly
01245          * affect the endpoint list itself.
01246          */
01247         list_for_each_entry ( endpoint, &usbio->endpoints, list )
01248                 usbio_endpoint_poll ( endpoint );
01249 }
01250 
01251 /******************************************************************************
01252  *
01253  * EFI driver interface
01254  *
01255  ******************************************************************************
01256  */
01257 
01258 /** USB I/O host controller driver operations */
01259 static struct usb_host_operations usbio_operations = {
01260         .endpoint = {
01261                 .open = usbio_endpoint_open,
01262                 .close = usbio_endpoint_close,
01263                 .reset = usbio_endpoint_reset,
01264                 .mtu = usbio_endpoint_mtu,
01265                 .message = usbio_endpoint_message,
01266                 .stream = usbio_endpoint_stream,
01267         },
01268         .device = {
01269                 .open = usbio_device_open,
01270                 .close = usbio_device_close,
01271                 .address = usbio_device_address,
01272         },
01273         .bus = {
01274                 .open = usbio_bus_open,
01275                 .close = usbio_bus_close,
01276                 .poll = usbio_bus_poll,
01277         },
01278         .hub = {
01279                 .open = usbio_hub_open,
01280                 .close = usbio_hub_close,
01281         },
01282         .root = {
01283                 .open = usbio_root_open,
01284                 .close = usbio_root_close,
01285                 .enable = usbio_root_enable,
01286                 .disable = usbio_root_disable,
01287                 .speed = usbio_root_speed,
01288                 .clear_tt = usbio_root_clear_tt,
01289         },
01290 };
01291 
01292 /**
01293  * Check to see if driver supports a device
01294  *
01295  * @v handle            EFI device handle
01296  * @ret rc              Return status code
01297  */
01298 static int usbio_supported ( EFI_HANDLE handle ) {
01299         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01300         EFI_USB_DEVICE_DESCRIPTOR device;
01301         EFI_USB_INTERFACE_DESCRIPTOR interface;
01302         struct usb_function_descriptor desc;
01303         struct usb_driver *driver;
01304         struct usb_device_id *id;
01305         union {
01306                 void *interface;
01307                 EFI_USB_IO_PROTOCOL *io;
01308         } usb;
01309         EFI_STATUS efirc;
01310         int rc;
01311 
01312         /* Get protocol */
01313         if ( ( efirc = bs->OpenProtocol ( handle, &efi_usb_io_protocol_guid,
01314                                           &usb.interface, efi_image_handle,
01315                                           handle,
01316                                           EFI_OPEN_PROTOCOL_GET_PROTOCOL ))!=0){
01317                 rc = -EEFI ( efirc );
01318                 DBGCP ( handle, "USB %s is not a USB device\n",
01319                         efi_handle_name ( handle ) );
01320                 goto err_open_protocol;
01321         }
01322 
01323         /* Get device descriptor */
01324         if ( ( efirc = usb.io->UsbGetDeviceDescriptor ( usb.io,
01325                                                         &device ) ) != 0 ) {
01326                 rc = -EEFI ( efirc );
01327                 DBGC ( handle, "USB %s could not get device descriptor: "
01328                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01329                 goto err_get_device_descriptor;
01330         }
01331         memset ( &desc, 0, sizeof ( desc ) );
01332         desc.vendor = device.IdVendor;
01333         desc.product = device.IdProduct;
01334 
01335         /* Get interface descriptor */
01336         if ( ( efirc = usb.io->UsbGetInterfaceDescriptor ( usb.io,
01337                                                            &interface ) ) !=0){
01338                 rc = -EEFI ( efirc );
01339                 DBGC ( handle, "USB %s could not get interface descriptor: "
01340                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01341                 goto err_get_interface_descriptor;
01342         }
01343         desc.class.class.class = interface.InterfaceClass;
01344         desc.class.class.subclass = interface.InterfaceSubClass;
01345         desc.class.class.protocol = interface.InterfaceProtocol;
01346 
01347         /* Look for a driver for this interface */
01348         driver = usb_find_driver ( &desc, &id );
01349         if ( ! driver ) {
01350                 rc = -ENOTSUP;
01351                 goto err_unsupported;
01352         }
01353 
01354         /* Success */
01355         rc = 0;
01356 
01357  err_unsupported:
01358  err_get_interface_descriptor:
01359  err_get_device_descriptor:
01360         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01361                             efi_image_handle, handle );
01362  err_open_protocol:
01363         return rc;
01364 }
01365 
01366 /**
01367  * Fetch configuration descriptor
01368  *
01369  * @v usbio             USB I/O device
01370  * @ret rc              Return status code
01371  */
01372 static int usbio_config ( struct usbio_device *usbio ) {
01373         EFI_HANDLE handle = usbio->handle;
01374         EFI_USB_IO_PROTOCOL *io = usbio->io;
01375         EFI_USB_DEVICE_DESCRIPTOR device;
01376         EFI_USB_CONFIG_DESCRIPTOR partial;
01377         union {
01378                 struct usb_setup_packet setup;
01379                 EFI_USB_DEVICE_REQUEST efi;
01380         } msg;
01381         UINT32 status;
01382         size_t len;
01383         unsigned int count;
01384         unsigned int value;
01385         unsigned int i;
01386         EFI_STATUS efirc;
01387         int rc;
01388 
01389         /* Get device descriptor */
01390         if ( ( efirc = io->UsbGetDeviceDescriptor ( io, &device ) ) != 0 ) {
01391                 rc = -EEFI ( efirc );
01392                 DBGC ( usbio, "USB %s could not get device descriptor: "
01393                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01394                 goto err_get_device_descriptor;
01395         }
01396         count = device.NumConfigurations;
01397 
01398         /* Get current partial configuration descriptor */
01399         if ( ( efirc = io->UsbGetConfigDescriptor ( io, &partial ) ) != 0 ) {
01400                 rc = -EEFI ( efirc );
01401                 DBGC ( usbio, "USB %s could not get partial configuration "
01402                        "descriptor: %s\n", efi_handle_name ( handle ),
01403                        strerror ( rc ) );
01404                 goto err_get_configuration_descriptor;
01405         }
01406         len = le16_to_cpu ( partial.TotalLength );
01407 
01408         /* Allocate configuration descriptor */
01409         usbio->config = malloc ( len );
01410         if ( ! usbio->config ) {
01411                 rc = -ENOMEM;
01412                 goto err_alloc;
01413         }
01414 
01415         /* There is, naturally, no way to retrieve the entire device
01416          * configuration descriptor via EFI_USB_IO_PROTOCOL.  Worse,
01417          * there is no way to even retrieve the index of the current
01418          * configuration descriptor.  We have to iterate over all
01419          * possible configuration descriptors looking for the
01420          * descriptor that matches the current configuration value.
01421          */
01422         for ( i = 0 ; i < count ; i++ ) {
01423 
01424                 /* Construct request */
01425                 msg.setup.request = cpu_to_le16 ( USB_GET_DESCRIPTOR );
01426                 value = ( ( USB_CONFIGURATION_DESCRIPTOR << 8 ) | i );
01427                 msg.setup.value = cpu_to_le16 ( value );
01428                 msg.setup.index = 0;
01429                 msg.setup.len = cpu_to_le16 ( len );
01430 
01431                 /* Get full configuration descriptor */
01432                 if ( ( efirc = io->UsbControlTransfer ( io, &msg.efi,
01433                                                         EfiUsbDataIn, 0,
01434                                                         usbio->config, len,
01435                                                         &status ) ) != 0 ) {
01436                         rc = -EEFI ( efirc );
01437                         DBGC ( usbio, "USB %s could not get configuration %d "
01438                                "descriptor: %s\n", efi_handle_name ( handle ),
01439                                i, strerror ( rc ) );
01440                         goto err_control_transfer;
01441                 }
01442 
01443                 /* Ignore unless this is the current configuration */
01444                 if ( usbio->config->config != partial.ConfigurationValue )
01445                         continue;
01446 
01447                 /* Check length */
01448                 if ( le16_to_cpu ( usbio->config->len ) != len ) {
01449                         DBGC ( usbio, "USB %s configuration descriptor length "
01450                                "mismatch\n", efi_handle_name ( handle ) );
01451                         rc = -EINVAL;
01452                         goto err_len;
01453                 }
01454 
01455                 return 0;
01456         }
01457 
01458         /* No match found */
01459         DBGC ( usbio, "USB %s could not find current configuration "
01460                "descriptor\n", efi_handle_name ( handle ) );
01461         rc = -ENOENT;
01462 
01463  err_len:
01464  err_control_transfer:
01465         free ( usbio->config );
01466  err_alloc:
01467  err_get_configuration_descriptor:
01468  err_get_device_descriptor:
01469         return rc;
01470 }
01471 
01472 /**
01473  * Construct device path for opening other interfaces
01474  *
01475  * @v usbio             USB I/O device
01476  * @ret rc              Return status code
01477  */
01478 static int usbio_path ( struct usbio_device *usbio ) {
01479         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01480         EFI_HANDLE handle = usbio->handle;
01481         EFI_DEVICE_PATH_PROTOCOL *path;
01482         EFI_DEVICE_PATH_PROTOCOL *end;
01483         USB_DEVICE_PATH *usbpath;
01484         union {
01485                 void *interface;
01486                 EFI_DEVICE_PATH_PROTOCOL *path;
01487         } u;
01488         size_t len;
01489         EFI_STATUS efirc;
01490         int rc;
01491 
01492         /* Open device path protocol */
01493         if ( ( efirc = bs->OpenProtocol ( handle,
01494                                           &efi_device_path_protocol_guid,
01495                                           &u.interface, efi_image_handle,
01496                                           handle,
01497                                           EFI_OPEN_PROTOCOL_GET_PROTOCOL ))!=0){
01498                 rc = -EEFI ( efirc );
01499                 DBGC ( usbio, "USBIO %s cannot open device path protocol: "
01500                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01501                 goto err_open_protocol;
01502         }
01503         path = u.interface;
01504 
01505         /* Locate end of device path and sanity check */
01506         len = efi_devpath_len ( path );
01507         if ( len < sizeof ( *usbpath ) ) {
01508                 DBGC ( usbio, "USBIO %s underlength device path\n",
01509                        efi_handle_name ( handle ) );
01510                 rc = -EINVAL;
01511                 goto err_underlength;
01512         }
01513         usbpath = ( ( ( void * ) path ) + len - sizeof ( *usbpath ) );
01514         if ( ! ( ( usbpath->Header.Type == MESSAGING_DEVICE_PATH ) &&
01515                  ( usbpath->Header.SubType == MSG_USB_DP ) ) ) {
01516                 DBGC ( usbio, "USBIO %s not a USB device path: ",
01517                        efi_handle_name ( handle ) );
01518                 DBGC ( usbio, "%s\n", efi_devpath_text ( path ) );
01519                 rc = -EINVAL;
01520                 goto err_non_usb;
01521         }
01522 
01523         /* Allocate copy of device path */
01524         usbio->path = malloc ( len + sizeof ( *end ) );
01525         if ( ! usbio->path ) {
01526                 rc = -ENOMEM;
01527                 goto err_alloc;
01528         }
01529         memcpy ( usbio->path, path, ( len + sizeof ( *end ) ) );
01530         usbio->usbpath = ( ( ( void * ) usbio->path ) + len -
01531                            sizeof ( *usbpath ) );
01532 
01533         /* Close protocol */
01534         bs->CloseProtocol ( handle, &efi_device_path_protocol_guid,
01535                             efi_image_handle, handle );
01536 
01537         return 0;
01538 
01539         free ( usbio->path );
01540  err_alloc:
01541  err_non_usb:
01542  err_underlength:
01543         bs->CloseProtocol ( handle, &efi_device_path_protocol_guid,
01544                             efi_image_handle, handle );
01545  err_open_protocol:
01546         return rc;
01547 }
01548 
01549 /**
01550  * Construct interface list
01551  *
01552  * @v usbio             USB I/O device
01553  * @ret rc              Return status code
01554  */
01555 static int usbio_interfaces ( struct usbio_device *usbio ) {
01556         EFI_HANDLE handle = usbio->handle;
01557         EFI_USB_IO_PROTOCOL *io = usbio->io;
01558         EFI_USB_INTERFACE_DESCRIPTOR interface;
01559         unsigned int first;
01560         unsigned int count;
01561         EFI_STATUS efirc;
01562         int rc;
01563 
01564         /* Get interface descriptor */
01565         if ( ( efirc = io->UsbGetInterfaceDescriptor ( io, &interface ) ) != 0){
01566                 rc = -EEFI ( efirc );
01567                 DBGC ( usbio, "USB %s could not get interface descriptor: "
01568                        "%s\n", efi_handle_name ( handle ), strerror ( rc ) );
01569                 goto err_get_interface_descriptor;
01570         }
01571 
01572         /* Record first interface number */
01573         first = interface.InterfaceNumber;
01574         count = usbio->config->interfaces;
01575         assert ( first < count );
01576         usbio->first = first;
01577 
01578         /* Allocate interface list */
01579         usbio->interface = zalloc ( count * sizeof ( usbio->interface[0] ) );
01580         if ( ! usbio->interface ) {
01581                 rc = -ENOMEM;
01582                 goto err_alloc;
01583         }
01584 
01585         /* Use already-opened protocol for control transfers and for
01586          * the first interface.
01587          */
01588         usbio->interface[0].handle = handle;
01589         usbio->interface[0].io = io;
01590         usbio->interface[0].count = 1;
01591         usbio->interface[first].handle = handle;
01592         usbio->interface[first].io = io;
01593         usbio->interface[first].count = 1;
01594 
01595         return 0;
01596 
01597         free ( usbio->interface );
01598  err_alloc:
01599  err_get_interface_descriptor:
01600         return rc;
01601 }
01602 
01603 /**
01604  * Attach driver to device
01605  *
01606  * @v efidev            EFI device
01607  * @ret rc              Return status code
01608  */
01609 static int usbio_start ( struct efi_device *efidev ) {
01610         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01611         EFI_HANDLE handle = efidev->device;
01612         struct usbio_device *usbio;
01613         struct usb_port *port;
01614         union {
01615                 void *interface;
01616                 EFI_USB_IO_PROTOCOL *io;
01617         } u;
01618         EFI_STATUS efirc;
01619         int rc;
01620 
01621         /* Allocate and initialise structure */
01622         usbio = zalloc ( sizeof ( *usbio ) );
01623         if ( ! usbio ) {
01624                 rc = -ENOMEM;
01625                 goto err_alloc;
01626         }
01627         efidev_set_drvdata ( efidev, usbio );
01628         usbio->handle = handle;
01629         INIT_LIST_HEAD ( &usbio->endpoints );
01630 
01631         /* Open USB I/O protocol */
01632         if ( ( efirc = bs->OpenProtocol ( handle, &efi_usb_io_protocol_guid,
01633                                           &u.interface, efi_image_handle,
01634                                           handle,
01635                                           ( EFI_OPEN_PROTOCOL_BY_DRIVER |
01636                                             EFI_OPEN_PROTOCOL_EXCLUSIVE )))!=0){
01637                 rc = -EEFI ( efirc );
01638                 DBGC ( usbio, "USBIO %s cannot open USB I/O protocol: %s\n",
01639                        efi_handle_name ( handle ), strerror ( rc ) );
01640                 DBGC_EFI_OPENERS ( usbio, handle, &efi_usb_io_protocol_guid );
01641                 goto err_open_usbio;
01642         }
01643         usbio->io = u.io;
01644 
01645         /* Describe generic device */
01646         efi_device_info ( handle, "USB", &usbio->dev );
01647         usbio->dev.parent = &efidev->dev;
01648         list_add ( &usbio->dev.siblings, &efidev->dev.children );
01649         INIT_LIST_HEAD ( &usbio->dev.children );
01650 
01651         /* Fetch configuration descriptor */
01652         if ( ( rc = usbio_config ( usbio ) ) != 0 )
01653                 goto err_config;
01654 
01655         /* Construct device path */
01656         if ( ( rc = usbio_path ( usbio ) ) != 0 )
01657                 goto err_path;
01658 
01659         /* Construct interface list */
01660         if ( ( rc = usbio_interfaces ( usbio ) ) != 0 )
01661                 goto err_interfaces;
01662 
01663         /* Allocate USB bus */
01664         usbio->bus = alloc_usb_bus ( &usbio->dev, 1 /* single "port" */,
01665                                      USBIO_MTU, &usbio_operations );
01666         if ( ! usbio->bus ) {
01667                 rc = -ENOMEM;
01668                 goto err_alloc_bus;
01669         }
01670         usb_bus_set_hostdata ( usbio->bus, usbio );
01671         usb_hub_set_drvdata ( usbio->bus->hub, usbio );
01672 
01673         /* Set port protocol */
01674         port = usb_port ( usbio->bus->hub, 1 );
01675         port->protocol = USB_PROTO_2_0;
01676 
01677         /* Register USB bus */
01678         if ( ( rc = register_usb_bus ( usbio->bus ) ) != 0 )
01679                 goto err_register;
01680 
01681         return 0;
01682 
01683         unregister_usb_bus ( usbio->bus );
01684  err_register:
01685         free_usb_bus ( usbio->bus );
01686  err_alloc_bus:
01687         free ( usbio->interface );
01688  err_interfaces:
01689         free ( usbio->path );
01690  err_path:
01691         free ( usbio->config );
01692  err_config:
01693         list_del ( &usbio->dev.siblings );
01694         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01695                             efi_image_handle, handle );
01696  err_open_usbio:
01697         free ( usbio );
01698  err_alloc:
01699         return rc;
01700 }
01701 
01702 /**
01703  * Detach driver from device
01704  *
01705  * @v efidev            EFI device
01706  */
01707 static void usbio_stop ( struct efi_device *efidev ) {
01708         EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
01709         EFI_HANDLE handle = efidev->device;
01710         struct usbio_device *usbio = efidev_get_drvdata ( efidev );
01711 
01712         unregister_usb_bus ( usbio->bus );
01713         free_usb_bus ( usbio->bus );
01714         free ( usbio->interface );
01715         free ( usbio->path );
01716         free ( usbio->config );
01717         list_del ( &usbio->dev.siblings );
01718         bs->CloseProtocol ( handle, &efi_usb_io_protocol_guid,
01719                             efi_image_handle, handle );
01720         free ( usbio );
01721 }
01722 
01723 /** EFI USB I/O driver */
01724 struct efi_driver usbio_driver __efi_driver ( EFI_DRIVER_NORMAL ) = {
01725         .name = "USBIO",
01726         .supported = usbio_supported,
01727         .start = usbio_start,
01728         .stop = usbio_stop,
01729 };