| /** @file |
| The Firmware Volume Protocol provides file-level access to the firmware volume. |
| Each firmware volume driver must produce an instance of the |
| Firmware Volume Protocol if the firmware volume is to be visible to |
| the system during the DXE phase. The Firmware Volume Protocol also provides |
| mechanisms for determining and modifying some attributes of the firmware volume. |
| |
| Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @par Revision Reference: PI |
| Version 1.00. |
| |
| **/ |
| |
| #ifndef __FIRMWARE_VOLUME2_H__ |
| #define __FIRMWARE_VOLUME2_H__ |
| |
| #define EFI_FIRMWARE_VOLUME2_PROTOCOL_GUID \ |
| { 0x220e73b6, 0x6bdb, 0x4413, { 0x84, 0x5, 0xb9, 0x74, 0xb1, 0x8, 0x61, 0x9a } } |
| |
| typedef struct _EFI_FIRMWARE_VOLUME2_PROTOCOL EFI_FIRMWARE_VOLUME2_PROTOCOL; |
| |
| |
| /// |
| /// EFI_FV_ATTRIBUTES |
| /// |
| typedef UINT64 EFI_FV_ATTRIBUTES; |
| |
| // |
| // EFI_FV_ATTRIBUTES bit definitions |
| // |
| // EFI_FV_ATTRIBUTES bit semantics |
| #define EFI_FV2_READ_DISABLE_CAP 0x0000000000000001ULL |
| #define EFI_FV2_READ_ENABLE_CAP 0x0000000000000002ULL |
| #define EFI_FV2_READ_STATUS 0x0000000000000004ULL |
| #define EFI_FV2_WRITE_DISABLE_CAP 0x0000000000000008ULL |
| #define EFI_FV2_WRITE_ENABLE_CAP 0x0000000000000010ULL |
| #define EFI_FV2_WRITE_STATUS 0x0000000000000020ULL |
| #define EFI_FV2_LOCK_CAP 0x0000000000000040ULL |
| #define EFI_FV2_LOCK_STATUS 0x0000000000000080ULL |
| #define EFI_FV2_WRITE_POLICY_RELIABLE 0x0000000000000100ULL |
| #define EFI_FV2_READ_LOCK_CAP 0x0000000000001000ULL |
| #define EFI_FV2_READ_LOCK_STATUS 0x0000000000002000ULL |
| #define EFI_FV2_WRITE_LOCK_CAP 0x0000000000004000ULL |
| #define EFI_FV2_WRITE_LOCK_STATUS 0x0000000000008000ULL |
| #define EFI_FV2_ALIGNMENT 0x00000000001F0000ULL |
| #define EFI_FV2_ALIGNMENT_1 0x0000000000000000ULL |
| #define EFI_FV2_ALIGNMENT_2 0x0000000000010000ULL |
| #define EFI_FV2_ALIGNMENT_4 0x0000000000020000ULL |
| #define EFI_FV2_ALIGNMENT_8 0x0000000000030000ULL |
| #define EFI_FV2_ALIGNMENT_16 0x0000000000040000ULL |
| #define EFI_FV2_ALIGNMENT_32 0x0000000000050000ULL |
| #define EFI_FV2_ALIGNMENT_64 0x0000000000060000ULL |
| #define EFI_FV2_ALIGNMENT_128 0x0000000000070000ULL |
| #define EFI_FV2_ALIGNMENT_256 0x0000000000080000ULL |
| #define EFI_FV2_ALIGNMENT_512 0x0000000000090000ULL |
| #define EFI_FV2_ALIGNMENT_1K 0x00000000000A0000ULL |
| #define EFI_FV2_ALIGNMENT_2K 0x00000000000B0000ULL |
| #define EFI_FV2_ALIGNMENT_4K 0x00000000000C0000ULL |
| #define EFI_FV2_ALIGNMENT_8K 0x00000000000D0000ULL |
| #define EFI_FV2_ALIGNMENT_16K 0x00000000000E0000ULL |
| #define EFI_FV2_ALIGNMENT_32K 0x00000000000F0000ULL |
| #define EFI_FV2_ALIGNMENT_64K 0x0000000000100000ULL |
| #define EFI_FV2_ALIGNMENT_128K 0x0000000000110000ULL |
| #define EFI_FV2_ALIGNMENT_256K 0x0000000000120000ULL |
| #define EFI_FV2_ALIGNMENT_512K 0x0000000000130000ULL |
| #define EFI_FV2_ALIGNMENT_1M 0x0000000000140000ULL |
| #define EFI_FV2_ALIGNMENT_2M 0x0000000000150000ULL |
| #define EFI_FV2_ALIGNMENT_4M 0x0000000000160000ULL |
| #define EFI_FV2_ALIGNMENT_8M 0x0000000000170000ULL |
| #define EFI_FV2_ALIGNMENT_16M 0x0000000000180000ULL |
| #define EFI_FV2_ALIGNMENT_32M 0x0000000000190000ULL |
| #define EFI_FV2_ALIGNMENT_64M 0x00000000001A0000ULL |
| #define EFI_FV2_ALIGNMENT_128M 0x00000000001B0000ULL |
| #define EFI_FV2_ALIGNMENT_256M 0x00000000001C0000ULL |
| #define EFI_FV2_ALIGNMENT_512M 0x00000000001D0000ULL |
| #define EFI_FV2_ALIGNMENT_1G 0x00000000001E0000ULL |
| #define EFI_FV2_ALIGNMENT_2G 0x00000000001F0000ULL |
| |
| /** |
| Returns the attributes and current settings of the firmware volume. |
| |
| Because of constraints imposed by the underlying firmware |
| storage, an instance of the Firmware Volume Protocol may not |
| be to able to support all possible variations of this |
| architecture. These constraints and the current state of the |
| firmware volume are exposed to the caller using the |
| GetVolumeAttributes() function. GetVolumeAttributes() is |
| callable only from TPL_NOTIFY and below. Behavior of |
| GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is |
| undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which |
| the attributes and current settings are |
| returned. |
| |
| |
| @retval EFI_SUCCESS The firmware volume attributes were |
| returned. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_GET_ATTRIBUTES)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| OUT EFI_FV_ATTRIBUTES *FvAttributes |
| ); |
| |
| |
| /** |
| Modifies the current settings of the firmware volume according to the input parameter. |
| |
| The SetVolumeAttributes() function is used to set configurable |
| firmware volume attributes. Only EFI_FV_READ_STATUS, |
| EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and |
| then only in accordance with the declared capabilities. All |
| other bits of FvAttributes are ignored on input. On successful |
| return, all bits of *FvAttributes are valid and it contains the |
| completed EFI_FV_ATTRIBUTES for the volume. To modify an |
| attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES |
| is set to the desired value on input. The EFI_FV_LOCK_STATUS bit |
| does not affect the ability to read or write the firmware |
| volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it |
| prevents further modification to all the attribute bits. |
| SetVolumeAttributes() is callable only from TPL_NOTIFY and |
| below. Behavior of SetVolumeAttributes() at any EFI_TPL above |
| TPL_NOTIFY is undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param FvAttributes On input, FvAttributes is a pointer to |
| an EFI_FV_ATTRIBUTES containing the |
| desired firmware volume settings. On |
| successful return, it contains the new |
| settings of the firmware volume. On |
| unsuccessful return, FvAttributes is not |
| modified and the firmware volume |
| settings are not changed. |
| |
| @retval EFI_SUCCESS The requested firmware volume attributes |
| were set and the resulting |
| EFI_FV_ATTRIBUTES is returned in |
| FvAttributes. |
| |
| @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS |
| is set to 1 on input, but the |
| device does not support enabling |
| reads |
| (FvAttributes:EFI_FV_READ_ENABLE |
| is clear on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS |
| is cleared to 0 on input, but |
| the device does not support |
| disabling reads |
| (FvAttributes:EFI_FV_READ_DISABL |
| is clear on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS |
| is set to 1 on input, but the |
| device does not support enabling |
| writes |
| (FvAttributes:EFI_FV_WRITE_ENABL |
| is clear on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS |
| is cleared to 0 on input, but |
| the device does not support |
| disabling writes |
| (FvAttributes:EFI_FV_WRITE_DISAB |
| is clear on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS |
| is set on input, but the device |
| does not support locking |
| (FvAttributes:EFI_FV_LOCK_CAP is |
| clear on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| @retval EFI_ACCESS_DENIED Device is locked and does not |
| allow attribute modification |
| (FvAttributes:EFI_FV_LOCK_STATUS |
| is set on return from |
| GetVolumeAttributes()). Actual |
| volume attributes are unchanged. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_SET_ATTRIBUTES)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN OUT EFI_FV_ATTRIBUTES *FvAttributes |
| ); |
| |
| |
| /** |
| Retrieves a file and/or file information from the firmware volume. |
| |
| ReadFile() is used to retrieve any file from a firmware volume |
| during the DXE phase. The actual binary encoding of the file in |
| the firmware volume media may be in any arbitrary format as long |
| as it does the following: It is accessed using the Firmware |
| Volume Protocol. The image that is returned follows the image |
| format defined in Code Definitions: PI Firmware File Format. |
| If the input value of Buffer==NULL, it indicates the caller is |
| requesting only that the type, attributes, and size of the |
| file be returned and that there is no output buffer. In this |
| case, the following occurs: |
| - BufferSize is returned with the size that is required to |
| successfully complete the read. |
| - The output parameters FoundType and *FileAttributes are |
| returned with valid values. |
| - The returned value of *AuthenticationStatus is undefined. |
| |
| If the input value of Buffer!=NULL, the output buffer is |
| specified by a double indirection of the Buffer parameter. The |
| input value of *Buffer is used to determine if the output |
| buffer is caller allocated or is dynamically allocated by |
| ReadFile(). If the input value of *Buffer!=NULL, it indicates |
| the output buffer is caller allocated. In this case, the input |
| value of *BufferSize indicates the size of the |
| caller-allocated output buffer. If the output buffer is not |
| large enough to contain the entire requested output, it is |
| filled up to the point that the output buffer is exhausted and |
| EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is |
| returned with the size required to successfully complete the |
| read. All other output parameters are returned with valid |
| values. If the input value of *Buffer==NULL, it indicates the |
| output buffer is to be allocated by ReadFile(). In this case, |
| ReadFile() will allocate an appropriately sized buffer from |
| boot services pool memory, which will be returned in Buffer. |
| The size of the new buffer is returned in BufferSize and all |
| other output parameters are returned with valid values. |
| ReadFile() is callable only from TPL_NOTIFY and below. |
| Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is |
| undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param NameGuid Pointer to an EFI_GUID, which is the file |
| name. All firmware file names are EFI_GUIDs. |
| A single firmware volume must not have two |
| valid files with the same file name |
| EFI_GUID. |
| |
| @param Buffer Pointer to a pointer to a buffer in which the |
| file contents are returned, not including the |
| file header. |
| |
| @param BufferSize Pointer to a caller-allocated UINTN. It |
| indicates the size of the memory |
| represented by Buffer. |
| |
| @param FoundType Pointer to a caller-allocated EFI_FV_FILETYPE. |
| |
| @param FileAttributes Pointer to a caller-allocated |
| EFI_FV_FILE_ATTRIBUTES. |
| |
| @param AuthenticationStatus Pointer to a caller-allocated |
| UINT32 in which the |
| authentication status is |
| returned. |
| |
| @retval EFI_SUCCESS The call completed successfully. |
| |
| @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to |
| contain the requested |
| output. The buffer is |
| filled and the output is |
| truncated. |
| |
| @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. |
| |
| @retval EFI_NOT_FOUND Name was not found in the firmware volume. |
| |
| @retval EFI_DEVICE_ERROR A hardware error occurred when |
| attempting to access the firmware volume. |
| |
| @retval EFI_ACCESS_DENIED The firmware volume is configured to |
| disallow reads. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_READ_FILE)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN CONST EFI_GUID *NameGuid, |
| IN OUT VOID **Buffer, |
| IN OUT UINTN *BufferSize, |
| OUT EFI_FV_FILETYPE *FoundType, |
| OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, |
| OUT UINT32 *AuthenticationStatus |
| ); |
| |
| |
| |
| /** |
| Locates the requested section within a file and returns it in a buffer. |
| |
| ReadSection() is used to retrieve a specific section from a file |
| within a firmware volume. The section returned is determined |
| using a depth-first, left-to-right search algorithm through all |
| sections found in the specified file. The output buffer is specified by a double indirection |
| of the Buffer parameter. The input value of Buffer is used to |
| determine if the output buffer is caller allocated or is |
| dynamically allocated by ReadSection(). If the input value of |
| Buffer!=NULL, it indicates that the output buffer is caller |
| allocated. In this case, the input value of *BufferSize |
| indicates the size of the caller-allocated output buffer. If |
| the output buffer is not large enough to contain the entire |
| requested output, it is filled up to the point that the output |
| buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned, |
| and then BufferSize is returned with the size that is required |
| to successfully complete the read. All other |
| output parameters are returned with valid values. If the input |
| value of *Buffer==NULL, it indicates the output buffer is to |
| be allocated by ReadSection(). In this case, ReadSection() |
| will allocate an appropriately sized buffer from boot services |
| pool memory, which will be returned in *Buffer. The size of |
| the new buffer is returned in *BufferSize and all other output |
| parameters are returned with valid values. ReadSection() is |
| callable only from TPL_NOTIFY and below. Behavior of |
| ReadSection() at any EFI_TPL above TPL_NOTIFY is |
| undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param NameGuid Pointer to an EFI_GUID, which indicates the |
| file name from which the requested section |
| will be read. |
| |
| @param SectionType Indicates the section type to return. |
| SectionType in conjunction with |
| SectionInstance indicates which section to |
| return. |
| |
| @param SectionInstance Indicates which instance of sections |
| with a type of SectionType to return. |
| SectionType in conjunction with |
| SectionInstance indicates which |
| section to return. SectionInstance is |
| zero based. |
| |
| @param Buffer Pointer to a pointer to a buffer in which the |
| section contents are returned, not including |
| the section header. |
| |
| @param BufferSize Pointer to a caller-allocated UINTN. It |
| indicates the size of the memory |
| represented by Buffer. |
| |
| @param AuthenticationStatus Pointer to a caller-allocated |
| UINT32 in which the authentication |
| status is returned. |
| |
| |
| @retval EFI_SUCCESS The call completed successfully. |
| |
| @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated |
| buffer is too small to |
| contain the requested |
| output. The buffer is |
| filled and the output is |
| truncated. |
| |
| @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. |
| |
| @retval EFI_NOT_FOUND The requested file was not found in |
| the firmware volume. EFI_NOT_FOUND The |
| requested section was not found in the |
| specified file. |
| |
| @retval EFI_DEVICE_ERROR A hardware error occurred when |
| attempting to access the firmware |
| volume. |
| |
| @retval EFI_ACCESS_DENIED The firmware volume is configured to |
| disallow reads. EFI_PROTOCOL_ERROR |
| The requested section was not found, |
| but the file could not be fully |
| parsed because a required |
| GUIDED_SECTION_EXTRACTION_PROTOCOL |
| was not found. It is possible the |
| requested section exists within the |
| file and could be successfully |
| extracted once the required |
| GUIDED_SECTION_EXTRACTION_PROTOCOL |
| is published. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_READ_SECTION)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN CONST EFI_GUID *NameGuid, |
| IN EFI_SECTION_TYPE SectionType, |
| IN UINTN SectionInstance, |
| IN OUT VOID **Buffer, |
| IN OUT UINTN *BufferSize, |
| OUT UINT32 *AuthenticationStatus |
| ); |
| |
| /// |
| /// EFI_FV_WRITE_POLICY, two policies (unreliable write and reliable write) are defined. |
| /// |
| typedef UINT32 EFI_FV_WRITE_POLICY; |
| #define EFI_FV_UNRELIABLE_WRITE 0x00000000 |
| #define EFI_FV_RELIABLE_WRITE 0x00000001 |
| |
| // |
| // EFI_FV_WRITE_FILE_DATA |
| // |
| typedef struct { |
| /// |
| /// Pointer to a GUID, which is the file name to be written. |
| /// |
| EFI_GUID *NameGuid; |
| /// |
| /// Indicates the type of file to be written. |
| /// |
| EFI_FV_FILETYPE Type; |
| /// |
| /// Indicates the attributes for the file to be written. |
| /// |
| EFI_FV_FILE_ATTRIBUTES FileAttributes; |
| /// |
| /// Pointer to a buffer containing the file to be written. |
| /// |
| VOID *Buffer; |
| /// |
| /// Indicates the size of the file image contained in Buffer. |
| /// |
| UINT32 BufferSize; |
| } EFI_FV_WRITE_FILE_DATA; |
| |
| /** |
| Locates the requested section within a file and returns it in a buffer. |
| |
| WriteFile() is used to write one or more files to a firmware |
| volume. Each file to be written is described by an |
| EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that |
| any required alignment for all files listed in the FileData |
| array is compatible with the firmware volume. Firmware volume |
| capabilities can be determined using the GetVolumeAttributes() |
| call. Similarly, if the WritePolicy is set to |
| EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume |
| capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the |
| firmware volume. EFI_FV_UNRELIABLE_WRITE must always be |
| supported. Writing a file with a size of zero |
| (FileData[n].BufferSize == 0) deletes the file from the firmware |
| volume if it exists. Deleting a file must be done one at a time. |
| Deleting a file as part of a multiple file write is not allowed. |
| Platform Initialization Specification VOLUME 3 Shared |
| Architectural Elements 84 August 21, 2006 Version 1.0 |
| WriteFile() is callable only from TPL_NOTIFY and below. |
| Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is |
| undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param NumberOfFiles Indicates the number of elements in the array pointed to by FileData |
| |
| @param WritePolicy Indicates the level of reliability for the |
| write in the event of a power failure or |
| other system failure during the write |
| operation. |
| |
| @param FileData Pointer to an array of |
| EFI_FV_WRITE_FILE_DATA. Each element of |
| FileData[] represents a file to be written. |
| |
| |
| @retval EFI_SUCCESS The write completed successfully. |
| |
| @retval EFI_OUT_OF_RESOURCES The firmware volume does not |
| have enough free space to |
| storefile(s). |
| |
| @retval EFI_DEVICE_ERROR A hardware error occurred when |
| attempting to access the firmware volume. |
| |
| @retval EFI_WRITE_PROTECTED The firmware volume is |
| configured to disallow writes. |
| |
| @retval EFI_NOT_FOUND A delete was requested, but the |
| requested file was not found in the |
| firmware volume. |
| |
| @retval EFI_INVALID_PARAMETER A delete was requested with a |
| multiple file write. |
| |
| @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was |
| requested. |
| |
| @retval EFI_INVALID_PARAMETER An unknown file type was |
| specified. |
| |
| @retval EFI_INVALID_PARAMETER A file system specific error |
| has occurred. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_WRITE_FILE)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN UINT32 NumberOfFiles, |
| IN EFI_FV_WRITE_POLICY WritePolicy, |
| IN EFI_FV_WRITE_FILE_DATA *FileData |
| ); |
| |
| |
| /** |
| Retrieves information about the next file in the firmware volume store |
| that matches the search criteria. |
| |
| GetNextFile() is the interface that is used to search a firmware |
| volume for a particular file. It is called successively until |
| the desired file is located or the function returns |
| EFI_NOT_FOUND. To filter uninteresting files from the output, |
| the type of file to search for may be specified in FileType. For |
| example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of |
| this type will be returned in the output. If *FileType is |
| EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key |
| parameter is used to indicate a starting point of the search. If |
| the buffer *Key is completely initialized to zero, the search |
| re-initialized and starts at the beginning. Subsequent calls to |
| GetNextFile() must maintain the value of *Key returned by the |
| immediately previous call. The actual contents of *Key are |
| implementation specific and no semantic content is implied. |
| GetNextFile() is callable only from TPL_NOTIFY and below. |
| Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is |
| undefined. |
| |
| @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance. |
| |
| @param Key Pointer to a caller-allocated buffer that contains implementation-specific data that is |
| used to track where to begin the search for the next file. The size of the buffer must be |
| at least This->KeySize bytes long. To re-initialize the search and begin from the |
| beginning of the firmware volume, the entire buffer must be cleared to zero. Other |
| than clearing the buffer to initiate a new search, the caller must not modify the data in |
| the buffer between calls to GetNextFile(). |
| |
| @param FileType Pointer to a caller-allocated |
| EFI_FV_FILETYPE. The GetNextFile() API can |
| filter its search for files based on the |
| value of the FileType input. A *FileType |
| input of EFI_FV_FILETYPE_ALL causes |
| GetNextFile() to search for files of all |
| types. If a file is found, the file's type |
| is returned in FileType. *FileType is not |
| modified if no file is found. |
| |
| @param NameGuid Pointer to a caller-allocated EFI_GUID. If a |
| matching file is found, the file's name is |
| returned in NameGuid. If no matching file is |
| found, *NameGuid is not modified. |
| |
| @param Attributes Pointer to a caller-allocated |
| EFI_FV_FILE_ATTRIBUTES. If a matching file |
| is found, the file's attributes are returned |
| in Attributes. If no matching file is found, |
| Attributes is not modified. Type |
| EFI_FV_FILE_ATTRIBUTES is defined in |
| ReadFile(). |
| |
| @param Size Pointer to a caller-allocated UINTN. If a |
| matching file is found, the file's size is |
| returned in *Size. If no matching file is found, |
| Size is not modified. |
| |
| @retval EFI_SUCCESS The output parameters are filled with data |
| obtained from the first matching file that |
| was found. |
| |
| @retval FI_NOT_FOUND No files of type FileType were found. |
| |
| |
| @retval EFI_DEVICE_ERROR A hardware error occurred when |
| attempting to access the firmware |
| volume. |
| |
| @retval EFI_ACCESS_DENIED The firmware volume is configured to |
| disallow reads. |
| |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI * EFI_FV_GET_NEXT_FILE)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN OUT VOID *Key, |
| IN OUT EFI_FV_FILETYPE *FileType, |
| OUT EFI_GUID *NameGuid, |
| OUT EFI_FV_FILE_ATTRIBUTES *Attributes, |
| OUT UINTN *Size |
| ); |
| |
| /** |
| Return information about a firmware volume. |
| |
| The GetInfo() function returns information of type |
| InformationType for the requested firmware volume. If the volume |
| does not support the requested information type, then |
| EFI_UNSUPPORTED is returned. If the buffer is not large enough |
| to hold the requested structure, EFI_BUFFER_TOO_SMALL is |
| returned and the BufferSize is set to the size of buffer that is |
| required to make the request. The information types defined by |
| this specification are required information types that all file |
| systems must support. |
| |
| @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL |
| instance that is the file handle the requested |
| information is for. |
| |
| @param InformationType The type identifier for the |
| information being requested. |
| |
| @param BufferSize On input, the size of Buffer. On output, |
| the amount of data returned in Buffer. In |
| both cases, the size is measured in bytes. |
| |
| @param Buffer A pointer to the data buffer to return. The |
| buffer's type is indicated by InformationType. |
| |
| |
| @retval EFI_SUCCESS The information was retrieved. |
| |
| @retval EFI_UNSUPPORTED The InformationType is not known. |
| |
| @retval EFI_NO_MEDIA The device has no medium. |
| |
| @retval EFI_DEVICE_ERROR The device reported an error. |
| |
| @retval EFI_VOLUME_CORRUPTED The file system structures are |
| corrupted. |
| |
| @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to |
| read the current directory |
| entry. BufferSize has been |
| updated with the size needed to |
| complete the request. |
| |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_FV_GET_INFO)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN CONST EFI_GUID *InformationType, |
| IN OUT UINTN *BufferSize, |
| OUT VOID *Buffer |
| ); |
| |
| |
| /** |
| Sets information about a firmware volume. |
| |
| The SetInfo() function sets information of type InformationType |
| on the requested firmware volume. |
| |
| |
| @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL |
| instance that is the file handle the information |
| is for. |
| |
| @param InformationType The type identifier for the |
| information being set. |
| |
| @param BufferSize The size, in bytes, of Buffer. |
| |
| @param Buffer A pointer to the data buffer to write. The |
| buffer's type is indicated by InformationType. |
| |
| @retval EFI_SUCCESS The information was set. |
| |
| @retval EFI_UNSUPPORTED The InformationType is not known. |
| |
| @retval EFI_NO_MEDIA The device has no medium. |
| |
| @retval EFI_DEVICE_ERROR The device reported an error. |
| |
| @retval EFI_VOLUME_CORRUPTED The file system structures are |
| corrupted. |
| |
| |
| @retval EFI_WRITE_PROTECTED The media is read only. |
| |
| @retval EFI_VOLUME_FULL The volume is full. |
| |
| @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the |
| size of the type indicated by |
| InformationType. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_FV_SET_INFO)( |
| IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This, |
| IN CONST EFI_GUID *InformationType, |
| IN UINTN BufferSize, |
| IN CONST VOID *Buffer |
| ); |
| |
| |
| /// |
| /// The Firmware Volume Protocol contains the file-level |
| /// abstraction to the firmware volume as well as some firmware |
| /// volume attribute reporting and configuration services. The |
| /// Firmware Volume Protocol is the interface used by all parts of |
| /// DXE that are not directly involved with managing the firmware |
| /// volume itself. This abstraction allows many varied types of |
| /// firmware volume implementations. A firmware volume may be a |
| /// flash device or it may be a file in the UEFI system partition, |
| /// for example. This level of firmware volume implementation |
| /// detail is not visible to the consumers of the Firmware Volume |
| /// Protocol. |
| /// |
| struct _EFI_FIRMWARE_VOLUME2_PROTOCOL { |
| EFI_FV_GET_ATTRIBUTES GetVolumeAttributes; |
| EFI_FV_SET_ATTRIBUTES SetVolumeAttributes; |
| EFI_FV_READ_FILE ReadFile; |
| EFI_FV_READ_SECTION ReadSection; |
| EFI_FV_WRITE_FILE WriteFile; |
| EFI_FV_GET_NEXT_FILE GetNextFile; |
| |
| /// |
| /// Data field that indicates the size in bytes |
| /// of the Key input buffer for the |
| /// GetNextFile() API. |
| /// |
| UINT32 KeySize; |
| |
| /// |
| /// Handle of the parent firmware volume. |
| /// |
| EFI_HANDLE ParentHandle; |
| EFI_FV_GET_INFO GetInfo; |
| EFI_FV_SET_INFO SetInfo; |
| }; |
| |
| |
| extern EFI_GUID gEfiFirmwareVolume2ProtocolGuid; |
| |
| #endif |