MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c

   1 /** @file
   2   Implementation of the USB mass storage Bulk-Only Transport protocol,
   3   according to USB Mass Storage Class Bulk-Only Transport, Revision 1.0.
   4
   5 Copyright (c) 2007 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "UsbMassBoot.h"
  17 #include "UsbMassBot.h"
  18
  19 //
  20 // Definition of USB BOT Transport Protocol
  21 //
  22 USB_MASS_TRANSPORT mUsbBotTransport = {
  23   USB_MASS_STORE_BOT,
  24   UsbBotInit,
  25   UsbBotExecCommand,
  26   UsbBotResetDevice,
  27   UsbBotGetMaxLun,
  28   UsbBotCleanUp
  29 };
  30
  31 /**
  32   Initializes USB BOT protocol.
  33
  34   This function initializes the USB mass storage class BOT protocol.
  35   It will save its context which is a USB_BOT_PROTOCOL structure
  36   in the Context if Context isn't NULL.
  37
  38   @param  UsbIo                 The USB I/O Protocol instance
  39   @param  Context               The buffer to save the context to
  40
  41   @retval EFI_SUCCESS           The device is successfully initialized.
  42   @retval EFI_UNSUPPORTED       The transport protocol doesn't support the device.
  43   @retval Other                 The USB BOT initialization fails.
  44
  45 **/
  46 EFI_STATUS
  47 UsbBotInit (
  48   IN  EFI_USB_IO_PROTOCOL       *UsbIo,
  49   OUT VOID                      **Context OPTIONAL
  50   )
  51 {
  52   USB_BOT_PROTOCOL              *UsbBot;
  53   EFI_USB_INTERFACE_DESCRIPTOR  *Interface;
  54   EFI_USB_ENDPOINT_DESCRIPTOR   EndPoint;
  55   EFI_STATUS                    Status;
  56   UINT8                         Index;
  57
  58   //
  59   // Allocate the BOT context for USB_BOT_PROTOCOL and two endpoint descriptors.
  60   //
  61   UsbBot = AllocateZeroPool (sizeof (USB_BOT_PROTOCOL) + 2 * sizeof (EFI_USB_ENDPOINT_DESCRIPTOR));
  62   ASSERT (UsbBot != NULL);
  63
  64   UsbBot->UsbIo = UsbIo;
  65
  66   //
  67   // Get the interface descriptor and validate that it
  68   // is a USB Mass Storage BOT interface.
  69   //
  70   Status = UsbIo->UsbGetInterfaceDescriptor (UsbIo, &UsbBot->Interface);
  71
  72   if (EFI_ERROR (Status)) {
  73     goto ON_ERROR;
  74   }
  75
  76   Interface = &UsbBot->Interface;
  77
  78   if (Interface->InterfaceProtocol != USB_MASS_STORE_BOT) {
  79     Status = EFI_UNSUPPORTED;
  80     goto ON_ERROR;
  81   }
  82
  83   //
  84   // Locate and save the first bulk-in and bulk-out endpoint
  85   //
  86   for (Index = 0; Index < Interface->NumEndpoints; Index++) {
  87     Status = UsbIo->UsbGetEndpointDescriptor (UsbIo, Index, &EndPoint);
  88
  89     if (EFI_ERROR (Status) || !USB_IS_BULK_ENDPOINT (EndPoint.Attributes)) {
  90       continue;
  91     }
  92
  93     if (USB_IS_IN_ENDPOINT (EndPoint.EndpointAddress) &&
  94        (UsbBot->BulkInEndpoint == NULL)) {
  95
  96       UsbBot->BulkInEndpoint  = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbBot + 1);
  97       CopyMem(UsbBot->BulkInEndpoint, &EndPoint, sizeof (EndPoint));
  98     }
  99
 100     if (USB_IS_OUT_ENDPOINT (EndPoint.EndpointAddress) &&
 101        (UsbBot->BulkOutEndpoint == NULL)) {
 102
 103       UsbBot->BulkOutEndpoint   = (EFI_USB_ENDPOINT_DESCRIPTOR *) (UsbBot + 1) + 1;
 104       CopyMem (UsbBot->BulkOutEndpoint, &EndPoint, sizeof(EndPoint));
 105     }
 106   }
 107
 108   //
 109   // If bulk-in or bulk-out endpoint is not found, report error.
 110   //
 111   if ((UsbBot->BulkInEndpoint == NULL) || (UsbBot->BulkOutEndpoint == NULL)) {
 112     Status = EFI_UNSUPPORTED;
 113     goto ON_ERROR;
 114   }
 115
 116   //
 117   // The USB BOT protocol uses CBWTag to match the CBW and CSW.
 118   //
 119   UsbBot->CbwTag = 0x01;
 120
 121   if (Context != NULL) {
 122     *Context = UsbBot;
 123   } else {
 124     FreePool (UsbBot);
 125   }
 126
 127   return EFI_SUCCESS;
 128
 129 ON_ERROR:
 130   FreePool (UsbBot);
 131   return Status;
 132 }
 133
 134 /**
 135   Send the command to the device using Bulk-Out endpoint.
 136
 137   This function sends the command to the device using Bulk-Out endpoint.
 138   BOT transfer is composed of three phases: Command, Data, and Status.
 139   This is the Command phase.
 140
 141   @param  UsbBot                The USB BOT device
 142   @param  Cmd                   The command to transfer to device
 143   @param  CmdLen                The length of the command
 144   @param  DataDir               The direction of the data
 145   @param  TransLen              The expected length of the data
 146   @param  Lun                   The number of logic unit
 147
 148   @retval EFI_SUCCESS           The command is sent to the device.
 149   @retval EFI_NOT_READY         The device return NAK to the transfer
 150   @retval Others                Failed to send the command to device
 151
 152 **/
 153 EFI_STATUS
 154 UsbBotSendCommand (
 155   IN USB_BOT_PROTOCOL         *UsbBot,
 156   IN UINT8                    *Cmd,
 157   IN UINT8                    CmdLen,
 158   IN EFI_USB_DATA_DIRECTION   DataDir,
 159   IN UINT32                   TransLen,
 160   IN UINT8                    Lun
 161   )
 162 {
 163   USB_BOT_CBW               Cbw;
 164   EFI_STATUS                Status;
 165   UINT32                    Result;
 166   UINTN                     DataLen;
 167   UINTN                     Timeout;
 168
 169   ASSERT ((CmdLen > 0) && (CmdLen <= USB_BOT_MAX_CMDLEN));
 170
 171   //
 172   // Fill in the Command Block Wrapper.
 173   //
 174   Cbw.Signature = USB_BOT_CBW_SIGNATURE;
 175   Cbw.Tag       = UsbBot->CbwTag;
 176   Cbw.DataLen   = TransLen;
 177   Cbw.Flag      = (UINT8) ((DataDir == EfiUsbDataIn) ? BIT7 : 0);
 178   Cbw.Lun       = Lun;
 179   Cbw.CmdLen    = CmdLen;
 180
 181   ZeroMem (Cbw.CmdBlock, USB_BOT_MAX_CMDLEN);
 182   CopyMem (Cbw.CmdBlock, Cmd, CmdLen);
 183
 184   Result  = 0;
 185   DataLen = sizeof (USB_BOT_CBW);
 186   Timeout = USB_BOT_SEND_CBW_TIMEOUT / USB_MASS_1_MILLISECOND;
 187
 188   //
 189   // Use USB I/O Protocol to send the Command Block Wrapper to the device.
 190   //
 191   Status = UsbBot->UsbIo->UsbBulkTransfer (
 192                             UsbBot->UsbIo,
 193                             UsbBot->BulkOutEndpoint->EndpointAddress,
 194                             &Cbw,
 195                             &DataLen,
 196                             Timeout,
 197                             &Result
 198                             );
 199   if (EFI_ERROR (Status)) {
 200     if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL) && DataDir == EfiUsbDataOut) {
 201       //
 202       // Respond to Bulk-Out endpoint stall with a Reset Recovery,
 203       // according to section 5.3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
 204       //
 205       UsbBotResetDevice (UsbBot, FALSE);
 206     } else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
 207       Status = EFI_NOT_READY;
 208     }
 209   }
 210
 211   return Status;
 212 }
 213
 214
 215 /**
 216   Transfer the data between the device and host.
 217
 218   This function transfers the data between the device and host.
 219   BOT transfer is composed of three phases: Command, Data, and Status.
 220   This is the Data phase.
 221
 222   @param  UsbBot                The USB BOT device
 223   @param  DataDir               The direction of the data
 224   @param  Data                  The buffer to hold data
 225   @param  TransLen              The expected length of the data
 226   @param  Timeout               The time to wait the command to complete
 227
 228   @retval EFI_SUCCESS           The data is transferred
 229   @retval EFI_SUCCESS           No data to transfer
 230   @retval EFI_NOT_READY         The device return NAK to the transfer
 231   @retval Others                Failed to transfer data
 232
 233 **/
 234 EFI_STATUS
 235 UsbBotDataTransfer (
 236   IN USB_BOT_PROTOCOL         *UsbBot,
 237   IN EFI_USB_DATA_DIRECTION   DataDir,
 238   IN OUT UINT8                *Data,
 239   IN OUT UINTN                *TransLen,
 240   IN UINT32                   Timeout
 241   )
 242 {
 243   EFI_USB_ENDPOINT_DESCRIPTOR *Endpoint;
 244   EFI_STATUS                  Status;
 245   UINT32                      Result;
 246
 247   //
 248   // If no data to transfer, just return EFI_SUCCESS.
 249   //
 250   if ((DataDir == EfiUsbNoData) || (*TransLen == 0)) {
 251     return EFI_SUCCESS;
 252   }
 253
 254   //
 255   // Select the endpoint then issue the transfer
 256   //
 257   if (DataDir == EfiUsbDataIn) {
 258     Endpoint = UsbBot->BulkInEndpoint;
 259   } else {
 260     Endpoint = UsbBot->BulkOutEndpoint;
 261   }
 262
 263   Result  = 0;
 264   Timeout = Timeout / USB_MASS_1_MILLISECOND;
 265
 266   Status = UsbBot->UsbIo->UsbBulkTransfer (
 267                             UsbBot->UsbIo,
 268                             Endpoint->EndpointAddress,
 269                             Data,
 270                             TransLen,
 271                             Timeout,
 272                             &Result
 273                             );
 274   if (EFI_ERROR (Status)) {
 275     if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
 276       UsbClearEndpointStall (UsbBot->UsbIo, Endpoint->EndpointAddress);
 277     } else if (USB_IS_ERROR (Result, EFI_USB_ERR_NAK)) {
 278       Status = EFI_NOT_READY;
 279     }
 280   }
 281
 282   return Status;
 283 }
 284
 285
 286 /**
 287   Get the command execution status from device.
 288
 289   This function gets the command execution status from device.
 290   BOT transfer is composed of three phases: Command, Data, and Status.
 291   This is the Status phase.
 292
 293   This function returns the transfer status of the BOT's CSW status,
 294   and returns the high level command execution result in Result. So
 295   even if EFI_SUCCESS is returned, the command may still have failed.
 296
 297   @param  UsbBot         The USB BOT device.
 298   @param  TransLen       The expected length of the data.
 299   @param  CmdStatus      The result of the command execution.
 300
 301   @retval EFI_SUCCESS    Command execute result is retrieved and in the Result.
 302   @retval Other          Error occurred when trying to get status.
 303
 304 **/
 305 EFI_STATUS
 306 UsbBotGetStatus (
 307   IN  USB_BOT_PROTOCOL      *UsbBot,
 308   IN  UINT32                TransLen,
 309   OUT UINT8                 *CmdStatus
 310   )
 311 {
 312   USB_BOT_CSW               Csw;
 313   UINTN                     Len;
 314   UINT8                     Endpoint;
 315   EFI_STATUS                Status;
 316   UINT32                    Result;
 317   EFI_USB_IO_PROTOCOL       *UsbIo;
 318   UINT32                    Index;
 319   UINTN                     Timeout;
 320
 321   *CmdStatus = USB_BOT_COMMAND_ERROR;
 322   Status     = EFI_DEVICE_ERROR;
 323   Endpoint   = UsbBot->BulkInEndpoint->EndpointAddress;
 324   UsbIo      = UsbBot->UsbIo;
 325   Timeout    = USB_BOT_RECV_CSW_TIMEOUT / USB_MASS_1_MILLISECOND;
 326
 327   for (Index = 0; Index < USB_BOT_RECV_CSW_RETRY; Index++) {
 328     //
 329     // Attemp to the read Command Status Wrapper from bulk in endpoint
 330     //
 331     ZeroMem (&Csw, sizeof (USB_BOT_CSW));
 332     Result = 0;
 333     Len    = sizeof (USB_BOT_CSW);
 334     Status = UsbIo->UsbBulkTransfer (
 335                       UsbIo,
 336                       Endpoint,
 337                       &Csw,
 338                       &Len,
 339                       Timeout,
 340                       &Result
 341                       );
 342     if (EFI_ERROR(Status)) {
 343       if (USB_IS_ERROR (Result, EFI_USB_ERR_STALL)) {
 344         UsbClearEndpointStall (UsbIo, Endpoint);
 345       }
 346       continue;
 347     }
 348
 349     if (Csw.Signature != USB_BOT_CSW_SIGNATURE) {
 350       //
 351       // CSW is invalid, so perform reset recovery
 352       //
 353       Status = UsbBotResetDevice (UsbBot, FALSE);
 354     } else if (Csw.CmdStatus == USB_BOT_COMMAND_ERROR) {
 355       //
 356       // Respond phase error also needs reset recovery
 357       //
 358       Status = UsbBotResetDevice (UsbBot, FALSE);
 359     } else {
 360       *CmdStatus = Csw.CmdStatus;
 361       break;
 362     }
 363   }
 364   //
 365   //The tag is increased even if there is an error.
 366   //
 367   UsbBot->CbwTag++;
 368
 369   return Status;
 370 }
 371
 372
 373 /**
 374   Call the USB Mass Storage Class BOT protocol to issue
 375   the command/data/status circle to execute the commands.
 376
 377   @param  Context               The context of the BOT protocol, that is,
 378                                 USB_BOT_PROTOCOL
 379   @param  Cmd                   The high level command
 380   @param  CmdLen                The command length
 381   @param  DataDir               The direction of the data transfer
 382   @param  Data                  The buffer to hold data
 383   @param  DataLen               The length of the data
 384   @param  Lun                   The number of logic unit
 385   @param  Timeout               The time to wait command
 386   @param  CmdStatus             The result of high level command execution
 387
 388   @retval EFI_SUCCESS           The command is executed successfully.
 389   @retval Other                 Failed to excute command
 390
 391 **/
 392 EFI_STATUS
 393 UsbBotExecCommand (
 394   IN  VOID                    *Context,
 395   IN  VOID                    *Cmd,
 396   IN  UINT8                   CmdLen,
 397   IN  EFI_USB_DATA_DIRECTION  DataDir,
 398   IN  VOID                    *Data,
 399   IN  UINT32                  DataLen,
 400   IN  UINT8                   Lun,
 401   IN  UINT32                  Timeout,
 402   OUT UINT32                  *CmdStatus
 403   )
 404 {
 405   USB_BOT_PROTOCOL          *UsbBot;
 406   EFI_STATUS                Status;
 407   UINTN                     TransLen;
 408   UINT8                     Result;
 409
 410   *CmdStatus  = USB_MASS_CMD_FAIL;
 411   UsbBot      = (USB_BOT_PROTOCOL *) Context;
 412
 413   //
 414   // Send the command to the device. Return immediately if device
 415   // rejects the command.
 416   //
 417   Status = UsbBotSendCommand (UsbBot, Cmd, CmdLen, DataDir, DataLen, Lun);
 418   if (EFI_ERROR (Status)) {
 419     DEBUG ((EFI_D_ERROR, "UsbBotExecCommand: UsbBotSendCommand (%r)\n", Status));
 420     return Status;
 421   }
 422
 423   //
 424   // Transfer the data. Don't return immediately even data transfer
 425   // failed. The host should attempt to receive the CSW no matter
 426   // whether it succeeds or fails.
 427   //
 428   TransLen = (UINTN) DataLen;
 429   UsbBotDataTransfer (UsbBot, DataDir, Data, &TransLen, Timeout);
 430
 431   //
 432   // Get the status, if that succeeds, interpret the result
 433   //
 434   Status = UsbBotGetStatus (UsbBot, DataLen, &Result);
 435   if (EFI_ERROR (Status)) {
 436     DEBUG ((EFI_D_ERROR, "UsbBotExecCommand: UsbBotGetStatus (%r)\n", Status));
 437     return Status;
 438   }
 439
 440   if (Result == 0) {
 441     *CmdStatus = USB_MASS_CMD_SUCCESS;
 442   }
 443
 444   return EFI_SUCCESS;
 445 }
 446
 447
 448 /**
 449   Reset the USB mass storage device by BOT protocol.
 450
 451   @param  Context               The context of the BOT protocol, that is,
 452                                 USB_BOT_PROTOCOL.
 453   @param  ExtendedVerification  If FALSE, just issue Bulk-Only Mass Storage Reset request.
 454                                 If TRUE, additionally reset parent hub port.
 455
 456   @retval EFI_SUCCESS           The device is reset.
 457   @retval Others                Failed to reset the device..
 458
 459 **/
 460 EFI_STATUS
 461 UsbBotResetDevice (
 462   IN  VOID                    *Context,
 463   IN  BOOLEAN                 ExtendedVerification
 464   )
 465 {
 466   USB_BOT_PROTOCOL        *UsbBot;
 467   EFI_USB_DEVICE_REQUEST  Request;
 468   EFI_STATUS              Status;
 469   UINT32                  Result;
 470   UINT32                  Timeout;
 471
 472   UsbBot = (USB_BOT_PROTOCOL *) Context;
 473
 474   if (ExtendedVerification) {
 475     //
 476     // If we need to do strictly reset, reset its parent hub port
 477     //
 478     Status = UsbBot->UsbIo->UsbPortReset (UsbBot->UsbIo);
 479     if (EFI_ERROR (Status)) {
 480       return Status;
 481     }
 482   }
 483
 484   //
 485   // Issue a class specific Bulk-Only Mass Storage Reset request,
 486   // according to section 3.1 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
 487   //
 488   Request.RequestType = 0x21;
 489   Request.Request     = USB_BOT_RESET_REQUEST;
 490   Request.Value       = 0;
 491   Request.Index       = UsbBot->Interface.InterfaceNumber;
 492   Request.Length      = 0;
 493   Timeout             = USB_BOT_RESET_DEVICE_TIMEOUT / USB_MASS_1_MILLISECOND;
 494
 495   Status = UsbBot->UsbIo->UsbControlTransfer (
 496                             UsbBot->UsbIo,
 497                             &Request,
 498                             EfiUsbNoData,
 499                             Timeout,
 500                             NULL,
 501                             0,
 502                             &Result
 503                             );
 504
 505   if (EFI_ERROR (Status)) {
 506     return Status;
 507   }
 508
 509   //
 510   // The device shall NAK the host's request until the reset is
 511   // complete. We can use this to sync the device and host. For
 512   // now just stall 100ms to wait for the device.
 513   //
 514   gBS->Stall (USB_BOT_RESET_DEVICE_STALL);
 515
 516   //
 517   // Clear the Bulk-In and Bulk-Out stall condition.
 518   //
 519   UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkInEndpoint->EndpointAddress);
 520   UsbClearEndpointStall (UsbBot->UsbIo, UsbBot->BulkOutEndpoint->EndpointAddress);
 521
 522   return Status;
 523 }
 524
 525
 526 /**
 527   Get the max LUN (Logical Unit Number) of USB mass storage device.
 528
 529   @param  Context          The context of the BOT protocol, that is, USB_BOT_PROTOCOL
 530   @param  MaxLun           Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and
 531                            LUN1 in all.)
 532
 533   @retval EFI_SUCCESS      Max LUN is got successfully.
 534   @retval Others           Fail to execute this request.
 535
 536 **/
 537 EFI_STATUS
 538 UsbBotGetMaxLun (
 539   IN  VOID                    *Context,
 540   OUT UINT8                   *MaxLun
 541   )
 542 {
 543   USB_BOT_PROTOCOL        *UsbBot;
 544   EFI_USB_DEVICE_REQUEST  Request;
 545   EFI_STATUS              Status;
 546   UINT32                  Result;
 547   UINT32                  Timeout;
 548
 549   ASSERT (Context);
 550
 551   UsbBot = (USB_BOT_PROTOCOL *) Context;
 552
 553   //
 554   // Issue a class specific Bulk-Only Mass Storage get max lun reqest.
 555   // according to section 3.2 of USB Mass Storage Class Bulk-Only Transport Spec, v1.0.
 556   //
 557   Request.RequestType = 0xA1;
 558   Request.Request     = USB_BOT_GETLUN_REQUEST;
 559   Request.Value       = 0;
 560   Request.Index       = UsbBot->Interface.InterfaceNumber;
 561   Request.Length      = 1;
 562   Timeout             = USB_BOT_RESET_DEVICE_TIMEOUT / USB_MASS_1_MILLISECOND;
 563
 564   Status = UsbBot->UsbIo->UsbControlTransfer (
 565                             UsbBot->UsbIo,
 566                             &Request,
 567                             EfiUsbDataIn,
 568                             Timeout,
 569                             (VOID *) MaxLun,
 570                             1,
 571                             &Result
 572                             );
 573
 574   return Status;
 575 }
 576
 577 /**
 578   Clean up the resource used by this BOT protocol.
 579
 580   @param  Context         The context of the BOT protocol, that is, USB_BOT_PROTOCOL.
 581
 582   @retval EFI_SUCCESS     The resource is cleaned up.
 583
 584 **/
 585 EFI_STATUS
 586 UsbBotCleanUp (
 587   IN  VOID                    *Context
 588   )
 589 {
 590   FreePool (Context);
 591   return EFI_SUCCESS;
 592 }
 593