1 /** @file 2 Firmware File System protocol. Layers on top of Firmware 3 Block protocol to produce a file abstraction of FV based files. 4 5 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 **/ 15 16 #ifndef __FW_VOL_DRIVER_H_ 17 #define __FW_VOL_DRIVER_H_ 18 19 20 #define FV2_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '2') 21 22 // 23 // Used to track all non-deleted files 24 // 25 typedef struct { 26 LIST_ENTRY Link; 27 EFI_FFS_FILE_HEADER *FfsHeader; 28 UINTN StreamHandle; 29 BOOLEAN FileCached; 30 } FFS_FILE_LIST_ENTRY; 31 32 typedef struct { 33 UINTN Signature; 34 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb; 35 EFI_HANDLE Handle; 36 EFI_FIRMWARE_VOLUME2_PROTOCOL Fv; 37 38 EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader; 39 UINT8 *CachedFv; 40 UINT8 *EndOfCachedFv; 41 42 FFS_FILE_LIST_ENTRY *LastKey; 43 44 LIST_ENTRY FfsFileListHeader; 45 46 UINT32 AuthenticationStatus; 47 UINT8 ErasePolarity; 48 BOOLEAN IsFfs3Fv; 49 BOOLEAN IsMemoryMapped; 50 } FV_DEVICE; 51 52 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE) 53 54 /** 55 Retrieves attributes, insures positive polarity of attribute bits, returns 56 resulting attributes in output parameter. 57 58 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 59 @param Attributes output buffer which contains attributes. 60 61 @retval EFI_SUCCESS Successfully got volume attributes. 62 63 **/ 64 EFI_STATUS 65 EFIAPI 66 FvGetVolumeAttributes ( 67 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 68 OUT EFI_FV_ATTRIBUTES *Attributes 69 ); 70 71 72 /** 73 Sets current attributes for volume 74 75 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 76 @param Attributes At input, contains attributes to be set. At output 77 contains new value of FV. 78 79 @retval EFI_UNSUPPORTED Could not be set. 80 81 **/ 82 EFI_STATUS 83 EFIAPI 84 FvSetVolumeAttributes ( 85 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 86 IN OUT EFI_FV_ATTRIBUTES *Attributes 87 ); 88 89 90 /** 91 Given the input key, search for the next matching file in the volume. 92 93 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 94 @param Key Key is a pointer to a caller allocated 95 buffer that contains implementation specific 96 data that is used to track where to begin 97 the search for the next file. The size of 98 the buffer must be at least This->KeySize 99 bytes long. To reinitialize the search and 100 begin from the beginning of the firmware 101 volume, the entire buffer must be cleared to 102 zero. Other than clearing the buffer to 103 initiate a new search, the caller must not 104 modify the data in the buffer between calls 105 to GetNextFile(). 106 @param FileType FileType is a pointer to a caller allocated 107 EFI_FV_FILETYPE. The GetNextFile() API can 108 filter it's search for files based on the 109 value of *FileType input. A *FileType input 110 of 0 causes GetNextFile() to search for 111 files of all types. If a file is found, the 112 file's type is returned in *FileType. 113 *FileType is not modified if no file is 114 found. 115 @param NameGuid NameGuid is a pointer to a caller allocated 116 EFI_GUID. If a file is found, the file's 117 name is returned in *NameGuid. *NameGuid is 118 not modified if no file is found. 119 @param Attributes Attributes is a pointer to a caller 120 allocated EFI_FV_FILE_ATTRIBUTES. If a file 121 is found, the file's attributes are returned 122 in *Attributes. *Attributes is not modified 123 if no file is found. 124 @param Size Size is a pointer to a caller allocated 125 UINTN. If a file is found, the file's size 126 is returned in *Size. *Size is not modified 127 if no file is found. 128 129 @retval EFI_SUCCESS Successfully find the file. 130 @retval EFI_DEVICE_ERROR Device error. 131 @retval EFI_ACCESS_DENIED Fv could not read. 132 @retval EFI_NOT_FOUND No matching file found. 133 @retval EFI_INVALID_PARAMETER Invalid parameter 134 135 **/ 136 EFI_STATUS 137 EFIAPI 138 FvGetNextFile ( 139 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 140 IN OUT VOID *Key, 141 IN OUT EFI_FV_FILETYPE *FileType, 142 OUT EFI_GUID *NameGuid, 143 OUT EFI_FV_FILE_ATTRIBUTES *Attributes, 144 OUT UINTN *Size 145 ); 146 147 148 149 /** 150 Locates a file in the firmware volume and 151 copies it to the supplied buffer. 152 153 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 154 @param NameGuid Pointer to an EFI_GUID, which is the 155 filename. 156 @param Buffer Buffer is a pointer to pointer to a buffer 157 in which the file or section contents or are 158 returned. 159 @param BufferSize BufferSize is a pointer to caller allocated 160 UINTN. On input *BufferSize indicates the 161 size in bytes of the memory region pointed 162 to by Buffer. On output, *BufferSize 163 contains the number of bytes required to 164 read the file. 165 @param FoundType FoundType is a pointer to a caller allocated 166 EFI_FV_FILETYPE that on successful return 167 from Read() contains the type of file read. 168 This output reflects the file type 169 irrespective of the value of the SectionType 170 input. 171 @param FileAttributes FileAttributes is a pointer to a caller 172 allocated EFI_FV_FILE_ATTRIBUTES. On 173 successful return from Read(), 174 *FileAttributes contains the attributes of 175 the file read. 176 @param AuthenticationStatus AuthenticationStatus is a pointer to a 177 caller allocated UINTN in which the 178 authentication status is returned. 179 180 @retval EFI_SUCCESS Successfully read to memory buffer. 181 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small. 182 @retval EFI_NOT_FOUND Not found. 183 @retval EFI_DEVICE_ERROR Device error. 184 @retval EFI_ACCESS_DENIED Could not read. 185 @retval EFI_INVALID_PARAMETER Invalid parameter. 186 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated. 187 188 **/ 189 EFI_STATUS 190 EFIAPI 191 FvReadFile ( 192 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 193 IN CONST EFI_GUID *NameGuid, 194 IN OUT VOID **Buffer, 195 IN OUT UINTN *BufferSize, 196 OUT EFI_FV_FILETYPE *FoundType, 197 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, 198 OUT UINT32 *AuthenticationStatus 199 ); 200 201 202 /** 203 Locates a section in a given FFS File and 204 copies it to the supplied buffer (not including section header). 205 206 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 207 @param NameGuid Pointer to an EFI_GUID, which is the 208 filename. 209 @param SectionType Indicates the section type to return. 210 @param SectionInstance Indicates which instance of sections with a 211 type of SectionType to return. 212 @param Buffer Buffer is a pointer to pointer to a buffer 213 in which the file or section contents or are 214 returned. 215 @param BufferSize BufferSize is a pointer to caller allocated 216 UINTN. 217 @param AuthenticationStatus AuthenticationStatus is a pointer to a 218 caller allocated UINT32 in which the 219 authentication status is returned. 220 221 @retval EFI_SUCCESS Successfully read the file section into 222 buffer. 223 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small. 224 @retval EFI_NOT_FOUND Section not found. 225 @retval EFI_DEVICE_ERROR Device error. 226 @retval EFI_ACCESS_DENIED Could not read. 227 @retval EFI_INVALID_PARAMETER Invalid parameter. 228 229 **/ 230 EFI_STATUS 231 EFIAPI 232 FvReadFileSection ( 233 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 234 IN CONST EFI_GUID *NameGuid, 235 IN EFI_SECTION_TYPE SectionType, 236 IN UINTN SectionInstance, 237 IN OUT VOID **Buffer, 238 IN OUT UINTN *BufferSize, 239 OUT UINT32 *AuthenticationStatus 240 ); 241 242 243 /** 244 Writes one or more files to the firmware volume. 245 246 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 247 @param NumberOfFiles Number of files. 248 @param WritePolicy WritePolicy indicates the level of reliability 249 for the write in the event of a power failure or 250 other system failure during the write operation. 251 @param FileData FileData is an pointer to an array of 252 EFI_FV_WRITE_DATA. Each element of array 253 FileData represents a file to be written. 254 255 @retval EFI_SUCCESS Files successfully written to firmware volume 256 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated. 257 @retval EFI_DEVICE_ERROR Device error. 258 @retval EFI_WRITE_PROTECTED Write protected. 259 @retval EFI_NOT_FOUND Not found. 260 @retval EFI_INVALID_PARAMETER Invalid parameter. 261 @retval EFI_UNSUPPORTED This function not supported. 262 263 **/ 264 EFI_STATUS 265 EFIAPI 266 FvWriteFile ( 267 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 268 IN UINT32 NumberOfFiles, 269 IN EFI_FV_WRITE_POLICY WritePolicy, 270 IN EFI_FV_WRITE_FILE_DATA *FileData 271 ); 272 273 274 /** 275 Return information of type InformationType for the requested firmware 276 volume. 277 278 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 279 @param InformationType InformationType for requested. 280 @param BufferSize On input, size of Buffer.On output, the amount of data 281 returned in Buffer. 282 @param Buffer A poniter to the data buffer to return. 283 284 @retval EFI_SUCCESS Successfully got volume Information. 285 286 **/ 287 EFI_STATUS 288 EFIAPI 289 FvGetVolumeInfo ( 290 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 291 IN CONST EFI_GUID *InformationType, 292 IN OUT UINTN *BufferSize, 293 OUT VOID *Buffer 294 ); 295 296 297 298 /** 299 Set information of type InformationType for the requested firmware 300 volume. 301 302 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL. 303 @param InformationType InformationType for requested. 304 @param BufferSize On input, size of Buffer.On output, the amount of data 305 returned in Buffer. 306 @param Buffer A poniter to the data buffer to return. 307 308 @retval EFI_SUCCESS Successfully set volume Information. 309 310 **/ 311 EFI_STATUS 312 EFIAPI 313 FvSetVolumeInfo ( 314 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 315 IN CONST EFI_GUID *InformationType, 316 IN UINTN BufferSize, 317 IN CONST VOID *Buffer 318 ); 319 320 321 322 /** 323 Check if a block of buffer is erased. 324 325 @param ErasePolarity Erase polarity attribute of the firmware volume 326 @param InBuffer The buffer to be checked 327 @param BufferSize Size of the buffer in bytes 328 329 @retval TRUE The block of buffer is erased 330 @retval FALSE The block of buffer is not erased 331 332 **/ 333 BOOLEAN 334 IsBufferErased ( 335 IN UINT8 ErasePolarity, 336 IN VOID *InBuffer, 337 IN UINTN BufferSize 338 ); 339 340 341 /** 342 Get the FFS file state by checking the highest bit set in the header's state field. 343 344 @param ErasePolarity Erase polarity attribute of the firmware volume 345 @param FfsHeader Points to the FFS file header 346 347 @return FFS File state 348 349 **/ 350 EFI_FFS_FILE_STATE 351 GetFileState ( 352 IN UINT8 ErasePolarity, 353 IN EFI_FFS_FILE_HEADER *FfsHeader 354 ); 355 356 357 /** 358 Set the FFS file state. 359 360 @param State The state to be set. 361 @param FfsHeader Points to the FFS file header 362 363 @return None. 364 365 **/ 366 VOID 367 SetFileState ( 368 IN UINT8 State, 369 IN EFI_FFS_FILE_HEADER *FfsHeader 370 ); 371 372 /** 373 Check if it's a valid FFS file header. 374 375 @param ErasePolarity Erase polarity attribute of the firmware volume 376 @param FfsHeader Points to the FFS file header to be checked 377 @param FileState FFS file state to be returned 378 379 @retval TRUE Valid FFS file header 380 @retval FALSE Invalid FFS file header 381 382 **/ 383 BOOLEAN 384 IsValidFfsHeader ( 385 IN UINT8 ErasePolarity, 386 IN EFI_FFS_FILE_HEADER *FfsHeader, 387 OUT EFI_FFS_FILE_STATE *FileState 388 ); 389 390 391 /** 392 Check if it's a valid FFS file. 393 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first. 394 395 @param ErasePolarity Erase polarity attribute of the firmware volume 396 @param FfsHeader Points to the FFS file to be checked 397 398 @retval TRUE Valid FFS file 399 @retval FALSE Invalid FFS file 400 401 **/ 402 BOOLEAN 403 IsValidFfsFile ( 404 IN UINT8 ErasePolarity, 405 IN EFI_FFS_FILE_HEADER *FfsHeader 406 ); 407 408 #endif 409