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 0x0002001F 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 extern EFI_GUID gEfiBlockIoProtocolGuid; 233 234 #endif 235