EdkCompatibilityPkg/Compatibility/Fv2ToFvThunk/Fv2ToFvThunk.c

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