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