1 /** @file 2 The Firmware Volume Protocol provides file-level access to the firmware volume. 3 Each firmware volume driver must produce an instance of the 4 Firmware Volume Protocol if the firmware volume is to be visible to 5 the system during the DXE phase. The Firmware Volume Protocol also provides 6 mechanisms for determining and modifying some attributes of the firmware volume. 7 8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 9 SPDX-License-Identifier: BSD-2-Clause-Patent 10 11 @par Revision Reference: PI 12 Version 1.00. 13 14 **/ 15 16 #ifndef __FIRMWARE_VOLUME2_H__ 17 #define __FIRMWARE_VOLUME2_H__ 18 19 #define EFI_FIRMWARE_VOLUME2_PROTOCOL_GUID \ 20 { 0x220e73b6, 0x6bdb, 0x4413, { 0x84, 0x5, 0xb9, 0x74, 0xb1, 0x8, 0x61, 0x9a } } 21 22 typedef struct _EFI_FIRMWARE_VOLUME2_PROTOCOL EFI_FIRMWARE_VOLUME2_PROTOCOL; 23 24 /// 25 /// EFI_FV_ATTRIBUTES 26 /// 27 typedef UINT64 EFI_FV_ATTRIBUTES; 28 29 // 30 // EFI_FV_ATTRIBUTES bit definitions 31 // 32 // EFI_FV_ATTRIBUTES bit semantics 33 #define EFI_FV2_READ_DISABLE_CAP 0x0000000000000001ULL 34 #define EFI_FV2_READ_ENABLE_CAP 0x0000000000000002ULL 35 #define EFI_FV2_READ_STATUS 0x0000000000000004ULL 36 #define EFI_FV2_WRITE_DISABLE_CAP 0x0000000000000008ULL 37 #define EFI_FV2_WRITE_ENABLE_CAP 0x0000000000000010ULL 38 #define EFI_FV2_WRITE_STATUS 0x0000000000000020ULL 39 #define EFI_FV2_LOCK_CAP 0x0000000000000040ULL 40 #define EFI_FV2_LOCK_STATUS 0x0000000000000080ULL 41 #define EFI_FV2_WRITE_POLICY_RELIABLE 0x0000000000000100ULL 42 #define EFI_FV2_READ_LOCK_CAP 0x0000000000001000ULL 43 #define EFI_FV2_READ_LOCK_STATUS 0x0000000000002000ULL 44 #define EFI_FV2_WRITE_LOCK_CAP 0x0000000000004000ULL 45 #define EFI_FV2_WRITE_LOCK_STATUS 0x0000000000008000ULL 46 #define EFI_FV2_ALIGNMENT 0x00000000001F0000ULL 47 #define EFI_FV2_ALIGNMENT_1 0x0000000000000000ULL 48 #define EFI_FV2_ALIGNMENT_2 0x0000000000010000ULL 49 #define EFI_FV2_ALIGNMENT_4 0x0000000000020000ULL 50 #define EFI_FV2_ALIGNMENT_8 0x0000000000030000ULL 51 #define EFI_FV2_ALIGNMENT_16 0x0000000000040000ULL 52 #define EFI_FV2_ALIGNMENT_32 0x0000000000050000ULL 53 #define EFI_FV2_ALIGNMENT_64 0x0000000000060000ULL 54 #define EFI_FV2_ALIGNMENT_128 0x0000000000070000ULL 55 #define EFI_FV2_ALIGNMENT_256 0x0000000000080000ULL 56 #define EFI_FV2_ALIGNMENT_512 0x0000000000090000ULL 57 #define EFI_FV2_ALIGNMENT_1K 0x00000000000A0000ULL 58 #define EFI_FV2_ALIGNMENT_2K 0x00000000000B0000ULL 59 #define EFI_FV2_ALIGNMENT_4K 0x00000000000C0000ULL 60 #define EFI_FV2_ALIGNMENT_8K 0x00000000000D0000ULL 61 #define EFI_FV2_ALIGNMENT_16K 0x00000000000E0000ULL 62 #define EFI_FV2_ALIGNMENT_32K 0x00000000000F0000ULL 63 #define EFI_FV2_ALIGNMENT_64K 0x0000000000100000ULL 64 #define EFI_FV2_ALIGNMENT_128K 0x0000000000110000ULL 65 #define EFI_FV2_ALIGNMENT_256K 0x0000000000120000ULL 66 #define EFI_FV2_ALIGNMENT_512K 0x0000000000130000ULL 67 #define EFI_FV2_ALIGNMENT_1M 0x0000000000140000ULL 68 #define EFI_FV2_ALIGNMENT_2M 0x0000000000150000ULL 69 #define EFI_FV2_ALIGNMENT_4M 0x0000000000160000ULL 70 #define EFI_FV2_ALIGNMENT_8M 0x0000000000170000ULL 71 #define EFI_FV2_ALIGNMENT_16M 0x0000000000180000ULL 72 #define EFI_FV2_ALIGNMENT_32M 0x0000000000190000ULL 73 #define EFI_FV2_ALIGNMENT_64M 0x00000000001A0000ULL 74 #define EFI_FV2_ALIGNMENT_128M 0x00000000001B0000ULL 75 #define EFI_FV2_ALIGNMENT_256M 0x00000000001C0000ULL 76 #define EFI_FV2_ALIGNMENT_512M 0x00000000001D0000ULL 77 #define EFI_FV2_ALIGNMENT_1G 0x00000000001E0000ULL 78 #define EFI_FV2_ALIGNMENT_2G 0x00000000001F0000ULL 79 80 /** 81 Returns the attributes and current settings of the firmware volume. 82 83 Because of constraints imposed by the underlying firmware 84 storage, an instance of the Firmware Volume Protocol may not 85 be to able to support all possible variations of this 86 architecture. These constraints and the current state of the 87 firmware volume are exposed to the caller using the 88 GetVolumeAttributes() function. GetVolumeAttributes() is 89 callable only from TPL_NOTIFY and below. Behavior of 90 GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is 91 undefined. 92 93 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 94 95 @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which 96 the attributes and current settings are 97 returned. 98 99 100 @retval EFI_SUCCESS The firmware volume attributes were 101 returned. 102 103 **/ 104 typedef 105 EFI_STATUS 106 (EFIAPI *EFI_FV_GET_ATTRIBUTES)( 107 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 108 OUT EFI_FV_ATTRIBUTES *FvAttributes 109 ); 110 111 /** 112 Modifies the current settings of the firmware volume according to the input parameter. 113 114 The SetVolumeAttributes() function is used to set configurable 115 firmware volume attributes. Only EFI_FV_READ_STATUS, 116 EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and 117 then only in accordance with the declared capabilities. All 118 other bits of FvAttributes are ignored on input. On successful 119 return, all bits of *FvAttributes are valid and it contains the 120 completed EFI_FV_ATTRIBUTES for the volume. To modify an 121 attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES 122 is set to the desired value on input. The EFI_FV_LOCK_STATUS bit 123 does not affect the ability to read or write the firmware 124 volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it 125 prevents further modification to all the attribute bits. 126 SetVolumeAttributes() is callable only from TPL_NOTIFY and 127 below. Behavior of SetVolumeAttributes() at any EFI_TPL above 128 TPL_NOTIFY is undefined. 129 130 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 131 132 @param FvAttributes On input, FvAttributes is a pointer to 133 an EFI_FV_ATTRIBUTES containing the 134 desired firmware volume settings. On 135 successful return, it contains the new 136 settings of the firmware volume. On 137 unsuccessful return, FvAttributes is not 138 modified and the firmware volume 139 settings are not changed. 140 141 @retval EFI_SUCCESS The requested firmware volume attributes 142 were set and the resulting 143 EFI_FV_ATTRIBUTES is returned in 144 FvAttributes. 145 146 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 147 is set to 1 on input, but the 148 device does not support enabling 149 reads 150 (FvAttributes:EFI_FV_READ_ENABLE 151 is clear on return from 152 GetVolumeAttributes()). Actual 153 volume attributes are unchanged. 154 155 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 156 is cleared to 0 on input, but 157 the device does not support 158 disabling reads 159 (FvAttributes:EFI_FV_READ_DISABL 160 is clear on return from 161 GetVolumeAttributes()). Actual 162 volume attributes are unchanged. 163 164 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 165 is set to 1 on input, but the 166 device does not support enabling 167 writes 168 (FvAttributes:EFI_FV_WRITE_ENABL 169 is clear on return from 170 GetVolumeAttributes()). Actual 171 volume attributes are unchanged. 172 173 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 174 is cleared to 0 on input, but 175 the device does not support 176 disabling writes 177 (FvAttributes:EFI_FV_WRITE_DISAB 178 is clear on return from 179 GetVolumeAttributes()). Actual 180 volume attributes are unchanged. 181 182 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS 183 is set on input, but the device 184 does not support locking 185 (FvAttributes:EFI_FV_LOCK_CAP is 186 clear on return from 187 GetVolumeAttributes()). Actual 188 volume attributes are unchanged. 189 190 @retval EFI_ACCESS_DENIED Device is locked and does not 191 allow attribute modification 192 (FvAttributes:EFI_FV_LOCK_STATUS 193 is set on return from 194 GetVolumeAttributes()). Actual 195 volume attributes are unchanged. 196 197 **/ 198 typedef 199 EFI_STATUS 200 (EFIAPI *EFI_FV_SET_ATTRIBUTES)( 201 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 202 IN OUT EFI_FV_ATTRIBUTES *FvAttributes 203 ); 204 205 /** 206 Retrieves a file and/or file information from the firmware volume. 207 208 ReadFile() is used to retrieve any file from a firmware volume 209 during the DXE phase. The actual binary encoding of the file in 210 the firmware volume media may be in any arbitrary format as long 211 as it does the following: It is accessed using the Firmware 212 Volume Protocol. The image that is returned follows the image 213 format defined in Code Definitions: PI Firmware File Format. 214 If the input value of Buffer==NULL, it indicates the caller is 215 requesting only that the type, attributes, and size of the 216 file be returned and that there is no output buffer. In this 217 case, the following occurs: 218 - BufferSize is returned with the size that is required to 219 successfully complete the read. 220 - The output parameters FoundType and *FileAttributes are 221 returned with valid values. 222 - The returned value of *AuthenticationStatus is undefined. 223 224 If the input value of Buffer!=NULL, the output buffer is 225 specified by a double indirection of the Buffer parameter. The 226 input value of *Buffer is used to determine if the output 227 buffer is caller allocated or is dynamically allocated by 228 ReadFile(). If the input value of *Buffer!=NULL, it indicates 229 the output buffer is caller allocated. In this case, the input 230 value of *BufferSize indicates the size of the 231 caller-allocated output buffer. If the output buffer is not 232 large enough to contain the entire requested output, it is 233 filled up to the point that the output buffer is exhausted and 234 EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is 235 returned with the size required to successfully complete the 236 read. All other output parameters are returned with valid 237 values. If the input value of *Buffer==NULL, it indicates the 238 output buffer is to be allocated by ReadFile(). In this case, 239 ReadFile() will allocate an appropriately sized buffer from 240 boot services pool memory, which will be returned in Buffer. 241 The size of the new buffer is returned in BufferSize and all 242 other output parameters are returned with valid values. 243 ReadFile() is callable only from TPL_NOTIFY and below. 244 Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is 245 undefined. 246 247 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 248 249 @param NameGuid Pointer to an EFI_GUID, which is the file 250 name. All firmware file names are EFI_GUIDs. 251 A single firmware volume must not have two 252 valid files with the same file name 253 EFI_GUID. 254 255 @param Buffer Pointer to a pointer to a buffer in which the 256 file contents are returned, not including the 257 file header. 258 259 @param BufferSize Pointer to a caller-allocated UINTN. It 260 indicates the size of the memory 261 represented by Buffer. 262 263 @param FoundType Pointer to a caller-allocated EFI_FV_FILETYPE. 264 265 @param FileAttributes Pointer to a caller-allocated 266 EFI_FV_FILE_ATTRIBUTES. 267 268 @param AuthenticationStatus Pointer to a caller-allocated 269 UINT32 in which the 270 authentication status is 271 returned. 272 273 @retval EFI_SUCCESS The call completed successfully. 274 275 @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to 276 contain the requested 277 output. The buffer is 278 filled and the output is 279 truncated. 280 281 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 282 283 @retval EFI_NOT_FOUND Name was not found in the firmware volume. 284 285 @retval EFI_DEVICE_ERROR A hardware error occurred when 286 attempting to access the firmware volume. 287 288 @retval EFI_ACCESS_DENIED The firmware volume is configured to 289 disallow reads. 290 291 **/ 292 typedef 293 EFI_STATUS 294 (EFIAPI *EFI_FV_READ_FILE)( 295 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 296 IN CONST EFI_GUID *NameGuid, 297 IN OUT VOID **Buffer, 298 IN OUT UINTN *BufferSize, 299 OUT EFI_FV_FILETYPE *FoundType, 300 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, 301 OUT UINT32 *AuthenticationStatus 302 ); 303 304 /** 305 Locates the requested section within a file and returns it in a buffer. 306 307 ReadSection() is used to retrieve a specific section from a file 308 within a firmware volume. The section returned is determined 309 using a depth-first, left-to-right search algorithm through all 310 sections found in the specified file. The output buffer is specified by a double indirection 311 of the Buffer parameter. The input value of Buffer is used to 312 determine if the output buffer is caller allocated or is 313 dynamically allocated by ReadSection(). If the input value of 314 Buffer!=NULL, it indicates that the output buffer is caller 315 allocated. In this case, the input value of *BufferSize 316 indicates the size of the caller-allocated output buffer. If 317 the output buffer is not large enough to contain the entire 318 requested output, it is filled up to the point that the output 319 buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, 320 and then BufferSize is returned with the size that is required 321 to successfully complete the read. All other 322 output parameters are returned with valid values. If the input 323 value of *Buffer==NULL, it indicates the output buffer is to 324 be allocated by ReadSection(). In this case, ReadSection() 325 will allocate an appropriately sized buffer from boot services 326 pool memory, which will be returned in *Buffer. The size of 327 the new buffer is returned in *BufferSize and all other output 328 parameters are returned with valid values. ReadSection() is 329 callable only from TPL_NOTIFY and below. Behavior of 330 ReadSection() at any EFI_TPL above TPL_NOTIFY is 331 undefined. 332 333 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 334 335 @param NameGuid Pointer to an EFI_GUID, which indicates the 336 file name from which the requested section 337 will be read. 338 339 @param SectionType Indicates the section type to return. 340 SectionType in conjunction with 341 SectionInstance indicates which section to 342 return. 343 344 @param SectionInstance Indicates which instance of sections 345 with a type of SectionType to return. 346 SectionType in conjunction with 347 SectionInstance indicates which 348 section to return. SectionInstance is 349 zero based. 350 351 @param Buffer Pointer to a pointer to a buffer in which the 352 section contents are returned, not including 353 the section header. 354 355 @param BufferSize Pointer to a caller-allocated UINTN. It 356 indicates the size of the memory 357 represented by Buffer. 358 359 @param AuthenticationStatus Pointer to a caller-allocated 360 UINT32 in which the authentication 361 status is returned. 362 363 364 @retval EFI_SUCCESS The call completed successfully. 365 366 @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated 367 buffer is too small to 368 contain the requested 369 output. The buffer is 370 filled and the output is 371 truncated. 372 373 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 374 375 @retval EFI_NOT_FOUND The requested file was not found in 376 the firmware volume. EFI_NOT_FOUND The 377 requested section was not found in the 378 specified file. 379 380 @retval EFI_DEVICE_ERROR A hardware error occurred when 381 attempting to access the firmware 382 volume. 383 384 @retval EFI_ACCESS_DENIED The firmware volume is configured to 385 disallow reads. EFI_PROTOCOL_ERROR 386 The requested section was not found, 387 but the file could not be fully 388 parsed because a required 389 GUIDED_SECTION_EXTRACTION_PROTOCOL 390 was not found. It is possible the 391 requested section exists within the 392 file and could be successfully 393 extracted once the required 394 GUIDED_SECTION_EXTRACTION_PROTOCOL 395 is published. 396 397 **/ 398 typedef 399 EFI_STATUS 400 (EFIAPI *EFI_FV_READ_SECTION)( 401 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 402 IN CONST EFI_GUID *NameGuid, 403 IN EFI_SECTION_TYPE SectionType, 404 IN UINTN SectionInstance, 405 IN OUT VOID **Buffer, 406 IN OUT UINTN *BufferSize, 407 OUT UINT32 *AuthenticationStatus 408 ); 409 410 /// 411 /// EFI_FV_WRITE_POLICY, two policies (unreliable write and reliable write) are defined. 412 /// 413 typedef UINT32 EFI_FV_WRITE_POLICY; 414 #define EFI_FV_UNRELIABLE_WRITE 0x00000000 415 #define EFI_FV_RELIABLE_WRITE 0x00000001 416 417 // 418 // EFI_FV_WRITE_FILE_DATA 419 // 420 typedef struct { 421 /// 422 /// Pointer to a GUID, which is the file name to be written. 423 /// 424 EFI_GUID *NameGuid; 425 /// 426 /// Indicates the type of file to be written. 427 /// 428 EFI_FV_FILETYPE Type; 429 /// 430 /// Indicates the attributes for the file to be written. 431 /// 432 EFI_FV_FILE_ATTRIBUTES FileAttributes; 433 /// 434 /// Pointer to a buffer containing the file to be written. 435 /// 436 VOID *Buffer; 437 /// 438 /// Indicates the size of the file image contained in Buffer. 439 /// 440 UINT32 BufferSize; 441 } EFI_FV_WRITE_FILE_DATA; 442 443 /** 444 Locates the requested section within a file and returns it in a buffer. 445 446 WriteFile() is used to write one or more files to a firmware 447 volume. Each file to be written is described by an 448 EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that 449 any required alignment for all files listed in the FileData 450 array is compatible with the firmware volume. Firmware volume 451 capabilities can be determined using the GetVolumeAttributes() 452 call. Similarly, if the WritePolicy is set to 453 EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume 454 capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the 455 firmware volume. EFI_FV_UNRELIABLE_WRITE must always be 456 supported. Writing a file with a size of zero 457 (FileData[n].BufferSize == 0) deletes the file from the firmware 458 volume if it exists. Deleting a file must be done one at a time. 459 Deleting a file as part of a multiple file write is not allowed. 460 Platform Initialization Specification VOLUME 3 Shared 461 Architectural Elements 84 August 21, 2006 Version 1.0 462 WriteFile() is callable only from TPL_NOTIFY and below. 463 Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is 464 undefined. 465 466 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 467 468 @param NumberOfFiles Indicates the number of elements in the array pointed to by FileData 469 470 @param WritePolicy Indicates the level of reliability for the 471 write in the event of a power failure or 472 other system failure during the write 473 operation. 474 475 @param FileData Pointer to an array of 476 EFI_FV_WRITE_FILE_DATA. Each element of 477 FileData[] represents a file to be written. 478 479 480 @retval EFI_SUCCESS The write completed successfully. 481 482 @retval EFI_OUT_OF_RESOURCES The firmware volume does not 483 have enough free space to 484 storefile(s). 485 486 @retval EFI_DEVICE_ERROR A hardware error occurred when 487 attempting to access the firmware volume. 488 489 @retval EFI_WRITE_PROTECTED The firmware volume is 490 configured to disallow writes. 491 492 @retval EFI_NOT_FOUND A delete was requested, but the 493 requested file was not found in the 494 firmware volume. 495 496 @retval EFI_INVALID_PARAMETER A delete was requested with a 497 multiple file write. 498 499 @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was 500 requested. 501 502 @retval EFI_INVALID_PARAMETER An unknown file type was 503 specified. 504 505 @retval EFI_INVALID_PARAMETER A file system specific error 506 has occurred. 507 508 **/ 509 typedef 510 EFI_STATUS 511 (EFIAPI *EFI_FV_WRITE_FILE)( 512 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 513 IN UINT32 NumberOfFiles, 514 IN EFI_FV_WRITE_POLICY WritePolicy, 515 IN EFI_FV_WRITE_FILE_DATA *FileData 516 ); 517 518 /** 519 Retrieves information about the next file in the firmware volume store 520 that matches the search criteria. 521 522 GetNextFile() is the interface that is used to search a firmware 523 volume for a particular file. It is called successively until 524 the desired file is located or the function returns 525 EFI_NOT_FOUND. To filter uninteresting files from the output, 526 the type of file to search for may be specified in FileType. For 527 example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of 528 this type will be returned in the output. If *FileType is 529 EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key 530 parameter is used to indicate a starting point of the search. If 531 the buffer *Key is completely initialized to zero, the search 532 re-initialized and starts at the beginning. Subsequent calls to 533 GetNextFile() must maintain the value of *Key returned by the 534 immediately previous call. The actual contents of *Key are 535 implementation specific and no semantic content is implied. 536 GetNextFile() is callable only from TPL_NOTIFY and below. 537 Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is 538 undefined. 539 540 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 541 542 @param Key Pointer to a caller-allocated buffer that contains implementation-specific data that is 543 used to track where to begin the search for the next file. The size of the buffer must be 544 at least This->KeySize bytes long. To re-initialize the search and begin from the 545 beginning of the firmware volume, the entire buffer must be cleared to zero. Other 546 than clearing the buffer to initiate a new search, the caller must not modify the data in 547 the buffer between calls to GetNextFile(). 548 549 @param FileType Pointer to a caller-allocated 550 EFI_FV_FILETYPE. The GetNextFile() API can 551 filter its search for files based on the 552 value of the FileType input. A *FileType 553 input of EFI_FV_FILETYPE_ALL causes 554 GetNextFile() to search for files of all 555 types. If a file is found, the file's type 556 is returned in FileType. *FileType is not 557 modified if no file is found. 558 559 @param NameGuid Pointer to a caller-allocated EFI_GUID. If a 560 matching file is found, the file's name is 561 returned in NameGuid. If no matching file is 562 found, *NameGuid is not modified. 563 564 @param Attributes Pointer to a caller-allocated 565 EFI_FV_FILE_ATTRIBUTES. If a matching file 566 is found, the file's attributes are returned 567 in Attributes. If no matching file is found, 568 Attributes is not modified. Type 569 EFI_FV_FILE_ATTRIBUTES is defined in 570 ReadFile(). 571 572 @param Size Pointer to a caller-allocated UINTN. If a 573 matching file is found, the file's size is 574 returned in *Size. If no matching file is found, 575 Size is not modified. 576 577 @retval EFI_SUCCESS The output parameters are filled with data 578 obtained from the first matching file that 579 was found. 580 581 @retval FI_NOT_FOUND No files of type FileType were found. 582 583 584 @retval EFI_DEVICE_ERROR A hardware error occurred when 585 attempting to access the firmware 586 volume. 587 588 @retval EFI_ACCESS_DENIED The firmware volume is configured to 589 disallow reads. 590 591 592 **/ 593 typedef 594 EFI_STATUS 595 (EFIAPI *EFI_FV_GET_NEXT_FILE)( 596 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 597 IN OUT VOID *Key, 598 IN OUT EFI_FV_FILETYPE *FileType, 599 OUT EFI_GUID *NameGuid, 600 OUT EFI_FV_FILE_ATTRIBUTES *Attributes, 601 OUT UINTN *Size 602 ); 603 604 /** 605 Return information about a firmware volume. 606 607 The GetInfo() function returns information of type 608 InformationType for the requested firmware volume. If the volume 609 does not support the requested information type, then 610 EFI_UNSUPPORTED is returned. If the buffer is not large enough 611 to hold the requested structure, EFI_BUFFER_TOO_SMALL is 612 returned and the BufferSize is set to the size of buffer that is 613 required to make the request. The information types defined by 614 this specification are required information types that all file 615 systems must support. 616 617 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 618 instance that is the file handle the requested 619 information is for. 620 621 @param InformationType The type identifier for the 622 information being requested. 623 624 @param BufferSize On input, the size of Buffer. On output, 625 the amount of data returned in Buffer. In 626 both cases, the size is measured in bytes. 627 628 @param Buffer A pointer to the data buffer to return. The 629 buffer's type is indicated by InformationType. 630 631 632 @retval EFI_SUCCESS The information was retrieved. 633 634 @retval EFI_UNSUPPORTED The InformationType is not known. 635 636 @retval EFI_NO_MEDIA The device has no medium. 637 638 @retval EFI_DEVICE_ERROR The device reported an error. 639 640 @retval EFI_VOLUME_CORRUPTED The file system structures are 641 corrupted. 642 643 @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to 644 read the current directory 645 entry. BufferSize has been 646 updated with the size needed to 647 complete the request. 648 649 650 **/ 651 typedef 652 EFI_STATUS 653 (EFIAPI *EFI_FV_GET_INFO)( 654 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 655 IN CONST EFI_GUID *InformationType, 656 IN OUT UINTN *BufferSize, 657 OUT VOID *Buffer 658 ); 659 660 /** 661 Sets information about a firmware volume. 662 663 The SetInfo() function sets information of type InformationType 664 on the requested firmware volume. 665 666 667 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 668 instance that is the file handle the information 669 is for. 670 671 @param InformationType The type identifier for the 672 information being set. 673 674 @param BufferSize The size, in bytes, of Buffer. 675 676 @param Buffer A pointer to the data buffer to write. The 677 buffer's type is indicated by InformationType. 678 679 @retval EFI_SUCCESS The information was set. 680 681 @retval EFI_UNSUPPORTED The InformationType is not known. 682 683 @retval EFI_NO_MEDIA The device has no medium. 684 685 @retval EFI_DEVICE_ERROR The device reported an error. 686 687 @retval EFI_VOLUME_CORRUPTED The file system structures are 688 corrupted. 689 690 691 @retval EFI_WRITE_PROTECTED The media is read only. 692 693 @retval EFI_VOLUME_FULL The volume is full. 694 695 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the 696 size of the type indicated by 697 InformationType. 698 699 **/ 700 typedef 701 EFI_STATUS 702 (EFIAPI *EFI_FV_SET_INFO)( 703 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 704 IN CONST EFI_GUID *InformationType, 705 IN UINTN BufferSize, 706 IN CONST VOID *Buffer 707 ); 708 709 /// 710 /// The Firmware Volume Protocol contains the file-level 711 /// abstraction to the firmware volume as well as some firmware 712 /// volume attribute reporting and configuration services. The 713 /// Firmware Volume Protocol is the interface used by all parts of 714 /// DXE that are not directly involved with managing the firmware 715 /// volume itself. This abstraction allows many varied types of 716 /// firmware volume implementations. A firmware volume may be a 717 /// flash device or it may be a file in the UEFI system partition, 718 /// for example. This level of firmware volume implementation 719 /// detail is not visible to the consumers of the Firmware Volume 720 /// Protocol. 721 /// 722 struct _EFI_FIRMWARE_VOLUME2_PROTOCOL { 723 EFI_FV_GET_ATTRIBUTES GetVolumeAttributes; 724 EFI_FV_SET_ATTRIBUTES SetVolumeAttributes; 725 EFI_FV_READ_FILE ReadFile; 726 EFI_FV_READ_SECTION ReadSection; 727 EFI_FV_WRITE_FILE WriteFile; 728 EFI_FV_GET_NEXT_FILE GetNextFile; 729 730 /// 731 /// Data field that indicates the size in bytes 732 /// of the Key input buffer for the 733 /// GetNextFile() API. 734 /// 735 UINT32 KeySize; 736 737 /// 738 /// Handle of the parent firmware volume. 739 /// 740 EFI_HANDLE ParentHandle; 741 EFI_FV_GET_INFO GetInfo; 742 EFI_FV_SET_INFO SetInfo; 743 }; 744 745 extern EFI_GUID gEfiFirmwareVolume2ProtocolGuid; 746 747 #endif 748