MdePkg/Include/Protocol/FirmwareVolume2.h

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