EdkCompatibilityPkg/Compatibility/Fv2OnFvThunk/Fv2OnFvThunk.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  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 /**
 787   Convert FV attributes defined in Framework Specification
 788   to FV attributes defined in PI specification.
 789
 790   @param FvAttributes          The FV attributes defined in Framework Specification.
 791
 792   @retval                      The FV attributes defined in PI Specification.
 793 **/
 794 EFI_FV_ATTRIBUTES
 795 FvAttributesToFv2Attributes (
 796   EFI_FV_ATTRIBUTES FvAttributes
 797   )
 798 {
 799   INTN                           Alignment;
 800
 801   Alignment = LowBitSet64 (RShiftU64 (FvAttributes, 16) & 0xffff);
 802   if (Alignment != -1) {
 803     Alignment = Alignment << 16;
 804   } else {
 805     Alignment = 0;
 806   }
 807   FvAttributes = (FvAttributes & 0x1ff) | Alignment;
 808
 809   return FvAttributes;
 810 }
 811
 812 /**
 813
 814   Because of constraints imposed by the underlying firmware
 815   storage, an instance of the Firmware Volume Protocol may not
 816   be to able to support all possible variations of this
 817   architecture. These constraints and the current state of the
 818   firmware volume are exposed to the caller using the
 819   GetVolumeAttributes() function. GetVolumeAttributes() is
 820   callable only from TPL_NOTIFY and below. Behavior of
 821   GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is
 822   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI
 823   2.0 specification.
 824
 825   @param  This    Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 826                   instance.
 827
 828   @param  FvAttributes  Pointer to an EFI_FV_ATTRIBUTES in which
 829                         the attributes and current settings are
 830                         returned.
 831
 832
 833   @retval EFI_SUCCESS   The firmware volume attributes were
 834                         returned.
 835
 836 **/
 837 EFI_STATUS
 838 EFIAPI
 839 Fv2GetVolumeAttributes (
 840   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 841   OUT       EFI_FV_ATTRIBUTES             *FvAttributes
 842   )
 843 {
 844   EFI_STATUS                     Status;
 845   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
 846   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
 847
 848   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
 849   FirmwareVolume = Private->FirmwareVolume;
 850   Status = FirmwareVolume->GetVolumeAttributes (
 851                              FirmwareVolume,
 852                              (FRAMEWORK_EFI_FV_ATTRIBUTES *)FvAttributes
 853                              );
 854   if (!EFI_ERROR (Status)) {
 855     *FvAttributes = FvAttributesToFv2Attributes (*FvAttributes);
 856   }
 857   return Status;
 858 }
 859
 860 /**
 861   The SetVolumeAttributes() function is used to set configurable
 862   firmware volume attributes. Only EFI_FV_READ_STATUS,
 863   EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and
 864    then only in accordance with the declared capabilities. All
 865   other bits of FvAttributes are ignored on input. On successful
 866   return, all bits of *FvAttributes are valid and it contains the
 867   completed EFI_FV_ATTRIBUTES for the volume. To modify an
 868   attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES
 869   is set to the desired value on input. The EFI_FV_LOCK_STATUS bit
 870   does not affect the ability to read or write the firmware
 871   volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it
 872   prevents further modification to all the attribute bits.
 873   SetVolumeAttributes() is callable only from TPL_NOTIFY and
 874   below. Behavior of SetVolumeAttributes() at any EFI_TPL above
 875   TPL_NOTIFY is undefined. Type EFI_TPL is defined in
 876   RaiseTPL() in the UEFI 2.0 specification.
 877
 878
 879   @param  This  Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 880                 instance.
 881
 882   @param  FvAttributes  On input, FvAttributes is a pointer to
 883                         an EFI_FV_ATTRIBUTES containing the
 884                         desired firmware volume settings. On
 885                         successful return, it contains the new
 886                         settings of the firmware volume. On
 887                         unsuccessful return, FvAttributes is not
 888                         modified and the firmware volume
 889                         settings are not changed.
 890
 891   @retval EFI_SUCCESS   The requested firmware volume attributes
 892                         were set and the resulting
 893                         EFI_FV_ATTRIBUTES is returned in
 894                         FvAttributes.
 895
 896   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS
 897                                 is set to 1 on input, but the
 898                                 device does not support enabling
 899                                 reads
 900                                 (FvAttributes:EFI_FV_READ_ENABLE
 901                                 is clear on return from
 902                                 GetVolumeAttributes()). Actual
 903                                 volume attributes are unchanged.
 904
 905   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS
 906                                 is cleared to 0 on input, but
 907                                 the device does not support
 908                                 disabling reads
 909                                 (FvAttributes:EFI_FV_READ_DISABL
 910                                 is clear on return from
 911                                 GetVolumeAttributes()). Actual
 912                                 volume attributes are unchanged.
 913
 914   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS
 915                                 is set to 1 on input, but the
 916                                 device does not support enabling
 917                                 writes
 918                                 (FvAttributes:EFI_FV_WRITE_ENABL
 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 cleared to 0 on input, but
 925                                 the device does not support
 926                                 disabling writes
 927                                 (FvAttributes:EFI_FV_WRITE_DISAB
 928                                 is clear on return from
 929                                 GetVolumeAttributes()). Actual
 930                                 volume attributes are unchanged.
 931
 932   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS
 933                                 is set on input, but the device
 934                                 does not support locking
 935                                 (FvAttributes:EFI_FV_LOCK_CAP is
 936                                 clear on return from
 937                                 GetVolumeAttributes()). Actual
 938                                 volume attributes are unchanged.
 939
 940   @retval EFI_ACCESS_DENIED     Device is locked and does not
 941                                 allow attribute modification
 942                                 (FvAttributes:EFI_FV_LOCK_STATUS
 943                                 is set on return from
 944                                 GetVolumeAttributes()). Actual
 945                                 volume attributes are unchanged.
 946
 947 **/
 948 EFI_STATUS
 949 EFIAPI
 950 Fv2SetVolumeAttributes (
 951   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 952   IN OUT    EFI_FV_ATTRIBUTES             *FvAttributes
 953   )
 954 {
 955   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
 956   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
 957   FRAMEWORK_EFI_FV_ATTRIBUTES    FrameworkFvAttributes;
 958   EFI_STATUS                     Status;
 959   UINTN                          Shift;
 960
 961   if (*FvAttributes & (EFI_FV2_READ_LOCK_STATUS | EFI_FV2_WRITE_LOCK_STATUS)) {
 962     //
 963     // Framework FV protocol does not support EFI_FV2_READ_LOCK_* | EFI_FV2_WRITE_LOCK_*
 964     //
 965     return EFI_INVALID_PARAMETER;
 966   }
 967
 968   *FvAttributes = *FvAttributes & (EFI_FV2_READ_STATUS | EFI_FV2_WRITE_STATUS | EFI_FV2_LOCK_STATUS);
 969
 970   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
 971   FirmwareVolume = Private->FirmwareVolume;
 972
 973   FrameworkFvAttributes = (*FvAttributes & 0x1ff);
 974   Shift = (UINTN) RShiftU64(*FvAttributes & EFI_FV2_ALIGNMENT, 16);
 975   FrameworkFvAttributes = FrameworkFvAttributes | LShiftU64 (EFI_FV_ALIGNMENT_2, Shift);
 976
 977   Status =  FirmwareVolume->SetVolumeAttributes (
 978                            FirmwareVolume,
 979                            &FrameworkFvAttributes
 980                            );
 981
 982   if (!EFI_ERROR (Status)) {
 983     *FvAttributes = FvAttributesToFv2Attributes (FrameworkFvAttributes);
 984   }
 985
 986   return Status;
 987 }
 988
 989 /**
 990   ReadFile() is used to retrieve any file from a firmware volume
 991   during the DXE phase. The actual binary encoding of the file in
 992   the firmware volume media may be in any arbitrary format as long
 993   as it does the following: ?It is accessed using the Firmware
 994   Volume Protocol. ?The image that is returned follows the image
 995   format defined in Code Definitions: PI Firmware File Format.
 996   If the input value of Buffer==NULL, it indicates the caller is
 997   requesting only that the type, attributes, and size of the
 998   file be returned and that there is no output buffer. In this
 999   case, the following occurs:
1000   - BufferSize is returned with the size that is required to
1001     successfully complete the read.
1002   - The output parameters FoundType and *FileAttributes are
1003   returned with valid values.
1004   - The returned value of *AuthenticationStatus is undefined.
1005
1006   If the input value of Buffer!=NULL, the output buffer is
1007   specified by a double indirection of the Buffer parameter. The
1008   input value of *Buffer is used to determine if the output
1009   buffer is caller allocated or is dynamically allocated by
1010   ReadFile(). If the input value of *Buffer!=NULL, it indicates
1011   the output buffer is caller allocated. In this case, the input
1012    value of *BufferSize indicates the size of the
1013   caller-allocated output buffer. If the output buffer is not
1014   large enough to contain the entire requested output, it is
1015   filled up to the point that the output buffer is exhausted and
1016   EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is
1017    returned with the size required to successfully complete the
1018   read. All other output parameters are returned with valid
1019   values. If the input value of *Buffer==NULL, it indicates the
1020   output buffer is to be allocated by ReadFile(). In this case,
1021   ReadFile() will allocate an appropriately sized buffer from
1022   boot services pool memory, which will be returned in Buffer.
1023   The size of the new buffer is returned in BufferSize and all
1024   other output parameters are returned with valid values.
1025   ReadFile() is callable only from TPL_NOTIFY and below.
1026   Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is
1027   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI
1028   2.0 specification.
1029
1030   @param  This  Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
1031                 instance.
1032
1033   @param  NameGuid  Pointer to an EFI_GUID, which is the file
1034                     name. All firmware file names are EFI_GUIDs.
1035                     A single firmware volume must not have two
1036                     valid files with the same file name
1037                     EFI_GUID.
1038
1039   @param  Buffer  Pointer to a pointer to a buffer in which the
1040                   file contents are returned, not including the
1041                   file header.
1042   @param  BufferSize  Pointer to a caller-allocated UINTN. It
1043                       indicates the size of the memory
1044                       represented by Buffer.
1045
1046   @param  FoundType   Pointer to a caller-allocated
1047                       EFI_FV_FILETYPE.
1048
1049   @param  FileAttributes  Pointer to a  caller-allocated
1050                           EFI_FV_FILE_ATTRIBUTES.
1051
1052   @param  AuthenticationStatus  Pointer to a caller-allocated
1053                                 UINT32 in which the
1054                                 authentication status is
1055                                 returned.
1056
1057   @retval EFI_SUCCESS   The call completed successfully.
1058
1059   @retval EFI_WARN_BUFFER_TOO_SMALL   The buffer is too small to
1060                                       contain the requested
1061                                       output. The buffer is
1062                                       filled and the output is
1063                                       truncated.
1064
1065   @retval EFI_OUT_OF_RESOURCES  An allocation failure occurred.
1066
1067   @retavl EFI_NOT_FOUND   Name was not found in the firmware
1068                           volume.
1069
1070   @retval EFI_DEVICE_ERROR  A hardware error occurred when
1071                             attempting to access the firmware
1072                             volume.
1073
1074   @retval EFI_ACCESS_DENIED The firmware volume is configured to
1075                             isallow reads.
1076
1077 **/
1078 EFI_STATUS
1079 EFIAPI
1080 Fv2ReadFile (
1081   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1082   IN CONST  EFI_GUID                      *NameGuid,
1083   IN OUT    VOID                          **Buffer,
1084   IN OUT    UINTN                         *BufferSize,
1085   OUT       EFI_FV_FILETYPE               *FoundType,
1086   OUT       EFI_FV_FILE_ATTRIBUTES        *FileAttributes,
1087   OUT       UINT32                        *AuthenticationStatus
1088   )
1089 {
1090   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
1091   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
1092
1093   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
1094   FirmwareVolume = Private->FirmwareVolume;
1095
1096   return FirmwareVolume->ReadFile (
1097                            FirmwareVolume,
1098                            (EFI_GUID *)NameGuid,
1099                            Buffer,
1100                            BufferSize,
1101                            FoundType,
1102                            FileAttributes,
1103                            AuthenticationStatus
1104                            );
1105 }
1106
1107 /**
1108   ReadSection() is used to retrieve a specific section from a file
1109   within a firmware volume. The section returned is determined
1110   using a depth-first, left-to-right search algorithm through all
1111   sections found in the specified file. See
1112    ????Firmware File Sections???? on page 9 for more details about
1113   sections. The output buffer is specified by a double indirection
1114   of the Buffer parameter. The input value of Buffer is used to
1115   determine if the output buffer is caller allocated or is
1116   dynamically allocated by ReadSection(). If the input value of
1117   Buffer!=NULL, it indicates that the output buffer is caller
1118   allocated. In this case, the input value of *BufferSize
1119   indicates the size of the caller-allocated output buffer. If
1120   the output buffer is not large enough to contain the entire
1121   requested output, it is filled up to the point that the output
1122   buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned,
1123   and then BufferSize is returned with the size that is required
1124   to successfully complete the read. All other
1125   output parameters are returned with valid values. If the input
1126   value of *Buffer==NULL, it indicates the output buffer is to
1127   be allocated by ReadSection(). In this case, ReadSection()
1128   will allocate an appropriately sized buffer from boot services
1129   pool memory, which will be returned in *Buffer. The size of
1130   the new buffer is returned in *BufferSize and all other output
1131   parameters are returned with valid values. ReadSection() is
1132   callable only from TPL_NOTIFY and below. Behavior of
1133   ReadSection() at any EFI_TPL above TPL_NOTIFY is
1134   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI
1135   2.0 specification.
1136
1137
1138   @param This   Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
1139                 instance.
1140
1141   @param NameGuid   Pointer to an EFI_GUID, which indicates the
1142                     file name from which the requested section
1143                     will be read.
1144
1145   @param SectionType  Indicates the section type to return.
1146                       SectionType in conjunction with
1147                       SectionInstance indicates which section to
1148                       return.
1149
1150   @param SectionInstance  Indicates which instance of sections
1151                           with a type of SectionType to return.
1152                           SectionType in conjunction with
1153                           SectionInstance indicates which
1154                           section to return. SectionInstance is
1155                           zero based.
1156
1157   @param Buffer   Pointer to a pointer to a buffer in which the
1158                   section contents are returned, not including
1159                   the section header.
1160
1161   @param BufferSize   Pointer to a caller-allocated UINTN. It
1162                       indicates the size of the memory
1163                       represented by Buffer.
1164
1165   @param AuthenticationStatus Pointer to a caller-allocated
1166                               UINT32 in which the authentication
1167                               status is returned.
1168
1169
1170   @retval EFI_SUCCESS   The call completed successfully.
1171
1172   @retval EFI_WARN_BUFFER_TOO_SMALL   The caller-allocated
1173                                       buffer is too small to
1174                                       contain the requested
1175                                       output. The buffer is
1176                                       filled and the output is
1177                                       truncated.
1178
1179   @retval EFI_OUT_OF_RESOURCES  An allocation failure occurred.
1180
1181   @retval EFI_NOT_FOUND   The requested file was not found in
1182                           the firmware volume. EFI_NOT_FOUND The
1183                           requested section was not found in the
1184                           specified file.
1185
1186   @retval EFI_DEVICE_ERROR  A hardware error occurred when
1187                             attempting to access the firmware
1188                             volume.
1189
1190   @retval EFI_ACCESS_DENIED The firmware volume is configured to
1191                             disallow reads. EFI_PROTOCOL_ERROR
1192                             The requested section was not found,
1193                             but the file could not be fully
1194                             parsed because a required
1195                             GUIDED_SECTION_EXTRACTION_PROTOCOL
1196                             was not found. It is possible the
1197                             requested section exists within the
1198                             file and could be successfully
1199                             extracted once the required
1200                             GUIDED_SECTION_EXTRACTION_PROTOCOL
1201                             is published.
1202
1203 **/
1204 EFI_STATUS
1205 EFIAPI
1206 Fv2ReadSection (
1207   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1208   IN CONST  EFI_GUID                      *NameGuid,
1209   IN        EFI_SECTION_TYPE              SectionType,
1210   IN        UINTN                         SectionInstance,
1211   IN OUT    VOID                          **Buffer,
1212   IN OUT    UINTN                         *BufferSize,
1213   OUT       UINT32                        *AuthenticationStatus
1214   )
1215 {
1216   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
1217   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
1218
1219   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
1220   FirmwareVolume = Private->FirmwareVolume;
1221
1222   return FirmwareVolume->ReadSection (
1223                            FirmwareVolume,
1224                            (EFI_GUID *)NameGuid,
1225                            SectionType,
1226                            SectionInstance,
1227                            Buffer,
1228                            BufferSize,
1229                            AuthenticationStatus
1230                            );
1231 }
1232
1233 /**
1234   WriteFile() is used to write one or more files to a firmware
1235   volume. Each file to be written is described by an
1236   EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that
1237   any required alignment for all files listed in the FileData
1238   array is compatible with the firmware volume. Firmware volume
1239   capabilities can be determined using the GetVolumeAttributes()
1240   call. Similarly, if the WritePolicy is set to
1241   EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume
1242   capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the
1243   firmware volume. EFI_FV_UNRELIABLE_WRITE must always be
1244   supported. Writing a file with a size of zero
1245   (FileData[n].BufferSize == 0) deletes the file from the firmware
1246   volume if it exists. Deleting a file must be done one at a time.
1247   Deleting a file as part of a multiple file write is not allowed.
1248   Platform Initialization Specification VOLUME 3 Shared
1249   Architectural Elements 84 August 21, 2006 Version 1.0
1250   WriteFile() is callable only from TPL_NOTIFY and below.
1251   Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is
1252   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0
1253   specification.
1254
1255   @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
1256               instance. NumberOfFiles Indicates the number of
1257               elements in the array pointed to by FileData.
1258
1259
1260   @param WritePolicy  Indicates the level of reliability for the
1261                       write in the event of a power failure or
1262                       other system failure during the write
1263                       operation.
1264
1265   @param FileData   Pointer to an array of
1266                     EFI_FV_WRITE_FILE_DATA. Each element of
1267                     FileData[] represents a file to be written.
1268
1269
1270   @retval EFI_SUCCESS The write completed successfully.
1271
1272   @retval EFI_OUT_OF_RESOURCES  The firmware volume does not
1273                                 have enough free space to
1274                                 storefile(s).
1275
1276   @retval EFI_DEVICE_ERROR  A hardware error occurred when
1277                             attempting to access the firmware volume.
1278
1279   @retval EFI_WRITE_PROTECTED   The firmware volume is
1280                                 configured to disallow writes.
1281
1282   @retval EFI_NOT_FOUND   A delete was requested, but the
1283                           requested file was not found in the
1284                           firmware volume.
1285
1286   @retval EFI_INVALID_PARAMETER   A delete was requested with a
1287                                   multiple file write.
1288
1289   @retval EFI_INVALID_PARAMETER   An unsupported WritePolicy was
1290                                   requested.
1291
1292   @retval EFI_INVALID_PARAMETER   An unknown file type was
1293                                   specified.
1294
1295   @retval EFI_INVALID_PARAMETER   A file system specific error
1296                                   has occurred.
1297
1298 **/
1299 EFI_STATUS
1300 EFIAPI
1301 Fv2WriteFile (
1302   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1303   IN        UINT32                        NumberOfFiles,
1304   IN        EFI_FV_WRITE_POLICY           WritePolicy,
1305   IN        EFI_FV_WRITE_FILE_DATA        *FileData
1306   )
1307 {
1308   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
1309   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
1310
1311   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
1312   FirmwareVolume = Private->FirmwareVolume;
1313
1314   return FirmwareVolume->WriteFile (
1315                            FirmwareVolume,
1316                            NumberOfFiles,
1317                            WritePolicy,
1318                            (FRAMEWORK_EFI_FV_WRITE_FILE_DATA *)FileData
1319                            );
1320 }
1321
1322 /**
1323   GetNextFile() is the interface that is used to search a firmware
1324   volume for a particular file. It is called successively until
1325   the desired file is located or the function returns
1326    EFI_NOT_FOUND. To filter uninteresting files from the output,
1327   the type of file to search for may be specified in FileType. For
1328   example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of
1329   this type will be returned in the output. If *FileType is
1330   EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key
1331   parameter is used to indicate a starting point of the search. If
1332   the buffer *Key is completely initialized to zero, the search
1333   re-initialized and starts at the beginning. Subsequent calls to
1334   GetNextFile() must maintain the value of *Key returned by the
1335   immediately previous call. The actual contents of *Key are
1336   implementation specific and no semantic content is implied.
1337   GetNextFile() is callable only from TPL_NOTIFY and below.
1338   Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is
1339   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0
1340   specification. Status Codes Returned
1341
1342
1343   @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
1344               instance. Key Pointer to a caller-allocated buffer
1345               that contains implementation-specific data that is
1346               used to track where to begin the search for the
1347               next file. The size of the buffer must be at least
1348               This->KeySize bytes long. To re-initialize the
1349               search and begin from the beginning of the
1350               firmware volume, the entire buffer must be cleared
1351               to zero. Other than clearing the buffer to
1352               initiate a new search, the caller must not modify
1353               the data in the buffer between calls to
1354               GetNextFile().
1355
1356   @param FileType   Pointer to a caller-allocated
1357                     EFI_FV_FILETYPE. The GetNextFile() API can
1358                     filter its search for files based on the
1359                     value of the FileType input. A *FileType
1360                     input of EFI_FV_FILETYPE_ALL causes
1361                     GetNextFile() to search for files of all
1362                     types. If a file is found, the file's type
1363                     is returned in FileType. *FileType is not
1364                     modified if no file is found.
1365
1366   @param NameGuid   Pointer to a caller-allocated EFI_GUID. If a
1367                     matching file is found, the file's name is
1368                     returned in NameGuid. If no matching file is
1369                     found, *NameGuid is not modified.
1370
1371   @param Attributes Pointer to a caller-allocated
1372                     EFI_FV_FILE_ATTRIBUTES. If a matching file
1373                     is found, the file's attributes are returned
1374                     in Attributes. If no matching file is found,
1375                     Attributes is not modified. Type
1376                     EFI_FV_FILE_ATTRIBUTES is defined in
1377                     ReadFile().
1378
1379   @param Size   Pointer to a caller-allocated UINTN. If a
1380                 matching file is found, the file's size is
1381                 returned in *Size. If no matching file is found,
1382                 Size is not modified.
1383
1384   @retval EFI_SUCCESS The output parameters are filled with data
1385                       obtained from the first matching file that
1386                       was found.
1387
1388   @retval FI_NOT_FOUND  No files of type FileType were found.
1389
1390
1391   @retval EFI_DEVICE_ERROR  A hardware error occurred when
1392                             attempting to access the firmware
1393                             volume.
1394
1395   @retval EFI_ACCESS_DENIED The firmware volume is configured to
1396                             disallow reads.
1397
1398
1399 **/
1400 EFI_STATUS
1401 EFIAPI
1402 Fv2GetNextFile (
1403   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1404   IN OUT    VOID                          *Key,
1405   IN OUT    EFI_FV_FILETYPE               *FileType,
1406   OUT       EFI_GUID                      *NameGuid,
1407   OUT       EFI_FV_FILE_ATTRIBUTES        *Attributes,
1408   OUT       UINTN                         *Size
1409   )
1410 {
1411   FIRMWARE_VOLUME2_PRIVATE_DATA  *Private;
1412   EFI_FIRMWARE_VOLUME_PROTOCOL   *FirmwareVolume;
1413
1414   Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);
1415   FirmwareVolume = Private->FirmwareVolume;
1416
1417   return FirmwareVolume->GetNextFile (
1418                            FirmwareVolume,
1419                            Key,
1420                            FileType,
1421                            NameGuid,
1422                            Attributes,
1423                            Size
1424                            );
1425 }
1426
1427 /**
1428   The GetInfo() function returns information of type
1429   InformationType for the requested firmware volume. If the volume
1430   does not support the requested information type, then
1431   EFI_UNSUPPORTED is returned. If the buffer is not large enough
1432   to hold the requested structure, EFI_BUFFER_TOO_SMALL is
1433   returned and the BufferSize is set to the size of buffer that is
1434   required to make the request. The information types defined by
1435   this specification are required information types that all file
1436   systems must support.
1437
1438   @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
1439               instance that is the file handle the requested
1440               information is for.
1441
1442   @param InformationType  The type identifier for the
1443                           information being requested.
1444
1445   @param BufferSize   On input, the size of Buffer. On output,
1446                       the amount of data returned in Buffer. In
1447                       both cases, the size is measured in bytes.
1448
1449   @param Buffer   A pointer to the data buffer to return. The
1450                   buffer's type is indicated by InformationType.
1451
1452
1453   @retval EFI_SUCCESS   The information was retrieved.
1454
1455   @retval EFI_UNSUPPORTED   The InformationType is not known.
1456
1457   @retval EFI_NO_MEDIA  The device has no medium.
1458
1459   @retval EFI_DEVICE_ERROR  The device reported an error.
1460
1461   @retval EFI_VOLUME_CORRUPTED  The file system structures are
1462                                 corrupted.
1463
1464   @retval EFI_BUFFER_TOO_SMALL  The BufferSize is too small to
1465                                 read the current directory
1466                                 entry. BufferSize has been
1467                                 updated with the size needed to
1468                                 complete the request.
1469
1470
1471 **/
1472 EFI_STATUS
1473 EFIAPI
1474 Fv2GetInfo (
1475   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1476   IN CONST  EFI_GUID                      *InformationType,
1477   IN OUT    UINTN                         *BufferSize,
1478   OUT       VOID                          *Buffer
1479   )
1480 {
1481   return EFI_UNSUPPORTED;
1482 }
1483
1484 /**
1485
1486   The SetInfo() function sets information of type InformationType
1487   on the requested firmware volume.
1488
1489
1490   @param This   A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
1491                 instance that is the file handle the information
1492                 is for.
1493
1494   @param InformationType  The type identifier for the
1495                           information being set.
1496
1497   @param BufferSize   The size, in bytes, of Buffer.
1498
1499   @param Buffer A pointer to the data buffer to write. The
1500                 buffer's type is indicated by InformationType.
1501
1502   @retval EFI_SUCCESS The information was set.
1503
1504   @retval EFI_UNSUPPORTED The InformationType is not known.
1505
1506   @retval EFI_NO_MEDIA  The device has no medium.
1507
1508   @retval EFI_DEVICE_ERROR  The device reported an error.
1509
1510   @retval EFI_VOLUME_CORRUPTED  The file system structures are
1511                                 corrupted.
1512
1513
1514   @retval EFI_WRITE_PROTECTED The media is read only.
1515
1516   @retval EFI_VOLUME_FULL   The volume is full.
1517
1518   @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the
1519                               size of the type indicated by
1520                               InformationType.
1521
1522 **/
1523 EFI_STATUS
1524 EFIAPI
1525 Fv2SetInfo (
1526   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
1527   IN CONST  EFI_GUID                      *InformationType,
1528   IN        UINTN                         BufferSize,
1529   IN CONST  VOID                          *Buffer
1530   )
1531 {
1532   return EFI_UNSUPPORTED;
1533 }