1 /** @file 2 This file provides control over block-oriented firmware devices. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 @par Revision Reference: PI 8 Version 1.0 and 1.2. 9 10 **/ 11 12 #ifndef __FIRMWARE_VOLUME_BLOCK_H__ 13 #define __FIRMWARE_VOLUME_BLOCK_H__ 14 15 // 16 // EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL is defined in PI 1.0 spec and its GUID value 17 // is later updated to be the same as that of EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL 18 // defined in PI 1.2 spec. 19 // 20 #define EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL_GUID \ 21 { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } } 22 23 #define EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL_GUID \ 24 { 0x8f644fa9, 0xe850, 0x4db1, {0x9c, 0xe2, 0xb, 0x44, 0x69, 0x8e, 0x8d, 0xa4 } } 25 26 typedef struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL; 27 28 typedef EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL; 29 30 /** 31 The GetAttributes() function retrieves the attributes and 32 current settings of the block. 33 34 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 35 36 @param Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the 37 attributes and current settings are 38 returned. Type EFI_FVB_ATTRIBUTES_2 is defined 39 in EFI_FIRMWARE_VOLUME_HEADER. 40 41 @retval EFI_SUCCESS The firmware volume attributes were 42 returned. 43 44 **/ 45 typedef 46 EFI_STATUS 47 (EFIAPI * EFI_FVB_GET_ATTRIBUTES)( 48 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 49 OUT EFI_FVB_ATTRIBUTES_2 *Attributes 50 ); 51 52 53 /** 54 The SetAttributes() function sets configurable firmware volume 55 attributes and returns the new settings of the firmware volume. 56 57 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 58 59 @param Attributes On input, Attributes is a pointer to 60 EFI_FVB_ATTRIBUTES_2 that contains the 61 desired firmware volume settings. On 62 successful return, it contains the new 63 settings of the firmware volume. Type 64 EFI_FVB_ATTRIBUTES_2 is defined in 65 EFI_FIRMWARE_VOLUME_HEADER. 66 67 @retval EFI_SUCCESS The firmware volume attributes were returned. 68 69 @retval EFI_INVALID_PARAMETER The attributes requested are in 70 conflict with the capabilities 71 as declared in the firmware 72 volume header. 73 74 **/ 75 typedef 76 EFI_STATUS 77 (EFIAPI * EFI_FVB_SET_ATTRIBUTES)( 78 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 79 IN OUT EFI_FVB_ATTRIBUTES_2 *Attributes 80 ); 81 82 83 /** 84 The GetPhysicalAddress() function retrieves the base address of 85 a memory-mapped firmware volume. This function should be called 86 only for memory-mapped firmware volumes. 87 88 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 89 90 @param Address Pointer to a caller-allocated 91 EFI_PHYSICAL_ADDRESS that, on successful 92 return from GetPhysicalAddress(), contains the 93 base address of the firmware volume. 94 95 @retval EFI_SUCCESS The firmware volume base address was returned. 96 97 @retval EFI_UNSUPPORTED The firmware volume is not memory mapped. 98 99 **/ 100 typedef 101 EFI_STATUS 102 (EFIAPI * EFI_FVB_GET_PHYSICAL_ADDRESS)( 103 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 104 OUT EFI_PHYSICAL_ADDRESS *Address 105 ); 106 107 /** 108 The GetBlockSize() function retrieves the size of the requested 109 block. It also returns the number of additional blocks with 110 the identical size. The GetBlockSize() function is used to 111 retrieve the block map (see EFI_FIRMWARE_VOLUME_HEADER). 112 113 114 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 115 116 @param Lba Indicates the block for which to return the size. 117 118 @param BlockSize Pointer to a caller-allocated UINTN in which 119 the size of the block is returned. 120 121 @param NumberOfBlocks Pointer to a caller-allocated UINTN in 122 which the number of consecutive blocks, 123 starting with Lba, is returned. All 124 blocks in this range have a size of 125 BlockSize. 126 127 128 @retval EFI_SUCCESS The firmware volume base address was returned. 129 130 @retval EFI_INVALID_PARAMETER The requested LBA is out of range. 131 132 **/ 133 typedef 134 EFI_STATUS 135 (EFIAPI * EFI_FVB_GET_BLOCK_SIZE)( 136 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 137 IN EFI_LBA Lba, 138 OUT UINTN *BlockSize, 139 OUT UINTN *NumberOfBlocks 140 ); 141 142 143 /** 144 Reads the specified number of bytes into a buffer from the specified block. 145 146 The Read() function reads the requested number of bytes from the 147 requested block and stores them in the provided buffer. 148 Implementations should be mindful that the firmware volume 149 might be in the ReadDisabled state. If it is in this state, 150 the Read() function must return the status code 151 EFI_ACCESS_DENIED without modifying the contents of the 152 buffer. The Read() function must also prevent spanning block 153 boundaries. If a read is requested that would span a block 154 boundary, the read must read up to the boundary but not 155 beyond. The output parameter NumBytes must be set to correctly 156 indicate the number of bytes actually read. The caller must be 157 aware that a read may be partially completed. 158 159 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 160 161 @param Lba The starting logical block index 162 from which to read. 163 164 @param Offset Offset into the block at which to begin reading. 165 166 @param NumBytes Pointer to a UINTN. At entry, *NumBytes 167 contains the total size of the buffer. At 168 exit, *NumBytes contains the total number of 169 bytes read. 170 171 @param Buffer Pointer to a caller-allocated buffer that will 172 be used to hold the data that is read. 173 174 @retval EFI_SUCCESS The firmware volume was read successfully, 175 and contents are in Buffer. 176 177 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA 178 boundary. On output, NumBytes 179 contains the total number of bytes 180 returned in Buffer. 181 182 @retval EFI_ACCESS_DENIED The firmware volume is in the 183 ReadDisabled state. 184 185 @retval EFI_DEVICE_ERROR The block device is not 186 functioning correctly and could 187 not be read. 188 189 **/ 190 typedef 191 EFI_STATUS 192 (EFIAPI *EFI_FVB_READ)( 193 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 194 IN EFI_LBA Lba, 195 IN UINTN Offset, 196 IN OUT UINTN *NumBytes, 197 IN OUT UINT8 *Buffer 198 ); 199 200 /** 201 Writes the specified number of bytes from the input buffer to the block. 202 203 The Write() function writes the specified number of bytes from 204 the provided buffer to the specified block and offset. If the 205 firmware volume is sticky write, the caller must ensure that 206 all the bits of the specified range to write are in the 207 EFI_FVB_ERASE_POLARITY state before calling the Write() 208 function, or else the result will be unpredictable. This 209 unpredictability arises because, for a sticky-write firmware 210 volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY 211 state but cannot flip it back again. Before calling the 212 Write() function, it is recommended for the caller to first call 213 the EraseBlocks() function to erase the specified block to 214 write. A block erase cycle will transition bits from the 215 (NOT)EFI_FVB_ERASE_POLARITY state back to the 216 EFI_FVB_ERASE_POLARITY state. Implementations should be 217 mindful that the firmware volume might be in the WriteDisabled 218 state. If it is in this state, the Write() function must 219 return the status code EFI_ACCESS_DENIED without modifying the 220 contents of the firmware volume. The Write() function must 221 also prevent spanning block boundaries. If a write is 222 requested that spans a block boundary, the write must store up 223 to the boundary but not beyond. The output parameter NumBytes 224 must be set to correctly indicate the number of bytes actually 225 written. The caller must be aware that a write may be 226 partially completed. All writes, partial or otherwise, must be 227 fully flushed to the hardware before the Write() service 228 returns. 229 230 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL instance. 231 232 @param Lba The starting logical block index to write to. 233 234 @param Offset Offset into the block at which to begin writing. 235 236 @param NumBytes The pointer to a UINTN. At entry, *NumBytes 237 contains the total size of the buffer. At 238 exit, *NumBytes contains the total number of 239 bytes actually written. 240 241 @param Buffer The pointer to a caller-allocated buffer that 242 contains the source for the write. 243 244 @retval EFI_SUCCESS The firmware volume was written successfully. 245 246 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an 247 LBA boundary. On output, NumBytes 248 contains the total number of bytes 249 actually written. 250 251 @retval EFI_ACCESS_DENIED The firmware volume is in the 252 WriteDisabled state. 253 254 @retval EFI_DEVICE_ERROR The block device is malfunctioning 255 and could not be written. 256 257 258 **/ 259 typedef 260 EFI_STATUS 261 (EFIAPI * EFI_FVB_WRITE)( 262 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 263 IN EFI_LBA Lba, 264 IN UINTN Offset, 265 IN OUT UINTN *NumBytes, 266 IN UINT8 *Buffer 267 ); 268 269 270 271 272 /// 273 /// EFI_LBA_LIST_TERMINATOR 274 /// 275 #define EFI_LBA_LIST_TERMINATOR 0xFFFFFFFFFFFFFFFFULL 276 277 278 /** 279 Erases and initializes a firmware volume block. 280 281 The EraseBlocks() function erases one or more blocks as denoted 282 by the variable argument list. The entire parameter list of 283 blocks must be verified before erasing any blocks. If a block is 284 requested that does not exist within the associated firmware 285 volume (it has a larger index than the last block of the 286 firmware volume), the EraseBlocks() function must return the 287 status code EFI_INVALID_PARAMETER without modifying the contents 288 of the firmware volume. Implementations should be mindful that 289 the firmware volume might be in the WriteDisabled state. If it 290 is in this state, the EraseBlocks() function must return the 291 status code EFI_ACCESS_DENIED without modifying the contents of 292 the firmware volume. All calls to EraseBlocks() must be fully 293 flushed to the hardware before the EraseBlocks() service 294 returns. 295 296 @param This Indicates the EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL 297 instance. 298 299 @param ... The variable argument list is a list of tuples. 300 Each tuple describes a range of LBAs to erase 301 and consists of the following: 302 - An EFI_LBA that indicates the starting LBA 303 - A UINTN that indicates the number of blocks to 304 erase. 305 306 The list is terminated with an 307 EFI_LBA_LIST_TERMINATOR. For example, the 308 following indicates that two ranges of blocks 309 (5-7 and 10-11) are to be erased: EraseBlocks 310 (This, 5, 3, 10, 2, EFI_LBA_LIST_TERMINATOR); 311 312 @retval EFI_SUCCESS The erase request successfully 313 completed. 314 315 @retval EFI_ACCESS_DENIED The firmware volume is in the 316 WriteDisabled state. 317 @retval EFI_DEVICE_ERROR The block device is not functioning 318 correctly and could not be written. 319 The firmware device may have been 320 partially erased. 321 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed 322 in the variable argument list do 323 not exist in the firmware volume. 324 325 **/ 326 typedef 327 EFI_STATUS 328 (EFIAPI * EFI_FVB_ERASE_BLOCKS)( 329 IN CONST EFI_FIRMWARE_VOLUME_BLOCK2_PROTOCOL *This, 330 ... 331 ); 332 333 /// 334 /// The Firmware Volume Block Protocol is the low-level interface 335 /// to a firmware volume. File-level access to a firmware volume 336 /// should not be done using the Firmware Volume Block Protocol. 337 /// Normal access to a firmware volume must use the Firmware 338 /// Volume Protocol. Typically, only the file system driver that 339 /// produces the Firmware Volume Protocol will bind to the 340 /// Firmware Volume Block Protocol. 341 /// 342 struct _EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL{ 343 EFI_FVB_GET_ATTRIBUTES GetAttributes; 344 EFI_FVB_SET_ATTRIBUTES SetAttributes; 345 EFI_FVB_GET_PHYSICAL_ADDRESS GetPhysicalAddress; 346 EFI_FVB_GET_BLOCK_SIZE GetBlockSize; 347 EFI_FVB_READ Read; 348 EFI_FVB_WRITE Write; 349 EFI_FVB_ERASE_BLOCKS EraseBlocks; 350 /// 351 /// The handle of the parent firmware volume. 352 /// 353 EFI_HANDLE ParentHandle; 354 }; 355 356 357 extern EFI_GUID gEfiFirmwareVolumeBlockProtocolGuid; 358 extern EFI_GUID gEfiFirmwareVolumeBlock2ProtocolGuid; 359 360 #endif 361