MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h

   1 /** @file
   2   DiskIo driver that layers it's self on every Block IO protocol in the system.
   3   DiskIo converts a block oriented device to a byte oriented device.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
   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 _DISK_IO_H
  17 #define _DISK_IO_H
  18
  19 #include <Uefi.h>
  20 #include <Protocol/BlockIo.h>
  21 #include <Protocol/ComponentName.h>
  22 #include <Protocol/DriverBinding.h>
  23 #include <Protocol/DiskIo.h>
  24 #include <Library/DebugLib.h>
  25 #include <Library/UefiDriverEntryPoint.h>
  26 #include <Library/UefiLib.h>
  27 #include <Library/BaseLib.h>
  28 #include <Library/BaseMemoryLib.h>
  29 #include <Library/MemoryAllocationLib.h>
  30 #include <Library/UefiBootServicesTableLib.h>
  31
  32
  33 #define DISK_IO_PRIVATE_DATA_SIGNATURE  EFI_SIGNATURE_32 ('d', 's', 'k', 'I')
  34
  35 #define DATA_BUFFER_BLOCK_NUM           (64)
  36
  37 typedef struct {
  38   UINTN                 Signature;
  39   EFI_DISK_IO_PROTOCOL  DiskIo;
  40   EFI_BLOCK_IO_PROTOCOL *BlockIo;
  41 } DISK_IO_PRIVATE_DATA;
  42
  43 #define DISK_IO_PRIVATE_DATA_FROM_THIS(a) CR (a, DISK_IO_PRIVATE_DATA, DiskIo, DISK_IO_PRIVATE_DATA_SIGNATURE)
  44
  45 //
  46 // Global Variables
  47 //
  48 extern EFI_DRIVER_BINDING_PROTOCOL   gDiskIoDriverBinding;
  49 extern EFI_COMPONENT_NAME_PROTOCOL   gDiskIoComponentName;
  50 extern EFI_COMPONENT_NAME2_PROTOCOL  gDiskIoComponentName2;
  51
  52 //
  53 // Prototypes
  54 // Driver model protocol interface
  55 //
  56 /**
  57   Test to see if this driver supports ControllerHandle.
  58
  59   @param  This                Protocol instance pointer.
  60   @param  ControllerHandle    Handle of device to test
  61   @param  RemainingDevicePath Optional parameter use to pick a specific child
  62                               device to start.
  63
  64   @retval EFI_SUCCESS         This driver supports this device
  65   @retval EFI_ALREADY_STARTED This driver is already running on this device
  66   @retval other               This driver does not support this device
  67
  68 **/
  69 EFI_STATUS
  70 EFIAPI
  71 DiskIoDriverBindingSupported (
  72   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
  73   IN EFI_HANDLE                     ControllerHandle,
  74   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
  75   );
  76
  77 /**
  78   Start this driver on ControllerHandle by opening a Block IO protocol and
  79   installing a Disk IO protocol on ControllerHandle.
  80
  81   @param  This                 Protocol instance pointer.
  82   @param  ControllerHandle     Handle of device to bind driver to
  83   @param  RemainingDevicePath  Optional parameter use to pick a specific child
  84                                device to start.
  85
  86   @retval EFI_SUCCESS          This driver is added to ControllerHandle
  87   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
  88   @retval other                This driver does not support this device
  89
  90 **/
  91 EFI_STATUS
  92 EFIAPI
  93 DiskIoDriverBindingStart (
  94   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
  95   IN EFI_HANDLE                     ControllerHandle,
  96   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
  97   );
  98
  99 /**
 100   Stop this driver on ControllerHandle by removing Disk IO protocol and closing
 101   the Block IO protocol on ControllerHandle.
 102
 103   @param  This              Protocol instance pointer.
 104   @param  ControllerHandle  Handle of device to stop driver on
 105   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
 106                             children is zero stop the entire bus driver.
 107   @param  ChildHandleBuffer List of Child Handles to Stop.
 108
 109   @retval EFI_SUCCESS       This driver is removed ControllerHandle
 110   @retval other             This driver was not removed from this device
 111
 112 **/
 113 EFI_STATUS
 114 EFIAPI
 115 DiskIoDriverBindingStop (
 116   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 117   IN  EFI_HANDLE                     ControllerHandle,
 118   IN  UINTN                          NumberOfChildren,
 119   IN  EFI_HANDLE                     *ChildHandleBuffer
 120   );
 121
 122 //
 123 // Disk I/O Protocol Interface
 124 //
 125 /**
 126   Read BufferSize bytes from Offset into Buffer.
 127   Reads may support reads that are not aligned on
 128   sector boundaries. There are three cases:
 129     UnderRun - The first byte is not on a sector boundary or the read request is
 130                less than a sector in length.
 131     Aligned  - A read of N contiguous sectors.
 132     OverRun  - The last byte is not on a sector boundary.
 133
 134   @param  This                  Protocol instance pointer.
 135   @param  MediaId               Id of the media, changes every time the media is replaced.
 136   @param  Offset                The starting byte offset to read from
 137   @param  BufferSize            Size of Buffer
 138   @param  Buffer                Buffer containing read data
 139
 140   @retval EFI_SUCCESS           The data was read correctly from the device.
 141   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
 142   @retval EFI_NO_MEDIA          There is no media in the device.
 143   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 144   @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not
 145                                 valid for the device.
 146
 147 **/
 148 EFI_STATUS
 149 EFIAPI
 150 DiskIoReadDisk (
 151   IN EFI_DISK_IO_PROTOCOL  *This,
 152   IN UINT32                MediaId,
 153   IN UINT64                Offset,
 154   IN UINTN                 BufferSize,
 155   OUT VOID                 *Buffer
 156   );
 157
 158 /**
 159   Read BufferSize bytes from Offset into Buffer.
 160   Writes may require a read modify write to support writes that are not
 161   aligned on sector boundaries. There are three cases:
 162     UnderRun - The first byte is not on a sector boundary or the write request
 163                is less than a sector in length. Read modify write is required.
 164     Aligned  - A write of N contiguous sectors.
 165     OverRun  - The last byte is not on a sector boundary. Read modified write
 166                required.
 167
 168   @param  This       Protocol instance pointer.
 169   @param  MediaId    Id of the media, changes every time the media is replaced.
 170   @param  Offset     The starting byte offset to read from
 171   @param  BufferSize Size of Buffer
 172   @param  Buffer     Buffer containing read data
 173
 174   @retval EFI_SUCCESS           The data was written correctly to the device.
 175   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 176   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 177   @retval EFI_NO_MEDIA          There is no media in the device.
 178   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 179   @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not
 180                                  valid for the device.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 DiskIoWriteDisk (
 186   IN EFI_DISK_IO_PROTOCOL  *This,
 187   IN UINT32                MediaId,
 188   IN UINT64                Offset,
 189   IN UINTN                 BufferSize,
 190   IN VOID                  *Buffer
 191   );
 192
 193 //
 194 // EFI Component Name Functions
 195 //
 196 /**
 197   Retrieves a Unicode string that is the user readable name of the driver.
 198
 199   This function retrieves the user readable name of a driver in the form of a
 200   Unicode string. If the driver specified by This has a user readable name in
 201   the language specified by Language, then a pointer to the driver name is
 202   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 203   by This does not support the language specified by Language,
 204   then EFI_UNSUPPORTED is returned.
 205
 206   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 207                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 208
 209   @param  Language[in]          A pointer to a Null-terminated ASCII string
 210                                 array indicating the language. This is the
 211                                 language of the driver name that the caller is
 212                                 requesting, and it must match one of the
 213                                 languages specified in SupportedLanguages. The
 214                                 number of languages supported by a driver is up
 215                                 to the driver writer. Language is specified
 216                                 in RFC 3066 or ISO 639-2 language code format.
 217
 218   @param  DriverName[out]       A pointer to the Unicode string to return.
 219                                 This Unicode string is the name of the
 220                                 driver specified by This in the language
 221                                 specified by Language.
 222
 223   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 224                                 This and the language specified by Language was
 225                                 returned in DriverName.
 226
 227   @retval EFI_INVALID_PARAMETER Language is NULL.
 228
 229   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 230
 231   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 232                                 the language specified by Language.
 233
 234 **/
 235 EFI_STATUS
 236 EFIAPI
 237 DiskIoComponentNameGetDriverName (
 238   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 239   IN  CHAR8                        *Language,
 240   OUT CHAR16                       **DriverName
 241   );
 242
 243
 244 /**
 245   Retrieves a Unicode string that is the user readable name of the controller
 246   that is being managed by a driver.
 247
 248   This function retrieves the user readable name of the controller specified by
 249   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 250   driver specified by This has a user readable name in the language specified by
 251   Language, then a pointer to the controller name is returned in ControllerName,
 252   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 253   managing the controller specified by ControllerHandle and ChildHandle,
 254   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 255   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 256
 257   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 258                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 259
 260   @param  ControllerHandle[in]  The handle of a controller that the driver
 261                                 specified by This is managing.  This handle
 262                                 specifies the controller whose name is to be
 263                                 returned.
 264
 265   @param  ChildHandle[in]       The handle of the child controller to retrieve
 266                                 the name of.  This is an optional parameter that
 267                                 may be NULL.  It will be NULL for device
 268                                 drivers.  It will also be NULL for a bus drivers
 269                                 that wish to retrieve the name of the bus
 270                                 controller.  It will not be NULL for a bus
 271                                 driver that wishes to retrieve the name of a
 272                                 child controller.
 273
 274   @param  Language[in]          A pointer to a Null-terminated ASCII string
 275                                 array indicating the language.  This is the
 276                                 language of the driver name that the caller is
 277                                 requesting, and it must match one of the
 278                                 languages specified in SupportedLanguages. The
 279                                 number of languages supported by a driver is up
 280                                 to the driver writer. Language is specified in
 281                                 RFC 3066 or ISO 639-2 language code format.
 282
 283   @param  ControllerName[out]   A pointer to the Unicode string to return.
 284                                 This Unicode string is the name of the
 285                                 controller specified by ControllerHandle and
 286                                 ChildHandle in the language specified by
 287                                 Language from the point of view of the driver
 288                                 specified by This.
 289
 290   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 291                                 the language specified by Language for the
 292                                 driver specified by This was returned in
 293                                 DriverName.
 294
 295   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 296
 297   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 298                                 EFI_HANDLE.
 299
 300   @retval EFI_INVALID_PARAMETER Language is NULL.
 301
 302   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 303
 304   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 305                                 managing the controller specified by
 306                                 ControllerHandle and ChildHandle.
 307
 308   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 309                                 the language specified by Language.
 310
 311 **/
 312 EFI_STATUS
 313 EFIAPI
 314 DiskIoComponentNameGetControllerName (
 315   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 316   IN  EFI_HANDLE                                      ControllerHandle,
 317   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 318   IN  CHAR8                                           *Language,
 319   OUT CHAR16                                          **ControllerName
 320   );
 321
 322
 323 #endif