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