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