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