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