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