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