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