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