MdePkg/Include/Protocol/BlockIo2.h

   1 /** @file
   2   Block IO2 protocol as defined in the UEFI 2.3.1 specification.
   3
   4   The Block IO2 protocol defines an extension to the Block IO protocol which
   5   enables the ability to read and write data at a block level in a non-blocking
   6   manner.
   7
   8   Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __BLOCK_IO2_H__
  14 #define __BLOCK_IO2_H__
  15
  16 #include <Protocol/BlockIo.h>
  17
  18 #define EFI_BLOCK_IO2_PROTOCOL_GUID \
  19   { \
  20     0xa77b2472, 0xe282, 0x4e9f, {0xa2, 0x45, 0xc2, 0xc0, 0xe2, 0x7b, 0xbc, 0xc1} \
  21   }
  22
  23 typedef struct _EFI_BLOCK_IO2_PROTOCOL  EFI_BLOCK_IO2_PROTOCOL;
  24
  25 /**
  26   The struct of Block IO2 Token.
  27 **/
  28 typedef struct {
  29
  30   ///
  31   /// If Event is NULL, then blocking I/O is performed.If Event is not NULL and
  32   /// non-blocking I/O is supported, then non-blocking I/O is performed, and
  33   /// Event will be signaled when the read request is completed.
  34   ///
  35   EFI_EVENT               Event;
  36
  37   ///
  38   /// Defines whether or not the signaled event encountered an error.
  39   ///
  40   EFI_STATUS              TransactionStatus;
  41 } EFI_BLOCK_IO2_TOKEN;
  42
  43
  44 /**
  45   Reset the block device hardware.
  46
  47   @param[in]  This                 Indicates a pointer to the calling context.
  48   @param[in]  ExtendedVerification Indicates that the driver may perform a more
  49                                    exhausive verification operation of the device
  50                                    during reset.
  51
  52   @retval EFI_SUCCESS          The device was reset.
  53   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
  54                                not be reset.
  55
  56 **/
  57 typedef
  58 EFI_STATUS
  59 (EFIAPI *EFI_BLOCK_RESET_EX) (
  60   IN EFI_BLOCK_IO2_PROTOCOL  *This,
  61   IN BOOLEAN                 ExtendedVerification
  62   );
  63
  64 /**
  65   Read BufferSize bytes from Lba into Buffer.
  66
  67   This function reads the requested number of blocks from the device. All the
  68   blocks are read, or an error is returned.
  69   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and
  70   non-blocking I/O is being used, the Event associated with this request will
  71   not be signaled.
  72
  73   @param[in]       This       Indicates a pointer to the calling context.
  74   @param[in]       MediaId    Id of the media, changes every time the media is
  75                               replaced.
  76   @param[in]       Lba        The starting Logical Block Address to read from.
  77   @param[in, out]  Token      A pointer to the token associated with the transaction.
  78   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
  79   @param[out]      Buffer     A pointer to the destination buffer for the data. The
  80                               caller is responsible for either having implicit or
  81                               explicit ownership of the buffer.
  82
  83   @retval EFI_SUCCESS           The read request was queued if Token->Event is
  84                                 not NULL.The data was read correctly from the
  85                                 device if the Token->Event is NULL.
  86   @retval EFI_DEVICE_ERROR      The device reported an error while performing
  87                                 the read.
  88   @retval EFI_NO_MEDIA          There is no media in the device.
  89   @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.
  90   @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of the
  91                                 intrinsic block size of the device.
  92   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  93                                 or the buffer is not on proper alignment.
  94   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
  95                                 of resources.
  96 **/
  97 typedef
  98 EFI_STATUS
  99 (EFIAPI *EFI_BLOCK_READ_EX) (
 100   IN     EFI_BLOCK_IO2_PROTOCOL *This,
 101   IN     UINT32                 MediaId,
 102   IN     EFI_LBA                LBA,
 103   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 104   IN     UINTN                  BufferSize,
 105      OUT VOID                  *Buffer
 106   );
 107
 108 /**
 109   Write BufferSize bytes from Lba into Buffer.
 110
 111   This function writes the requested number of blocks to the device. All blocks
 112   are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA,
 113   EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is
 114   being used, the Event associated with this request will not be signaled.
 115
 116   @param[in]       This       Indicates a pointer to the calling context.
 117   @param[in]       MediaId    The media ID that the write request is for.
 118   @param[in]       Lba        The starting logical block address to be written. The
 119                               caller is responsible for writing to only legitimate
 120                               locations.
 121   @param[in, out]  Token      A pointer to the token associated with the transaction.
 122   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
 123   @param[in]       Buffer     A pointer to the source buffer for the data.
 124
 125   @retval EFI_SUCCESS           The write request was queued if Event is not NULL.
 126                                 The data was written correctly to the device if
 127                                 the Event is NULL.
 128   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 129   @retval EFI_NO_MEDIA          There is no media in the device.
 130   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 131   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 132   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
 133   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
 134                                 or the buffer is not on proper alignment.
 135   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
 136                                 of resources.
 137
 138 **/
 139 typedef
 140 EFI_STATUS
 141 (EFIAPI *EFI_BLOCK_WRITE_EX) (
 142   IN     EFI_BLOCK_IO2_PROTOCOL  *This,
 143   IN     UINT32                 MediaId,
 144   IN     EFI_LBA                LBA,
 145   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 146   IN     UINTN                  BufferSize,
 147   IN     VOID                   *Buffer
 148   );
 149
 150 /**
 151   Flush the Block Device.
 152
 153   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED
 154   is returned and non-blocking I/O is being used, the Event associated with
 155   this request will not be signaled.
 156
 157   @param[in]      This     Indicates a pointer to the calling context.
 158   @param[in,out]  Token    A pointer to the token associated with the transaction
 159
 160   @retval EFI_SUCCESS          The flush request was queued if Event is not NULL.
 161                                All outstanding data was written correctly to the
 162                                device if the Event is NULL.
 163   @retval EFI_DEVICE_ERROR     The device reported an error while writting back
 164                                the data.
 165   @retval EFI_WRITE_PROTECTED  The device cannot be written to.
 166   @retval EFI_NO_MEDIA         There is no media in the device.
 167   @retval EFI_MEDIA_CHANGED    The MediaId is not for the current media.
 168   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
 169                                of resources.
 170
 171 **/
 172 typedef
 173 EFI_STATUS
 174 (EFIAPI *EFI_BLOCK_FLUSH_EX) (
 175   IN     EFI_BLOCK_IO2_PROTOCOL   *This,
 176   IN OUT EFI_BLOCK_IO2_TOKEN      *Token
 177   );
 178
 179 ///
 180 ///  The Block I/O2 protocol defines an extension to the Block I/O protocol which
 181 ///  enables the ability to read and write data at a block level in a non-blocking
 182 //   manner.
 183 ///
 184 struct _EFI_BLOCK_IO2_PROTOCOL {
 185   ///
 186   /// A pointer to the EFI_BLOCK_IO_MEDIA data for this device.
 187   /// Type EFI_BLOCK_IO_MEDIA is defined in BlockIo.h.
 188   ///
 189   EFI_BLOCK_IO_MEDIA      *Media;
 190
 191   EFI_BLOCK_RESET_EX      Reset;
 192   EFI_BLOCK_READ_EX       ReadBlocksEx;
 193   EFI_BLOCK_WRITE_EX      WriteBlocksEx;
 194   EFI_BLOCK_FLUSH_EX      FlushBlocksEx;
 195 };
 196
 197 extern EFI_GUID gEfiBlockIo2ProtocolGuid;
 198
 199 #endif
 200