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