MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassImpl.h

   1 /** @file
   2   Definitions of functions for Driver Binding Protocol and Block I/O Protocol,
   3   and other internal definitions.
   4
   5 Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR>
   6 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_IMPL_H_
  17 #define _EFI_USBMASS_IMPL_H_
  18
  19 #define  USB_MASS_SIGNATURE    SIGNATURE_32 ('U', 's', 'b', 'M')
  20
  21 #define USB_MASS_DEVICE_FROM_BLOCK_IO(a) \
  22         CR (a, USB_MASS_DEVICE, BlockIo, USB_MASS_SIGNATURE)
  23
  24 #define USB_MASS_DEVICE_FROM_DISK_INFO(a) \
  25         CR (a, USB_MASS_DEVICE, DiskInfo, USB_MASS_SIGNATURE)
  26
  27
  28 extern EFI_COMPONENT_NAME_PROTOCOL   gUsbMassStorageComponentName;
  29 extern EFI_COMPONENT_NAME2_PROTOCOL  gUsbMassStorageComponentName2;
  30
  31 //
  32 // Functions for Driver Binding Protocol
  33 //
  34
  35 /**
  36   Check whether the controller is a supported USB mass storage.
  37
  38   @param  This                   The USB mass storage driver binding protocol.
  39   @param  Controller             The controller handle to check.
  40   @param  RemainingDevicePath    The remaining device path.
  41
  42   @retval EFI_SUCCESS            The driver supports this controller.
  43   @retval other                  This device isn't supported.
  44
  45 **/
  46 EFI_STATUS
  47 EFIAPI
  48 USBMassDriverBindingSupported (
  49   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  50   IN EFI_HANDLE                   Controller,
  51   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  52   );
  53
  54 /**
  55   Starts the USB mass storage device with this driver.
  56
  57   This function consumes USB I/O Portocol, intializes USB mass storage device,
  58   installs Block I/O Protocol, and submits Asynchronous Interrupt
  59   Transfer to manage the USB mass storage device.
  60
  61   @param  This                  The USB mass storage driver binding protocol.
  62   @param  Controller            The USB mass storage device to start on
  63   @param  RemainingDevicePath   The remaining device path.
  64
  65   @retval EFI_SUCCESS           This driver supports this device.
  66   @retval EFI_UNSUPPORTED       This driver does not support this device.
  67   @retval EFI_DEVICE_ERROR      This driver cannot be started due to device Error.
  68   @retval EFI_OUT_OF_RESOURCES  Can't allocate memory resources.
  69   @retval EFI_ALREADY_STARTED   This driver has been started.
  70
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 USBMassDriverBindingStart (
  75   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  76   IN EFI_HANDLE                   Controller,
  77   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  78   );
  79
  80 /**
  81   Stop controlling the device.
  82
  83   @param  This                   The USB mass storage driver binding
  84   @param  Controller             The device controller controlled by the driver.
  85   @param  NumberOfChildren       The number of children of this device
  86   @param  ChildHandleBuffer      The buffer of children handle.
  87
  88   @retval EFI_SUCCESS            The driver stopped from controlling the device.
  89   @retval EFI_DEVICE_ERROR       The device could not be stopped due to a device error.
  90   @retval EFI_UNSUPPORTED        Block I/O Protocol is not installed on Controller.
  91   @retval Others                 Failed to stop the driver
  92
  93 **/
  94 EFI_STATUS
  95 EFIAPI
  96 USBMassDriverBindingStop (
  97   IN  EFI_DRIVER_BINDING_PROTOCOL *This,
  98   IN  EFI_HANDLE                  Controller,
  99   IN  UINTN                       NumberOfChildren,
 100   IN  EFI_HANDLE                  *ChildHandleBuffer
 101   );
 102
 103 //
 104 // Functions for Block I/O Protocol
 105 //
 106
 107 /**
 108   Reset the block device.
 109
 110   This function implements EFI_BLOCK_IO_PROTOCOL.Reset().
 111   It resets the block device hardware.
 112   ExtendedVerification is ignored in this implementation.
 113
 114   @param  This                   Indicates a pointer to the calling context.
 115   @param  ExtendedVerification   Indicates that the driver may perform a more exhaustive
 116                                  verification operation of the device during reset.
 117
 118   @retval EFI_SUCCESS            The block device was reset.
 119   @retval EFI_DEVICE_ERROR       The block device is not functioning correctly and could not be reset.
 120
 121 **/
 122 EFI_STATUS
 123 EFIAPI
 124 UsbMassReset (
 125   IN EFI_BLOCK_IO_PROTOCOL    *This,
 126   IN BOOLEAN                  ExtendedVerification
 127   );
 128
 129 /**
 130   Reads the requested number of blocks from the device.
 131
 132   This function implements EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
 133   It reads the requested number of blocks from the device.
 134   All the blocks are read, or an error is returned.
 135
 136   @param  This                   Indicates a pointer to the calling context.
 137   @param  MediaId                The media ID that the read request is for.
 138   @param  Lba                    The starting logical block address to read from on the device.
 139   @param  BufferSize             The size of the Buffer in bytes.
 140                                  This must be a multiple of the intrinsic block size of the device.
 141   @param  Buffer                 A pointer to the destination buffer for the data. The caller is
 142                                  responsible for either having implicit or explicit ownership of the buffer.
 143
 144   @retval EFI_SUCCESS            The data was read correctly from the device.
 145   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to perform the read operation.
 146   @retval EFI_NO_MEDIA           There is no media in the device.
 147   @retval EFI_MEDIA_CHANGED      The MediaId is not for the current media.
 148   @retval EFI_BAD_BUFFER_SIZE    The BufferSize parameter is not a multiple of the intrinsic block size of the device.
 149   @retval EFI_INVALID_PARAMETER  The read request contains LBAs that are not valid,
 150                                  or the buffer is not on proper alignment.
 151
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 UsbMassReadBlocks (
 156   IN EFI_BLOCK_IO_PROTOCOL    *This,
 157   IN UINT32                   MediaId,
 158   IN EFI_LBA                  Lba,
 159   IN UINTN                    BufferSize,
 160   OUT VOID                    *Buffer
 161   );
 162
 163 /**
 164   Writes a specified number of blocks to the device.
 165
 166   This function implements EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
 167   It writes a specified number of blocks to the device.
 168   All blocks are written, or an error is returned.
 169
 170   @param  This                   Indicates a pointer to the calling context.
 171   @param  MediaId                The media ID that the write request is for.
 172   @param  Lba                    The starting logical block address to be written.
 173   @param  BufferSize             The size of the Buffer in bytes.
 174                                  This must be a multiple of the intrinsic block size of the device.
 175   @param  Buffer                 Pointer to the source buffer for the data.
 176
 177   @retval EFI_SUCCESS            The data were written correctly to the device.
 178   @retval EFI_WRITE_PROTECTED    The device cannot be written to.
 179   @retval EFI_NO_MEDIA           There is no media in the device.
 180   @retval EFI_MEDIA_CHANGED      The MediaId is not for the current media.
 181   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to perform the write operation.
 182   @retval EFI_BAD_BUFFER_SIZE    The BufferSize parameter is not a multiple of the intrinsic
 183                                  block size of the device.
 184   @retval EFI_INVALID_PARAMETER  The write request contains LBAs that are not valid,
 185                                  or the buffer is not on proper alignment.
 186
 187 **/
 188 EFI_STATUS
 189 EFIAPI
 190 UsbMassWriteBlocks (
 191   IN EFI_BLOCK_IO_PROTOCOL    *This,
 192   IN UINT32                   MediaId,
 193   IN EFI_LBA                  Lba,
 194   IN UINTN                    BufferSize,
 195   IN VOID                     *Buffer
 196   );
 197
 198 /**
 199   Flushes all modified data to a physical block device.
 200
 201   This function implements EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
 202   USB mass storage device doesn't support write cache,
 203   so return EFI_SUCCESS directly.
 204
 205   @param  This                   Indicates a pointer to the calling context.
 206
 207   @retval EFI_SUCCESS            All outstanding data were written correctly to the device.
 208   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to write data.
 209   @retval EFI_NO_MEDIA           There is no media in the device.
 210
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 UsbMassFlushBlocks (
 215   IN EFI_BLOCK_IO_PROTOCOL  *This
 216   );
 217
 218 //
 219 // EFI Component Name Functions
 220 //
 221
 222 /**
 223   Retrieves a Unicode string that is the user readable name of the driver.
 224
 225   This function retrieves the user readable name of a driver in the form of a
 226   Unicode string. If the driver specified by This has a user readable name in
 227   the language specified by Language, then a pointer to the driver name is
 228   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 229   by This does not support the language specified by Language,
 230   then EFI_UNSUPPORTED is returned.
 231
 232   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 233                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 234   @param  Language              A pointer to a Null-terminated ASCII string
 235                                 array indicating the language. This is the
 236                                 language of the driver name that the caller is
 237                                 requesting, and it must match one of the
 238                                 languages specified in SupportedLanguages. The
 239                                 number of languages supported by a driver is up
 240                                 to the driver writer. Language is specified
 241                                 in RFC 4646 or ISO 639-2 language code format.
 242   @param  DriverName            A pointer to the Unicode string to return.
 243                                 This Unicode string is the name of the
 244                                 driver specified by This in the language
 245                                 specified by Language.
 246
 247   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 248                                 This and the language specified by Language was
 249                                 returned in DriverName.
 250   @retval EFI_INVALID_PARAMETER Language is NULL.
 251   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 252   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 253                                 the language specified by Language.
 254
 255 **/
 256 EFI_STATUS
 257 EFIAPI
 258 UsbMassStorageGetDriverName (
 259   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 260   IN  CHAR8                        *Language,
 261   OUT CHAR16                       **DriverName
 262   );
 263
 264
 265 /**
 266   Retrieves a Unicode string that is the user readable name of the controller
 267   that is being managed by a driver.
 268
 269   This function retrieves the user readable name of the controller specified by
 270   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 271   driver specified by This has a user readable name in the language specified by
 272   Language, then a pointer to the controller name is returned in ControllerName,
 273   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 274   managing the controller specified by ControllerHandle and ChildHandle,
 275   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 276   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 277
 278   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 279                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 280   @param  ControllerHandle      The handle of a controller that the driver
 281                                 specified by This is managing.  This handle
 282                                 specifies the controller whose name is to be
 283                                 returned.
 284   @param  ChildHandle           The handle of the child controller to retrieve
 285                                 the name of.  This is an optional parameter that
 286                                 may be NULL.  It will be NULL for device
 287                                 drivers.  It will also be NULL for a bus drivers
 288                                 that wish to retrieve the name of the bus
 289                                 controller.  It will not be NULL for a bus
 290                                 driver that wishes to retrieve the name of a
 291                                 child controller.
 292   @param  Language              A pointer to a Null-terminated ASCII string
 293                                 array indicating the language.  This is the
 294                                 language of the driver name that the caller is
 295                                 requesting, and it must match one of the
 296                                 languages specified in SupportedLanguages. The
 297                                 number of languages supported by a driver is up
 298                                 to the driver writer. Language is specified in
 299                                 RFC 4646 or ISO 639-2 language code format.
 300   @param  ControllerName        A pointer to the Unicode string to return.
 301                                 This Unicode string is the name of the
 302                                 controller specified by ControllerHandle and
 303                                 ChildHandle in the language specified by
 304                                 Language from the point of view of the driver
 305                                 specified by This.
 306
 307   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 308                                 the language specified by Language for the
 309                                 driver specified by This was returned in
 310                                 DriverName.
 311   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 312   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 313                                 EFI_HANDLE.
 314   @retval EFI_INVALID_PARAMETER Language is NULL.
 315   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 316   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 317                                 managing the controller specified by
 318                                 ControllerHandle and ChildHandle.
 319   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 320                                 the language specified by Language.
 321
 322 **/
 323 EFI_STATUS
 324 EFIAPI
 325 UsbMassStorageGetControllerName (
 326   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 327   IN  EFI_HANDLE                                      ControllerHandle,
 328   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 329   IN  CHAR8                                           *Language,
 330   OUT CHAR16                                          **ControllerName
 331   );
 332
 333 #endif