MdePkg/Include/Protocol/DiskIo2.h

   1 /** @file
   2   Disk I/O 2 protocol as defined in the UEFI 2.4 specification.
   3
   4   The Disk I/O 2 protocol defines an extension to the Disk I/O protocol to enable
   5   non-blocking / asynchronous byte-oriented disk operation.
   6
   7   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __DISK_IO2_H__
  13 #define __DISK_IO2_H__
  14
  15 #define EFI_DISK_IO2_PROTOCOL_GUID \
  16   { \
  17     0x151c8eae, 0x7f2c, 0x472c, 0x9e, 0x54, 0x98, 0x28, 0x19, 0x4f, 0x6a, 0x88 \
  18   }
  19
  20 typedef struct _EFI_DISK_IO2_PROTOCOL EFI_DISK_IO2_PROTOCOL;
  21
  22 /**
  23   The struct of Disk IO2 Token.
  24 **/
  25 typedef struct {
  26   //
  27   // If Event is NULL, then blocking I/O is performed.
  28   // If Event is not NULL and non-blocking I/O is supported, then non-blocking I/O is performed,
  29   // and Event will be signaled when the I/O request is completed.
  30   // The caller must be prepared to handle the case where the callback associated with Event occurs
  31   // before the original asynchronous I/O request call returns.
  32   //
  33   EFI_EVENT  Event;
  34
  35   //
  36   // Defines whether or not the signaled event encountered an error.
  37   //
  38   EFI_STATUS TransactionStatus;
  39 } EFI_DISK_IO2_TOKEN;
  40
  41 /**
  42   Terminate outstanding asynchronous requests to a device.
  43
  44   @param This                   Indicates a pointer to the calling context.
  45
  46   @retval EFI_SUCCESS           All outstanding requests were successfully terminated.
  47   @retval EFI_DEVICE_ERROR      The device reported an error while performing the cancel
  48                                 operation.
  49 **/
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EFI_DISK_CANCEL_EX) (
  53   IN EFI_DISK_IO2_PROTOCOL *This
  54   );
  55
  56 /**
  57   Reads a specified number of bytes from a device.
  58
  59   @param This                   Indicates a pointer to the calling context.
  60   @param MediaId                ID of the medium to be read.
  61   @param Offset                 The starting byte offset on the logical block I/O device to read from.
  62   @param Token                  A pointer to the token associated with the transaction.
  63                                 If this field is NULL, synchronous/blocking IO is performed.
  64   @param  BufferSize            The size in bytes of Buffer. The number of bytes to read from the device.
  65   @param  Buffer                A pointer to the destination buffer for the data.
  66                                 The caller is responsible either having implicit or explicit ownership of the buffer.
  67
  68   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was read correctly from the device.
  69                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
  70                                                                          Event will be signaled upon completion.
  71   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
  72   @retval EFI_NO_MEDIA          There is no medium in the device.
  73   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
  74   @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not valid for the device.
  75   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  76
  77 **/
  78 typedef
  79 EFI_STATUS
  80 (EFIAPI *EFI_DISK_READ_EX) (
  81   IN EFI_DISK_IO2_PROTOCOL        *This,
  82   IN UINT32                       MediaId,
  83   IN UINT64                       Offset,
  84   IN OUT EFI_DISK_IO2_TOKEN       *Token,
  85   IN UINTN                        BufferSize,
  86   OUT VOID                        *Buffer
  87   );
  88
  89 /**
  90   Writes a specified number of bytes to a device.
  91
  92   @param This        Indicates a pointer to the calling context.
  93   @param MediaId     ID of the medium to be written.
  94   @param Offset      The starting byte offset on the logical block I/O device to write to.
  95   @param Token       A pointer to the token associated with the transaction.
  96                      If this field is NULL, synchronous/blocking IO is performed.
  97   @param BufferSize  The size in bytes of Buffer. The number of bytes to write to the device.
  98   @param Buffer      A pointer to the buffer containing the data to be written.
  99
 100   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was written correctly to the device.
 101                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
 102                                                                          Event will be signaled upon completion.
 103   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
 104   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
 105   @retval EFI_NO_MEDIA          There is no medium in the device.
 106   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
 107   @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not valid for the device.
 108   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 109
 110 **/
 111 typedef
 112 EFI_STATUS
 113 (EFIAPI *EFI_DISK_WRITE_EX) (
 114   IN EFI_DISK_IO2_PROTOCOL        *This,
 115   IN UINT32                       MediaId,
 116   IN UINT64                       Offset,
 117   IN OUT EFI_DISK_IO2_TOKEN       *Token,
 118   IN UINTN                        BufferSize,
 119   IN VOID                         *Buffer
 120   );
 121
 122 /**
 123   Flushes all modified data to the physical device.
 124
 125   @param This        Indicates a pointer to the calling context.
 126   @param MediaId     ID of the medium to be written.
 127   @param Token       A pointer to the token associated with the transaction.
 128                      If this field is NULL, synchronous/blocking IO is performed.
 129
 130   @retval EFI_SUCCESS           If Event is NULL (blocking I/O): The data was flushed successfully to the device.
 131                                 If Event is not NULL (asynchronous I/O): The request was successfully queued for processing.
 132                                                                          Event will be signaled upon completion.
 133   @retval EFI_WRITE_PROTECTED   The device cannot be written to.
 134   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write operation.
 135   @retval EFI_NO_MEDIA          There is no medium in the device.
 136   @retval EFI_MEDIA_CHNAGED     The MediaId is not for the current medium.
 137   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 138 **/
 139 typedef
 140 EFI_STATUS
 141 (EFIAPI *EFI_DISK_FLUSH_EX) (
 142   IN EFI_DISK_IO2_PROTOCOL        *This,
 143   IN OUT EFI_DISK_IO2_TOKEN       *Token
 144   );
 145
 146 #define EFI_DISK_IO2_PROTOCOL_REVISION 0x00020000
 147
 148 ///
 149 /// This protocol is used to abstract Block I/O interfaces.
 150 ///
 151 struct _EFI_DISK_IO2_PROTOCOL {
 152   ///
 153   /// The revision to which the disk I/O interface adheres. All future
 154   /// revisions must be backwards compatible. If a future version is not
 155   /// backwards compatible, it is not the same GUID.
 156   ///
 157   UINT64             Revision;
 158   EFI_DISK_CANCEL_EX Cancel;
 159   EFI_DISK_READ_EX   ReadDiskEx;
 160   EFI_DISK_WRITE_EX  WriteDiskEx;
 161   EFI_DISK_FLUSH_EX  FlushDiskEx;
 162 };
 163
 164 extern EFI_GUID gEfiDiskIo2ProtocolGuid;
 165
 166 #endif