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