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
   8 All rights reserved. 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     gBS->FreePool (UsbCbi);
 150   }
 151
 152   return EFI_SUCCESS;
 153
 154 ON_ERROR:
 155   gBS->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     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiSendCommand (%r)\n",Status));
 461     return Status;
 462   }
 463
 464   //
 465   // Transfer the data. Return this status if no interrupt endpoint
 466   // is used to report the transfer status.
 467   //
 468   TransLen = (UINTN) DataLen;
 469
 470   Status   = UsbCbiDataTransfer (UsbCbi, DataDir, Data, &TransLen, Timeout);
 471   if (UsbCbi->InterruptEndpoint == NULL) {
 472     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiDataTransfer (%r)\n",Status));
 473     return Status;
 474   }
 475
 476   //
 477   // Get the status. If it succeeds, interpret the result.
 478   //
 479   Status = UsbCbiGetStatus (UsbCbi, Timeout, &Result);
 480   if (EFI_ERROR (Status)) {
 481     DEBUG ((EFI_D_ERROR, "UsbCbiExecCommand: UsbCbiGetStatus (%r)\n",Status));
 482     return Status;
 483   }
 484
 485   if (UsbCbi->Interface.InterfaceSubClass == USB_MASS_STORE_UFI) {
 486     //
 487     // For UFI device, ASC and ASCQ are returned.
 488     //
 489     if (Result.Type != 0) {
 490       *CmdStatus = USB_MASS_CMD_FAIL;
 491     }
 492
 493   } else {
 494     //
 495     // Check page 27, CBI spec 1.1 for vaious reture status.
 496     //
 497     switch (Result.Value & 0x03) {
 498     case 0x00:
 499       //
 500       // Pass
 501       //
 502       *CmdStatus = USB_MASS_CMD_SUCCESS;
 503       break;
 504
 505     case 0x02:
 506       //
 507       // Phase Error, response with reset.
 508       // No break here to fall through to "Fail".
 509       //
 510       UsbCbiResetDevice (UsbCbi, FALSE);
 511
 512     case 0x01:
 513       //
 514       // Fail
 515       //
 516       *CmdStatus = USB_MASS_CMD_FAIL;
 517       break;
 518
 519     case 0x03:
 520       //
 521       // Persistent Fail. Need to send REQUEST SENSE.
 522       //
 523       *CmdStatus = USB_MASS_CMD_PERSISTENT;
 524       break;
 525     }
 526   }
 527
 528   return EFI_SUCCESS;
 529 }
 530
 531
 532 /**
 533   Reset the USB mass storage device by CBI protocol.
 534
 535   This function resets the USB mass storage device by CBI protocol.
 536   The reset is defined as a non-data command. Don't use UsbCbiExecCommand
 537   to send the command to device because that may introduce recursive loop.
 538
 539   @param  Context               The USB CBI protocol
 540   @param  ExtendedVerification  The flag controlling the rule of reset.
 541                                 Not used here.
 542
 543   @retval EFI_SUCCESS           The device is reset.
 544   @retval Others                Failed to reset the device.
 545
 546 **/
 547 EFI_STATUS
 548 UsbCbiResetDevice (
 549   IN  VOID                    *Context,
 550   IN  BOOLEAN                  ExtendedVerification
 551   )
 552 {
 553   UINT8                     ResetCmd[USB_CBI_RESET_CMD_LEN];
 554   USB_CBI_PROTOCOL          *UsbCbi;
 555   USB_CBI_STATUS            Result;
 556   EFI_STATUS                Status;
 557   UINT32                    Timeout;
 558
 559   UsbCbi = (USB_CBI_PROTOCOL *) Context;
 560
 561   //
 562   // Fill in the reset command.
 563   //
 564   SetMem (ResetCmd, USB_CBI_RESET_CMD_LEN, 0xFF);
 565
 566   ResetCmd[0] = 0x1D;
 567   ResetCmd[1] = 0x04;
 568   Timeout     = USB_CBI_RESET_DEVICE_TIMEOUT / USB_MASS_1_MILLISECOND;
 569
 570   //
 571   // Send the command to the device. Don't use UsbCbiExecCommand here.
 572   //
 573   Status = UsbCbiSendCommand (UsbCbi, ResetCmd, USB_CBI_RESET_CMD_LEN, Timeout);
 574   if (EFI_ERROR (Status)) {
 575     return Status;
 576   }
 577
 578   //
 579   // Just retrieve the status and ignore that. Then stall
 580   // 50ms to wait for it to complete.
 581   //
 582   UsbCbiGetStatus (UsbCbi, Timeout, &Result);
 583   gBS->Stall (USB_CBI_RESET_DEVICE_STALL);
 584
 585   //
 586   // Clear the Bulk-In and Bulk-Out stall condition and init data toggle.
 587   //
 588   UsbClearEndpointStall (UsbCbi->UsbIo, UsbCbi->BulkInEndpoint->EndpointAddress);
 589   UsbClearEndpointStall (UsbCbi->UsbIo, UsbCbi->BulkOutEndpoint->EndpointAddress);
 590
 591   return Status;
 592 }
 593
 594
 595 /**
 596   Clean up the CBI protocol's resource.
 597
 598   @param  Context               The instance of CBI protocol.
 599
 600   @retval EFI_SUCCESS           The resource is cleaned up.
 601
 602 **/
 603 EFI_STATUS
 604 UsbCbiCleanUp (
 605   IN  VOID                   *Context
 606   )
 607 {
 608   gBS->FreePool (Context);
 609   return EFI_SUCCESS;
 610 }