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