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