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   @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. Type EFI_TPL is defined in RaiseTPL() in the UEFI
  98   2.0 specification.
  99
 100   @param  This    Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 101                   instance.
 102
 103   @param  FvAttributes  Pointer to an EFI_FV_ATTRIBUTES in which
 104                         the attributes and current settings are
 105                         returned.
 106
 107
 108   @retval EFI_SUCCESS   The firmware volume attributes were
 109                         returned.
 110
 111 **/
 112 typedef
 113 EFI_STATUS
 114 (EFIAPI * EFI_FV_GET_ATTRIBUTES)(
 115   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 116   OUT       EFI_FV_ATTRIBUTES             *FvAttributes
 117 );
 118
 119
 120 /**
 121   The SetVolumeAttributes() function is used to set configurable
 122   firmware volume attributes. Only EFI_FV_READ_STATUS,
 123   EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and
 124    then only in accordance with the declared capabilities. All
 125   other bits of FvAttributes are ignored on input. On successful
 126   return, all bits of *FvAttributes are valid and it contains the
 127   completed EFI_FV_ATTRIBUTES for the volume. To modify an
 128   attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES
 129   is set to the desired value on input. The EFI_FV_LOCK_STATUS bit
 130   does not affect the ability to read or write the firmware
 131   volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it
 132   prevents further modification to all the attribute bits.
 133   SetVolumeAttributes() is callable only from TPL_NOTIFY and
 134   below. Behavior of SetVolumeAttributes() at any EFI_TPL above
 135   TPL_NOTIFY is undefined. Type EFI_TPL is defined in
 136   RaiseTPL() in the UEFI 2.0 specification.
 137
 138
 139   @param  This  Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 140                 instance.
 141
 142   @param  FvAttributes  On input, FvAttributes is a pointer to
 143                         an EFI_FV_ATTRIBUTES containing the
 144                         desired firmware volume settings. On
 145                         successful return, it contains the new
 146                         settings of the firmware volume. On
 147                         unsuccessful return, FvAttributes is not
 148                         modified and the firmware volume
 149                         settings are not changed.
 150
 151   @retval EFI_SUCCESS   The requested firmware volume attributes
 152                         were set and the resulting
 153                         EFI_FV_ATTRIBUTES is returned in
 154                         FvAttributes.
 155
 156   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS
 157                                 is set to 1 on input, but the
 158                                 device does not support enabling
 159                                 reads
 160                                 (FvAttributes:EFI_FV_READ_ENABLE
 161                                 is clear on return from
 162                                 GetVolumeAttributes()). Actual
 163                                 volume attributes are unchanged.
 164
 165   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS
 166                                 is cleared to 0 on input, but
 167                                 the device does not support
 168                                 disabling reads
 169                                 (FvAttributes:EFI_FV_READ_DISABL
 170                                 is clear on return from
 171                                 GetVolumeAttributes()). Actual
 172                                 volume attributes are unchanged.
 173
 174   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS
 175                                 is set to 1 on input, but the
 176                                 device does not support enabling
 177                                 writes
 178                                 (FvAttributes:EFI_FV_WRITE_ENABL
 179                                 is clear on return from
 180                                 GetVolumeAttributes()). Actual
 181                                 volume attributes are unchanged.
 182
 183   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS
 184                                 is cleared to 0 on input, but
 185                                 the device does not support
 186                                 disabling writes
 187                                 (FvAttributes:EFI_FV_WRITE_DISAB
 188                                 is clear on return from
 189                                 GetVolumeAttributes()). Actual
 190                                 volume attributes are unchanged.
 191
 192   @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS
 193                                 is set on input, but the device
 194                                 does not support locking
 195                                 (FvAttributes:EFI_FV_LOCK_CAP is
 196                                 clear on return from
 197                                 GetVolumeAttributes()). Actual
 198                                 volume attributes are unchanged.
 199
 200   @retval EFI_ACCESS_DENIED     Device is locked and does not
 201                                 allow attribute modification
 202                                 (FvAttributes:EFI_FV_LOCK_STATUS
 203                                 is set on return from
 204                                 GetVolumeAttributes()). Actual
 205                                 volume attributes are unchanged.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI * EFI_FV_SET_ATTRIBUTES)(
 211   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 212   IN OUT    EFI_FV_ATTRIBUTES             *FvAttributes
 213 );
 214
 215
 216 /**
 217   ReadFile() is used to retrieve any file from a firmware volume
 218   during the DXE phase. The actual binary encoding of the file in
 219   the firmware volume media may be in any arbitrary format as long
 220   as it does the following: ?It is accessed using the Firmware
 221   Volume Protocol. ?The image that is returned follows the image
 222   format defined in Code Definitions: PI Firmware File Format.
 223   If the input value of Buffer==NULL, it indicates the caller is
 224   requesting only that the type, attributes, and size of the
 225   file be returned and that there is no output buffer. In this
 226   case, the following occurs:
 227   - BufferSize is returned with the size that is required to
 228     successfully complete the read.
 229   - The output parameters FoundType and *FileAttributes are
 230   returned with valid values.
 231   - The returned value of *AuthenticationStatus is undefined.
 232
 233   If the input value of Buffer!=NULL, the output buffer is
 234   specified by a double indirection of the Buffer parameter. The
 235   input value of *Buffer is used to determine if the output
 236   buffer is caller allocated or is dynamically allocated by
 237   ReadFile(). If the input value of *Buffer!=NULL, it indicates
 238   the output buffer is caller allocated. In this case, the input
 239    value of *BufferSize indicates the size of the
 240   caller-allocated output buffer. If the output buffer is not
 241   large enough to contain the entire requested output, it is
 242   filled up to the point that the output buffer is exhausted and
 243   EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is
 244    returned with the size required to successfully complete the
 245   read. All other output parameters are returned with valid
 246   values. If the input value of *Buffer==NULL, it indicates the
 247   output buffer is to be allocated by ReadFile(). In this case,
 248   ReadFile() will allocate an appropriately sized buffer from
 249   boot services pool memory, which will be returned in Buffer.
 250   The size of the new buffer is returned in BufferSize and all
 251   other output parameters are returned with valid values.
 252   ReadFile() is callable only from TPL_NOTIFY and below.
 253   Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is
 254   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI
 255   2.0 specification.
 256
 257   @param  This  Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 258                 instance.
 259
 260   @param  NameGuid  Pointer to an EFI_GUID, which is the file
 261                     name. All firmware file names are EFI_GUIDs.
 262                     A single firmware volume must not have two
 263                     valid files with the same file name
 264                     EFI_GUID.
 265
 266   @param  Buffer  Pointer to a pointer to a buffer in which the
 267                   file contents are returned, not including the
 268                   file header.
 269   @param  BufferSize  Pointer to a caller-allocated UINTN. It
 270                       indicates the size of the memory
 271                       represented by Buffer.
 272
 273   @param  FoundType   Pointer to a caller-allocated
 274                       EFI_FV_FILETYPE.
 275
 276   @param  FileAttributes  Pointer to a  caller-allocated
 277                           EFI_FV_FILE_ATTRIBUTES.
 278
 279   @param  AuthenticationStatus  Pointer to a caller-allocated
 280                                 UINT32 in which the
 281                                 authentication status is
 282                                 returned.
 283
 284   @retval EFI_SUCCESS   The call completed successfully.
 285
 286   @retval EFI_WARN_BUFFER_TOO_SMALL   The buffer is too small to
 287                                       contain the requested
 288                                       output. The buffer is
 289                                       filled and the output is
 290                                       truncated.
 291
 292   @retval EFI_OUT_OF_RESOURCES  An allocation failure occurred.
 293
 294   @retavl EFI_NOT_FOUND   Name was not found in the firmware
 295                           volume.
 296
 297   @retval EFI_DEVICE_ERROR  A hardware error occurred when
 298                             attempting to access the firmware
 299                             volume.
 300
 301   @retval EFI_ACCESS_DENIED The firmware volume is configured to
 302                             isallow reads.
 303
 304 **/
 305 typedef
 306 EFI_STATUS
 307 (EFIAPI * EFI_FV_READ_FILE)(
 308   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 309   IN CONST  EFI_GUID                      *NameGuid,
 310   IN OUT    VOID                          **Buffer,
 311   IN OUT    UINTN                         *BufferSize,
 312   OUT       EFI_FV_FILETYPE               *FoundType,
 313   OUT       EFI_FV_FILE_ATTRIBUTES        *FileAttributes,
 314   OUT       UINT32                        *AuthenticationStatus
 315 );
 316
 317
 318
 319 /**
 320   ReadSection() is used to retrieve a specific section from a file
 321   within a firmware volume. The section returned is determined
 322   using a depth-first, left-to-right search algorithm through all
 323   sections found in the specified file. See
 324    ????Firmware File Sections???? on page 9 for more details about
 325   sections. The output buffer is specified by a double indirection
 326   of the Buffer parameter. The input value of Buffer is used to
 327   determine if the output buffer is caller allocated or is
 328   dynamically allocated by ReadSection(). If the input value of
 329   Buffer!=NULL, it indicates that the output buffer is caller
 330   allocated. In this case, the input value of *BufferSize
 331   indicates the size of the caller-allocated output buffer. If
 332   the output buffer is not large enough to contain the entire
 333   requested output, it is filled up to the point that the output
 334   buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned,
 335   and then BufferSize is returned with the size that is required
 336   to successfully complete the read. All other
 337   output parameters are returned with valid values. If the input
 338   value of *Buffer==NULL, it indicates the output buffer is to
 339   be allocated by ReadSection(). In this case, ReadSection()
 340   will allocate an appropriately sized buffer from boot services
 341   pool memory, which will be returned in *Buffer. The size of
 342   the new buffer is returned in *BufferSize and all other output
 343   parameters are returned with valid values. ReadSection() is
 344   callable only from TPL_NOTIFY and below. Behavior of
 345   ReadSection() at any EFI_TPL above TPL_NOTIFY is
 346   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI
 347   2.0 specification.
 348
 349
 350   @param This   Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 351                 instance.
 352
 353   @param NameGuid   Pointer to an EFI_GUID, which indicates the
 354                     file name from which the requested section
 355                     will be read.
 356
 357   @param SectionType  Indicates the section type to return.
 358                       SectionType in conjunction with
 359                       SectionInstance indicates which section to
 360                       return.
 361
 362   @param SectionInstance  Indicates which instance of sections
 363                           with a type of SectionType to return.
 364                           SectionType in conjunction with
 365                           SectionInstance indicates which
 366                           section to return. SectionInstance is
 367                           zero based.
 368
 369   @param Buffer   Pointer to a pointer to a buffer in which the
 370                   section contents are returned, not including
 371                   the section header.
 372
 373   @param BufferSize   Pointer to a caller-allocated UINTN. It
 374                       indicates the size of the memory
 375                       represented by Buffer.
 376
 377   @param AuthenticationStatus Pointer to a caller-allocated
 378                               UINT32 in which the authentication
 379                               status is returned.
 380
 381
 382   @retval EFI_SUCCESS   The call completed successfully.
 383
 384   @retval EFI_WARN_BUFFER_TOO_SMALL   The caller-allocated
 385                                       buffer is too small to
 386                                       contain the requested
 387                                       output. The buffer is
 388                                       filled and the output is
 389                                       truncated.
 390
 391   @retval EFI_OUT_OF_RESOURCES  An allocation failure occurred.
 392
 393   @retval EFI_NOT_FOUND   The requested file was not found in
 394                           the firmware volume. EFI_NOT_FOUND The
 395                           requested section was not found in the
 396                           specified file.
 397
 398   @retval EFI_DEVICE_ERROR  A hardware error occurred when
 399                             attempting to access the firmware
 400                             volume.
 401
 402   @retval EFI_ACCESS_DENIED The firmware volume is configured to
 403                             disallow reads. EFI_PROTOCOL_ERROR
 404                             The requested section was not found,
 405                             but the file could not be fully
 406                             parsed because a required
 407                             GUIDED_SECTION_EXTRACTION_PROTOCOL
 408                             was not found. It is possible the
 409                             requested section exists within the
 410                             file and could be successfully
 411                             extracted once the required
 412                             GUIDED_SECTION_EXTRACTION_PROTOCOL
 413                             is published.
 414
 415 **/
 416 typedef
 417 EFI_STATUS
 418 (EFIAPI * EFI_FV_READ_SECTION)(
 419   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 420   IN CONST  EFI_GUID                      *NameGuid,
 421   IN        EFI_SECTION_TYPE              SectionType,
 422   IN        UINTN                         SectionInstance,
 423   IN OUT    VOID                          **Buffer,
 424   IN OUT    UINTN                         *BufferSize,
 425   OUT       UINT32                        *AuthenticationStatus
 426 );
 427
 428 //
 429 // EFI_FV_WRITE_POLICY
 430 //
 431 typedef UINT32 EFI_FV_WRITE_POLICY;
 432 #define EFI_FV_UNRELIABLE_WRITE   0x00000000
 433 #define EFI_FV_RELIABLE_WRITE     0x00000001
 434
 435 //
 436 // EFI_FV_WRITE_FILE_DATA
 437 //
 438 typedef struct {
 439   EFI_GUID                *NameGuid;
 440   EFI_FV_FILETYPE         Type;
 441   EFI_FV_FILE_ATTRIBUTES  FileAttributes;
 442   VOID                    *Buffer;
 443   UINT32                  BufferSize;
 444 } EFI_FV_WRITE_FILE_DATA;
 445
 446 /**
 447   WriteFile() is used to write one or more files to a firmware
 448   volume. Each file to be written is described by an
 449   EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that
 450   any required alignment for all files listed in the FileData
 451   array is compatible with the firmware volume. Firmware volume
 452   capabilities can be determined using the GetVolumeAttributes()
 453   call. Similarly, if the WritePolicy is set to
 454   EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume
 455   capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the
 456   firmware volume. EFI_FV_UNRELIABLE_WRITE must always be
 457   supported. Writing a file with a size of zero
 458   (FileData[n].BufferSize == 0) deletes the file from the firmware
 459   volume if it exists. Deleting a file must be done one at a time.
 460   Deleting a file as part of a multiple file write is not allowed.
 461   Platform Initialization Specification VOLUME 3 Shared
 462   Architectural Elements 84 August 21, 2006 Version 1.0
 463   WriteFile() is callable only from TPL_NOTIFY and below.
 464   Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is
 465   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0
 466   specification.
 467
 468   @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 469               instance. NumberOfFiles Indicates the number of
 470               elements in the array pointed to by FileData.
 471
 472
 473   @param WritePolicy  Indicates the level of reliability for the
 474                       write in the event of a power failure or
 475                       other system failure during the write
 476                       operation.
 477
 478   @param FileData   Pointer to an array of
 479                     EFI_FV_WRITE_FILE_DATA. Each element of
 480                     FileData[] represents a file to be written.
 481
 482
 483   @retval EFI_SUCCESS The write completed successfully.
 484
 485   @retval EFI_OUT_OF_RESOURCES  The firmware volume does not
 486                                 have enough free space to
 487                                 storefile(s).
 488
 489   @retval EFI_DEVICE_ERROR  A hardware error occurred when
 490                             attempting to access the firmware volume.
 491
 492   @retval EFI_WRITE_PROTECTED   The firmware volume is
 493                                 configured to disallow writes.
 494
 495   @retval EFI_NOT_FOUND   A delete was requested, but the
 496                           requested file was not found in the
 497                           firmware volume.
 498
 499   @retval EFI_INVALID_PARAMETER   A delete was requested with a
 500                                   multiple file write.
 501
 502   @retval EFI_INVALID_PARAMETER   An unsupported WritePolicy was
 503                                   requested.
 504
 505   @retval EFI_INVALID_PARAMETER   An unknown file type was
 506                                   specified.
 507
 508   @retval EFI_INVALID_PARAMETER   A file system specific error
 509                                   has occurred.
 510
 511 **/
 512 typedef
 513 EFI_STATUS
 514 (EFIAPI * EFI_FV_WRITE_FILE)(
 515   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 516   IN        UINT32                        NumberOfFiles,
 517   IN        EFI_FV_WRITE_POLICY           WritePolicy,
 518   IN        EFI_FV_WRITE_FILE_DATA        *FileData
 519 );
 520
 521
 522 /**
 523   GetNextFile() is the interface that is used to search a firmware
 524   volume for a particular file. It is called successively until
 525   the desired file is located or the function returns
 526    EFI_NOT_FOUND. To filter uninteresting files from the output,
 527   the type of file to search for may be specified in FileType. For
 528   example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of
 529   this type will be returned in the output. If *FileType is
 530   EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key
 531   parameter is used to indicate a starting point of the search. If
 532   the buffer *Key is completely initialized to zero, the search
 533   re-initialized and starts at the beginning. Subsequent calls to
 534   GetNextFile() must maintain the value of *Key returned by the
 535   immediately previous call. The actual contents of *Key are
 536   implementation specific and no semantic content is implied.
 537   GetNextFile() is callable only from TPL_NOTIFY and below.
 538   Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is
 539   undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0
 540   specification. Status Codes Returned
 541
 542
 543   @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL
 544               instance. Key Pointer to a caller-allocated buffer
 545               that contains implementation-specific data that is
 546               used to track where to begin the search for the
 547               next file. The size of the buffer must be at least
 548               This->KeySize bytes long. To re-initialize the
 549               search and begin from the beginning of the
 550               firmware volume, the entire buffer must be cleared
 551               to zero. Other than clearing the buffer to
 552               initiate a new search, the caller must not modify
 553               the data in the buffer between calls to
 554               GetNextFile().
 555
 556   @param FileType   Pointer to a caller-allocated
 557                     EFI_FV_FILETYPE. The GetNextFile() API can
 558                     filter its search for files based on the
 559                     value of the FileType input. A *FileType
 560                     input of EFI_FV_FILETYPE_ALL causes
 561                     GetNextFile() to search for files of all
 562                     types. If a file is found, the file's type
 563                     is returned in FileType. *FileType is not
 564                     modified if no file is found.
 565
 566   @param NameGuid   Pointer to a caller-allocated EFI_GUID. If a
 567                     matching file is found, the file's name is
 568                     returned in NameGuid. If no matching file is
 569                     found, *NameGuid is not modified.
 570
 571   @param Attributes Pointer to a caller-allocated
 572                     EFI_FV_FILE_ATTRIBUTES. If a matching file
 573                     is found, the file's attributes are returned
 574                     in Attributes. If no matching file is found,
 575                     Attributes is not modified. Type
 576                     EFI_FV_FILE_ATTRIBUTES is defined in
 577                     ReadFile().
 578
 579   @param Size   Pointer to a caller-allocated UINTN. If a
 580                 matching file is found, the file's size is
 581                 returned in *Size. If no matching file is found,
 582                 Size is not modified.
 583
 584   @retval EFI_SUCCESS The output parameters are filled with data
 585                       obtained from the first matching file that
 586                       was found.
 587
 588   @retval FI_NOT_FOUND  No files of type FileType were found.
 589
 590
 591   @retval EFI_DEVICE_ERROR  A hardware error occurred when
 592                             attempting to access the firmware
 593                             volume.
 594
 595   @retval EFI_ACCESS_DENIED The firmware volume is configured to
 596                             disallow reads.
 597
 598
 599 **/
 600 typedef
 601 EFI_STATUS
 602 (EFIAPI * EFI_FV_GET_NEXT_FILE)(
 603   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 604   IN OUT    VOID                          *Key,
 605   IN OUT    EFI_FV_FILETYPE               *FileType,
 606   OUT       EFI_GUID                      *NameGuid,
 607   OUT       EFI_FV_FILE_ATTRIBUTES        *Attributes,
 608   OUT       UINTN                         *Size
 609 );
 610
 611 /**
 612   The GetInfo() function returns information of type
 613   InformationType for the requested firmware volume. If the volume
 614   does not support the requested information type, then
 615   EFI_UNSUPPORTED is returned. If the buffer is not large enough
 616   to hold the requested structure, EFI_BUFFER_TOO_SMALL is
 617   returned and the BufferSize is set to the size of buffer that is
 618   required to make the request. The information types defined by
 619   this specification are required information types that all file
 620   systems must support.
 621
 622   @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
 623               instance that is the file handle the requested
 624               information is for.
 625
 626   @param InformationType  The type identifier for the
 627                           information being requested.
 628
 629   @param BufferSize   On input, the size of Buffer. On output,
 630                       the amount of data returned in Buffer. In
 631                       both cases, the size is measured in bytes.
 632
 633   @param Buffer   A pointer to the data buffer to return. The
 634                   buffer's type is indicated by InformationType.
 635
 636
 637   @retval EFI_SUCCESS   The information was retrieved.
 638
 639   @retval EFI_UNSUPPORTED   The InformationType is not known.
 640
 641   @retval EFI_NO_MEDIA  The device has no medium.
 642
 643   @retval EFI_DEVICE_ERROR  The device reported an error.
 644
 645   @retval EFI_VOLUME_CORRUPTED  The file system structures are
 646                                 corrupted.
 647
 648   @retval EFI_BUFFER_TOO_SMALL  The BufferSize is too small to
 649                                 read the current directory
 650                                 entry. BufferSize has been
 651                                 updated with the size needed to
 652                                 complete the request.
 653
 654
 655 **/
 656 typedef
 657 EFI_STATUS
 658 (EFIAPI *EFI_FV_GET_INFO)(
 659   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 660   IN CONST  EFI_GUID                      *InformationType,
 661   IN OUT    UINTN                         *BufferSize,
 662   OUT       VOID                          *Buffer
 663 );
 664
 665
 666 /**
 667
 668   The SetInfo() function sets information of type InformationType
 669   on the requested firmware volume.
 670
 671
 672   @param This   A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
 673                 instance that is the file handle the information
 674                 is for.
 675
 676   @param InformationType  The type identifier for the
 677                           information being set.
 678
 679   @param BufferSize   The size, in bytes, of Buffer.
 680
 681   @param Buffer A pointer to the data buffer to write. The
 682                 buffer's type is indicated by InformationType.
 683
 684   @retval EFI_SUCCESS The information was set.
 685
 686   @retval EFI_UNSUPPORTED The InformationType is not known.
 687
 688   @retval EFI_NO_MEDIA  The device has no medium.
 689
 690   @retval EFI_DEVICE_ERROR  The device reported an error.
 691
 692   @retval EFI_VOLUME_CORRUPTED  The file system structures are
 693                                 corrupted.
 694
 695
 696   @retval EFI_WRITE_PROTECTED The media is read only.
 697
 698   @retval EFI_VOLUME_FULL   The volume is full.
 699
 700   @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the
 701                               size of the type indicated by
 702                               InformationType.
 703
 704 **/
 705 typedef
 706 EFI_STATUS
 707 (EFIAPI *EFI_FV_SET_INFO)(
 708   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 709   IN CONST  EFI_GUID                      *InformationType,
 710   IN        UINTN                         BufferSize,
 711   IN CONST  VOID                          *Buffer
 712 );
 713
 714
 715 /**
 716   The Firmware Volume Protocol contains the file-level
 717   abstraction to the firmware volume as well as some firmware
 718   volume attribute reporting and configuration services. The
 719   Firmware Volume Protocol is the interface used by all parts of
 720   DXE that are not directly involved with managing the firmware
 721   volume itself. This abstraction allows many varied types of
 722   firmware volume implementations. A firmware volume may be a
 723   flash device or it may be a file in the UEFI system partition,
 724   for example. This level of firmware volume implementation
 725   detail is not visible to the consumers of the Firmware Volume
 726   Protocol.
 727
 728   @param  GetVolumeAttributes   Retrieves volume capabilities
 729                                 and current settings. See the
 730                                 GetVolumeAttributes() function
 731                                 description.
 732
 733   @param  SetVolumeAttributes   Modifies the current settings of
 734                                 the firmware volume. See the
 735                                 SetVolumeAttributes() function
 736                                 description.
 737
 738   @param  ReadFile  Reads an entire file from the firmware
 739                     volume. See the ReadFile() function
 740                     description.
 741
 742   @param  ReadSection   Reads a single section from a file into
 743                         a buffer.
 744
 745   @param  WriteFile   Writes an entire file into the firmware
 746                       volume. See the WriteFile() function
 747                       description.
 748
 749   @param  GetNextFile Provides service to allow searching the
 750                       firmware volume. See the GetNextFile()
 751                       function description.
 752
 753   @param  KeySize   Data field that indicates the size in bytes
 754                     of the Key input buffer for the
 755                     GetNextFile() API.
 756
 757   @param  ParentHandle  Handle of the parent firmware volume.
 758                         Type EFI_HANDLE is defined in
 759                         InstallProtocolInterface() in the UEFI
 760                         2.0 specification.
 761
 762   @param  GetInfo   Gets the requested file or volume
 763                     information. See the GetInfo() function
 764                     description.
 765   @param  SetInfo   Sets the requested file information. See the
 766                     SetInfo() function description.
 767
 768 **/
 769 struct _EFI_FIRMWARE_VOLUME2_PROTOCOL {
 770   EFI_FV_GET_ATTRIBUTES   GetVolumeAttributes;
 771   EFI_FV_SET_ATTRIBUTES   SetVolumeAttributes;
 772   EFI_FV_READ_FILE        ReadFile;
 773   EFI_FV_READ_SECTION     ReadSection;
 774   EFI_FV_WRITE_FILE       WriteFile;
 775   EFI_FV_GET_NEXT_FILE    GetNextFile;
 776   UINT32                  KeySize;
 777   EFI_HANDLE              ParentHandle;
 778   EFI_FV_GET_INFO         GetInfo;
 779   EFI_FV_SET_INFO         SetInfo;
 780 };
 781
 782
 783 extern EFI_GUID gEfiFirmwareVolume2ProtocolGuid;
 784
 785 #endif