MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.c

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