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