MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBot.h

   1 /** @file
   2   Definition for the USB mass storage Bulk-Only Transport protocol,
   3   based on the "Universal Serial Bus Mass Storage Class Bulk-Only
   4   Transport" Revision 1.0, September 31, 1999.
   5
   6 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _EFI_USBMASS_BOT_H_
  12 #define _EFI_USBMASS_BOT_H_
  13
  14 extern USB_MASS_TRANSPORT  mUsbBotTransport;
  15
  16 //
  17 // Usb Bulk-Only class specific request
  18 //
  19 #define USB_BOT_RESET_REQUEST   0xFF        ///< Bulk-Only Mass Storage Reset
  20 #define USB_BOT_GETLUN_REQUEST  0xFE        ///< Get Max Lun
  21 #define USB_BOT_CBW_SIGNATURE   0x43425355  ///< dCBWSignature, tag the packet as CBW
  22 #define USB_BOT_CSW_SIGNATURE   0x53425355  ///< dCSWSignature, tag the packet as CSW
  23 #define USB_BOT_MAX_LUN         0x0F        ///< Lun number is from 0 to 15
  24 #define USB_BOT_MAX_CMDLEN      16          ///< Maximum number of command from command set
  25
  26 //
  27 // Usb BOT command block status values
  28 //
  29 #define USB_BOT_COMMAND_OK      0x00  ///< Command passed, good status
  30 #define USB_BOT_COMMAND_FAILED  0x01  ///< Command failed
  31 #define USB_BOT_COMMAND_ERROR   0x02  ///< Phase error, need to reset the device
  32
  33 //
  34 // Usb Bot retry to get CSW, refers to specification[BOT10-5.3, it says 2 times]
  35 //
  36 #define USB_BOT_RECV_CSW_RETRY  3
  37
  38 //
  39 // Usb Bot wait device reset complete, set by experience
  40 //
  41 #define USB_BOT_RESET_DEVICE_STALL  (100 * USB_MASS_1_MILLISECOND)
  42
  43 //
  44 // Usb Bot transport timeout, set by experience
  45 //
  46 #define USB_BOT_SEND_CBW_TIMEOUT      (3 * USB_MASS_1_SECOND)
  47 #define USB_BOT_RECV_CSW_TIMEOUT      (3 * USB_MASS_1_SECOND)
  48 #define USB_BOT_RESET_DEVICE_TIMEOUT  (3 * USB_MASS_1_SECOND)
  49
  50 #pragma pack(1)
  51 ///
  52 /// The CBW (Command Block Wrapper) structures used by the USB BOT protocol.
  53 ///
  54 typedef struct {
  55   UINT32    Signature;
  56   UINT32    Tag;
  57   UINT32    DataLen;            ///< Length of data between CBW and CSW
  58   UINT8     Flag;               ///< Bit 7, 0 ~ Data-Out, 1 ~ Data-In
  59   UINT8     Lun;                ///< Lun number. Bits 0~3 are used
  60   UINT8     CmdLen;             ///< Length of the command. Bits 0~4 are used
  61   UINT8     CmdBlock[USB_BOT_MAX_CMDLEN];
  62 } USB_BOT_CBW;
  63
  64 ///
  65 /// The and CSW (Command Status Wrapper) structures used by the USB BOT protocol.
  66 ///
  67 typedef struct {
  68   UINT32    Signature;
  69   UINT32    Tag;
  70   UINT32    DataResidue;
  71   UINT8     CmdStatus;
  72 } USB_BOT_CSW;
  73 #pragma pack()
  74
  75 typedef struct {
  76   //
  77   // Put Interface at the first field to make it easy to distinguish BOT/CBI Protocol instance
  78   //
  79   EFI_USB_INTERFACE_DESCRIPTOR    Interface;
  80   EFI_USB_ENDPOINT_DESCRIPTOR     *BulkInEndpoint;
  81   EFI_USB_ENDPOINT_DESCRIPTOR     *BulkOutEndpoint;
  82   UINT32                          CbwTag;
  83   EFI_USB_IO_PROTOCOL             *UsbIo;
  84 } USB_BOT_PROTOCOL;
  85
  86 /**
  87   Initializes USB BOT protocol.
  88
  89   This function initializes the USB mass storage class BOT protocol.
  90   It will save its context which is a USB_BOT_PROTOCOL structure
  91   in the Context if Context isn't NULL.
  92
  93   @param  UsbIo                 The USB I/O Protocol instance
  94   @param  Context               The buffer to save the context to
  95
  96   @retval EFI_SUCCESS           The device is successfully initialized.
  97   @retval EFI_UNSUPPORTED       The transport protocol doesn't support the device.
  98   @retval Other                 The USB BOT initialization fails.
  99
 100 **/
 101 EFI_STATUS
 102 UsbBotInit (
 103   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 104   OUT VOID                 **Context OPTIONAL
 105   );
 106
 107 /**
 108   Call the USB Mass Storage Class BOT protocol to issue
 109   the command/data/status circle to execute the commands.
 110
 111   @param  Context               The context of the BOT protocol, that is,
 112                                 USB_BOT_PROTOCOL
 113   @param  Cmd                   The high level command
 114   @param  CmdLen                The command length
 115   @param  DataDir               The direction of the data transfer
 116   @param  Data                  The buffer to hold data
 117   @param  DataLen               The length of the data
 118   @param  Lun                   The number of logic unit
 119   @param  Timeout               The time to wait command
 120   @param  CmdStatus             The result of high level command execution
 121
 122   @retval EFI_SUCCESS           The command is executed successfully.
 123   @retval Other                 Failed to execute command
 124
 125 **/
 126 EFI_STATUS
 127 UsbBotExecCommand (
 128   IN  VOID                    *Context,
 129   IN  VOID                    *Cmd,
 130   IN  UINT8                   CmdLen,
 131   IN  EFI_USB_DATA_DIRECTION  DataDir,
 132   IN  VOID                    *Data,
 133   IN  UINT32                  DataLen,
 134   IN  UINT8                   Lun,
 135   IN  UINT32                  Timeout,
 136   OUT UINT32                  *CmdStatus
 137   );
 138
 139 /**
 140   Reset the USB mass storage device by BOT protocol.
 141
 142   @param  Context               The context of the BOT protocol, that is,
 143                                 USB_BOT_PROTOCOL.
 144   @param  ExtendedVerification  If FALSE, just issue Bulk-Only Mass Storage Reset request.
 145                                 If TRUE, additionally reset parent hub port.
 146
 147   @retval EFI_SUCCESS           The device is reset.
 148   @retval Others                Failed to reset the device..
 149
 150 **/
 151 EFI_STATUS
 152 UsbBotResetDevice (
 153   IN  VOID     *Context,
 154   IN  BOOLEAN  ExtendedVerification
 155   );
 156
 157 /**
 158   Get the max LUN (Logical Unit Number) of USB mass storage device.
 159
 160   @param  Context          The context of the BOT protocol, that is, USB_BOT_PROTOCOL
 161   @param  MaxLun           Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and
 162                            LUN1 in all.)
 163
 164   @retval EFI_SUCCESS      Max LUN is got successfully.
 165   @retval Others           Fail to execute this request.
 166
 167 **/
 168 EFI_STATUS
 169 UsbBotGetMaxLun (
 170   IN  VOID   *Context,
 171   OUT UINT8  *MaxLun
 172   );
 173
 174 /**
 175   Clean up the resource used by this BOT protocol.
 176
 177   @param  Context         The context of the BOT protocol, that is, USB_BOT_PROTOCOL.
 178
 179   @retval EFI_SUCCESS     The resource is cleaned up.
 180
 181 **/
 182 EFI_STATUS
 183 UsbBotCleanUp (
 184   IN  VOID  *Context
 185   );
 186
 187 #endif