MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMass.h

   1 /** @file
   2   Definition of USB Mass Storage Class and its value, USB Mass Transport Protocol,
   3   and other common definitions.
   4
   5 Copyright (c) 2007 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_USBMASS_H_
  17 #define _EFI_USBMASS_H_
  18
  19
  20 #include <Uefi.h>
  21
  22 #include <Protocol/BlockIo.h>
  23 #include <Protocol/UsbIo.h>
  24 #include <Protocol/DevicePath.h>
  25
  26 #include <Library/BaseLib.h>
  27 #include <Library/DebugLib.h>
  28 #include <Library/BaseMemoryLib.h>
  29 #include <Library/UefiDriverEntryPoint.h>
  30 #include <Library/UefiBootServicesTableLib.h>
  31 #include <Library/UefiLib.h>
  32 #include <Library/MemoryAllocationLib.h>
  33 #include <Library/DevicePathLib.h>
  34
  35 #define USB_IS_IN_ENDPOINT(EndPointAddr)      (((EndPointAddr) & BIT7) == BIT7)
  36 #define USB_IS_OUT_ENDPOINT(EndPointAddr)     (((EndPointAddr) & BIT7) == 0)
  37 #define USB_IS_BULK_ENDPOINT(Attribute)       (((Attribute) & (BIT0 | BIT1)) == USB_ENDPOINT_BULK)
  38 #define USB_IS_INTERRUPT_ENDPOINT(Attribute)  (((Attribute) & (BIT0 | BIT1)) == USB_ENDPOINT_INTERRUPT)
  39 #define USB_IS_ERROR(Result, Error)           (((Result) & (Error)) != 0)
  40
  41 typedef enum {
  42   //
  43   // Usb mass storage class code
  44   //
  45   USB_MASS_STORE_CLASS    = 0x08,
  46
  47   //
  48   // Usb mass storage subclass code, specify the command set used.
  49   //
  50   USB_MASS_STORE_RBC      = 0x01, ///< Reduced Block Commands
  51   USB_MASS_STORE_8020I    = 0x02, ///< SFF-8020i, typically a CD/DVD device
  52   USB_MASS_STORE_QIC      = 0x03, ///< Typically a tape device
  53   USB_MASS_STORE_UFI      = 0x04, ///< Typically a floppy disk driver device
  54   USB_MASS_STORE_8070I    = 0x05, ///< SFF-8070i, typically a floppy disk driver device.
  55   USB_MASS_STORE_SCSI     = 0x06, ///< SCSI transparent command set
  56
  57   //
  58   // Usb mass storage protocol code, specify the transport protocol
  59   //
  60   USB_MASS_STORE_CBI0     = 0x00, ///< CBI protocol with command completion interrupt
  61   USB_MASS_STORE_CBI1     = 0x01, ///< CBI protocol without command completion interrupt
  62   USB_MASS_STORE_BOT      = 0x50, ///< Bulk-Only Transport
  63
  64   USB_MASS_1_MILLISECOND  = 1000,
  65   USB_MASS_1_SECOND       = 1000 * USB_MASS_1_MILLISECOND,
  66
  67   USB_MASS_CMD_SUCCESS    = 0,
  68   USB_MASS_CMD_FAIL,
  69   USB_MASS_CMD_PERSISTENT
  70 } USB_MASS_DEV_CLASS_AND_VALUE;
  71
  72 /**
  73   Initializes USB transport protocol.
  74
  75   This function initializes the USB mass storage class transport protocol.
  76   It will save its context in the Context if Context isn't NULL.
  77
  78   @param  UsbIo                 The USB I/O Protocol instance
  79   @param  Context               The buffer to save the context to
  80
  81   @retval EFI_SUCCESS           The device is successfully initialized.
  82   @retval EFI_UNSUPPORTED       The transport protocol doesn't support the device.
  83   @retval Other                 The USB transport initialization fails.
  84
  85 **/
  86 typedef
  87 EFI_STATUS
  88 (*USB_MASS_INIT_TRANSPORT) (
  89   IN  EFI_USB_IO_PROTOCOL     *Usb,
  90   OUT VOID                    **Context    OPTIONAL
  91   );
  92
  93 /**
  94   Execute USB mass storage command through the transport protocol.
  95
  96   @param  Context               The USB Transport Protocol.
  97   @param  Cmd                   The command to transfer to device
  98   @param  CmdLen                The length of the command
  99   @param  DataDir               The direction of data transfer
 100   @param  Data                  The buffer to hold the data
 101   @param  DataLen               The length of the buffer
 102   @param  Lun                   Should be 0, this field for bot only
 103   @param  Timeout               The time to wait
 104   @param  CmdStatus             The result of the command execution
 105
 106   @retval EFI_SUCCESS           The command is executed successfully.
 107   @retval Other                 Failed to execute the command
 108
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (*USB_MASS_EXEC_COMMAND) (
 113   IN  VOID                    *Context,
 114   IN  VOID                    *Cmd,
 115   IN  UINT8                   CmdLen,
 116   IN  EFI_USB_DATA_DIRECTION  DataDir,
 117   IN  VOID                    *Data,
 118   IN  UINT32                  DataLen,
 119   IN  UINT8                   Lun,
 120   IN  UINT32                  Timeout,
 121   OUT UINT32                  *CmdStatus
 122   );
 123
 124 /**
 125   Reset the USB mass storage device by Transport protocol.
 126
 127   @param  Context               The USB Transport Protocol
 128   @param  ExtendedVerification  The flag controlling the rule of reset.
 129                                 Not used here.
 130
 131   @retval EFI_SUCCESS           The device is reset.
 132   @retval Others                Failed to reset the device.
 133
 134 **/
 135 typedef
 136 EFI_STATUS
 137 (*USB_MASS_RESET) (
 138   IN  VOID                    *Context,
 139   IN  BOOLEAN                 ExtendedVerification
 140   );
 141
 142 /**
 143   Get the max LUN (Logical Unit Number) of USB mass storage device.
 144
 145   @param  Context          The context of the transport protocol.
 146   @param  MaxLun           Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and
 147                            LUN1 in all.)
 148
 149   @retval EFI_SUCCESS      Max LUN is got successfully.
 150   @retval Others           Fail to execute this request.
 151
 152 **/
 153 typedef
 154 EFI_STATUS
 155 (*USB_MASS_GET_MAX_LUN) (
 156   IN  VOID                    *Context,
 157   IN  UINT8                   *MaxLun
 158   );
 159
 160 /**
 161   Clean up the transport protocol's resource.
 162
 163   @param  Context               The instance of transport protocol.
 164
 165   @retval EFI_SUCCESS           The resource is cleaned up.
 166
 167 **/
 168 typedef
 169 EFI_STATUS
 170 (*USB_MASS_CLEAN_UP) (
 171   IN  VOID                    *Context
 172   );
 173
 174 ///
 175 /// This structure contains information necessary to select the
 176 /// proper transport protocol. The mass storage class defines
 177 /// two transport protocols. One is the CBI, and the other is BOT.
 178 /// CBI is being obseleted. The design is made modular by this
 179 /// structure so that the CBI protocol can be easily removed when
 180 /// it is no longer necessary.
 181 ///
 182 typedef struct {
 183   UINT8                   Protocol;
 184   USB_MASS_INIT_TRANSPORT Init;        ///< Initialize the mass storage transport protocol
 185   USB_MASS_EXEC_COMMAND   ExecCommand; ///< Transport command to the device then get result
 186   USB_MASS_RESET          Reset;       ///< Reset the device
 187   USB_MASS_GET_MAX_LUN    GetMaxLun;   ///< Get max lun, only for bot
 188   USB_MASS_CLEAN_UP       CleanUp;     ///< Clean up the resources.
 189 } USB_MASS_TRANSPORT;
 190
 191 typedef struct {
 192   UINT32                    Signature;
 193   EFI_HANDLE                Controller;
 194   EFI_USB_IO_PROTOCOL       *UsbIo;
 195   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 196   EFI_BLOCK_IO_PROTOCOL     BlockIo;
 197   EFI_BLOCK_IO_MEDIA        BlockIoMedia;
 198   BOOLEAN                   OpticalStorage;
 199   UINT8                     Lun;          ///< Logical Unit Number
 200   UINT8                     Pdt;          ///< Peripheral Device Type
 201   USB_MASS_TRANSPORT        *Transport;   ///< USB mass storage transport protocol
 202   VOID                      *Context;
 203 } USB_MASS_DEVICE;
 204
 205 #endif