MdePkg/Include/Protocol/BlockIo.h

   1 /** @file
   2   Block IO protocol as defined in the UEFI 2.0 specification.
   3
   4   The Block IO protocol is used to abstract block devices like hard drives,
   5   DVD-ROMs and floppy drives.
   6
   7   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __BLOCK_IO_H__
  13 #define __BLOCK_IO_H__
  14
  15 #define EFI_BLOCK_IO_PROTOCOL_GUID \
  16   { \
  17     0x964e5b21, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
  18   }
  19
  20 typedef struct _EFI_BLOCK_IO_PROTOCOL  EFI_BLOCK_IO_PROTOCOL;
  21
  22 ///
  23 /// Protocol GUID name defined in EFI1.1.
  24 ///
  25 #define BLOCK_IO_PROTOCOL       EFI_BLOCK_IO_PROTOCOL_GUID
  26
  27 ///
  28 /// Protocol defined in EFI1.1.
  29 ///
  30 typedef EFI_BLOCK_IO_PROTOCOL   EFI_BLOCK_IO;
  31
  32 /**
  33   Reset the Block Device.
  34
  35   @param  This                 Indicates a pointer to the calling context.
  36   @param  ExtendedVerification Driver may perform diagnostics on reset.
  37
  38   @retval EFI_SUCCESS          The device was reset.
  39   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
  40                                not be reset.
  41
  42 **/
  43 typedef
  44 EFI_STATUS
  45 (EFIAPI *EFI_BLOCK_RESET)(
  46   IN EFI_BLOCK_IO_PROTOCOL          *This,
  47   IN BOOLEAN                        ExtendedVerification
  48   );
  49
  50 /**
  51   Read BufferSize bytes from Lba into Buffer.
  52
  53   @param  This       Indicates a pointer to the calling context.
  54   @param  MediaId    Id of the media, changes every time the media is replaced.
  55   @param  Lba        The starting Logical Block Address to read from
  56   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  57   @param  Buffer     A pointer to the destination buffer for the data. The caller is
  58                      responsible for either having implicit or explicit ownership of the buffer.
  59
  60   @retval EFI_SUCCESS           The data was read correctly from the device.
  61   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
  62   @retval EFI_NO_MEDIA          There is no media in the device.
  63   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
  64   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  65   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  66                                 or the buffer is not on proper alignment.
  67
  68 **/
  69 typedef
  70 EFI_STATUS
  71 (EFIAPI *EFI_BLOCK_READ)(
  72   IN EFI_BLOCK_IO_PROTOCOL          *This,
  73   IN UINT32                         MediaId,
  74   IN EFI_LBA                        Lba,
  75   IN UINTN                          BufferSize,
  76   OUT VOID                          *Buffer
  77   );
  78
  79 /**
  80   Write BufferSize bytes from Lba into Buffer.
  81
  82   @param  This       Indicates a pointer to the calling context.
  83   @param  MediaId    The media ID that the write request is for.
  84   @param  Lba        The starting logical block address to be written. The caller is
  85                      responsible for writing to only legitimate locations.
  86   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  87   @param  Buffer     A pointer to the source buffer for the data.
  88
  89   @retval EFI_SUCCESS           The data was written correctly to the device.
  90   @retval EFI_WRITE_PROTECTED   The device can not be written to.
  91   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
  92   @retval EFI_NO_MEDIA          There is no media in the device.
  93   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
  94   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  95   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
  96                                 or the buffer is not on proper alignment.
  97
  98 **/
  99 typedef
 100 EFI_STATUS
 101 (EFIAPI *EFI_BLOCK_WRITE)(
 102   IN EFI_BLOCK_IO_PROTOCOL          *This,
 103   IN UINT32                         MediaId,
 104   IN EFI_LBA                        Lba,
 105   IN UINTN                          BufferSize,
 106   IN VOID                           *Buffer
 107   );
 108
 109 /**
 110   Flush the Block Device.
 111
 112   @param  This              Indicates a pointer to the calling context.
 113
 114   @retval EFI_SUCCESS       All outstanding data was written to the device
 115   @retval EFI_DEVICE_ERROR  The device reported an error while writting back the data
 116   @retval EFI_NO_MEDIA      There is no media in the device.
 117
 118 **/
 119 typedef
 120 EFI_STATUS
 121 (EFIAPI *EFI_BLOCK_FLUSH)(
 122   IN EFI_BLOCK_IO_PROTOCOL  *This
 123   );
 124
 125 /**
 126   Block IO read only mode data and updated only via members of BlockIO
 127 **/
 128 typedef struct {
 129   ///
 130   /// The curent media Id. If the media changes, this value is changed.
 131   ///
 132   UINT32  MediaId;
 133
 134   ///
 135   /// TRUE if the media is removable; otherwise, FALSE.
 136   ///
 137   BOOLEAN RemovableMedia;
 138
 139   ///
 140   /// TRUE if there is a media currently present in the device;
 141   /// othersise, FALSE. THis field shows the media present status
 142   /// as of the most recent ReadBlocks() or WriteBlocks() call.
 143   ///
 144   BOOLEAN MediaPresent;
 145
 146   ///
 147   /// TRUE if LBA 0 is the first block of a partition; otherwise
 148   /// FALSE. For media with only one partition this would be TRUE.
 149   ///
 150   BOOLEAN LogicalPartition;
 151
 152   ///
 153   /// TRUE if the media is marked read-only otherwise, FALSE.
 154   /// This field shows the read-only status as of the most recent WriteBlocks () call.
 155   ///
 156   BOOLEAN ReadOnly;
 157
 158   ///
 159   /// TRUE if the WriteBlock () function caches write data.
 160   ///
 161   BOOLEAN WriteCaching;
 162
 163   ///
 164   /// The intrinsic block size of the device. If the media changes, then
 165   /// this field is updated.
 166   ///
 167   UINT32  BlockSize;
 168
 169   ///
 170   /// Supplies the alignment requirement for any buffer to read or write block(s).
 171   ///
 172   UINT32  IoAlign;
 173
 174   ///
 175   /// The last logical block address on the device.
 176   /// If the media changes, then this field is updated.
 177   ///
 178   EFI_LBA LastBlock;
 179
 180   ///
 181   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
 182   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to
 183   /// a physical block boundary.
 184   ///
 185   EFI_LBA LowestAlignedLba;
 186
 187   ///
 188   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
 189   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks
 190   /// per physical block.
 191   ///
 192   UINT32 LogicalBlocksPerPhysicalBlock;
 193
 194   ///
 195   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
 196   /// EFI_BLOCK_IO_PROTOCOL_REVISION3. Returns the optimal transfer length
 197   /// granularity as a number of logical blocks.
 198   ///
 199   UINT32 OptimalTransferLengthGranularity;
 200 } EFI_BLOCK_IO_MEDIA;
 201
 202 #define EFI_BLOCK_IO_PROTOCOL_REVISION  0x00010000
 203 #define EFI_BLOCK_IO_PROTOCOL_REVISION2 0x00020001
 204 #define EFI_BLOCK_IO_PROTOCOL_REVISION3 0x00020031
 205
 206 ///
 207 /// Revision defined in EFI1.1.
 208 ///
 209 #define EFI_BLOCK_IO_INTERFACE_REVISION   EFI_BLOCK_IO_PROTOCOL_REVISION
 210
 211 ///
 212 ///  This protocol provides control over block devices.
 213 ///
 214 struct _EFI_BLOCK_IO_PROTOCOL {
 215   ///
 216   /// The revision to which the block IO interface adheres. All future
 217   /// revisions must be backwards compatible. If a future version is not
 218   /// back wards compatible, it is not the same GUID.
 219   ///
 220   UINT64              Revision;
 221   ///
 222   /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device.
 223   ///
 224   EFI_BLOCK_IO_MEDIA  *Media;
 225
 226   EFI_BLOCK_RESET     Reset;
 227   EFI_BLOCK_READ      ReadBlocks;
 228   EFI_BLOCK_WRITE     WriteBlocks;
 229   EFI_BLOCK_FLUSH     FlushBlocks;
 230
 231 };
 232
 233 extern EFI_GUID gEfiBlockIoProtocolGuid;
 234
 235 #endif