MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.c

   1 /** @file
   2   USB Mass Storage Driver that manages USB Mass Storage Device and produces Block I/O Protocol.
   3
   4 Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include "UsbMassImpl.h"
  16
  17 #define USB_MASS_TRANSPORT_COUNT    3
  18 //
  19 // Array of USB transport interfaces.
  20 //
  21 USB_MASS_TRANSPORT *mUsbMassTransport[USB_MASS_TRANSPORT_COUNT] = {
  22   &mUsbCbi0Transport,
  23   &mUsbCbi1Transport,
  24   &mUsbBotTransport,
  25 };
  26
  27 EFI_DRIVER_BINDING_PROTOCOL gUSBMassDriverBinding = {
  28   USBMassDriverBindingSupported,
  29   USBMassDriverBindingStart,
  30   USBMassDriverBindingStop,
  31   0x11,
  32   NULL,
  33   NULL
  34 };
  35
  36 /**
  37   Reset the block device.
  38
  39   This function implements EFI_BLOCK_IO_PROTOCOL.Reset().
  40   It resets the block device hardware.
  41   ExtendedVerification is ignored in this implementation.
  42
  43   @param  This                   Indicates a pointer to the calling context.
  44   @param  ExtendedVerification   Indicates that the driver may perform a more exhaustive
  45                                  verification operation of the device during reset.
  46
  47   @retval EFI_SUCCESS            The block device was reset.
  48   @retval EFI_DEVICE_ERROR       The block device is not functioning correctly and could not be reset.
  49
  50 **/
  51 EFI_STATUS
  52 EFIAPI
  53 UsbMassReset (
  54   IN EFI_BLOCK_IO_PROTOCOL    *This,
  55   IN BOOLEAN                  ExtendedVerification
  56   )
  57 {
  58   USB_MASS_DEVICE *UsbMass;
  59   EFI_TPL         OldTpl;
  60   EFI_STATUS      Status;
  61
  62   //
  63   // Raise TPL to TPL_NOTIFY to serialize all its operations
  64   // to protect shared data structures.
  65   //
  66   OldTpl  = gBS->RaiseTPL (TPL_NOTIFY);
  67
  68   UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (This);
  69   Status  = UsbMass->Transport->Reset (UsbMass->Context, ExtendedVerification);
  70
  71   gBS->RestoreTPL (OldTpl);
  72
  73   return Status;
  74 }
  75
  76 /**
  77   Reads the requested number of blocks from the device.
  78
  79   This function implements EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
  80   It reads the requested number of blocks from the device.
  81   All the blocks are read, or an error is returned.
  82
  83   @param  This                   Indicates a pointer to the calling context.
  84   @param  MediaId                The media ID that the read request is for.
  85   @param  Lba                    The starting logical block address to read from on the device.
  86   @param  BufferSize             The size of the Buffer in bytes.
  87                                  This must be a multiple of the intrinsic block size of the device.
  88   @param  Buffer                 A pointer to the destination buffer for the data. The caller is
  89                                  responsible for either having implicit or explicit ownership of the buffer.
  90
  91   @retval EFI_SUCCESS            The data was read correctly from the device.
  92   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to perform the read operation.
  93   @retval EFI_NO_MEDIA           There is no media in the device.
  94   @retval EFI_MEDIA_CHANGED      The MediaId is not for the current media.
  95   @retval EFI_BAD_BUFFER_SIZE    The BufferSize parameter is not a multiple of the intrinsic block size of the device.
  96   @retval EFI_INVALID_PARAMETER  The read request contains LBAs that are not valid,
  97                                  or the buffer is not on proper alignment.
  98
  99 **/
 100 EFI_STATUS
 101 EFIAPI
 102 UsbMassReadBlocks (
 103   IN EFI_BLOCK_IO_PROTOCOL    *This,
 104   IN UINT32                   MediaId,
 105   IN EFI_LBA                  Lba,
 106   IN UINTN                    BufferSize,
 107   OUT VOID                    *Buffer
 108   )
 109 {
 110   USB_MASS_DEVICE     *UsbMass;
 111   EFI_BLOCK_IO_MEDIA  *Media;
 112   EFI_STATUS          Status;
 113   EFI_TPL             OldTpl;
 114   UINTN               TotalBlock;
 115
 116   //
 117   // Raise TPL to TPL_NOTIFY to serialize all its operations
 118   // to protect shared data structures.
 119   //
 120   OldTpl  = gBS->RaiseTPL (TPL_NOTIFY);
 121   UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (This);
 122   Media   = &UsbMass->BlockIoMedia;
 123
 124   //
 125   // If it is a removable media, such as CD-Rom or Usb-Floppy,
 126   // need to detect the media before each read/write. While some of
 127   // Usb-Flash is marked as removable media.
 128   //
 129   if (Media->RemovableMedia) {
 130     Status = UsbBootDetectMedia (UsbMass);
 131     if (EFI_ERROR (Status)) {
 132       goto ON_EXIT;
 133     }
 134   }
 135
 136   if (!(Media->MediaPresent)) {
 137     Status = EFI_NO_MEDIA;
 138     goto ON_EXIT;
 139   }
 140
 141   if (MediaId != Media->MediaId) {
 142     Status = EFI_MEDIA_CHANGED;
 143     goto ON_EXIT;
 144   }
 145
 146   if (BufferSize == 0) {
 147     Status = EFI_SUCCESS;
 148     goto ON_EXIT;
 149   }
 150
 151   if (Buffer == NULL) {
 152     Status = EFI_INVALID_PARAMETER;
 153     goto ON_EXIT;
 154   }
 155
 156   //
 157   // BufferSize must be a multiple of the intrinsic block size of the device.
 158   //
 159   if ((BufferSize % Media->BlockSize) != 0) {
 160     Status = EFI_BAD_BUFFER_SIZE;
 161     goto ON_EXIT;
 162   }
 163
 164   TotalBlock = BufferSize / Media->BlockSize;
 165
 166   //
 167   // Make sure the range to read is valid.
 168   //
 169   if (Lba + TotalBlock - 1 > Media->LastBlock) {
 170     Status = EFI_INVALID_PARAMETER;
 171     goto ON_EXIT;
 172   }
 173
 174   Status = UsbBootReadBlocks (UsbMass, (UINT32) Lba, TotalBlock, Buffer);
 175   if (EFI_ERROR (Status)) {
 176     DEBUG ((EFI_D_ERROR, "UsbMassReadBlocks: UsbBootReadBlocks (%r) -> Reset\n", Status));
 177     UsbMassReset (This, TRUE);
 178   }
 179
 180 ON_EXIT:
 181   gBS->RestoreTPL (OldTpl);
 182   return Status;
 183 }
 184
 185
 186 /**
 187   Writes a specified number of blocks to the device.
 188
 189   This function implements EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
 190   It writes a specified number of blocks to the device.
 191   All blocks are written, or an error is returned.
 192
 193   @param  This                   Indicates a pointer to the calling context.
 194   @param  MediaId                The media ID that the write request is for.
 195   @param  Lba                    The starting logical block address to be written.
 196   @param  BufferSize             The size of the Buffer in bytes.
 197                                  This must be a multiple of the intrinsic block size of the device.
 198   @param  Buffer                 Pointer to the source buffer for the data.
 199
 200   @retval EFI_SUCCESS            The data were written correctly to the device.
 201   @retval EFI_WRITE_PROTECTED    The device cannot be written to.
 202   @retval EFI_NO_MEDIA           There is no media in the device.
 203   @retval EFI_MEDIA_CHANGED      The MediaId is not for the current media.
 204   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to perform the write operation.
 205   @retval EFI_BAD_BUFFER_SIZE    The BufferSize parameter is not a multiple of the intrinsic
 206                                  block size of the device.
 207   @retval EFI_INVALID_PARAMETER  The write request contains LBAs that are not valid,
 208                                  or the buffer is not on proper alignment.
 209
 210 **/
 211 EFI_STATUS
 212 EFIAPI
 213 UsbMassWriteBlocks (
 214   IN EFI_BLOCK_IO_PROTOCOL    *This,
 215   IN UINT32                   MediaId,
 216   IN EFI_LBA                  Lba,
 217   IN UINTN                    BufferSize,
 218   IN VOID                     *Buffer
 219   )
 220 {
 221   USB_MASS_DEVICE     *UsbMass;
 222   EFI_BLOCK_IO_MEDIA  *Media;
 223   EFI_STATUS          Status;
 224   EFI_TPL             OldTpl;
 225   UINTN               TotalBlock;
 226
 227   //
 228   // Raise TPL to TPL_NOTIFY to serialize all its operations
 229   // to protect shared data structures.
 230   //
 231   OldTpl  = gBS->RaiseTPL (TPL_NOTIFY);
 232   UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (This);
 233   Media   = &UsbMass->BlockIoMedia;
 234
 235   //
 236   // If it is a removable media, such as CD-Rom or Usb-Floppy,
 237   // need to detect the media before each read/write. Some of
 238   // USB Flash is marked as removable media.
 239   //
 240   if (Media->RemovableMedia) {
 241     Status = UsbBootDetectMedia (UsbMass);
 242     if (EFI_ERROR (Status)) {
 243       goto ON_EXIT;
 244     }
 245   }
 246
 247   if (!(Media->MediaPresent)) {
 248     Status = EFI_NO_MEDIA;
 249     goto ON_EXIT;
 250   }
 251
 252   if (MediaId != Media->MediaId) {
 253     Status = EFI_MEDIA_CHANGED;
 254     goto ON_EXIT;
 255   }
 256
 257   if (BufferSize == 0) {
 258     Status = EFI_SUCCESS;
 259     goto ON_EXIT;
 260   }
 261
 262   if (Buffer == NULL) {
 263     Status = EFI_INVALID_PARAMETER;
 264     goto ON_EXIT;
 265   }
 266
 267   //
 268   // BufferSize must be a multiple of the intrinsic block size of the device.
 269   //
 270   if ((BufferSize % Media->BlockSize) != 0) {
 271     Status = EFI_BAD_BUFFER_SIZE;
 272     goto ON_EXIT;
 273   }
 274
 275   TotalBlock = BufferSize / Media->BlockSize;
 276
 277   //
 278   // Make sure the range to write is valid.
 279   //
 280   if (Lba + TotalBlock - 1 > Media->LastBlock) {
 281     Status = EFI_INVALID_PARAMETER;
 282     goto ON_EXIT;
 283   }
 284
 285   //
 286   // Try to write the data even the device is marked as ReadOnly,
 287   // and clear the status should the write succeed.
 288   //
 289   Status = UsbBootWriteBlocks (UsbMass, (UINT32) Lba, TotalBlock, Buffer);
 290   if (EFI_ERROR (Status)) {
 291     DEBUG ((EFI_D_ERROR, "UsbMassWriteBlocks: UsbBootWriteBlocks (%r) -> Reset\n", Status));
 292     UsbMassReset (This, TRUE);
 293   }
 294
 295 ON_EXIT:
 296   gBS->RestoreTPL (OldTpl);
 297   return Status;
 298 }
 299
 300 /**
 301   Flushes all modified data to a physical block device.
 302
 303   This function implements EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
 304   USB mass storage device doesn't support write cache,
 305   so return EFI_SUCCESS directly.
 306
 307   @param  This                   Indicates a pointer to the calling context.
 308
 309   @retval EFI_SUCCESS            All outstanding data were written correctly to the device.
 310   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to write data.
 311   @retval EFI_NO_MEDIA           There is no media in the device.
 312
 313 **/
 314 EFI_STATUS
 315 EFIAPI
 316 UsbMassFlushBlocks (
 317   IN EFI_BLOCK_IO_PROTOCOL  *This
 318   )
 319 {
 320   return EFI_SUCCESS;
 321 }
 322
 323 /**
 324   Initialize the media parameter data for EFI_BLOCK_IO_MEDIA of Block I/O Protocol.
 325
 326   @param  UsbMass                The USB mass storage device
 327
 328   @retval EFI_SUCCESS            The media parameters are updated successfully.
 329   @retval Others                 Failed to get the media parameters.
 330
 331 **/
 332 EFI_STATUS
 333 UsbMassInitMedia (
 334   IN USB_MASS_DEVICE          *UsbMass
 335   )
 336 {
 337   EFI_BLOCK_IO_MEDIA          *Media;
 338   EFI_STATUS                  Status;
 339   UINTN                       Index;
 340
 341   Media = &UsbMass->BlockIoMedia;
 342
 343   //
 344   // Fields of EFI_BLOCK_IO_MEDIA are defined in UEFI 2.0 spec,
 345   // section for Block I/O Protocol.
 346   //
 347   Media->MediaPresent     = FALSE;
 348   Media->LogicalPartition = FALSE;
 349   Media->ReadOnly         = FALSE;
 350   Media->WriteCaching     = FALSE;
 351   Media->IoAlign          = 0;
 352   Media->MediaId          = 1;
 353
 354   //
 355   // Some device may spend several seconds before it is ready.
 356   // Try several times before giving up. Wait 5s at most.
 357   //
 358   Status = EFI_SUCCESS;
 359
 360   for (Index = 0; Index < USB_BOOT_INIT_MEDIA_RETRY; Index++) {
 361
 362     Status = UsbBootGetParams (UsbMass);
 363     if ((Status != EFI_MEDIA_CHANGED) && (Status != EFI_NOT_READY) && (Status != EFI_TIMEOUT)) {
 364       break;
 365     }
 366
 367     Status = UsbBootIsUnitReady (UsbMass);
 368     if (EFI_ERROR (Status)) {
 369       gBS->Stall (USB_BOOT_RETRY_UNIT_READY_STALL * (Index + 1));
 370     }
 371   }
 372
 373   return Status;
 374 }
 375
 376 /**
 377   Initilize the USB Mass Storage transport.
 378
 379   This function tries to find the matching USB Mass Storage transport
 380   protocol for USB device. If found, initializes the matching transport.
 381
 382   @param  This            The USB mass driver's driver binding.
 383   @param  Controller      The device to test.
 384   @param  Transport       The pointer to pointer to USB_MASS_TRANSPORT.
 385   @param  Context         The parameter for USB_MASS_DEVICE.Context.
 386   @param  MaxLun          Get the MaxLun if is BOT dev.
 387
 388   @retval EFI_SUCCESS     The initialization is successful.
 389   @retval EFI_UNSUPPORTED No matching transport protocol is found.
 390   @retval Others          Failed to initialize dev.
 391
 392 **/
 393 EFI_STATUS
 394 UsbMassInitTransport (
 395   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 396   IN  EFI_HANDLE                   Controller,
 397   OUT USB_MASS_TRANSPORT           **Transport,
 398   OUT VOID                         **Context,
 399   OUT UINT8                        *MaxLun
 400   )
 401 {
 402   EFI_USB_IO_PROTOCOL           *UsbIo;
 403   EFI_USB_INTERFACE_DESCRIPTOR  Interface;
 404   UINT8                         Index;
 405   EFI_STATUS                    Status;
 406
 407   Status = gBS->OpenProtocol (
 408                   Controller,
 409                   &gEfiUsbIoProtocolGuid,
 410                   (VOID **) &UsbIo,
 411                   This->DriverBindingHandle,
 412                   Controller,
 413                   EFI_OPEN_PROTOCOL_BY_DRIVER
 414                   );
 415
 416   if (EFI_ERROR (Status)) {
 417     return Status;
 418   }
 419
 420   Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &Interface);
 421   if (EFI_ERROR (Status)) {
 422     goto ON_EXIT;
 423   }
 424
 425   Status = EFI_UNSUPPORTED;
 426
 427   //
 428   // Traverse the USB_MASS_TRANSPORT arrary and try to find the
 429   // matching transport protocol.
 430   // If not found, return EFI_UNSUPPORTED.
 431   // If found, execute USB_MASS_TRANSPORT.Init() to initialize the transport context.
 432   //
 433   for (Index = 0; Index < USB_MASS_TRANSPORT_COUNT; Index++) {
 434     *Transport = mUsbMassTransport[Index];
 435
 436     if (Interface.InterfaceProtocol == (*Transport)->Protocol) {
 437       Status  = (*Transport)->Init (UsbIo, Context);
 438       break;
 439     }
 440   }
 441
 442   if (EFI_ERROR (Status)) {
 443     goto ON_EXIT;
 444   }
 445
 446   //
 447   // For BOT device, try to get its max LUN.
 448   // If max LUN is 0, then it is a non-lun device.
 449   // Otherwise, it is a multi-lun device.
 450   //
 451   if ((*Transport)->Protocol == USB_MASS_STORE_BOT) {
 452     (*Transport)->GetMaxLun (*Context, MaxLun);
 453   }
 454
 455 ON_EXIT:
 456   gBS->CloseProtocol (
 457          Controller,
 458          &gEfiUsbIoProtocolGuid,
 459          This->DriverBindingHandle,
 460          Controller
 461          );
 462   return Status;
 463 }
 464
 465 /**
 466   Initialize data for device that supports multiple LUNSs.
 467
 468   @param  This                 The Driver Binding Protocol instance.
 469   @param  Controller           The device to initialize.
 470   @param  Transport            Pointer to USB_MASS_TRANSPORT.
 471   @param  Context              Parameter for USB_MASS_DEVICE.Context.
 472   @param  DevicePath           The remaining device path.
 473   @param  MaxLun               The max LUN number.
 474
 475   @retval EFI_SUCCESS          At least one LUN is initialized successfully.
 476   @retval EFI_OUT_OF_RESOURCES Out of resource while creating device path node.
 477   @retval Other                Initialization fails.
 478
 479 **/
 480 EFI_STATUS
 481 UsbMassInitMultiLun (
 482   IN EFI_DRIVER_BINDING_PROTOCOL   *This,
 483   IN EFI_HANDLE                    Controller,
 484   IN USB_MASS_TRANSPORT            *Transport,
 485   IN VOID                          *Context,
 486   IN EFI_DEVICE_PATH_PROTOCOL      *DevicePath,
 487   IN UINT8                         MaxLun
 488   )
 489 {
 490   USB_MASS_DEVICE                  *UsbMass;
 491   EFI_USB_IO_PROTOCOL              *UsbIo;
 492   DEVICE_LOGICAL_UNIT_DEVICE_PATH  LunNode;
 493   UINT8                            Index;
 494   EFI_STATUS                       Status;
 495
 496   ASSERT (MaxLun > 0);
 497
 498   for (Index = 0; Index <= MaxLun; Index++) {
 499
 500     DEBUG ((EFI_D_INFO, "UsbMassInitMultiLun: Start to initialize No.%d logic unit\n", Index));
 501
 502     UsbIo   = NULL;
 503     UsbMass = AllocateZeroPool (sizeof (USB_MASS_DEVICE));
 504     ASSERT (UsbMass != NULL);
 505
 506     UsbMass->Signature            = USB_MASS_SIGNATURE;
 507     UsbMass->UsbIo                = UsbIo;
 508     UsbMass->BlockIo.Media        = &UsbMass->BlockIoMedia;
 509     UsbMass->BlockIo.Reset        = UsbMassReset;
 510     UsbMass->BlockIo.ReadBlocks   = UsbMassReadBlocks;
 511     UsbMass->BlockIo.WriteBlocks  = UsbMassWriteBlocks;
 512     UsbMass->BlockIo.FlushBlocks  = UsbMassFlushBlocks;
 513     UsbMass->OpticalStorage       = FALSE;
 514     UsbMass->Transport            = Transport;
 515     UsbMass->Context              = Context;
 516     UsbMass->Lun                  = Index;
 517
 518     //
 519     // Initialize the media parameter data for EFI_BLOCK_IO_MEDIA of Block I/O Protocol.
 520     //
 521     Status = UsbMassInitMedia (UsbMass);
 522     if (!EFI_ERROR (Status)) {
 523       //
 524       // According to USB Mass Storage Specification for Bootability, only following
 525       // 4 Peripheral Device Types are in spec.
 526       //
 527       if ((UsbMass->Pdt != USB_PDT_DIRECT_ACCESS) &&
 528            (UsbMass->Pdt != USB_PDT_CDROM) &&
 529            (UsbMass->Pdt != USB_PDT_OPTICAL) &&
 530            (UsbMass->Pdt != USB_PDT_SIMPLE_DIRECT)) {
 531         DEBUG ((EFI_D_ERROR, "UsbMassInitMultiLun: Found an unsupported peripheral type[%d]\n", UsbMass->Pdt));
 532         goto ON_ERROR;
 533       }
 534     } else if (Status != EFI_NO_MEDIA){
 535       DEBUG ((EFI_D_ERROR, "UsbMassInitMultiLun: UsbMassInitMedia (%r)\n", Status));
 536       goto ON_ERROR;
 537     }
 538
 539     //
 540     // Create a device path node for device logic unit, and append it.
 541     //
 542     LunNode.Header.Type    = MESSAGING_DEVICE_PATH;
 543     LunNode.Header.SubType = MSG_DEVICE_LOGICAL_UNIT_DP;
 544     LunNode.Lun            = UsbMass->Lun;
 545
 546     SetDevicePathNodeLength (&LunNode.Header, sizeof (LunNode));
 547
 548     UsbMass->DevicePath = AppendDevicePathNode (DevicePath, &LunNode.Header);
 549
 550     if (UsbMass->DevicePath == NULL) {
 551       DEBUG ((EFI_D_ERROR, "UsbMassInitMultiLun: failed to create device logic unit device path\n"));
 552
 553       Status = EFI_OUT_OF_RESOURCES;
 554       goto ON_ERROR;
 555     }
 556
 557     //
 558     // Create a new handle for each LUN, and install Block I/O Protocol and Device Path Protocol.
 559     //
 560     Status = gBS->InstallMultipleProtocolInterfaces (
 561                     &UsbMass->Controller,
 562                     &gEfiDevicePathProtocolGuid,
 563                     UsbMass->DevicePath,
 564                     &gEfiBlockIoProtocolGuid,
 565                     &UsbMass->BlockIo,
 566                     NULL
 567                     );
 568
 569     if (EFI_ERROR (Status)) {
 570       DEBUG ((EFI_D_ERROR, "UsbMassInitMultiLun: InstallMultipleProtocolInterfaces (%r)\n", Status));
 571       goto ON_ERROR;
 572     }
 573
 574     //
 575     // Open USB I/O Protocol by child to setup a parent-child relationship.
 576     //
 577     Status = gBS->OpenProtocol (
 578                     Controller,
 579                     &gEfiUsbIoProtocolGuid,
 580                     (VOID **) &UsbIo,
 581                     This->DriverBindingHandle,
 582                     UsbMass->Controller,
 583                     EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
 584                     );
 585
 586     if (EFI_ERROR (Status)) {
 587       DEBUG ((EFI_D_ERROR, "UsbMassInitMultiLun: OpenUsbIoProtocol By Child (%r)\n", Status));
 588       gBS->UninstallMultipleProtocolInterfaces (
 589              &UsbMass->Controller,
 590              &gEfiDevicePathProtocolGuid,
 591              UsbMass->DevicePath,
 592              &gEfiBlockIoProtocolGuid,
 593              &UsbMass->BlockIo,
 594              NULL
 595              );
 596       goto ON_ERROR;
 597     }
 598
 599     DEBUG ((EFI_D_INFO, "UsbMassInitMultiLun: Success to initialize No.%d logic unit\n", Index));
 600   }
 601
 602   return EFI_SUCCESS;
 603
 604 ON_ERROR:
 605   if (UsbMass != NULL) {
 606     if (UsbMass->DevicePath != NULL) {
 607       FreePool (UsbMass->DevicePath);
 608     }
 609     FreePool (UsbMass);
 610   }
 611   if (UsbIo != NULL) {
 612     gBS->CloseProtocol (
 613            Controller,
 614            &gEfiUsbIoProtocolGuid,
 615            This->DriverBindingHandle,
 616            UsbMass->Controller
 617            );
 618   }
 619
 620   //
 621   // Return EFI_SUCCESS if at least one LUN is initialized successfully.
 622   //
 623   if (Index > 0) {
 624     return EFI_SUCCESS;
 625   } else {
 626     return Status;
 627   }
 628 }
 629
 630 /**
 631   Initialize data for device that does not support multiple LUNSs.
 632
 633   @param  This            The Driver Binding Protocol instance.
 634   @param  Controller      The device to initialize.
 635   @param  Transport       Pointer to USB_MASS_TRANSPORT.
 636   @param  Context         Parameter for USB_MASS_DEVICE.Context.
 637
 638   @retval EFI_SUCCESS     Initialization succeeds.
 639   @retval Other           Initialization fails.
 640
 641 **/
 642 EFI_STATUS
 643 UsbMassInitNonLun (
 644   IN EFI_DRIVER_BINDING_PROTOCOL   *This,
 645   IN EFI_HANDLE                    Controller,
 646   IN USB_MASS_TRANSPORT            *Transport,
 647   IN VOID                          *Context
 648   )
 649 {
 650   USB_MASS_DEVICE             *UsbMass;
 651   EFI_USB_IO_PROTOCOL         *UsbIo;
 652   EFI_STATUS                  Status;
 653
 654   UsbIo   = NULL;
 655   UsbMass = AllocateZeroPool (sizeof (USB_MASS_DEVICE));
 656   ASSERT (UsbMass != NULL);
 657
 658   Status = gBS->OpenProtocol (
 659                   Controller,
 660                   &gEfiUsbIoProtocolGuid,
 661                   (VOID **) &UsbIo,
 662                   This->DriverBindingHandle,
 663                   Controller,
 664                   EFI_OPEN_PROTOCOL_BY_DRIVER
 665                   );
 666
 667   if (EFI_ERROR (Status)) {
 668     DEBUG ((EFI_D_ERROR, "UsbMassInitNonLun: OpenUsbIoProtocol By Driver (%r)\n", Status));
 669     goto ON_ERROR;
 670   }
 671
 672   UsbMass->Signature            = USB_MASS_SIGNATURE;
 673   UsbMass->Controller           = Controller;
 674   UsbMass->UsbIo                = UsbIo;
 675   UsbMass->BlockIo.Media        = &UsbMass->BlockIoMedia;
 676   UsbMass->BlockIo.Reset        = UsbMassReset;
 677   UsbMass->BlockIo.ReadBlocks   = UsbMassReadBlocks;
 678   UsbMass->BlockIo.WriteBlocks  = UsbMassWriteBlocks;
 679   UsbMass->BlockIo.FlushBlocks  = UsbMassFlushBlocks;
 680   UsbMass->OpticalStorage       = FALSE;
 681   UsbMass->Transport            = Transport;
 682   UsbMass->Context              = Context;
 683
 684   //
 685   // Initialize the media parameter data for EFI_BLOCK_IO_MEDIA of Block I/O Protocol.
 686   //
 687   Status = UsbMassInitMedia (UsbMass);
 688   if (!EFI_ERROR (Status)) {
 689     //
 690     // According to USB Mass Storage Specification for Bootability, only following
 691     // 4 Peripheral Device Types are in spec.
 692     //
 693     if ((UsbMass->Pdt != USB_PDT_DIRECT_ACCESS) &&
 694          (UsbMass->Pdt != USB_PDT_CDROM) &&
 695          (UsbMass->Pdt != USB_PDT_OPTICAL) &&
 696          (UsbMass->Pdt != USB_PDT_SIMPLE_DIRECT)) {
 697       DEBUG ((EFI_D_ERROR, "UsbMassInitNonLun: Found an unsupported peripheral type[%d]\n", UsbMass->Pdt));
 698       goto ON_ERROR;
 699     }
 700   } else if (Status != EFI_NO_MEDIA){
 701     DEBUG ((EFI_D_ERROR, "UsbMassInitNonLun: UsbMassInitMedia (%r)\n", Status));
 702     goto ON_ERROR;
 703   }
 704
 705   Status = gBS->InstallProtocolInterface (
 706                   &Controller,
 707                   &gEfiBlockIoProtocolGuid,
 708                   EFI_NATIVE_INTERFACE,
 709                   &UsbMass->BlockIo
 710                   );
 711   if (EFI_ERROR (Status)) {
 712     goto ON_ERROR;
 713   }
 714
 715   return EFI_SUCCESS;
 716
 717 ON_ERROR:
 718   if (UsbMass != NULL) {
 719     FreePool (UsbMass);
 720   }
 721   if (UsbIo != NULL) {
 722     gBS->CloseProtocol (
 723            Controller,
 724            &gEfiUsbIoProtocolGuid,
 725            This->DriverBindingHandle,
 726            Controller
 727            );
 728   }
 729   return Status;
 730 }
 731
 732
 733 /**
 734   Check whether the controller is a supported USB mass storage.
 735
 736   @param  This                   The USB mass storage driver binding protocol.
 737   @param  Controller             The controller handle to check.
 738   @param  RemainingDevicePath    The remaining device path.
 739
 740   @retval EFI_SUCCESS            The driver supports this controller.
 741   @retval other                  This device isn't supported.
 742
 743 **/
 744 EFI_STATUS
 745 EFIAPI
 746 USBMassDriverBindingSupported (
 747   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 748   IN EFI_HANDLE                   Controller,
 749   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 750   )
 751 {
 752   EFI_USB_IO_PROTOCOL           *UsbIo;
 753   EFI_USB_INTERFACE_DESCRIPTOR  Interface;
 754   USB_MASS_TRANSPORT            *Transport;
 755   EFI_STATUS                    Status;
 756   UINTN                         Index;
 757
 758   Status = gBS->OpenProtocol (
 759                   Controller,
 760                   &gEfiUsbIoProtocolGuid,
 761                   (VOID **) &UsbIo,
 762                   This->DriverBindingHandle,
 763                   Controller,
 764                   EFI_OPEN_PROTOCOL_BY_DRIVER
 765                   );
 766   if (EFI_ERROR (Status)) {
 767     return Status;
 768   }
 769
 770   //
 771   // Get the interface descriptor to check the USB class and find a transport
 772   // protocol handler.
 773   //
 774   Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &Interface);
 775   if (EFI_ERROR (Status)) {
 776     goto ON_EXIT;
 777   }
 778
 779   Status = EFI_UNSUPPORTED;
 780
 781   if (Interface.InterfaceClass != USB_MASS_STORE_CLASS) {
 782     goto ON_EXIT;
 783   }
 784
 785   //
 786   // Traverse the USB_MASS_TRANSPORT arrary and try to find the
 787   // matching transport method.
 788   // If not found, return EFI_UNSUPPORTED.
 789   // If found, execute USB_MASS_TRANSPORT.Init() to initialize the transport context.
 790   //
 791   for (Index = 0; Index < USB_MASS_TRANSPORT_COUNT; Index++) {
 792     Transport = mUsbMassTransport[Index];
 793     if (Interface.InterfaceProtocol == Transport->Protocol) {
 794       Status = Transport->Init (UsbIo, NULL);
 795       break;
 796     }
 797   }
 798
 799 ON_EXIT:
 800   gBS->CloseProtocol (
 801          Controller,
 802          &gEfiUsbIoProtocolGuid,
 803          This->DriverBindingHandle,
 804          Controller
 805          );
 806
 807   return Status;
 808 }
 809
 810 /**
 811   Starts the USB mass storage device with this driver.
 812
 813   This function consumes USB I/O Portocol, intializes USB mass storage device,
 814   installs Block I/O Protocol, and submits Asynchronous Interrupt
 815   Transfer to manage the USB mass storage device.
 816
 817   @param  This                  The USB mass storage driver binding protocol.
 818   @param  Controller            The USB mass storage device to start on
 819   @param  RemainingDevicePath   The remaining device path.
 820
 821   @retval EFI_SUCCESS           This driver supports this device.
 822   @retval EFI_UNSUPPORTED       This driver does not support this device.
 823   @retval EFI_DEVICE_ERROR      This driver cannot be started due to device Error.
 824   @retval EFI_OUT_OF_RESOURCES  Can't allocate memory resources.
 825   @retval EFI_ALREADY_STARTED   This driver has been started.
 826
 827 **/
 828 EFI_STATUS
 829 EFIAPI
 830 USBMassDriverBindingStart (
 831   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 832   IN EFI_HANDLE                   Controller,
 833   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 834   )
 835 {
 836   USB_MASS_TRANSPORT            *Transport;
 837   EFI_DEVICE_PATH_PROTOCOL      *DevicePath;
 838   VOID                          *Context;
 839   UINT8                         MaxLun;
 840   EFI_STATUS                    Status;
 841   EFI_USB_IO_PROTOCOL           *UsbIo;
 842   EFI_TPL                       OldTpl;
 843
 844   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 845
 846   Transport = NULL;
 847   Context   = NULL;
 848   MaxLun    = 0;
 849
 850   Status = UsbMassInitTransport (This, Controller, &Transport, &Context, &MaxLun);
 851
 852   if (EFI_ERROR (Status)) {
 853     DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: UsbMassInitTransport (%r)\n", Status));
 854     goto Exit;
 855   }
 856   if (MaxLun == 0) {
 857     //
 858     // Initialize data for device that does not support multiple LUNSs.
 859     //
 860     Status = UsbMassInitNonLun (This, Controller, Transport, Context);
 861     if (EFI_ERROR (Status)) {
 862       DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: UsbMassInitNonLun (%r)\n", Status));
 863     }
 864   } else {
 865     //
 866     // Open device path to prepare for appending Device Logic Unit node.
 867     //
 868     Status = gBS->OpenProtocol (
 869                     Controller,
 870                     &gEfiDevicePathProtocolGuid,
 871                     (VOID **) &DevicePath,
 872                     This->DriverBindingHandle,
 873                     Controller,
 874                     EFI_OPEN_PROTOCOL_BY_DRIVER
 875                     );
 876
 877     if (EFI_ERROR (Status)) {
 878       DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: OpenDevicePathProtocol By Driver (%r)\n", Status));
 879       goto Exit;
 880     }
 881
 882     Status = gBS->OpenProtocol (
 883                     Controller,
 884                     &gEfiUsbIoProtocolGuid,
 885                     (VOID **) &UsbIo,
 886                     This->DriverBindingHandle,
 887                     Controller,
 888                     EFI_OPEN_PROTOCOL_BY_DRIVER
 889                     );
 890
 891     if (EFI_ERROR (Status)) {
 892       DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: OpenUsbIoProtocol By Driver (%r)\n", Status));
 893       gBS->CloseProtocol (
 894              Controller,
 895              &gEfiDevicePathProtocolGuid,
 896              This->DriverBindingHandle,
 897              Controller
 898              );
 899       goto Exit;
 900     }
 901
 902     //
 903     // Initialize data for device that supports multiple LUNSs.
 904     // EFI_SUCCESS is returned if at least 1 LUN is initialized successfully.
 905     //
 906     Status = UsbMassInitMultiLun (This, Controller, Transport, Context, DevicePath, MaxLun);
 907     if (EFI_ERROR (Status)) {
 908       gBS->CloseProtocol (
 909               Controller,
 910               &gEfiDevicePathProtocolGuid,
 911               This->DriverBindingHandle,
 912               Controller
 913               );
 914       gBS->CloseProtocol (
 915               Controller,
 916               &gEfiUsbIoProtocolGuid,
 917               This->DriverBindingHandle,
 918               Controller
 919               );
 920       DEBUG ((EFI_D_ERROR, "USBMassDriverBindingStart: UsbMassInitMultiLun (%r) with Maxlun=%d\n", Status, MaxLun));
 921     }
 922   }
 923 Exit:
 924   gBS->RestoreTPL (OldTpl);
 925   return Status;
 926 }
 927
 928
 929 /**
 930   Stop controlling the device.
 931
 932   @param  This                   The USB mass storage driver binding
 933   @param  Controller             The device controller controlled by the driver.
 934   @param  NumberOfChildren       The number of children of this device
 935   @param  ChildHandleBuffer      The buffer of children handle.
 936
 937   @retval EFI_SUCCESS            The driver stopped from controlling the device.
 938   @retval EFI_DEVICE_ERROR       The device could not be stopped due to a device error.
 939   @retval EFI_UNSUPPORTED        Block I/O Protocol is not installed on Controller.
 940   @retval Others                 Failed to stop the driver
 941
 942 **/
 943 EFI_STATUS
 944 EFIAPI
 945 USBMassDriverBindingStop (
 946   IN  EFI_DRIVER_BINDING_PROTOCOL *This,
 947   IN  EFI_HANDLE                  Controller,
 948   IN  UINTN                       NumberOfChildren,
 949   IN  EFI_HANDLE                  *ChildHandleBuffer
 950   )
 951 {
 952   EFI_STATUS            Status;
 953   USB_MASS_DEVICE       *UsbMass;
 954   EFI_USB_IO_PROTOCOL   *UsbIo;
 955   EFI_BLOCK_IO_PROTOCOL *BlockIo;
 956   UINTN                 Index;
 957   BOOLEAN               AllChildrenStopped;
 958
 959   //
 960   // This is a bus driver stop function since multi-lun is supported.
 961   // There are three kinds of device handles that might be passed:
 962   // 1st is a handle with USB I/O & Block I/O installed (non-multi-lun)
 963   // 2nd is a handle with Device Path & USB I/O installed (multi-lun root)
 964   // 3rd is a handle with Device Path & USB I/O & Block I/O installed (multi-lun).
 965   //
 966   if (NumberOfChildren == 0) {
 967     //
 968     // A handle without any children, might be 1st and 2nd type.
 969     //
 970     Status = gBS->OpenProtocol (
 971                     Controller,
 972                     &gEfiBlockIoProtocolGuid,
 973                     (VOID **) &BlockIo,
 974                     This->DriverBindingHandle,
 975                     Controller,
 976                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
 977                     );
 978
 979     if (EFI_ERROR(Status)) {
 980       //
 981       // This is a 2nd type handle(multi-lun root), it needs to close devicepath
 982       // and usbio protocol.
 983       //
 984       gBS->CloseProtocol (
 985             Controller,
 986             &gEfiDevicePathProtocolGuid,
 987             This->DriverBindingHandle,
 988             Controller
 989             );
 990       gBS->CloseProtocol (
 991             Controller,
 992             &gEfiUsbIoProtocolGuid,
 993             This->DriverBindingHandle,
 994             Controller
 995             );
 996       DEBUG ((EFI_D_INFO, "Success to stop multi-lun root handle\n"));
 997       return EFI_SUCCESS;
 998     }
 999
1000     //
1001     // This is a 1st type handle(non-multi-lun), which only needs to uninstall
1002     // Block I/O Protocol, close USB I/O Protocol and free mass device.
1003     //
1004     UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (BlockIo);
1005
1006     //
1007     // Uninstall Block I/O protocol from the device handle,
1008     // then call the transport protocol to stop itself.
1009     //
1010     Status = gBS->UninstallProtocolInterface (
1011                     Controller,
1012                     &gEfiBlockIoProtocolGuid,
1013                     &UsbMass->BlockIo
1014                     );
1015     if (EFI_ERROR (Status)) {
1016       return Status;
1017     }
1018
1019     gBS->CloseProtocol (
1020           Controller,
1021           &gEfiUsbIoProtocolGuid,
1022           This->DriverBindingHandle,
1023           Controller
1024           );
1025
1026     UsbMass->Transport->CleanUp (UsbMass->Context);
1027     FreePool (UsbMass);
1028
1029     DEBUG ((EFI_D_INFO, "Success to stop non-multi-lun root handle\n"));
1030     return EFI_SUCCESS;
1031   }
1032
1033   //
1034   // This is a 3rd type handle(multi-lun), which needs uninstall
1035   // Block I/O Protocol and Device Path Protocol, close USB I/O Protocol and
1036   // free mass device for all children.
1037   //
1038   AllChildrenStopped = TRUE;
1039
1040   for (Index = 0; Index < NumberOfChildren; Index++) {
1041
1042     Status = gBS->OpenProtocol (
1043                     ChildHandleBuffer[Index],
1044                     &gEfiBlockIoProtocolGuid,
1045                     (VOID **) &BlockIo,
1046                     This->DriverBindingHandle,
1047                     Controller,
1048                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
1049                     );
1050     if (EFI_ERROR (Status)) {
1051       AllChildrenStopped = FALSE;
1052       DEBUG ((EFI_D_ERROR, "Fail to stop No.%d multi-lun child handle when opening blockio\n", (UINT32)Index));
1053       continue;
1054     }
1055
1056     UsbMass = USB_MASS_DEVICE_FROM_BLOCK_IO (BlockIo);
1057
1058     gBS->CloseProtocol (
1059            Controller,
1060            &gEfiUsbIoProtocolGuid,
1061            This->DriverBindingHandle,
1062            ChildHandleBuffer[Index]
1063            );
1064
1065     Status = gBS->UninstallMultipleProtocolInterfaces (
1066                     ChildHandleBuffer[Index],
1067                     &gEfiDevicePathProtocolGuid,
1068                     UsbMass->DevicePath,
1069                     &gEfiBlockIoProtocolGuid,
1070                     &UsbMass->BlockIo,
1071                     NULL
1072                     );
1073
1074     if (EFI_ERROR (Status)) {
1075       //
1076       // Fail to uninstall Block I/O Protocol and Device Path Protocol, so re-open USB I/O Protocol by child.
1077       //
1078       AllChildrenStopped = FALSE;
1079       DEBUG ((EFI_D_ERROR, "Fail to stop No.%d multi-lun child handle when uninstalling blockio and devicepath\n", (UINT32)Index));
1080
1081       gBS->OpenProtocol (
1082              Controller,
1083              &gEfiUsbIoProtocolGuid,
1084              (VOID **) &UsbIo,
1085              This->DriverBindingHandle,
1086              ChildHandleBuffer[Index],
1087              EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
1088              );
1089     } else {
1090       //
1091       // Succeed to stop this multi-lun handle, so go on with next child.
1092       //
1093       if (((Index + 1) == NumberOfChildren) && AllChildrenStopped) {
1094         UsbMass->Transport->CleanUp (UsbMass->Context);
1095       }
1096       FreePool (UsbMass);
1097     }
1098   }
1099
1100   if (!AllChildrenStopped) {
1101     return EFI_DEVICE_ERROR;
1102   }
1103
1104   DEBUG ((EFI_D_INFO, "Success to stop all %d multi-lun children handles\n", (UINT32) NumberOfChildren));
1105   return EFI_SUCCESS;
1106 }
1107
1108 /**
1109   Entrypoint of USB Mass Storage Driver.
1110
1111   This function is the entrypoint of USB Mass Storage Driver. It installs Driver Binding
1112   Protocol together with Component Name Protocols.
1113
1114   @param  ImageHandle       The firmware allocated handle for the EFI image.
1115   @param  SystemTable       A pointer to the EFI System Table.
1116
1117   @retval EFI_SUCCESS       The entry point is executed successfully.
1118
1119 **/
1120 EFI_STATUS
1121 EFIAPI
1122 USBMassStorageEntryPoint (
1123   IN EFI_HANDLE               ImageHandle,
1124   IN EFI_SYSTEM_TABLE         *SystemTable
1125   )
1126 {
1127   EFI_STATUS  Status;
1128
1129   //
1130   // Install driver binding protocol
1131   //
1132   Status = EfiLibInstallDriverBindingComponentName2 (
1133              ImageHandle,
1134              SystemTable,
1135              &gUSBMassDriverBinding,
1136              ImageHandle,
1137              &gUsbMassStorageComponentName,
1138              &gUsbMassStorageComponentName2
1139              );
1140   ASSERT_EFI_ERROR (Status);
1141
1142   return EFI_SUCCESS;
1143 }