MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h

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