1 /** @file 2 Module produce FV2 on top of FV. 3 4 UEFI PI specification supersedes Inte's Framework Specification. 5 EFI_FIRMWARE_VOLUME_PROTOCOL defined in Intel Framework Pkg is replaced by 6 EFI_FIRMWARE_VOLUME2_PROTOCOL in MdePkg. 7 This module produces FV2 on top of FV. This module is used on platform when both of 8 these two conditions are true: 9 1) Framework module producing FV is present 10 2) And the rest of modules on the platform consume FV2 11 12 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> 13 This program and the accompanying materials 14 are licensed and made available under the terms and conditions of the BSD License 15 which accompanies this distribution. The full text of the license may be found at 16 http://opensource.org/licenses/bsd-license.php 17 18 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 19 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 20 Module Name: 21 22 **/ 23 24 #include <PiDxe.h> 25 #include <Protocol/FirmwareVolume2.h> 26 #include <Protocol/FirmwareVolume.h> 27 #include <Library/BaseLib.h> 28 #include <Library/DebugLib.h> 29 #include <Library/UefiBootServicesTableLib.h> 30 #include <Library/UefiDriverEntryPoint.h> 31 #include <Library/UefiLib.h> 32 #include <Library/MemoryAllocationLib.h> 33 34 /** 35 36 Because of constraints imposed by the underlying firmware 37 storage, an instance of the Firmware Volume Protocol may not 38 be to able to support all possible variations of this 39 architecture. These constraints and the current state of the 40 firmware volume are exposed to the caller using the 41 GetVolumeAttributes() function. GetVolumeAttributes() is 42 callable only from TPL_NOTIFY and below. Behavior of 43 GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is 44 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 45 2.0 specification. 46 47 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 48 instance. 49 50 @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which 51 the attributes and current settings are 52 returned. 53 54 55 @retval EFI_SUCCESS The firmware volume attributes were 56 returned. 57 58 **/ 59 EFI_STATUS 60 EFIAPI 61 Fv2GetVolumeAttributes ( 62 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 63 OUT EFI_FV_ATTRIBUTES *FvAttributes 64 ); 65 66 67 /** 68 The SetVolumeAttributes() function is used to set configurable 69 firmware volume attributes. Only EFI_FV_READ_STATUS, 70 EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and 71 then only in accordance with the declared capabilities. All 72 other bits of FvAttributes are ignored on input. On successful 73 return, all bits of *FvAttributes are valid and it contains the 74 completed EFI_FV_ATTRIBUTES for the volume. To modify an 75 attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES 76 is set to the desired value on input. The EFI_FV_LOCK_STATUS bit 77 does not affect the ability to read or write the firmware 78 volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it 79 prevents further modification to all the attribute bits. 80 SetVolumeAttributes() is callable only from TPL_NOTIFY and 81 below. Behavior of SetVolumeAttributes() at any EFI_TPL above 82 TPL_NOTIFY is undefined. Type EFI_TPL is defined in 83 RaiseTPL() in the UEFI 2.0 specification. 84 85 86 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 87 instance. 88 89 @param FvAttributes On input, FvAttributes is a pointer to 90 an EFI_FV_ATTRIBUTES containing the 91 desired firmware volume settings. On 92 successful return, it contains the new 93 settings of the firmware volume. On 94 unsuccessful return, FvAttributes is not 95 modified and the firmware volume 96 settings are not changed. 97 98 @retval EFI_SUCCESS The requested firmware volume attributes 99 were set and the resulting 100 EFI_FV_ATTRIBUTES is returned in 101 FvAttributes. 102 103 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 104 is set to 1 on input, but the 105 device does not support enabling 106 reads 107 (FvAttributes:EFI_FV_READ_ENABLE 108 is clear on return from 109 GetVolumeAttributes()). Actual 110 volume attributes are unchanged. 111 112 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 113 is cleared to 0 on input, but 114 the device does not support 115 disabling reads 116 (FvAttributes:EFI_FV_READ_DISABL 117 is clear on return from 118 GetVolumeAttributes()). Actual 119 volume attributes are unchanged. 120 121 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 122 is set to 1 on input, but the 123 device does not support enabling 124 writes 125 (FvAttributes:EFI_FV_WRITE_ENABL 126 is clear on return from 127 GetVolumeAttributes()). Actual 128 volume attributes are unchanged. 129 130 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 131 is cleared to 0 on input, but 132 the device does not support 133 disabling writes 134 (FvAttributes:EFI_FV_WRITE_DISAB 135 is clear on return from 136 GetVolumeAttributes()). Actual 137 volume attributes are unchanged. 138 139 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS 140 is set on input, but the device 141 does not support locking 142 (FvAttributes:EFI_FV_LOCK_CAP is 143 clear on return from 144 GetVolumeAttributes()). Actual 145 volume attributes are unchanged. 146 147 @retval EFI_ACCESS_DENIED Device is locked and does not 148 allow attribute modification 149 (FvAttributes:EFI_FV_LOCK_STATUS 150 is set on return from 151 GetVolumeAttributes()). Actual 152 volume attributes are unchanged. 153 154 **/ 155 EFI_STATUS 156 EFIAPI 157 Fv2SetVolumeAttributes ( 158 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 159 IN OUT EFI_FV_ATTRIBUTES *FvAttributes 160 ); 161 162 163 /** 164 ReadFile() is used to retrieve any file from a firmware volume 165 during the DXE phase. The actual binary encoding of the file in 166 the firmware volume media may be in any arbitrary format as long 167 as it does the following: It is accessed using the Firmware 168 Volume Protocol. The image that is returned follows the image 169 format defined in Code Definitions: PI Firmware File Format. 170 If the input value of Buffer==NULL, it indicates the caller is 171 requesting only that the type, attributes, and size of the 172 file be returned and that there is no output buffer. In this 173 case, the following occurs: 174 - BufferSize is returned with the size that is required to 175 successfully complete the read. 176 - The output parameters FoundType and *FileAttributes are 177 returned with valid values. 178 - The returned value of *AuthenticationStatus is undefined. 179 180 If the input value of Buffer!=NULL, the output buffer is 181 specified by a double indirection of the Buffer parameter. The 182 input value of *Buffer is used to determine if the output 183 buffer is caller allocated or is dynamically allocated by 184 ReadFile(). If the input value of *Buffer!=NULL, it indicates 185 the output buffer is caller allocated. In this case, the input 186 value of *BufferSize indicates the size of the 187 caller-allocated output buffer. If the output buffer is not 188 large enough to contain the entire requested output, it is 189 filled up to the point that the output buffer is exhausted and 190 EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is 191 returned with the size required to successfully complete the 192 read. All other output parameters are returned with valid 193 values. If the input value of *Buffer==NULL, it indicates the 194 output buffer is to be allocated by ReadFile(). In this case, 195 ReadFile() will allocate an appropriately sized buffer from 196 boot services pool memory, which will be returned in Buffer. 197 The size of the new buffer is returned in BufferSize and all 198 other output parameters are returned with valid values. 199 ReadFile() is callable only from TPL_NOTIFY and below. 200 Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is 201 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 202 2.0 specification. 203 204 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 205 instance. 206 207 @param NameGuid Pointer to an EFI_GUID, which is the file 208 name. All firmware file names are EFI_GUIDs. 209 A single firmware volume must not have two 210 valid files with the same file name 211 EFI_GUID. 212 213 @param Buffer Pointer to a pointer to a buffer in which the 214 file contents are returned, not including the 215 file header. 216 @param BufferSize Pointer to a caller-allocated UINTN. It 217 indicates the size of the memory 218 represented by Buffer. 219 220 @param FoundType Pointer to a caller-allocated 221 EFI_FV_FILETYPE. 222 223 @param FileAttributes Pointer to a caller-allocated 224 EFI_FV_FILE_ATTRIBUTES. 225 226 @param AuthenticationStatus Pointer to a caller-allocated 227 UINT32 in which the 228 authentication status is 229 returned. 230 231 @retval EFI_SUCCESS The call completed successfully. 232 233 @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to 234 contain the requested 235 output. The buffer is 236 filled and the output is 237 truncated. 238 239 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 240 241 @retval EFI_NOT_FOUND Name was not found in the firmware 242 volume. 243 244 @retval EFI_DEVICE_ERROR A hardware error occurred when 245 attempting to access the firmware 246 volume. 247 248 @retval EFI_ACCESS_DENIED The firmware volume is configured to 249 isallow reads. 250 251 **/ 252 EFI_STATUS 253 EFIAPI 254 Fv2ReadFile ( 255 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 256 IN CONST EFI_GUID *NameGuid, 257 IN OUT VOID **Buffer, 258 IN OUT UINTN *BufferSize, 259 OUT EFI_FV_FILETYPE *FoundType, 260 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, 261 OUT UINT32 *AuthenticationStatus 262 ); 263 264 /** 265 ReadSection() is used to retrieve a specific section from a file 266 within a firmware volume. The section returned is determined 267 using a depth-first, left-to-right search algorithm through all 268 sections found in the specified file. The output buffer is 269 specified by a double indirection of the Buffer parameter. 270 The input value of Buffer is used to determine 271 if the output buffer is caller allocated or is 272 dynamically allocated by ReadSection(). If the input value of 273 Buffer!=NULL, it indicates that the output buffer is caller 274 allocated. In this case, the input value of *BufferSize 275 indicates the size of the caller-allocated output buffer. If 276 the output buffer is not large enough to contain the entire 277 requested output, it is filled up to the point that the output 278 buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, 279 and then BufferSize is returned with the size that is required 280 to successfully complete the read. All other 281 output parameters are returned with valid values. If the input 282 value of *Buffer==NULL, it indicates the output buffer is to 283 be allocated by ReadSection(). In this case, ReadSection() 284 will allocate an appropriately sized buffer from boot services 285 pool memory, which will be returned in *Buffer. The size of 286 the new buffer is returned in *BufferSize and all other output 287 parameters are returned with valid values. ReadSection() is 288 callable only from TPL_NOTIFY and below. Behavior of 289 ReadSection() at any EFI_TPL above TPL_NOTIFY is 290 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 291 2.0 specification. 292 293 294 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 295 instance. 296 297 @param NameGuid Pointer to an EFI_GUID, which indicates the 298 file name from which the requested section 299 will be read. 300 301 @param SectionType Indicates the section type to return. 302 SectionType in conjunction with 303 SectionInstance indicates which section to 304 return. 305 306 @param SectionInstance Indicates which instance of sections 307 with a type of SectionType to return. 308 SectionType in conjunction with 309 SectionInstance indicates which 310 section to return. SectionInstance is 311 zero based. 312 313 @param Buffer Pointer to a pointer to a buffer in which the 314 section contents are returned, not including 315 the section header. 316 317 @param BufferSize Pointer to a caller-allocated UINTN. It 318 indicates the size of the memory 319 represented by Buffer. 320 321 @param AuthenticationStatus Pointer to a caller-allocated 322 UINT32 in which the authentication 323 status is returned. 324 325 326 @retval EFI_SUCCESS The call completed successfully. 327 328 @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated 329 buffer is too small to 330 contain the requested 331 output. The buffer is 332 filled and the output is 333 truncated. 334 335 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 336 337 @retval EFI_NOT_FOUND The requested file was not found in 338 the firmware volume. EFI_NOT_FOUND The 339 requested section was not found in the 340 specified file. 341 342 @retval EFI_DEVICE_ERROR A hardware error occurred when 343 attempting to access the firmware 344 volume. 345 346 @retval EFI_ACCESS_DENIED The firmware volume is configured to 347 disallow reads. EFI_PROTOCOL_ERROR 348 The requested section was not found, 349 but the file could not be fully 350 parsed because a required 351 GUIDED_SECTION_EXTRACTION_PROTOCOL 352 was not found. It is possible the 353 requested section exists within the 354 file and could be successfully 355 extracted once the required 356 GUIDED_SECTION_EXTRACTION_PROTOCOL 357 is published. 358 359 **/ 360 EFI_STATUS 361 EFIAPI 362 Fv2ReadSection ( 363 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 364 IN CONST EFI_GUID *NameGuid, 365 IN EFI_SECTION_TYPE SectionType, 366 IN UINTN SectionInstance, 367 IN OUT VOID **Buffer, 368 IN OUT UINTN *BufferSize, 369 OUT UINT32 *AuthenticationStatus 370 ); 371 372 /** 373 WriteFile() is used to write one or more files to a firmware 374 volume. Each file to be written is described by an 375 EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that 376 any required alignment for all files listed in the FileData 377 array is compatible with the firmware volume. Firmware volume 378 capabilities can be determined using the GetVolumeAttributes() 379 call. Similarly, if the WritePolicy is set to 380 EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume 381 capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the 382 firmware volume. EFI_FV_UNRELIABLE_WRITE must always be 383 supported. Writing a file with a size of zero 384 (FileData[n].BufferSize == 0) deletes the file from the firmware 385 volume if it exists. Deleting a file must be done one at a time. 386 Deleting a file as part of a multiple file write is not allowed. 387 Platform Initialization Specification VOLUME 3 Shared 388 Architectural Elements 84 August 21, 2006 Version 1.0 389 WriteFile() is callable only from TPL_NOTIFY and below. 390 Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is 391 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 392 specification. 393 394 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 395 396 @param NumberOfFiles Indicates the number of elements in the 397 array pointed to by FileData. 398 399 @param WritePolicy Indicates the level of reliability for the 400 write in the event of a power failure or 401 other system failure during the write 402 operation. 403 404 @param FileData Pointer to an array of 405 EFI_FV_WRITE_FILE_DATA. Each element of 406 FileData[] represents a file to be written. 407 408 409 @retval EFI_SUCCESS The write completed successfully. 410 411 @retval EFI_OUT_OF_RESOURCES The firmware volume does not 412 have enough free space to 413 storefile(s). 414 415 @retval EFI_DEVICE_ERROR A hardware error occurred when 416 attempting to access the firmware volume. 417 418 @retval EFI_WRITE_PROTECTED The firmware volume is 419 configured to disallow writes. 420 421 @retval EFI_NOT_FOUND A delete was requested, but the 422 requested file was not found in the 423 firmware volume. 424 425 @retval EFI_INVALID_PARAMETER A delete was requested with a 426 multiple file write. 427 428 @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was 429 requested. 430 431 @retval EFI_INVALID_PARAMETER An unknown file type was 432 specified. 433 434 @retval EFI_INVALID_PARAMETER A file system specific error 435 has occurred. 436 437 **/ 438 EFI_STATUS 439 EFIAPI 440 Fv2WriteFile ( 441 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 442 IN UINT32 NumberOfFiles, 443 IN EFI_FV_WRITE_POLICY WritePolicy, 444 IN EFI_FV_WRITE_FILE_DATA *FileData 445 ); 446 447 /** 448 GetNextFile() is the interface that is used to search a firmware 449 volume for a particular file. It is called successively until 450 the desired file is located or the function returns 451 EFI_NOT_FOUND. To filter uninteresting files from the output, 452 the type of file to search for may be specified in FileType. For 453 example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of 454 this type will be returned in the output. If *FileType is 455 EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key 456 parameter is used to indicate a starting point of the search. If 457 the buffer *Key is completely initialized to zero, the search 458 re-initialized and starts at the beginning. Subsequent calls to 459 GetNextFile() must maintain the value of *Key returned by the 460 immediately previous call. The actual contents of *Key are 461 implementation specific and no semantic content is implied. 462 GetNextFile() is callable only from TPL_NOTIFY and below. 463 Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is 464 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 465 specification. Status Codes Returned 466 467 468 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 469 instance. 470 471 @param Key Pointer to a caller-allocated buffer 472 that contains implementation-specific data that is 473 used to track where to begin the search for the 474 next file. The size of the buffer must be at least 475 This->KeySize bytes long. To re-initialize the 476 search and begin from the beginning of the 477 firmware volume, the entire buffer must be cleared 478 to zero. Other than clearing the buffer to 479 initiate a new search, the caller must not modify 480 the data in the buffer between calls to 481 GetNextFile(). 482 483 @param FileType Pointer to a caller-allocated 484 EFI_FV_FILETYPE. The GetNextFile() API can 485 filter its search for files based on the 486 value of the FileType input. A *FileType 487 input of EFI_FV_FILETYPE_ALL causes 488 GetNextFile() to search for files of all 489 types. If a file is found, the file's type 490 is returned in FileType. *FileType is not 491 modified if no file is found. 492 493 @param NameGuid Pointer to a caller-allocated EFI_GUID. If a 494 matching file is found, the file's name is 495 returned in NameGuid. If no matching file is 496 found, *NameGuid is not modified. 497 498 @param Attributes Pointer to a caller-allocated 499 EFI_FV_FILE_ATTRIBUTES. If a matching file 500 is found, the file's attributes are returned 501 in Attributes. If no matching file is found, 502 Attributes is not modified. Type 503 EFI_FV_FILE_ATTRIBUTES is defined in 504 ReadFile(). 505 506 @param Size Pointer to a caller-allocated UINTN. If a 507 matching file is found, the file's size is 508 returned in *Size. If no matching file is found, 509 Size is not modified. 510 511 @retval EFI_SUCCESS The output parameters are filled with data 512 obtained from the first matching file that 513 was found. 514 515 @retval FI_NOT_FOUND No files of type FileType were found. 516 517 518 @retval EFI_DEVICE_ERROR A hardware error occurred when 519 attempting to access the firmware 520 volume. 521 522 @retval EFI_ACCESS_DENIED The firmware volume is configured to 523 disallow reads. 524 525 526 **/ 527 EFI_STATUS 528 EFIAPI 529 Fv2GetNextFile ( 530 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 531 IN OUT VOID *Key, 532 IN OUT EFI_FV_FILETYPE *FileType, 533 OUT EFI_GUID *NameGuid, 534 OUT EFI_FV_FILE_ATTRIBUTES *Attributes, 535 OUT UINTN *Size 536 ); 537 538 /** 539 The GetInfo() function returns information of type 540 InformationType for the requested firmware volume. If the volume 541 does not support the requested information type, then 542 EFI_UNSUPPORTED is returned. If the buffer is not large enough 543 to hold the requested structure, EFI_BUFFER_TOO_SMALL is 544 returned and the BufferSize is set to the size of buffer that is 545 required to make the request. The information types defined by 546 this specification are required information types that all file 547 systems must support. 548 549 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 550 instance that is the file handle the requested 551 information is for. 552 553 @param InformationType The type identifier for the 554 information being requested. 555 556 @param BufferSize On input, the size of Buffer. On output, 557 the amount of data returned in Buffer. In 558 both cases, the size is measured in bytes. 559 560 @param Buffer A pointer to the data buffer to return. The 561 buffer's type is indicated by InformationType. 562 563 564 @retval EFI_SUCCESS The information was retrieved. 565 566 @retval EFI_UNSUPPORTED The InformationType is not known. 567 568 @retval EFI_NO_MEDIA The device has no medium. 569 570 @retval EFI_DEVICE_ERROR The device reported an error. 571 572 @retval EFI_VOLUME_CORRUPTED The file system structures are 573 corrupted. 574 575 @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to 576 read the current directory 577 entry. BufferSize has been 578 updated with the size needed to 579 complete the request. 580 581 582 **/ 583 EFI_STATUS 584 EFIAPI 585 Fv2GetInfo ( 586 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 587 IN CONST EFI_GUID *InformationType, 588 IN OUT UINTN *BufferSize, 589 OUT VOID *Buffer 590 ); 591 592 /** 593 594 The SetInfo() function sets information of type InformationType 595 on the requested firmware volume. 596 597 598 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 599 instance that is the file handle the information 600 is for. 601 602 @param InformationType The type identifier for the 603 information being set. 604 605 @param BufferSize The size, in bytes, of Buffer. 606 607 @param Buffer A pointer to the data buffer to write. The 608 buffer's type is indicated by InformationType. 609 610 @retval EFI_SUCCESS The information was set. 611 612 @retval EFI_UNSUPPORTED The InformationType is not known. 613 614 @retval EFI_NO_MEDIA The device has no medium. 615 616 @retval EFI_DEVICE_ERROR The device reported an error. 617 618 @retval EFI_VOLUME_CORRUPTED The file system structures are 619 corrupted. 620 621 622 @retval EFI_WRITE_PROTECTED The media is read only. 623 624 @retval EFI_VOLUME_FULL The volume is full. 625 626 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the 627 size of the type indicated by 628 InformationType. 629 630 **/ 631 EFI_STATUS 632 EFIAPI 633 Fv2SetInfo ( 634 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 635 IN CONST EFI_GUID *InformationType, 636 IN UINTN BufferSize, 637 IN CONST VOID *Buffer 638 ); 639 640 // 641 // 642 // 643 #define FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('f', 'v', '2', 't') 644 645 typedef struct { 646 UINTN Signature; 647 EFI_FIRMWARE_VOLUME2_PROTOCOL FirmwareVolume2; 648 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 649 } FIRMWARE_VOLUME2_PRIVATE_DATA; 650 651 #define FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS(a) CR (a, FIRMWARE_VOLUME2_PRIVATE_DATA, FirmwareVolume2, FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE) 652 653 // 654 // Firmware Volume Protocol template 655 // 656 EFI_EVENT mFv2Registration; 657 658 FIRMWARE_VOLUME2_PRIVATE_DATA gFirmwareVolume2PrivateDataTemplate = { 659 FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE, 660 { 661 Fv2GetVolumeAttributes, 662 Fv2SetVolumeAttributes, 663 Fv2ReadFile, 664 Fv2ReadSection, 665 Fv2WriteFile, 666 Fv2GetNextFile, 667 0, 668 NULL, 669 Fv2GetInfo, 670 Fv2SetInfo 671 }, 672 NULL 673 }; 674 675 // 676 // Module globals 677 // 678 /** 679 This notification function is invoked when an instance of the 680 EFI_FIRMWARE_VOLUME_PROTOCOL is produced. It installs another instance of the 681 EFI_FIRMWARE_VOLUME2_PROTOCOL on the same handle. 682 683 @param Event The event that occured 684 @param Context Context of event. Not used in this nofication function. 685 686 **/ 687 VOID 688 EFIAPI 689 Fv2NotificationEvent ( 690 IN EFI_EVENT Event, 691 IN VOID *Context 692 ) 693 { 694 EFI_STATUS Status; 695 UINTN BufferSize; 696 EFI_HANDLE Handle; 697 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 698 EFI_FIRMWARE_VOLUME2_PROTOCOL *FirmwareVolume2; 699 700 while (TRUE) { 701 BufferSize = sizeof (Handle); 702 Status = gBS->LocateHandle ( 703 ByRegisterNotify, 704 &gEfiFirmwareVolumeProtocolGuid, 705 mFv2Registration, 706 &BufferSize, 707 &Handle 708 ); 709 if (EFI_ERROR (Status)) { 710 // 711 // Exit Path of While Loop.... 712 // 713 break; 714 } 715 716 // 717 // Skip this handle if the Firmware Volume Protocol is already installed 718 // 719 Status = gBS->HandleProtocol ( 720 Handle, 721 &gEfiFirmwareVolume2ProtocolGuid, 722 (VOID **)&FirmwareVolume2 723 ); 724 if (!EFI_ERROR (Status)) { 725 continue; 726 } 727 728 // 729 // Allocate private data structure 730 // 731 Private = AllocateCopyPool (sizeof (FIRMWARE_VOLUME2_PRIVATE_DATA), &gFirmwareVolume2PrivateDataTemplate); 732 if (Private == NULL) { 733 continue; 734 } 735 736 // 737 // Retrieve the Firmware Volume2 Protocol 738 // 739 Status = gBS->HandleProtocol ( 740 Handle, 741 &gEfiFirmwareVolumeProtocolGuid, 742 (VOID **)&Private->FirmwareVolume 743 ); 744 ASSERT_EFI_ERROR (Status); 745 746 // 747 // Fill in rest of private data structure 748 // 749 Private->FirmwareVolume2.KeySize = Private->FirmwareVolume->KeySize; 750 Private->FirmwareVolume2.ParentHandle = Private->FirmwareVolume->ParentHandle; 751 752 // 753 // Install Firmware Volume Protocol onto same handle 754 // 755 Status = gBS->InstallMultipleProtocolInterfaces ( 756 &Handle, 757 &gEfiFirmwareVolume2ProtocolGuid, 758 &Private->FirmwareVolume2, 759 NULL 760 ); 761 ASSERT_EFI_ERROR (Status); 762 } 763 } 764 765 766 /** 767 The user Entry Point for DXE driver. The user code starts with this function 768 as the real entry point for the image goes into a library that calls this 769 function. 770 771 @param[in] ImageHandle The firmware allocated handle for the EFI image. 772 @param[in] SystemTable A pointer to the EFI System Table. 773 774 @retval EFI_SUCCESS The entry point is executed successfully. 775 @retval other Some error occurs when executing this entry point. 776 777 **/ 778 EFI_STATUS 779 EFIAPI 780 InitializeFirmwareVolume ( 781 IN EFI_HANDLE ImageHandle, 782 IN EFI_SYSTEM_TABLE *SystemTable 783 ) 784 { 785 EfiCreateProtocolNotifyEvent ( 786 &gEfiFirmwareVolumeProtocolGuid, 787 TPL_CALLBACK, 788 Fv2NotificationEvent, 789 NULL, 790 &mFv2Registration 791 ); 792 return EFI_SUCCESS; 793 } 794 795 /** 796 Convert FV attributes defined in Framework Specification 797 to FV attributes defined in PI specification. 798 799 @param FvAttributes The FV attributes defined in Framework Specification. 800 801 @retval The FV attributes defined in PI Specification. 802 **/ 803 EFI_FV_ATTRIBUTES 804 FvAttributesToFv2Attributes ( 805 EFI_FV_ATTRIBUTES FvAttributes 806 ) 807 { 808 INTN Alignment; 809 810 Alignment = LowBitSet64 (RShiftU64 (FvAttributes, 16) & 0xffff); 811 if (Alignment != -1) { 812 Alignment = Alignment << 16; 813 } else { 814 Alignment = 0; 815 } 816 FvAttributes = (FvAttributes & 0x1ff) | Alignment; 817 818 return FvAttributes; 819 } 820 821 /** 822 823 Because of constraints imposed by the underlying firmware 824 storage, an instance of the Firmware Volume Protocol may not 825 be to able to support all possible variations of this 826 architecture. These constraints and the current state of the 827 firmware volume are exposed to the caller using the 828 GetVolumeAttributes() function. GetVolumeAttributes() is 829 callable only from TPL_NOTIFY and below. Behavior of 830 GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is 831 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 832 2.0 specification. 833 834 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 835 instance. 836 837 @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which 838 the attributes and current settings are 839 returned. 840 841 842 @retval EFI_SUCCESS The firmware volume attributes were 843 returned. 844 845 **/ 846 EFI_STATUS 847 EFIAPI 848 Fv2GetVolumeAttributes ( 849 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 850 OUT EFI_FV_ATTRIBUTES *FvAttributes 851 ) 852 { 853 EFI_STATUS Status; 854 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 855 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 856 857 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 858 FirmwareVolume = Private->FirmwareVolume; 859 Status = FirmwareVolume->GetVolumeAttributes ( 860 FirmwareVolume, 861 (FRAMEWORK_EFI_FV_ATTRIBUTES *)FvAttributes 862 ); 863 if (!EFI_ERROR (Status)) { 864 *FvAttributes = FvAttributesToFv2Attributes (*FvAttributes); 865 } 866 return Status; 867 } 868 869 /** 870 The SetVolumeAttributes() function is used to set configurable 871 firmware volume attributes. Only EFI_FV_READ_STATUS, 872 EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and 873 then only in accordance with the declared capabilities. All 874 other bits of FvAttributes are ignored on input. On successful 875 return, all bits of *FvAttributes are valid and it contains the 876 completed EFI_FV_ATTRIBUTES for the volume. To modify an 877 attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES 878 is set to the desired value on input. The EFI_FV_LOCK_STATUS bit 879 does not affect the ability to read or write the firmware 880 volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it 881 prevents further modification to all the attribute bits. 882 SetVolumeAttributes() is callable only from TPL_NOTIFY and 883 below. Behavior of SetVolumeAttributes() at any EFI_TPL above 884 TPL_NOTIFY is undefined. Type EFI_TPL is defined in 885 RaiseTPL() in the UEFI 2.0 specification. 886 887 888 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 889 instance. 890 891 @param FvAttributes On input, FvAttributes is a pointer to 892 an EFI_FV_ATTRIBUTES containing the 893 desired firmware volume settings. On 894 successful return, it contains the new 895 settings of the firmware volume. On 896 unsuccessful return, FvAttributes is not 897 modified and the firmware volume 898 settings are not changed. 899 900 @retval EFI_SUCCESS The requested firmware volume attributes 901 were set and the resulting 902 EFI_FV_ATTRIBUTES is returned in 903 FvAttributes. 904 905 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 906 is set to 1 on input, but the 907 device does not support enabling 908 reads 909 (FvAttributes:EFI_FV_READ_ENABLE 910 is clear on return from 911 GetVolumeAttributes()). Actual 912 volume attributes are unchanged. 913 914 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS 915 is cleared to 0 on input, but 916 the device does not support 917 disabling reads 918 (FvAttributes:EFI_FV_READ_DISABL 919 is clear on return from 920 GetVolumeAttributes()). Actual 921 volume attributes are unchanged. 922 923 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 924 is set to 1 on input, but the 925 device does not support enabling 926 writes 927 (FvAttributes:EFI_FV_WRITE_ENABL 928 is clear on return from 929 GetVolumeAttributes()). Actual 930 volume attributes are unchanged. 931 932 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS 933 is cleared to 0 on input, but 934 the device does not support 935 disabling writes 936 (FvAttributes:EFI_FV_WRITE_DISAB 937 is clear on return from 938 GetVolumeAttributes()). Actual 939 volume attributes are unchanged. 940 941 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS 942 is set on input, but the device 943 does not support locking 944 (FvAttributes:EFI_FV_LOCK_CAP is 945 clear on return from 946 GetVolumeAttributes()). Actual 947 volume attributes are unchanged. 948 949 @retval EFI_ACCESS_DENIED Device is locked and does not 950 allow attribute modification 951 (FvAttributes:EFI_FV_LOCK_STATUS 952 is set on return from 953 GetVolumeAttributes()). Actual 954 volume attributes are unchanged. 955 956 **/ 957 EFI_STATUS 958 EFIAPI 959 Fv2SetVolumeAttributes ( 960 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 961 IN OUT EFI_FV_ATTRIBUTES *FvAttributes 962 ) 963 { 964 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 965 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 966 FRAMEWORK_EFI_FV_ATTRIBUTES FrameworkFvAttributes; 967 EFI_STATUS Status; 968 UINTN Shift; 969 970 if ((*FvAttributes & (EFI_FV2_READ_LOCK_STATUS | EFI_FV2_WRITE_LOCK_STATUS)) != 0) { 971 // 972 // Framework FV protocol does not support EFI_FV2_READ_LOCK_* | EFI_FV2_WRITE_LOCK_* 973 // 974 return EFI_INVALID_PARAMETER; 975 } 976 977 *FvAttributes = *FvAttributes & (EFI_FV2_READ_STATUS | EFI_FV2_WRITE_STATUS | EFI_FV2_LOCK_STATUS); 978 979 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 980 FirmwareVolume = Private->FirmwareVolume; 981 982 FrameworkFvAttributes = (*FvAttributes & 0x1ff); 983 Shift = (UINTN) RShiftU64(*FvAttributes & EFI_FV2_ALIGNMENT, 16); 984 FrameworkFvAttributes = FrameworkFvAttributes | LShiftU64 (EFI_FV_ALIGNMENT_2, Shift); 985 986 Status = FirmwareVolume->SetVolumeAttributes ( 987 FirmwareVolume, 988 &FrameworkFvAttributes 989 ); 990 991 if (!EFI_ERROR (Status)) { 992 *FvAttributes = FvAttributesToFv2Attributes (FrameworkFvAttributes); 993 } 994 995 return Status; 996 } 997 998 /** 999 ReadFile() is used to retrieve any file from a firmware volume 1000 during the DXE phase. The actual binary encoding of the file in 1001 the firmware volume media may be in any arbitrary format as long 1002 as it does the following: It is accessed using the Firmware 1003 Volume Protocol. The image that is returned follows the image 1004 format defined in Code Definitions: PI Firmware File Format. 1005 If the input value of Buffer==NULL, it indicates the caller is 1006 requesting only that the type, attributes, and size of the 1007 file be returned and that there is no output buffer. In this 1008 case, the following occurs: 1009 - BufferSize is returned with the size that is required to 1010 successfully complete the read. 1011 - The output parameters FoundType and *FileAttributes are 1012 returned with valid values. 1013 - The returned value of *AuthenticationStatus is undefined. 1014 1015 If the input value of Buffer!=NULL, the output buffer is 1016 specified by a double indirection of the Buffer parameter. The 1017 input value of *Buffer is used to determine if the output 1018 buffer is caller allocated or is dynamically allocated by 1019 ReadFile(). If the input value of *Buffer!=NULL, it indicates 1020 the output buffer is caller allocated. In this case, the input 1021 value of *BufferSize indicates the size of the 1022 caller-allocated output buffer. If the output buffer is not 1023 large enough to contain the entire requested output, it is 1024 filled up to the point that the output buffer is exhausted and 1025 EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is 1026 returned with the size required to successfully complete the 1027 read. All other output parameters are returned with valid 1028 values. If the input value of *Buffer==NULL, it indicates the 1029 output buffer is to be allocated by ReadFile(). In this case, 1030 ReadFile() will allocate an appropriately sized buffer from 1031 boot services pool memory, which will be returned in Buffer. 1032 The size of the new buffer is returned in BufferSize and all 1033 other output parameters are returned with valid values. 1034 ReadFile() is callable only from TPL_NOTIFY and below. 1035 Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is 1036 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 1037 2.0 specification. 1038 1039 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 1040 instance. 1041 1042 @param NameGuid Pointer to an EFI_GUID, which is the file 1043 name. All firmware file names are EFI_GUIDs. 1044 A single firmware volume must not have two 1045 valid files with the same file name 1046 EFI_GUID. 1047 1048 @param Buffer Pointer to a pointer to a buffer in which the 1049 file contents are returned, not including the 1050 file header. 1051 @param BufferSize Pointer to a caller-allocated UINTN. It 1052 indicates the size of the memory 1053 represented by Buffer. 1054 1055 @param FoundType Pointer to a caller-allocated 1056 EFI_FV_FILETYPE. 1057 1058 @param FileAttributes Pointer to a caller-allocated 1059 EFI_FV_FILE_ATTRIBUTES. 1060 1061 @param AuthenticationStatus Pointer to a caller-allocated 1062 UINT32 in which the 1063 authentication status is 1064 returned. 1065 1066 @retval EFI_SUCCESS The call completed successfully. 1067 1068 @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to 1069 contain the requested 1070 output. The buffer is 1071 filled and the output is 1072 truncated. 1073 1074 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 1075 1076 @retval EFI_NOT_FOUND Name was not found in the firmware 1077 volume. 1078 1079 @retval EFI_DEVICE_ERROR A hardware error occurred when 1080 attempting to access the firmware 1081 volume. 1082 1083 @retval EFI_ACCESS_DENIED The firmware volume is configured to 1084 isallow reads. 1085 1086 **/ 1087 EFI_STATUS 1088 EFIAPI 1089 Fv2ReadFile ( 1090 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1091 IN CONST EFI_GUID *NameGuid, 1092 IN OUT VOID **Buffer, 1093 IN OUT UINTN *BufferSize, 1094 OUT EFI_FV_FILETYPE *FoundType, 1095 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, 1096 OUT UINT32 *AuthenticationStatus 1097 ) 1098 { 1099 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 1100 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 1101 1102 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 1103 FirmwareVolume = Private->FirmwareVolume; 1104 1105 return FirmwareVolume->ReadFile ( 1106 FirmwareVolume, 1107 (EFI_GUID *)NameGuid, 1108 Buffer, 1109 BufferSize, 1110 FoundType, 1111 FileAttributes, 1112 AuthenticationStatus 1113 ); 1114 } 1115 1116 /** 1117 ReadSection() is used to retrieve a specific section from a file 1118 within a firmware volume. The section returned is determined 1119 using a depth-first, left-to-right search algorithm through all 1120 sections found in the specified file.The output buffer is specified 1121 by a double indirection of the Buffer parameter. The input value of Buffer 1122 is used to determine if the output buffer is caller allocated or is 1123 dynamically allocated by ReadSection(). If the input value of 1124 Buffer!=NULL, it indicates that the output buffer is caller 1125 allocated. In this case, the input value of *BufferSize 1126 indicates the size of the caller-allocated output buffer. If 1127 the output buffer is not large enough to contain the entire 1128 requested output, it is filled up to the point that the output 1129 buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, 1130 and then BufferSize is returned with the size that is required 1131 to successfully complete the read. All other 1132 output parameters are returned with valid values. If the input 1133 value of *Buffer==NULL, it indicates the output buffer is to 1134 be allocated by ReadSection(). In this case, ReadSection() 1135 will allocate an appropriately sized buffer from boot services 1136 pool memory, which will be returned in *Buffer. The size of 1137 the new buffer is returned in *BufferSize and all other output 1138 parameters are returned with valid values. ReadSection() is 1139 callable only from TPL_NOTIFY and below. Behavior of 1140 ReadSection() at any EFI_TPL above TPL_NOTIFY is 1141 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 1142 2.0 specification. 1143 1144 1145 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 1146 instance. 1147 1148 @param NameGuid Pointer to an EFI_GUID, which indicates the 1149 file name from which the requested section 1150 will be read. 1151 1152 @param SectionType Indicates the section type to return. 1153 SectionType in conjunction with 1154 SectionInstance indicates which section to 1155 return. 1156 1157 @param SectionInstance Indicates which instance of sections 1158 with a type of SectionType to return. 1159 SectionType in conjunction with 1160 SectionInstance indicates which 1161 section to return. SectionInstance is 1162 zero based. 1163 1164 @param Buffer Pointer to a pointer to a buffer in which the 1165 section contents are returned, not including 1166 the section header. 1167 1168 @param BufferSize Pointer to a caller-allocated UINTN. It 1169 indicates the size of the memory 1170 represented by Buffer. 1171 1172 @param AuthenticationStatus Pointer to a caller-allocated 1173 UINT32 in which the authentication 1174 status is returned. 1175 1176 1177 @retval EFI_SUCCESS The call completed successfully. 1178 1179 @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated 1180 buffer is too small to 1181 contain the requested 1182 output. The buffer is 1183 filled and the output is 1184 truncated. 1185 1186 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. 1187 1188 @retval EFI_NOT_FOUND The requested file was not found in 1189 the firmware volume. EFI_NOT_FOUND The 1190 requested section was not found in the 1191 specified file. 1192 1193 @retval EFI_DEVICE_ERROR A hardware error occurred when 1194 attempting to access the firmware 1195 volume. 1196 1197 @retval EFI_ACCESS_DENIED The firmware volume is configured to 1198 disallow reads. EFI_PROTOCOL_ERROR 1199 The requested section was not found, 1200 but the file could not be fully 1201 parsed because a required 1202 GUIDED_SECTION_EXTRACTION_PROTOCOL 1203 was not found. It is possible the 1204 requested section exists within the 1205 file and could be successfully 1206 extracted once the required 1207 GUIDED_SECTION_EXTRACTION_PROTOCOL 1208 is published. 1209 1210 **/ 1211 EFI_STATUS 1212 EFIAPI 1213 Fv2ReadSection ( 1214 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1215 IN CONST EFI_GUID *NameGuid, 1216 IN EFI_SECTION_TYPE SectionType, 1217 IN UINTN SectionInstance, 1218 IN OUT VOID **Buffer, 1219 IN OUT UINTN *BufferSize, 1220 OUT UINT32 *AuthenticationStatus 1221 ) 1222 { 1223 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 1224 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 1225 1226 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 1227 FirmwareVolume = Private->FirmwareVolume; 1228 1229 return FirmwareVolume->ReadSection ( 1230 FirmwareVolume, 1231 (EFI_GUID *)NameGuid, 1232 SectionType, 1233 SectionInstance, 1234 Buffer, 1235 BufferSize, 1236 AuthenticationStatus 1237 ); 1238 } 1239 1240 /** 1241 WriteFile() is used to write one or more files to a firmware 1242 volume. Each file to be written is described by an 1243 EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that 1244 any required alignment for all files listed in the FileData 1245 array is compatible with the firmware volume. Firmware volume 1246 capabilities can be determined using the GetVolumeAttributes() 1247 call. Similarly, if the WritePolicy is set to 1248 EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume 1249 capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the 1250 firmware volume. EFI_FV_UNRELIABLE_WRITE must always be 1251 supported. Writing a file with a size of zero 1252 (FileData[n].BufferSize == 0) deletes the file from the firmware 1253 volume if it exists. Deleting a file must be done one at a time. 1254 Deleting a file as part of a multiple file write is not allowed. 1255 Platform Initialization Specification VOLUME 3 Shared 1256 Architectural Elements 84 August 21, 2006 Version 1.0 1257 WriteFile() is callable only from TPL_NOTIFY and below. 1258 Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is 1259 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 1260 specification. 1261 1262 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. 1263 1264 @param NumberOfFiles Indicates the number of 1265 elements in the array pointed to by FileData. 1266 1267 1268 @param WritePolicy Indicates the level of reliability for the 1269 write in the event of a power failure or 1270 other system failure during the write 1271 operation. 1272 1273 @param FileData Pointer to an array of 1274 EFI_FV_WRITE_FILE_DATA. Each element of 1275 FileData[] represents a file to be written. 1276 1277 1278 @retval EFI_SUCCESS The write completed successfully. 1279 1280 @retval EFI_OUT_OF_RESOURCES The firmware volume does not 1281 have enough free space to 1282 storefile(s). 1283 1284 @retval EFI_DEVICE_ERROR A hardware error occurred when 1285 attempting to access the firmware volume. 1286 1287 @retval EFI_WRITE_PROTECTED The firmware volume is 1288 configured to disallow writes. 1289 1290 @retval EFI_NOT_FOUND A delete was requested, but the 1291 requested file was not found in the 1292 firmware volume. 1293 1294 @retval EFI_INVALID_PARAMETER A delete was requested with a 1295 multiple file write. 1296 1297 @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was 1298 requested. 1299 1300 @retval EFI_INVALID_PARAMETER An unknown file type was 1301 specified. 1302 1303 @retval EFI_INVALID_PARAMETER A file system specific error 1304 has occurred. 1305 1306 **/ 1307 EFI_STATUS 1308 EFIAPI 1309 Fv2WriteFile ( 1310 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1311 IN UINT32 NumberOfFiles, 1312 IN EFI_FV_WRITE_POLICY WritePolicy, 1313 IN EFI_FV_WRITE_FILE_DATA *FileData 1314 ) 1315 { 1316 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 1317 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 1318 1319 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 1320 FirmwareVolume = Private->FirmwareVolume; 1321 1322 return FirmwareVolume->WriteFile ( 1323 FirmwareVolume, 1324 NumberOfFiles, 1325 WritePolicy, 1326 (FRAMEWORK_EFI_FV_WRITE_FILE_DATA *)FileData 1327 ); 1328 } 1329 1330 /** 1331 GetNextFile() is the interface that is used to search a firmware 1332 volume for a particular file. It is called successively until 1333 the desired file is located or the function returns 1334 EFI_NOT_FOUND. To filter uninteresting files from the output, 1335 the type of file to search for may be specified in FileType. For 1336 example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of 1337 this type will be returned in the output. If *FileType is 1338 EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key 1339 parameter is used to indicate a starting point of the search. If 1340 the buffer *Key is completely initialized to zero, the search 1341 re-initialized and starts at the beginning. Subsequent calls to 1342 GetNextFile() must maintain the value of *Key returned by the 1343 immediately previous call. The actual contents of *Key are 1344 implementation specific and no semantic content is implied. 1345 GetNextFile() is callable only from TPL_NOTIFY and below. 1346 Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is 1347 undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 1348 specification. Status Codes Returned 1349 1350 1351 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL 1352 instance. 1353 1354 @param Key Pointer to a caller-allocated buffer 1355 that contains implementation-specific data that is 1356 used to track where to begin the search for the 1357 next file. The size of the buffer must be at least 1358 This->KeySize bytes long. To re-initialize the 1359 search and begin from the beginning of the 1360 firmware volume, the entire buffer must be cleared 1361 to zero. Other than clearing the buffer to 1362 initiate a new search, the caller must not modify 1363 the data in the buffer between calls to 1364 GetNextFile(). 1365 1366 @param FileType Pointer to a caller-allocated 1367 EFI_FV_FILETYPE. The GetNextFile() API can 1368 filter its search for files based on the 1369 value of the FileType input. A *FileType 1370 input of EFI_FV_FILETYPE_ALL causes 1371 GetNextFile() to search for files of all 1372 types. If a file is found, the file's type 1373 is returned in FileType. *FileType is not 1374 modified if no file is found. 1375 1376 @param NameGuid Pointer to a caller-allocated EFI_GUID. If a 1377 matching file is found, the file's name is 1378 returned in NameGuid. If no matching file is 1379 found, *NameGuid is not modified. 1380 1381 @param Attributes Pointer to a caller-allocated 1382 EFI_FV_FILE_ATTRIBUTES. If a matching file 1383 is found, the file's attributes are returned 1384 in Attributes. If no matching file is found, 1385 Attributes is not modified. Type 1386 EFI_FV_FILE_ATTRIBUTES is defined in 1387 ReadFile(). 1388 1389 @param Size Pointer to a caller-allocated UINTN. If a 1390 matching file is found, the file's size is 1391 returned in *Size. If no matching file is found, 1392 Size is not modified. 1393 1394 @retval EFI_SUCCESS The output parameters are filled with data 1395 obtained from the first matching file that 1396 was found. 1397 1398 @retval FI_NOT_FOUND No files of type FileType were found. 1399 1400 1401 @retval EFI_DEVICE_ERROR A hardware error occurred when 1402 attempting to access the firmware 1403 volume. 1404 1405 @retval EFI_ACCESS_DENIED The firmware volume is configured to 1406 disallow reads. 1407 1408 1409 **/ 1410 EFI_STATUS 1411 EFIAPI 1412 Fv2GetNextFile ( 1413 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1414 IN OUT VOID *Key, 1415 IN OUT EFI_FV_FILETYPE *FileType, 1416 OUT EFI_GUID *NameGuid, 1417 OUT EFI_FV_FILE_ATTRIBUTES *Attributes, 1418 OUT UINTN *Size 1419 ) 1420 { 1421 FIRMWARE_VOLUME2_PRIVATE_DATA *Private; 1422 EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume; 1423 1424 Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This); 1425 FirmwareVolume = Private->FirmwareVolume; 1426 1427 return FirmwareVolume->GetNextFile ( 1428 FirmwareVolume, 1429 Key, 1430 FileType, 1431 NameGuid, 1432 Attributes, 1433 Size 1434 ); 1435 } 1436 1437 /** 1438 The GetInfo() function returns information of type 1439 InformationType for the requested firmware volume. If the volume 1440 does not support the requested information type, then 1441 EFI_UNSUPPORTED is returned. If the buffer is not large enough 1442 to hold the requested structure, EFI_BUFFER_TOO_SMALL is 1443 returned and the BufferSize is set to the size of buffer that is 1444 required to make the request. The information types defined by 1445 this specification are required information types that all file 1446 systems must support. 1447 1448 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 1449 instance that is the file handle the requested 1450 information is for. 1451 1452 @param InformationType The type identifier for the 1453 information being requested. 1454 1455 @param BufferSize On input, the size of Buffer. On output, 1456 the amount of data returned in Buffer. In 1457 both cases, the size is measured in bytes. 1458 1459 @param Buffer A pointer to the data buffer to return. The 1460 buffer's type is indicated by InformationType. 1461 1462 1463 @retval EFI_SUCCESS The information was retrieved. 1464 1465 @retval EFI_UNSUPPORTED The InformationType is not known. 1466 1467 @retval EFI_NO_MEDIA The device has no medium. 1468 1469 @retval EFI_DEVICE_ERROR The device reported an error. 1470 1471 @retval EFI_VOLUME_CORRUPTED The file system structures are 1472 corrupted. 1473 1474 @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to 1475 read the current directory 1476 entry. BufferSize has been 1477 updated with the size needed to 1478 complete the request. 1479 1480 1481 **/ 1482 EFI_STATUS 1483 EFIAPI 1484 Fv2GetInfo ( 1485 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1486 IN CONST EFI_GUID *InformationType, 1487 IN OUT UINTN *BufferSize, 1488 OUT VOID *Buffer 1489 ) 1490 { 1491 return EFI_UNSUPPORTED; 1492 } 1493 1494 /** 1495 1496 The SetInfo() function sets information of type InformationType 1497 on the requested firmware volume. 1498 1499 1500 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL 1501 instance that is the file handle the information 1502 is for. 1503 1504 @param InformationType The type identifier for the 1505 information being set. 1506 1507 @param BufferSize The size, in bytes, of Buffer. 1508 1509 @param Buffer A pointer to the data buffer to write. The 1510 buffer's type is indicated by InformationType. 1511 1512 @retval EFI_SUCCESS The information was set. 1513 1514 @retval EFI_UNSUPPORTED The InformationType is not known. 1515 1516 @retval EFI_NO_MEDIA The device has no medium. 1517 1518 @retval EFI_DEVICE_ERROR The device reported an error. 1519 1520 @retval EFI_VOLUME_CORRUPTED The file system structures are 1521 corrupted. 1522 1523 1524 @retval EFI_WRITE_PROTECTED The media is read only. 1525 1526 @retval EFI_VOLUME_FULL The volume is full. 1527 1528 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the 1529 size of the type indicated by 1530 InformationType. 1531 1532 **/ 1533 EFI_STATUS 1534 EFIAPI 1535 Fv2SetInfo ( 1536 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, 1537 IN CONST EFI_GUID *InformationType, 1538 IN UINTN BufferSize, 1539 IN CONST VOID *Buffer 1540 ) 1541 { 1542 return EFI_UNSUPPORTED; 1543 } 1544
