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