MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassCbi.c

   1 /** @file
   2   Implementation of the USB mass storage Control/Bulk/Interrupt transport,
   3   according to USB Mass Storage Class Control/Bulk/Interrupt (CBI) Transport, Revision 1.1.
   4   Notice: it is being obsoleted by the standard body in favor of the BOT
   5   (Bulk-Only Transport).
   6
   7 Copyright (c) 2007 - 2008, Intel Corporation. All rights reserved.<BR>
   8 This program and the accompanying materials
   9 are licensed and made available under the terms and conditions of the BSD License
  10 which accompanies this distribution.  The full text of the license may be found at
  11 http://opensource.org/licenses/bsd-license.php
  12
  13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #include "UsbMassBoot.h"
  19 #include "UsbMassCbi.h"
  20
  21 //
  22 // Definition of USB CBI0 Transport Protocol
  23 //
  24 USB_MASS_TRANSPORT mUsbCbi0Transport = {
  25   USB_MASS_STORE_CBI0,
  26   UsbCbiInit,
  27   UsbCbiExecCommand,
  28   UsbCbiResetDevice,
  29   NULL,
  30   UsbCbiCleanUp
  31 };
  32
  33 //
  34 // Definition of USB CBI1 Transport Protocol
  35 //
  36 USB_MASS_TRANSPORT mUsbCbi1Transport = {
  37   USB_MASS_STORE_CBI1,
  38   UsbCbiInit,
  39   UsbCbiExecCommand,
  40   UsbCbiResetDevice,
  41   NULL,
  42   UsbCbiCleanUp
  43 };
  44
  45 /**
  46   Initializes USB CBI protocol.
  47
  48   This function initializes the USB mass storage class CBI protocol.
  49   It will save its context which is a USB_CBI_PROTOCOL structure
  50   in the Context if Context isn't NULL.
  51
  52   @param  UsbIo                 The USB I/O Protocol instance
  53   @param  Context               The buffer to save the context to
  54
  55   @retval EFI_SUCCESS           The device is successfully initialized.
  56   @retval EFI_UNSUPPORTED       The transport protocol doesn't support the device.
  57   @retval Other                 The USB CBI initialization fails.
  58
  59 **/
  60 EFI_STATUS
  61 UsbCbiInit (
  62   IN  EFI_USB_IO_PROTOCOL   *UsbIo,
  63   OUT VOID                  **Context       OPTIONAL
  64   )
  65 {
  66   USB_CBI_PROTOCOL              *UsbCbi;
  67   EFI_USB_INTERFACE_DESCRIPTOR  *Interface;
  68   EFI_USB_ENDPOINT_DESCRIPTOR   EndPoint;
  69   EFI_STATUS                    Status;
  70   UINT8                         Index;
  71
  72   //
  73   // Allocate the CBI context for USB_CBI_PROTOCOL and 3 endpoint descriptors.
  74   //
  75   UsbCbi = AllocateZeroPool (
  76              sizeof (USB_CBI_PROTOCOL) + 3 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)
  77              );
  78   ASSERT (UsbCbi != NULL);
  79
  80   UsbCbi->UsbIo = UsbIo;
  81
  82   //
  83   // Get the interface descriptor and validate that it
  84   // is a USB Mass Storage CBI interface.
  85   //
  86   Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &UsbCbi->Interface);
  87   if (EFI_ERROR (Status)) {
  88     goto ON_ERROR;
  89   }
  90
  91   Interface = &UsbCbi->Interface;
  92   if ((Interface->InterfaceProtocol != USB_MASS_STORE_CBI0)
  93       && (Interface->InterfaceProtocol != USB_MASS_STORE_CBI1)) {
  94     Status = EFI_UNSUPPORTED;
  95     goto ON_ERROR;
  96   }
  97
  98   //
  99   // Locate and save the bulk-in, bulk-out, and interrupt endpoint
 100   //
 101   for (Index = 0; Index < Interface->NumEndpoints; Index++) {
 102     Status = UsbIo->UsbGetEndpointDescriptor (UsbIo, Index, &EndPoint);
 103     if (EFI_ERROR (Status)) {
 104       continue;
 105     }
 106
 107     if (USB_IS_BULK_ENDPOINT (EndPoint.Attributes)) {
 108       //
 109       // Use the first Bulk-In and Bulk-Out endpoints
 110       //
 111       if (USB_IS_IN_ENDPOINT (EndPoint.EndpointAddress) &&
 112          (UsbCbi->BulkInEndpoint == NULL)) {
 113
 114         UsbCbi->BulkInEndpoint  = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbCbi + 1);
 115         CopyMem(UsbCbi->BulkInEndpoint, &EndPoint, sizeof (EndPoint));;
 116       }
 117
 118       if (USB_IS_OUT_ENDPOINT (EndPoint.EndpointAddress) &&
 119          (UsbCbi->BulkOutEndpoint == NULL)) {
 120
 121         UsbCbi->BulkOutEndpoint   = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbCbi + 1) + 1;
 122         CopyMem(UsbCbi->BulkOutEndpoint, &EndPoint, sizeof (EndPoint));
 123       }
 124     } else if (USB_IS_INTERRUPT_ENDPOINT (EndPoint.Attributes)) {
 125       //
 126       // Use the first interrupt endpoint if it is CBI0
 127       //
 128       if ((Interface->InterfaceProtocol == USB_MASS_STORE_CBI0) &&
 129           (UsbCbi->InterruptEndpoint == NULL)) {
 130
 131         UsbCbi->InterruptEndpoint   = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbCbi + 1) + 2;
 132         CopyMem(UsbCbi->InterruptEndpoint, &EndPoint, sizeof (EndPoint));
 133       }
 134     }
 135   }
 136
 137   if ((UsbCbi->BulkInEndpoint == NULL) || (UsbCbi->BulkOutEndpoint == NULL)) {
 138     Status = EFI_UNSUPPORTED;
 139     goto ON_ERROR;
 140   }
 141   if ((Interface->InterfaceProtocol == USB_MASS_STORE_CBI0) && (UsbCbi->InterruptEndpoint == NULL)) {
 142     Status = EFI_UNSUPPORTED;
 143     goto ON_ERROR;
 144   }
 145
 146   if (Context != NULL) {
 147     *Context = UsbCbi;
 148   } else {
 149     FreePool (UsbCbi);
 150   }
 151
 152   return EFI_SUCCESS;
 153
 154 ON_ERROR:
 155   FreePool (UsbCbi);
 156   return Status;
 157 }
 158
 159 /**
 160   Send the command to the device using class specific control transfer.
 161
 162   This function sends command to the device using class specific control transfer.
 163   The CBI contains three phases: Command, Data, and Status. This is Command phase.
 164
 165   @param  UsbCbi                The USB CBI protocol
 166   @param  Cmd                   The high level command to transfer to device
 167   @param  CmdLen                The length of the command
 168   @param  Timeout               The time to wait the command to finish
 169
 170   @retval EFI_SUCCESS           The command is sent to the device.
 171   @retval Others                The command failed to transfer to device
 172
 173 **/
 174 EFI_STATUS
 175 UsbCbiSendCommand (
 176   IN USB_CBI_PROTOCOL       *UsbCbi,
 177   IN UINT8                  *Cmd,
 178   IN UINT8                  CmdLen,
 179   IN UINT32                 Timeout
 180   )
 181 {
 182   EFI_USB_DEVICE_REQUEST  Request;
 183   EFI_STATUS              Status;
 184   UINT32                  TransStatus;
 185   UINTN                   DataLen;
 186   INTN                    Retry;
 187
 188   //
 189   // Fill in the device request, CBI use the "Accept Device-Specific
 190   // Cmd" (ADSC) class specific request to send commands.
 191   //
 192   Request.RequestType = 0x21;
 193   Request.Request     = 0;
 194   Request.Value       = 0;
 195   Request.Index       = UsbCbi->Interface.InterfaceNumber;
 196   Request.Length      = CmdLen;
 197
 198   Status              = EFI_SUCCESS;
 199   Timeout             = Timeout / USB_MASS_1_MILLISECOND;
 200
 201   for (Retry = 0; Retry < USB_CBI_MAX_RETRY; Retry++) {
 202     //
 203     // Use USB I/O Protocol to send the command to the device
 204     //
 205     TransStatus = 0;
 206     DataLen     = CmdLen;
 207
 208     Status = UsbCbi->UsbIo->UsbControlTransfer (
 209                               UsbCbi->UsbIo,
 210                               &Request,
 211                               EfiUsbDataOut,
 212                               Timeout,
 213                               Cmd,
 214                               DataLen,
 215                               &TransStatus
 216                               );
 217     //
 218     // The device can fail the command by STALL the control endpoint.
 219     // It can delay the command by NAK the data or status stage, this
 220     // is a "class-specific exemption to the USB specification". Retry
 221     // if the command is NAKed.
 222     //
 223     if (EFI_ERROR (Status) && (TransStatus == EFI_USB_ERR_NAK)) {
 224       continue;
 225     }
 226
 227     break;
 228   }
 229
 230   return Status;
 231 }
 232
 233
 234 /**
 235   Transfer data between the device and host.
 236
 237   This function transfers data between the device and host.
 238   The CBI contains three phases: Command, Data, and Status. This is Data phase.
 239
 240   @param  UsbCbi                The USB CBI device
 241   @param  DataDir               The direction of the data transfer
 242   @param  Data                  The buffer to hold the data for input or output.
 243   @param  TransLen              On input, the expected transfer length.
 244                                 On output, the length of data actually transferred.
 245   @param  Timeout               The time to wait for the command to execute
 246
 247   @retval EFI_SUCCESS           The data transferred successfully.
 248   @retval EFI_SUCCESS           No data to transfer
 249   @retval Others                Failed to transfer all the data
 250
 251 **/
 252 EFI_STATUS
 253 UsbCbiDataTransfer (
 254   IN USB_CBI_PROTOCOL         *UsbCbi,
 255   IN EFI_USB_DATA_DIRECTION   DataDir,
 256   IN OUT UINT8                *Data,
 257   IN OUT UINTN                *TransLen,
 258   IN UINT32                   Timeout
 259   )
 260 {
 261   EFI_USB_ENDPOINT_DESCRIPTOR *Endpoint;
 262   EFI_STATUS                  Status;
 263   UINT32                      TransStatus;
 264   UINTN                       Remain;
 265   UINTN                       Increment;
 266   UINT8                       *Next;
 267   UINTN                       Retry;
 268
 269   //
 270   // If no data to transfer, just return EFI_SUCCESS.
 271   //
 272   if ((DataDir == EfiUsbNoData) || (*TransLen == 0)) {
 273     return EFI_SUCCESS;
 274   }
 275
 276   //
 277   // Select the endpoint then issue the transfer
 278   //
 279   if (DataDir == EfiUsbDataIn) {
 280     Endpoint = UsbCbi->BulkInEndpoint;
 281   } else {
 282     Endpoint = UsbCbi->BulkOutEndpoint;
 283   }
 284
 285   Next    = Data;
 286   Remain  = *TransLen;
 287   Retry   = 0;
 288   Status  = EFI_SUCCESS;
 289   Timeout = Timeout / USB_MASS_1_MILLISECOND;
 290
 291   //
 292   // Transfer the data with a loop. The length of data transferred once is restricted.
 293   //
 294   while (Remain > 0) {
 295     TransStatus = 0;
 296
 297     if (Remain > (UINTN) USB_CBI_MAX_PACKET_NUM * Endpoint->MaxPacketSize) {
 298       Increment = USB_CBI_MAX_PACKET_NUM * Endpoint->MaxPacketSize;
 299     } else {
 300       Increment = Remain;
 301     }
 302
 303     Status = UsbCbi->UsbIo->UsbBulkTransfer (
 304                               UsbCbi->UsbIo,
 305                               Endpoint->EndpointAddress,
 306                               Next,
 307                               &Increment,
 308                               Timeout,
 309                               &TransStatus
 310                               );
 311     if (EFI_ERROR (Status)) {
 312       if (TransStatus == EFI_USB_ERR_NAK) {
 313         //
 314         // The device can NAK the host if either the data/buffer isn't
 315         // aviable or the command is in-progress.
 316         // If data are partially transferred, we just ignore NAK and continue.
 317         // If all data have been transferred and status is NAK, then we retry for several times.
 318         // If retry exceeds the USB_CBI_MAX_RETRY, then return error status.
 319         //
 320         if (Increment == 0) {
 321           if (++Retry > USB_CBI_MAX_RETRY) {
 322             goto ON_EXIT;
 323           }
 324         } else {
 325           Next   += Increment;
 326           Remain -= Increment;
 327           Retry   = 0;
 328         }
 329
 330         continue;
 331       }
 332
 333       //
 334       // The device can fail the command by STALL the bulk endpoint.
 335       // Clear the stall if that is the case.
 336       //
 337       if (TransStatus == EFI_USB_ERR_STALL) {
 338         UsbClearEndpointStall (UsbCbi->UsbIo, Endpoint->EndpointAddress);
 339       }
 340
 341       goto ON_EXIT;
 342     }
 343
 344     Next += Increment;
 345     Remain -= Increment;
 346   }
 347
 348 ON_EXIT:
 349   *TransLen -= Remain;
 350   return Status;
 351 }
 352
 353
 354 /**
 355   Gets the result of high level command execution from interrupt endpoint.
 356
 357   This function returns the USB transfer status, and put the high level
 358   command execution result in Result.
 359   The CBI contains three phases: Command, Data, and Status. This is Status phase.
 360
 361   @param  UsbCbi                The USB CBI protocol
 362   @param  Timeout               The time to wait for the command to execute
 363   @param  Result                The result of the command execution.
 364
 365   @retval EFI_SUCCESS           The high level command execution result is
 366                                 retrieved in Result.
 367   @retval Others                Failed to retrieve the result.
 368
 369 **/
 370 EFI_STATUS
 371 UsbCbiGetStatus (
 372   IN  USB_CBI_PROTOCOL        *UsbCbi,
 373   IN  UINT32                  Timeout,
 374   OUT USB_CBI_STATUS          *Result
 375   )
 376 {
 377   UINTN                     Len;
 378   UINT8                     Endpoint;
 379   EFI_STATUS                Status;
 380   UINT32                    TransStatus;
 381   INTN                      Retry;
 382
 383   Endpoint  = UsbCbi->InterruptEndpoint->EndpointAddress;
 384   Status    = EFI_SUCCESS;
 385   Timeout   = Timeout / USB_MASS_1_MILLISECOND;
 386
 387   //
 388   // Attemp to the read the result from interrupt endpoint
 389   //
 390   for (Retry = 0; Retry < USB_CBI_MAX_RETRY; Retry++) {
 391     TransStatus = 0;
 392     Len         = sizeof (USB_CBI_STATUS);
 393
 394     Status = UsbCbi->UsbIo->UsbSyncInterruptTransfer (
 395                               UsbCbi->UsbIo,
 396                               Endpoint,
 397                               Result,
 398                               &Len,
 399                               Timeout,
 400                               &TransStatus
 401                               );
 402     //
 403     // The CBI can NAK the interrupt endpoint if the command is in-progress.
 404     //
 405     if (EFI_ERROR (Status) && (TransStatus == EFI_USB_ERR_NAK)) {
 406       continue;
 407     }
 408
 409     break;
 410   }
 411
 412   return Status;
 413 }
 414
 415
 416 /**
 417   Execute USB mass storage command through the CBI0/CBI1 transport protocol.
 418
 419   @param  Context               The USB CBI Protocol.
 420   @param  Cmd                   The command to transfer to device
 421   @param  CmdLen                The length of the command
 422   @param  DataDir               The direction of data transfer
 423   @param  Data                  The buffer to hold the data
 424   @param  DataLen               The length of the buffer
 425   @param  Lun                   Should be 0, this field for bot only
 426   @param  Timeout               The time to wait
 427   @param  CmdStatus             The result of the command execution
 428
 429   @retval EFI_SUCCESS           The command is executed successfully.
 430   @retval Other                 Failed to execute the command
 431
 432 **/
 433 EFI_STATUS
 434 UsbCbiExecCommand (
 435   IN  VOID                    *Context,
 436   IN  VOID                    *Cmd,
 437   IN  UINT8                   CmdLen,
 438   IN  EFI_USB_DATA_DIRECTION  DataDir,
 439   IN  VOID                    *Data,
 440   IN  UINT32                  DataLen,
 441   IN  UINT8                   Lun,
 442   IN  UINT32                  Timeout,
 443   OUT UINT32                  *CmdStatus
 444   )
 445 {
 446   USB_CBI_PROTOCOL          *UsbCbi;
 447   USB_CBI_STATUS            Result;
 448   EFI_STATUS                Status;
 449   UINTN                     TransLen;
 450
 451   *CmdStatus  = USB_MASS_CMD_SUCCESS;
 452   UsbCbi      = (USB_CBI_PROTOCOL *) Context;
 453
 454   //
 455   // Send the command to the device. Return immediately if device
 456   // rejects the command.
 457   //
 458   Status = UsbCbiSendCommand (UsbCbi, Cmd, CmdLen, Timeout);
 459   if (EFI_ERROR (Status)) {
 460     gBS->Stall(10 * USB_MASS_1_MILLISECOND);
 461     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiSendCommand (%r)\n",Status));
 462     return Status;
 463   }
 464
 465   //
 466   // Transfer the data. Return this status if no interrupt endpoint
 467   // is used to report the transfer status.
 468   //
 469   TransLen = (UINTN) DataLen;
 470
 471   Status   = UsbCbiDataTransfer (UsbCbi, DataDir, Data, &TransLen, Timeout);
 472   if (UsbCbi->InterruptEndpoint == NULL) {
 473     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiDataTransfer (%r)\n",Status));
 474     return Status;
 475   }
 476
 477   //
 478   // Get the status. If it succeeds, interpret the result.
 479   //
 480   Status = UsbCbiGetStatus (UsbCbi, Timeout, &Result);
 481   if (EFI_ERROR (Status)) {
 482     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiGetStatus (%r)\n",Status));
 483     return Status;
 484   }
 485
 486   if (UsbCbi->Interface.InterfaceSubClass == USB_MASS_STORE_UFI) {
 487     //
 488     // For UFI device, ASC and ASCQ are returned.
 489     //
 490     // Do not set the USB_MASS_CMD_FAIL for a request sense command
 491     // as a bad result type doesn't mean a cmd failure
 492     //
 493     if (Result.Type != 0 && *(UINT8*)Cmd != 0x03) {
 494       *CmdStatus = USB_MASS_CMD_FAIL;
 495     }
 496   } else {
 497     //
 498     // Check page 27, CBI spec 1.1 for vaious reture status.
 499     //
 500     switch (Result.Value & 0x03) {
 501     case 0x00:
 502       //
 503       // Pass
 504       //
 505       *CmdStatus = USB_MASS_CMD_SUCCESS;
 506       break;
 507
 508     case 0x02:
 509       //
 510       // Phase Error, response with reset.
 511       // No break here to fall through to "Fail".
 512       //
 513       UsbCbiResetDevice (UsbCbi, FALSE);
 514
 515     case 0x01:
 516       //
 517       // Fail
 518       //
 519       *CmdStatus = USB_MASS_CMD_FAIL;
 520       break;
 521
 522     case 0x03:
 523       //
 524       // Persistent Fail. Need to send REQUEST SENSE.
 525       //
 526       *CmdStatus = USB_MASS_CMD_PERSISTENT;
 527       break;
 528     }
 529   }
 530
 531   return EFI_SUCCESS;
 532 }
 533
 534
 535 /**
 536   Reset the USB mass storage device by CBI protocol.
 537
 538   This function resets the USB mass storage device by CBI protocol.
 539   The reset is defined as a non-data command. Don't use UsbCbiExecCommand
 540   to send the command to device because that may introduce recursive loop.
 541
 542   @param  Context               The USB CBI protocol
 543   @param  ExtendedVerification  The flag controlling the rule of reset.
 544                                 Not used here.
 545
 546   @retval EFI_SUCCESS           The device is reset.
 547   @retval Others                Failed to reset the device.
 548
 549 **/
 550 EFI_STATUS
 551 UsbCbiResetDevice (
 552   IN  VOID                    *Context,
 553   IN  BOOLEAN                  ExtendedVerification
 554   )
 555 {
 556   UINT8                     ResetCmd[USB_CBI_RESET_CMD_LEN];
 557   USB_CBI_PROTOCOL          *UsbCbi;
 558   USB_CBI_STATUS            Result;
 559   EFI_STATUS                Status;
 560   UINT32                    Timeout;
 561
 562   UsbCbi = (USB_CBI_PROTOCOL *) Context;
 563
 564   //
 565   // Fill in the reset command.
 566   //
 567   SetMem (ResetCmd, USB_CBI_RESET_CMD_LEN, 0xFF);
 568
 569   ResetCmd[0] = 0x1D;
 570   ResetCmd[1] = 0x04;
 571   Timeout     = USB_CBI_RESET_DEVICE_TIMEOUT / USB_MASS_1_MILLISECOND;
 572
 573   //
 574   // Send the command to the device. Don't use UsbCbiExecCommand here.
 575   //
 576   Status = UsbCbiSendCommand (UsbCbi, ResetCmd, USB_CBI_RESET_CMD_LEN, Timeout);
 577   if (EFI_ERROR (Status)) {
 578     return Status;
 579   }
 580
 581   //
 582   // Just retrieve the status and ignore that. Then stall
 583   // 50ms to wait for it to complete.
 584   //
 585   UsbCbiGetStatus (UsbCbi, Timeout, &Result);
 586   gBS->Stall (USB_CBI_RESET_DEVICE_STALL);
 587
 588   //
 589   // Clear the Bulk-In and Bulk-Out stall condition and init data toggle.
 590   //
 591   UsbClearEndpointStall (UsbCbi->UsbIo, UsbCbi->BulkInEndpoint->EndpointAddress);
 592   UsbClearEndpointStall (UsbCbi->UsbIo, UsbCbi->BulkOutEndpoint->EndpointAddress);
 593
 594   return Status;
 595 }
 596
 597
 598 /**
 599   Clean up the CBI protocol's resource.
 600
 601   @param  Context               The instance of CBI protocol.
 602
 603   @retval EFI_SUCCESS           The resource is cleaned up.
 604
 605 **/
 606 EFI_STATUS
 607 UsbCbiCleanUp (
 608   IN  VOID                   *Context
 609   )
 610 {
 611   FreePool (Context);
 612   return EFI_SUCCESS;
 613 }