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