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 - 2013, 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/BlockIo2.h>
  21 #include <Protocol/DiskIo2.h>
  22 #include <Protocol/ComponentName.h>
  23 #include <Protocol/DriverBinding.h>
  24 #include <Protocol/DiskIo.h>
  25 #include <Library/DebugLib.h>
  26 #include <Library/UefiDriverEntryPoint.h>
  27 #include <Library/UefiLib.h>
  28 #include <Library/BaseLib.h>
  29 #include <Library/BaseMemoryLib.h>
  30 #include <Library/MemoryAllocationLib.h>
  31 #include <Library/UefiBootServicesTableLib.h>
  32
  33 #define DISK_IO_PRIVATE_DATA_SIGNATURE  SIGNATURE_32 ('d', 's', 'k', 'I')
  34 typedef struct {
  35   UINT32                          Signature;
  36
  37   EFI_DISK_IO_PROTOCOL            DiskIo;
  38   EFI_DISK_IO2_PROTOCOL           DiskIo2;
  39   EFI_BLOCK_IO_PROTOCOL           *BlockIo;
  40   EFI_BLOCK_IO2_PROTOCOL          *BlockIo2;
  41
  42   UINT8                           *SharedWorkingBuffer;
  43
  44   EFI_LOCK                        TaskQueueLock;
  45   LIST_ENTRY                      TaskQueue;
  46 } DISK_IO_PRIVATE_DATA;
  47 #define DISK_IO_PRIVATE_DATA_FROM_DISK_IO(a)  CR (a, DISK_IO_PRIVATE_DATA, DiskIo,  DISK_IO_PRIVATE_DATA_SIGNATURE)
  48 #define DISK_IO_PRIVATE_DATA_FROM_DISK_IO2(a) CR (a, DISK_IO_PRIVATE_DATA, DiskIo2, DISK_IO_PRIVATE_DATA_SIGNATURE)
  49
  50 #define DISK_IO2_TASK_SIGNATURE   SIGNATURE_32 ('d', 'i', 'a', 't')
  51 typedef struct {
  52   UINT32                          Signature;
  53   LIST_ENTRY                      Link;     /// < link to other task
  54   LIST_ENTRY                      Subtasks; /// < header of subtasks
  55   EFI_DISK_IO2_TOKEN              *Token;
  56   DISK_IO_PRIVATE_DATA            *Instance;
  57 } DISK_IO2_TASK;
  58
  59 #define DISK_IO2_FLUSH_TASK_SIGNATURE SIGNATURE_32 ('d', 'i', 'f', 't')
  60 typedef struct {
  61   UINT32                          Signature;
  62   EFI_BLOCK_IO2_TOKEN             BlockIo2Token;
  63   EFI_DISK_IO2_TOKEN              *Token;
  64 } DISK_IO2_FLUSH_TASK;
  65
  66 #define DISK_IO_SUBTASK_SIGNATURE SIGNATURE_32 ('d', 'i', 's', 't')
  67 typedef struct {
  68   //
  69   // UnderRun:  Offset != 0, Length < BlockSize
  70   // OverRun:   Offset == 0, Length < BlockSize
  71   // Middle:    Offset is block aligned, Length is multiple of block size
  72   //
  73   UINT32                          Signature;
  74   LIST_ENTRY                      Link;
  75   BOOLEAN                         Write;
  76   UINT64                          Lba;
  77   UINT32                          Offset;
  78   UINTN                           Length;
  79   UINT8                           *WorkingBuffer; /// < NULL indicates using "Buffer" directly
  80   UINT8                           *Buffer;
  81   BOOLEAN                         Blocking;
  82
  83   //
  84   // Following fields are for DiskIo2
  85   //
  86   DISK_IO2_TASK                   *Task;
  87   EFI_BLOCK_IO2_TOKEN             BlockIo2Token;
  88 } DISK_IO_SUBTASK;
  89
  90 //
  91 // Global Variables
  92 //
  93 extern EFI_DRIVER_BINDING_PROTOCOL   gDiskIoDriverBinding;
  94 extern EFI_COMPONENT_NAME_PROTOCOL   gDiskIoComponentName;
  95 extern EFI_COMPONENT_NAME2_PROTOCOL  gDiskIoComponentName2;
  96
  97 //
  98 // Prototypes
  99 // Driver model protocol interface
 100 //
 101 /**
 102   Test to see if this driver supports ControllerHandle.
 103
 104   @param  This                Protocol instance pointer.
 105   @param  ControllerHandle    Handle of device to test
 106   @param  RemainingDevicePath Optional parameter use to pick a specific child
 107                               device to start.
 108
 109   @retval EFI_SUCCESS         This driver supports this device
 110   @retval EFI_ALREADY_STARTED This driver is already running on this device
 111   @retval other               This driver does not support this device
 112
 113 **/
 114 EFI_STATUS
 115 EFIAPI
 116 DiskIoDriverBindingSupported (
 117   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 118   IN EFI_HANDLE                   ControllerHandle,
 119   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 120   );
 121
 122 /**
 123   Start this driver on ControllerHandle by opening a Block IO protocol and
 124   installing a Disk IO protocol on ControllerHandle.
 125
 126   @param  This                 Protocol instance pointer.
 127   @param  ControllerHandle     Handle of device to bind driver to
 128   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 129                                device to start.
 130
 131   @retval EFI_SUCCESS          This driver is added to ControllerHandle
 132   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
 133   @retval other                This driver does not support this device
 134
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 DiskIoDriverBindingStart (
 139   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 140   IN EFI_HANDLE                   ControllerHandle,
 141   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 142   );
 143
 144 /**
 145   Stop this driver on ControllerHandle by removing Disk IO protocol and closing
 146   the Block IO protocol on ControllerHandle.
 147
 148   @param  This              Protocol instance pointer.
 149   @param  ControllerHandle  Handle of device to stop driver on
 150   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
 151                             children is zero stop the entire bus driver.
 152   @param  ChildHandleBuffer List of Child Handles to Stop.
 153
 154   @retval EFI_SUCCESS       This driver is removed ControllerHandle
 155   @retval other             This driver was not removed from this device
 156
 157 **/
 158 EFI_STATUS
 159 EFIAPI
 160 DiskIoDriverBindingStop (
 161   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 162   IN  EFI_HANDLE                     ControllerHandle,
 163   IN  UINTN                          NumberOfChildren,
 164   IN  EFI_HANDLE                     *ChildHandleBuffer
 165   );
 166
 167 //
 168 // Disk I/O Protocol Interface
 169 //
 170 /**
 171   Read BufferSize bytes from Offset into Buffer.
 172   Reads may support reads that are not aligned on
 173   sector boundaries. There are three cases:
 174     UnderRun - The first byte is not on a sector boundary or the read request is
 175                less than a sector in length.
 176     Aligned  - A read of N contiguous sectors.
 177     OverRun  - The last byte is not on a sector boundary.
 178
 179   @param  This                  Protocol instance pointer.
 180   @param  MediaId               Id of the media, changes every time the media is replaced.
 181   @param  Offset                The starting byte offset to read from
 182   @param  BufferSize            Size of Buffer
 183   @param  Buffer                Buffer containing read data
 184
 185   @retval EFI_SUCCESS           The data was read correctly from the device.
 186   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
 187   @retval EFI_NO_MEDIA          There is no media in the device.
 188   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 189   @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not
 190                                 valid for the device.
 191
 192 **/
 193 EFI_STATUS
 194 EFIAPI
 195 DiskIoReadDisk (
 196   IN EFI_DISK_IO_PROTOCOL  *This,
 197   IN UINT32                MediaId,
 198   IN UINT64                Offset,
 199   IN UINTN                 BufferSize,
 200   OUT VOID                 *Buffer
 201   );
 202
 203 /**
 204   Writes BufferSize bytes from Buffer into Offset.
 205   Writes may require a read modify write to support writes that are not
 206   aligned on sector boundaries. There are three cases:
 207     UnderRun - The first byte is not on a sector boundary or the write request
 208                is less than a sector in length. Read modify write is required.
 209     Aligned  - A write of N contiguous sectors.
 210     OverRun  - The last byte is not on a sector boundary. Read modified write
 211                required.
 212
 213   @param  This       Protocol instance pointer.
 214   @param  MediaId    Id of the media, changes every time the media is replaced.
 215   @param  Offset     The starting byte offset to read from
 216   @param  BufferSize Size of Buffer
 217   @param  Buffer     Buffer containing read data
 218
 219   @retval EFI_SUCCESS           The data was written correctly to the device.
 220   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 221   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 222   @retval EFI_NO_MEDIA          There is no media in the device.
 223   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 224   @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not
 225                                  valid for the device.
 226
 227 **/
 228 EFI_STATUS
 229 EFIAPI
 230 DiskIoWriteDisk (
 231   IN EFI_DISK_IO_PROTOCOL  *This,
 232   IN UINT32                MediaId,
 233   IN UINT64                Offset,
 234   IN UINTN                 BufferSize,
 235   IN VOID                  *Buffer
 236   );
 237
 238
 239 /**
 240   Terminate outstanding asynchronous requests to a device.
 241
 242   @param This                   Indicates a pointer to the calling context.
 243
 244   @retval EFI_SUCCESS           All outstanding requests were successfully terminated.
 245   @retval EFI_DEVICE_ERROR      The device reported an error while performing the cancel
 246                                 operation.
 247 **/
 248 EFI_STATUS
 249 EFIAPI
 250 DiskIo2Cancel (
 251   IN EFI_DISK_IO2_PROTOCOL *This
 252   );
 253
 254 /**
 255   Reads a specified number of bytes from a device.
 256
 257   @param This                   Indicates a pointer to the calling context.
 258   @param MediaId                ID of the medium to be read.
 259   @param Offset                 The starting byte offset on the logical block I/O device to read from.
 260   @param Token                  A pointer to the token associated with the transaction.
 261                                 If this field is NULL, synchronous/blocking IO is performed.
 262   @param  BufferSize            The size in bytes of Buffer. The number of bytes to read from the device.
 263   @param  Buffer                A pointer to the destination buffer for the data.
 264                                 The caller is responsible either having implicit or explicit ownership of the buffer.
 265
 266   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was read correctly from the device.
 267                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
 268                                                                          Event will be signaled upon completion.
 269   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 270   @retval EFI_NO_MEDIA          There is no medium in the device.
 271   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
 272   @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not valid for the device.
 273   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 274
 275 **/
 276 EFI_STATUS
 277 EFIAPI
 278 DiskIo2ReadDiskEx (
 279   IN EFI_DISK_IO2_PROTOCOL        *This,
 280   IN UINT32                       MediaId,
 281   IN UINT64                       Offset,
 282   IN OUT EFI_DISK_IO2_TOKEN       *Token,
 283   IN UINTN                        BufferSize,
 284   OUT VOID                        *Buffer
 285   );
 286
 287 /**
 288   Writes a specified number of bytes to a device.
 289
 290   @param This        Indicates a pointer to the calling context.
 291   @param MediaId     ID of the medium to be written.
 292   @param Offset      The starting byte offset on the logical block I/O device to write to.
 293   @param Token       A pointer to the token associated with the transaction.
 294                      If this field is NULL, synchronous/blocking IO is performed.
 295   @param BufferSize  The size in bytes of Buffer. The number of bytes to write to the device.
 296   @param Buffer      A pointer to the buffer containing the data to be written.
 297
 298   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was written correctly to the device.
 299                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
 300                                                                          Event will be signaled upon completion.
 301   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
 302   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
 303   @retval EFI_NO_MEDIA          There is no medium in the device.
 304   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
 305   @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not valid for the device.
 306   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 307
 308 **/
 309 EFI_STATUS
 310 EFIAPI
 311 DiskIo2WriteDiskEx (
 312   IN EFI_DISK_IO2_PROTOCOL        *This,
 313   IN UINT32                       MediaId,
 314   IN UINT64                       Offset,
 315   IN EFI_DISK_IO2_TOKEN           *Token,
 316   IN UINTN                        BufferSize,
 317   IN VOID                         *Buffer
 318   );
 319
 320 /**
 321   Flushes all modified data to the physical device.
 322
 323   @param This        Indicates a pointer to the calling context.
 324   @param Token       A pointer to the token associated with the transaction.
 325                      If this field is NULL, synchronous/blocking IO is performed.
 326
 327   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was flushed successfully to the device.
 328                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
 329                                                                          Event will be signaled upon completion.
 330   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
 331   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
 332   @retval EFI_NO_MEDIA          There is no medium in the device.
 333   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 334 **/
 335 EFI_STATUS
 336 EFIAPI
 337 DiskIo2FlushDiskEx (
 338   IN EFI_DISK_IO2_PROTOCOL        *This,
 339   IN OUT EFI_DISK_IO2_TOKEN       *Token
 340   );
 341
 342 //
 343 // EFI Component Name Functions
 344 //
 345 /**
 346   Retrieves a Unicode string that is the user readable name of the driver.
 347
 348   This function retrieves the user readable name of a driver in the form of a
 349   Unicode string. If the driver specified by This has a user readable name in
 350   the language specified by Language, then a pointer to the driver name is
 351   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 352   by This does not support the language specified by Language,
 353   then EFI_UNSUPPORTED is returned.
 354
 355   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 356                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 357
 358   @param  Language[in]          A pointer to a Null-terminated ASCII string
 359                                 array indicating the language. This is the
 360                                 language of the driver name that the caller is
 361                                 requesting, and it must match one of the
 362                                 languages specified in SupportedLanguages. The
 363                                 number of languages supported by a driver is up
 364                                 to the driver writer. Language is specified
 365                                 in RFC 4646 or ISO 639-2 language code format.
 366
 367   @param  DriverName[out]       A pointer to the Unicode string to return.
 368                                 This Unicode string is the name of the
 369                                 driver specified by This in the language
 370                                 specified by Language.
 371
 372   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 373                                 This and the language specified by Language was
 374                                 returned in DriverName.
 375
 376   @retval EFI_INVALID_PARAMETER Language is NULL.
 377
 378   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 379
 380   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 381                                 the language specified by Language.
 382
 383 **/
 384 EFI_STATUS
 385 EFIAPI
 386 DiskIoComponentNameGetDriverName (
 387   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 388   IN  CHAR8                        *Language,
 389   OUT CHAR16                       **DriverName
 390   );
 391
 392
 393 /**
 394   Retrieves a Unicode string that is the user readable name of the controller
 395   that is being managed by a driver.
 396
 397   This function retrieves the user readable name of the controller specified by
 398   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 399   driver specified by This has a user readable name in the language specified by
 400   Language, then a pointer to the controller name is returned in ControllerName,
 401   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 402   managing the controller specified by ControllerHandle and ChildHandle,
 403   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 404   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 405
 406   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 407                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 408
 409   @param  ControllerHandle[in]  The handle of a controller that the driver
 410                                 specified by This is managing.  This handle
 411                                 specifies the controller whose name is to be
 412                                 returned.
 413
 414   @param  ChildHandle[in]       The handle of the child controller to retrieve
 415                                 the name of.  This is an optional parameter that
 416                                 may be NULL.  It will be NULL for device
 417                                 drivers.  It will also be NULL for a bus drivers
 418                                 that wish to retrieve the name of the bus
 419                                 controller.  It will not be NULL for a bus
 420                                 driver that wishes to retrieve the name of a
 421                                 child controller.
 422
 423   @param  Language[in]          A pointer to a Null-terminated ASCII string
 424                                 array indicating the language.  This is the
 425                                 language of the driver name that the caller is
 426                                 requesting, and it must match one of the
 427                                 languages specified in SupportedLanguages. The
 428                                 number of languages supported by a driver is up
 429                                 to the driver writer. Language is specified in
 430                                 RFC 4646 or ISO 639-2 language code format.
 431
 432   @param  ControllerName[out]   A pointer to the Unicode string to return.
 433                                 This Unicode string is the name of the
 434                                 controller specified by ControllerHandle and
 435                                 ChildHandle in the language specified by
 436                                 Language from the point of view of the driver
 437                                 specified by This.
 438
 439   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 440                                 the language specified by Language for the
 441                                 driver specified by This was returned in
 442                                 DriverName.
 443
 444   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 445
 446   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 447                                 EFI_HANDLE.
 448
 449   @retval EFI_INVALID_PARAMETER Language is NULL.
 450
 451   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 452
 453   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 454                                 managing the controller specified by
 455                                 ControllerHandle and ChildHandle.
 456
 457   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 458                                 the language specified by Language.
 459
 460 **/
 461 EFI_STATUS
 462 EFIAPI
 463 DiskIoComponentNameGetControllerName (
 464   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 465   IN  EFI_HANDLE                                      ControllerHandle,
 466   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 467   IN  CHAR8                                           *Language,
 468   OUT CHAR16                                          **ControllerName
 469   );
 470
 471
 472 #endif