--- /dev/null
+/**\r
+Module produce FV2 on top of FV.\r
+\r
+UEFI PI specification supersedes Inte's Framework Specification.\r
+EFI_FIRMWARE_VOLUME_PROTOCOL defined in Intel Framework Pkg is replaced by\r
+EFI_FIRMWARE_VOLUME2_PROTOCOL in MdePkg.\r
+This module produces FV2 on top of FV. This module is used on platform when both of\r
+these two conditions are true:\r
+1) Framework module producing FV is present\r
+2) And the rest of modules on the platform consume FV2\r
+\r
+Copyright (c) 2006 - 2008 Intel Corporation. <BR>\r
+All rights reserved. This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution. The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+Module Name:\r
+\r
+**/\r
+\r
+#include <PiDxe.h>\r
+#include <Protocol/FirmwareVolume2.h>\r
+#include <Protocol/FirmwareVolume.h>\r
+#include <Library/BaseLib.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/UefiBootServicesTableLib.h>\r
+#include <Library/UefiDriverEntryPoint.h>\r
+#include <Library/UefiLib.h>\r
+#include <Library/MemoryAllocationLib.h>\r
+\r
+/**\r
+ \r
+ Because of constraints imposed by the underlying firmware\r
+ storage, an instance of the Firmware Volume Protocol may not\r
+ be to able to support all possible variations of this\r
+ architecture. These constraints and the current state of the\r
+ firmware volume are exposed to the caller using the\r
+ GetVolumeAttributes() function. GetVolumeAttributes() is\r
+ callable only from TPL_NOTIFY and below. Behavior of\r
+ GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+ \r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which\r
+ the attributes and current settings are\r
+ returned.\r
+\r
+\r
+ @retval EFI_SUCCESS The firmware volume attributes were\r
+ returned.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetVolumeAttributes (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ OUT EFI_FV_ATTRIBUTES *FvAttributes\r
+ );\r
+\r
+\r
+/**\r
+ The SetVolumeAttributes() function is used to set configurable\r
+ firmware volume attributes. Only EFI_FV_READ_STATUS,\r
+ EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and\r
+ then only in accordance with the declared capabilities. All\r
+ other bits of FvAttributes are ignored on input. On successful\r
+ return, all bits of *FvAttributes are valid and it contains the\r
+ completed EFI_FV_ATTRIBUTES for the volume. To modify an\r
+ attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES\r
+ is set to the desired value on input. The EFI_FV_LOCK_STATUS bit\r
+ does not affect the ability to read or write the firmware\r
+ volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it\r
+ prevents further modification to all the attribute bits.\r
+ SetVolumeAttributes() is callable only from TPL_NOTIFY and\r
+ below. Behavior of SetVolumeAttributes() at any EFI_TPL above\r
+ TPL_NOTIFY is undefined. Type EFI_TPL is defined in\r
+ RaiseTPL() in the UEFI 2.0 specification.\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param FvAttributes On input, FvAttributes is a pointer to\r
+ an EFI_FV_ATTRIBUTES containing the\r
+ desired firmware volume settings. On\r
+ successful return, it contains the new\r
+ settings of the firmware volume. On\r
+ unsuccessful return, FvAttributes is not\r
+ modified and the firmware volume\r
+ settings are not changed.\r
+ \r
+ @retval EFI_SUCCESS The requested firmware volume attributes\r
+ were set and the resulting\r
+ EFI_FV_ATTRIBUTES is returned in\r
+ FvAttributes.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
+ is set to 1 on input, but the\r
+ device does not support enabling\r
+ reads\r
+ (FvAttributes:EFI_FV_READ_ENABLE\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
+ is cleared to 0 on input, but\r
+ the device does not support\r
+ disabling reads\r
+ (FvAttributes:EFI_FV_READ_DISABL\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
+ is set to 1 on input, but the\r
+ device does not support enabling\r
+ writes\r
+ (FvAttributes:EFI_FV_WRITE_ENABL\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
+ is cleared to 0 on input, but\r
+ the device does not support\r
+ disabling writes\r
+ (FvAttributes:EFI_FV_WRITE_DISAB\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS\r
+ is set on input, but the device\r
+ does not support locking\r
+ (FvAttributes:EFI_FV_LOCK_CAP is\r
+ clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_ACCESS_DENIED Device is locked and does not\r
+ allow attribute modification\r
+ (FvAttributes:EFI_FV_LOCK_STATUS\r
+ is set on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2SetVolumeAttributes (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN OUT EFI_FV_ATTRIBUTES *FvAttributes\r
+ );\r
+\r
+\r
+/**\r
+ ReadFile() is used to retrieve any file from a firmware volume\r
+ during the DXE phase. The actual binary encoding of the file in\r
+ the firmware volume media may be in any arbitrary format as long\r
+ as it does the following: ?It is accessed using the Firmware\r
+ Volume Protocol. ?The image that is returned follows the image\r
+ format defined in Code Definitions: PI Firmware File Format.\r
+ If the input value of Buffer==NULL, it indicates the caller is\r
+ requesting only that the type, attributes, and size of the\r
+ file be returned and that there is no output buffer. In this\r
+ case, the following occurs:\r
+ - BufferSize is returned with the size that is required to\r
+ successfully complete the read.\r
+ - The output parameters FoundType and *FileAttributes are\r
+ returned with valid values.\r
+ - The returned value of *AuthenticationStatus is undefined.\r
+\r
+ If the input value of Buffer!=NULL, the output buffer is\r
+ specified by a double indirection of the Buffer parameter. The\r
+ input value of *Buffer is used to determine if the output\r
+ buffer is caller allocated or is dynamically allocated by\r
+ ReadFile(). If the input value of *Buffer!=NULL, it indicates\r
+ the output buffer is caller allocated. In this case, the input\r
+ value of *BufferSize indicates the size of the\r
+ caller-allocated output buffer. If the output buffer is not\r
+ large enough to contain the entire requested output, it is\r
+ filled up to the point that the output buffer is exhausted and\r
+ EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is\r
+ returned with the size required to successfully complete the\r
+ read. All other output parameters are returned with valid\r
+ values. If the input value of *Buffer==NULL, it indicates the\r
+ output buffer is to be allocated by ReadFile(). In this case,\r
+ ReadFile() will allocate an appropriately sized buffer from\r
+ boot services pool memory, which will be returned in Buffer.\r
+ The size of the new buffer is returned in BufferSize and all\r
+ other output parameters are returned with valid values.\r
+ ReadFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+ \r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param NameGuid Pointer to an EFI_GUID, which is the file\r
+ name. All firmware file names are EFI_GUIDs.\r
+ A single firmware volume must not have two\r
+ valid files with the same file name\r
+ EFI_GUID.\r
+ \r
+ @param Buffer Pointer to a pointer to a buffer in which the\r
+ file contents are returned, not including the\r
+ file header.\r
+ @param BufferSize Pointer to a caller-allocated UINTN. It\r
+ indicates the size of the memory\r
+ represented by Buffer.\r
+ \r
+ @param FoundType Pointer to a caller-allocated\r
+ EFI_FV_FILETYPE.\r
+ \r
+ @param FileAttributes Pointer to a caller-allocated\r
+ EFI_FV_FILE_ATTRIBUTES.\r
+ \r
+ @param AuthenticationStatus Pointer to a caller-allocated\r
+ UINT32 in which the\r
+ authentication status is\r
+ returned.\r
+ \r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ \r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to\r
+ contain the requested\r
+ output. The buffer is\r
+ filled and the output is\r
+ truncated.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
+\r
+ @retavl EFI_NOT_FOUND Name was not found in the firmware\r
+ volume.\r
+\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ isallow reads.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2ReadFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *NameGuid,\r
+ IN OUT VOID **Buffer,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT EFI_FV_FILETYPE *FoundType,\r
+ OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,\r
+ OUT UINT32 *AuthenticationStatus\r
+ );\r
+\r
+/**\r
+ ReadSection() is used to retrieve a specific section from a file\r
+ within a firmware volume. The section returned is determined\r
+ using a depth-first, left-to-right search algorithm through all\r
+ sections found in the specified file. See\r
+ ????Firmware File Sections???? on page 9 for more details about\r
+ sections. The output buffer is specified by a double indirection\r
+ of the Buffer parameter. The input value of Buffer is used to\r
+ determine if the output buffer is caller allocated or is\r
+ dynamically allocated by ReadSection(). If the input value of\r
+ Buffer!=NULL, it indicates that the output buffer is caller\r
+ allocated. In this case, the input value of *BufferSize\r
+ indicates the size of the caller-allocated output buffer. If\r
+ the output buffer is not large enough to contain the entire\r
+ requested output, it is filled up to the point that the output\r
+ buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned,\r
+ and then BufferSize is returned with the size that is required\r
+ to successfully complete the read. All other\r
+ output parameters are returned with valid values. If the input\r
+ value of *Buffer==NULL, it indicates the output buffer is to\r
+ be allocated by ReadSection(). In this case, ReadSection()\r
+ will allocate an appropriately sized buffer from boot services\r
+ pool memory, which will be returned in *Buffer. The size of\r
+ the new buffer is returned in *BufferSize and all other output\r
+ parameters are returned with valid values. ReadSection() is\r
+ callable only from TPL_NOTIFY and below. Behavior of\r
+ ReadSection() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param NameGuid Pointer to an EFI_GUID, which indicates the\r
+ file name from which the requested section\r
+ will be read.\r
+ \r
+ @param SectionType Indicates the section type to return.\r
+ SectionType in conjunction with\r
+ SectionInstance indicates which section to\r
+ return.\r
+ \r
+ @param SectionInstance Indicates which instance of sections\r
+ with a type of SectionType to return.\r
+ SectionType in conjunction with\r
+ SectionInstance indicates which\r
+ section to return. SectionInstance is\r
+ zero based.\r
+ \r
+ @param Buffer Pointer to a pointer to a buffer in which the\r
+ section contents are returned, not including\r
+ the section header.\r
+ \r
+ @param BufferSize Pointer to a caller-allocated UINTN. It\r
+ indicates the size of the memory\r
+ represented by Buffer.\r
+ \r
+ @param AuthenticationStatus Pointer to a caller-allocated\r
+ UINT32 in which the authentication\r
+ status is returned.\r
+ \r
+ \r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ \r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated\r
+ buffer is too small to\r
+ contain the requested\r
+ output. The buffer is\r
+ filled and the output is\r
+ truncated.\r
+ \r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
+ \r
+ @retval EFI_NOT_FOUND The requested file was not found in\r
+ the firmware volume. EFI_NOT_FOUND The\r
+ requested section was not found in the\r
+ specified file.\r
+ \r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+ \r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ disallow reads. EFI_PROTOCOL_ERROR\r
+ The requested section was not found,\r
+ but the file could not be fully\r
+ parsed because a required\r
+ GUIDED_SECTION_EXTRACTION_PROTOCOL\r
+ was not found. It is possible the\r
+ requested section exists within the\r
+ file and could be successfully\r
+ extracted once the required\r
+ GUIDED_SECTION_EXTRACTION_PROTOCOL\r
+ is published.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2ReadSection (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *NameGuid,\r
+ IN EFI_SECTION_TYPE SectionType,\r
+ IN UINTN SectionInstance,\r
+ IN OUT VOID **Buffer,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT UINT32 *AuthenticationStatus\r
+ );\r
+\r
+/**\r
+ WriteFile() is used to write one or more files to a firmware\r
+ volume. Each file to be written is described by an\r
+ EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that\r
+ any required alignment for all files listed in the FileData\r
+ array is compatible with the firmware volume. Firmware volume\r
+ capabilities can be determined using the GetVolumeAttributes()\r
+ call. Similarly, if the WritePolicy is set to\r
+ EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume\r
+ capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the\r
+ firmware volume. EFI_FV_UNRELIABLE_WRITE must always be\r
+ supported. Writing a file with a size of zero\r
+ (FileData[n].BufferSize == 0) deletes the file from the firmware\r
+ volume if it exists. Deleting a file must be done one at a time.\r
+ Deleting a file as part of a multiple file write is not allowed.\r
+ Platform Initialization Specification VOLUME 3 Shared\r
+ Architectural Elements 84 August 21, 2006 Version 1.0\r
+ WriteFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0\r
+ specification.\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance. NumberOfFiles Indicates the number of\r
+ elements in the array pointed to by FileData.\r
+\r
+\r
+ @param WritePolicy Indicates the level of reliability for the\r
+ write in the event of a power failure or\r
+ other system failure during the write\r
+ operation.\r
+\r
+ @param FileData Pointer to an array of\r
+ EFI_FV_WRITE_FILE_DATA. Each element of\r
+ FileData[] represents a file to be written.\r
+\r
+\r
+ @retval EFI_SUCCESS The write completed successfully.\r
+ \r
+ @retval EFI_OUT_OF_RESOURCES The firmware volume does not\r
+ have enough free space to\r
+ storefile(s).\r
+ \r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware volume.\r
+ \r
+ @retval EFI_WRITE_PROTECTED The firmware volume is\r
+ configured to disallow writes.\r
+ \r
+ @retval EFI_NOT_FOUND A delete was requested, but the\r
+ requested file was not found in the\r
+ firmware volume.\r
+ \r
+ @retval EFI_INVALID_PARAMETER A delete was requested with a\r
+ multiple file write.\r
+ \r
+ @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was\r
+ requested.\r
+\r
+ @retval EFI_INVALID_PARAMETER An unknown file type was\r
+ specified.\r
+\r
+ @retval EFI_INVALID_PARAMETER A file system specific error\r
+ has occurred.\r
+ \r
+**/\r
+EFI_STATUS \r
+EFIAPI\r
+Fv2WriteFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN UINT32 NumberOfFiles,\r
+ IN EFI_FV_WRITE_POLICY WritePolicy,\r
+ IN EFI_FV_WRITE_FILE_DATA *FileData\r
+ );\r
+\r
+/**\r
+ GetNextFile() is the interface that is used to search a firmware\r
+ volume for a particular file. It is called successively until\r
+ the desired file is located or the function returns\r
+ EFI_NOT_FOUND. To filter uninteresting files from the output,\r
+ the type of file to search for may be specified in FileType. For\r
+ example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of\r
+ this type will be returned in the output. If *FileType is\r
+ EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key\r
+ parameter is used to indicate a starting point of the search. If\r
+ the buffer *Key is completely initialized to zero, the search\r
+ re-initialized and starts at the beginning. Subsequent calls to\r
+ GetNextFile() must maintain the value of *Key returned by the\r
+ immediately previous call. The actual contents of *Key are\r
+ implementation specific and no semantic content is implied.\r
+ GetNextFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0\r
+ specification. Status Codes Returned\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance. Key Pointer to a caller-allocated buffer\r
+ that contains implementation-specific data that is\r
+ used to track where to begin the search for the\r
+ next file. The size of the buffer must be at least\r
+ This->KeySize bytes long. To re-initialize the\r
+ search and begin from the beginning of the\r
+ firmware volume, the entire buffer must be cleared\r
+ to zero. Other than clearing the buffer to\r
+ initiate a new search, the caller must not modify\r
+ the data in the buffer between calls to\r
+ GetNextFile().\r
+\r
+ @param FileType Pointer to a caller-allocated\r
+ EFI_FV_FILETYPE. The GetNextFile() API can\r
+ filter its search for files based on the\r
+ value of the FileType input. A *FileType\r
+ input of EFI_FV_FILETYPE_ALL causes\r
+ GetNextFile() to search for files of all\r
+ types. If a file is found, the file's type\r
+ is returned in FileType. *FileType is not\r
+ modified if no file is found.\r
+\r
+ @param NameGuid Pointer to a caller-allocated EFI_GUID. If a\r
+ matching file is found, the file's name is\r
+ returned in NameGuid. If no matching file is\r
+ found, *NameGuid is not modified.\r
+\r
+ @param Attributes Pointer to a caller-allocated\r
+ EFI_FV_FILE_ATTRIBUTES. If a matching file\r
+ is found, the file's attributes are returned\r
+ in Attributes. If no matching file is found,\r
+ Attributes is not modified. Type\r
+ EFI_FV_FILE_ATTRIBUTES is defined in\r
+ ReadFile().\r
+\r
+ @param Size Pointer to a caller-allocated UINTN. If a\r
+ matching file is found, the file's size is\r
+ returned in *Size. If no matching file is found,\r
+ Size is not modified.\r
+\r
+ @retval EFI_SUCCESS The output parameters are filled with data\r
+ obtained from the first matching file that\r
+ was found.\r
+\r
+ @retval FI_NOT_FOUND No files of type FileType were found.\r
+\r
+\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ disallow reads.\r
+\r
+ \r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetNextFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN OUT VOID *Key,\r
+ IN OUT EFI_FV_FILETYPE *FileType,\r
+ OUT EFI_GUID *NameGuid,\r
+ OUT EFI_FV_FILE_ATTRIBUTES *Attributes,\r
+ OUT UINTN *Size\r
+ );\r
+\r
+/**\r
+ The GetInfo() function returns information of type\r
+ InformationType for the requested firmware volume. If the volume\r
+ does not support the requested information type, then\r
+ EFI_UNSUPPORTED is returned. If the buffer is not large enough\r
+ to hold the requested structure, EFI_BUFFER_TOO_SMALL is\r
+ returned and the BufferSize is set to the size of buffer that is\r
+ required to make the request. The information types defined by\r
+ this specification are required information types that all file\r
+ systems must support.\r
+\r
+ @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance that is the file handle the requested\r
+ information is for.\r
+ \r
+ @param InformationType The type identifier for the\r
+ information being requested.\r
+ \r
+ @param BufferSize On input, the size of Buffer. On output,\r
+ the amount of data returned in Buffer. In\r
+ both cases, the size is measured in bytes.\r
+ \r
+ @param Buffer A pointer to the data buffer to return. The\r
+ buffer's type is indicated by InformationType.\r
+ \r
+ \r
+ @retval EFI_SUCCESS The information was retrieved.\r
+ \r
+ @retval EFI_UNSUPPORTED The InformationType is not known.\r
+ \r
+ @retval EFI_NO_MEDIA The device has no medium.\r
+ \r
+ @retval EFI_DEVICE_ERROR The device reported an error.\r
+ \r
+ @retval EFI_VOLUME_CORRUPTED The file system structures are\r
+ corrupted.\r
+ \r
+ @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to\r
+ read the current directory\r
+ entry. BufferSize has been\r
+ updated with the size needed to\r
+ complete the request.\r
+\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetInfo (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *InformationType,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT VOID *Buffer\r
+ );\r
+\r
+/**\r
+\r
+ The SetInfo() function sets information of type InformationType\r
+ on the requested firmware volume.\r
+\r
+\r
+ @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance that is the file handle the information\r
+ is for.\r
+\r
+ @param InformationType The type identifier for the\r
+ information being set.\r
+\r
+ @param BufferSize The size, in bytes, of Buffer.\r
+\r
+ @param Buffer A pointer to the data buffer to write. The\r
+ buffer's type is indicated by InformationType.\r
+\r
+ @retval EFI_SUCCESS The information was set.\r
+\r
+ @retval EFI_UNSUPPORTED The InformationType is not known.\r
+\r
+ @retval EFI_NO_MEDIA The device has no medium.\r
+\r
+ @retval EFI_DEVICE_ERROR The device reported an error.\r
+\r
+ @retval EFI_VOLUME_CORRUPTED The file system structures are\r
+ corrupted.\r
+\r
+\r
+ @retval EFI_WRITE_PROTECTED The media is read only.\r
+\r
+ @retval EFI_VOLUME_FULL The volume is full.\r
+\r
+ @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the\r
+ size of the type indicated by\r
+ InformationType.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2SetInfo (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *InformationType,\r
+ IN UINTN BufferSize,\r
+ IN CONST VOID *Buffer\r
+ );\r
+\r
+//\r
+//\r
+//\r
+#define FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('f', 'v', '2', 't')\r
+\r
+typedef struct {\r
+ UINTN Signature;\r
+ EFI_FIRMWARE_VOLUME2_PROTOCOL FirmwareVolume2;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+} FIRMWARE_VOLUME2_PRIVATE_DATA;\r
+\r
+#define FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS(a) CR (a, FIRMWARE_VOLUME2_PRIVATE_DATA, FirmwareVolume2, FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE)\r
+\r
+//\r
+// Firmware Volume Protocol template\r
+//\r
+EFI_EVENT mFv2Registration;\r
+\r
+FIRMWARE_VOLUME2_PRIVATE_DATA gFirmwareVolume2PrivateDataTemplate = {\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA_SIGNATURE,\r
+ {\r
+ Fv2GetVolumeAttributes,\r
+ Fv2SetVolumeAttributes,\r
+ Fv2ReadFile,\r
+ Fv2ReadSection,\r
+ Fv2WriteFile,\r
+ Fv2GetNextFile,\r
+ 0,\r
+ NULL,\r
+ Fv2GetInfo,\r
+ Fv2SetInfo\r
+ },\r
+ NULL\r
+};\r
+\r
+//\r
+// Module globals\r
+//\r
+\r
+VOID\r
+EFIAPI\r
+Fv2NotificationEvent (\r
+ IN EFI_EVENT Event,\r
+ IN VOID *Context\r
+ )\r
+{\r
+ EFI_STATUS Status;\r
+ UINTN BufferSize;\r
+ EFI_HANDLE Handle;\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME2_PROTOCOL *FirmwareVolume2;\r
+\r
+ while (TRUE) {\r
+ BufferSize = sizeof (Handle);\r
+ Status = gBS->LocateHandle (\r
+ ByRegisterNotify,\r
+ &gEfiFirmwareVolumeProtocolGuid,\r
+ mFv2Registration,\r
+ &BufferSize,\r
+ &Handle\r
+ );\r
+ if (EFI_ERROR (Status)) {\r
+ //\r
+ // Exit Path of While Loop....\r
+ //\r
+ break;\r
+ }\r
+\r
+ //\r
+ // Skip this handle if the Firmware Volume Protocol is already installed\r
+ //\r
+ Status = gBS->HandleProtocol (\r
+ Handle,\r
+ &gEfiFirmwareVolume2ProtocolGuid,\r
+ (VOID **)&FirmwareVolume2\r
+ );\r
+ if (!EFI_ERROR (Status)) {\r
+ continue;\r
+ }\r
+\r
+ //\r
+ // Allocate private data structure\r
+ //\r
+ Private = AllocateCopyPool (sizeof (FIRMWARE_VOLUME2_PRIVATE_DATA), &gFirmwareVolume2PrivateDataTemplate);\r
+ if (Private == NULL) {\r
+ continue;\r
+ }\r
+\r
+ //\r
+ // Retrieve the Firmware Volume2 Protocol\r
+ //\r
+ Status = gBS->HandleProtocol (\r
+ Handle,\r
+ &gEfiFirmwareVolumeProtocolGuid,\r
+ (VOID **)&Private->FirmwareVolume\r
+ );\r
+ ASSERT_EFI_ERROR (Status);\r
+\r
+ //\r
+ // Fill in rest of private data structure\r
+ //\r
+ Private->FirmwareVolume2.KeySize = Private->FirmwareVolume->KeySize;\r
+ Private->FirmwareVolume2.ParentHandle = Private->FirmwareVolume->ParentHandle;\r
+\r
+ //\r
+ // Install Firmware Volume Protocol onto same handle\r
+ //\r
+ Status = gBS->InstallMultipleProtocolInterfaces (\r
+ &Handle,\r
+ &gEfiFirmwareVolume2ProtocolGuid,\r
+ &Private->FirmwareVolume2,\r
+ NULL\r
+ );\r
+ ASSERT_EFI_ERROR (Status);\r
+ }\r
+}\r
+\r
+\r
+/**\r
+ The user Entry Point for DXE driver. The user code starts with this function\r
+ as the real entry point for the image goes into a library that calls this \r
+ function.\r
+\r
+ @param[in] ImageHandle The firmware allocated handle for the EFI image. \r
+ @param[in] SystemTable A pointer to the EFI System Table.\r
+ \r
+ @retval EFI_SUCCESS The entry point is executed successfully.\r
+ @retval other Some error occurs when executing this entry point.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+InitializeFirmwareVolume (\r
+ IN EFI_HANDLE ImageHandle,\r
+ IN EFI_SYSTEM_TABLE *SystemTable\r
+ )\r
+{\r
+ EfiCreateProtocolNotifyEvent (\r
+ &gEfiFirmwareVolumeProtocolGuid,\r
+ TPL_CALLBACK,\r
+ Fv2NotificationEvent,\r
+ NULL,\r
+ &mFv2Registration\r
+ );\r
+ return EFI_SUCCESS;\r
+}\r
+\r
+/**\r
+ Convert FV attributes defined in Framework Specification\r
+ to FV attributes defined in PI specification.\r
+ \r
+ @param FvAttributes The FV attributes defined in Framework Specification.\r
+ \r
+ @retval The FV attributes defined in PI Specification.\r
+**/\r
+EFI_FV_ATTRIBUTES\r
+FvAttributesToFv2Attributes (\r
+ EFI_FV_ATTRIBUTES FvAttributes\r
+ )\r
+{\r
+ INTN Alignment;\r
+ \r
+ Alignment = LowBitSet64 (RShiftU64 (FvAttributes, 16) & 0xffff);\r
+ if (Alignment != -1) {\r
+ Alignment = Alignment << 16;\r
+ } else {\r
+ Alignment = 0;\r
+ }\r
+ FvAttributes = (FvAttributes & 0x1ff) | Alignment;\r
+\r
+ return FvAttributes;\r
+}\r
+\r
+/**\r
+ \r
+ Because of constraints imposed by the underlying firmware\r
+ storage, an instance of the Firmware Volume Protocol may not\r
+ be to able to support all possible variations of this\r
+ architecture. These constraints and the current state of the\r
+ firmware volume are exposed to the caller using the\r
+ GetVolumeAttributes() function. GetVolumeAttributes() is\r
+ callable only from TPL_NOTIFY and below. Behavior of\r
+ GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+ \r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which\r
+ the attributes and current settings are\r
+ returned.\r
+\r
+\r
+ @retval EFI_SUCCESS The firmware volume attributes were\r
+ returned.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetVolumeAttributes (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ OUT EFI_FV_ATTRIBUTES *FvAttributes\r
+ )\r
+{\r
+ EFI_STATUS Status;\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+ Status = FirmwareVolume->GetVolumeAttributes (\r
+ FirmwareVolume,\r
+ (FRAMEWORK_EFI_FV_ATTRIBUTES *)FvAttributes\r
+ );\r
+ if (!EFI_ERROR (Status)) {\r
+ *FvAttributes = FvAttributesToFv2Attributes (*FvAttributes);\r
+ }\r
+ return Status;\r
+}\r
+\r
+/**\r
+ The SetVolumeAttributes() function is used to set configurable\r
+ firmware volume attributes. Only EFI_FV_READ_STATUS,\r
+ EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and\r
+ then only in accordance with the declared capabilities. All\r
+ other bits of FvAttributes are ignored on input. On successful\r
+ return, all bits of *FvAttributes are valid and it contains the\r
+ completed EFI_FV_ATTRIBUTES for the volume. To modify an\r
+ attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES\r
+ is set to the desired value on input. The EFI_FV_LOCK_STATUS bit\r
+ does not affect the ability to read or write the firmware\r
+ volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it\r
+ prevents further modification to all the attribute bits.\r
+ SetVolumeAttributes() is callable only from TPL_NOTIFY and\r
+ below. Behavior of SetVolumeAttributes() at any EFI_TPL above\r
+ TPL_NOTIFY is undefined. Type EFI_TPL is defined in\r
+ RaiseTPL() in the UEFI 2.0 specification.\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param FvAttributes On input, FvAttributes is a pointer to\r
+ an EFI_FV_ATTRIBUTES containing the\r
+ desired firmware volume settings. On\r
+ successful return, it contains the new\r
+ settings of the firmware volume. On\r
+ unsuccessful return, FvAttributes is not\r
+ modified and the firmware volume\r
+ settings are not changed.\r
+ \r
+ @retval EFI_SUCCESS The requested firmware volume attributes\r
+ were set and the resulting\r
+ EFI_FV_ATTRIBUTES is returned in\r
+ FvAttributes.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
+ is set to 1 on input, but the\r
+ device does not support enabling\r
+ reads\r
+ (FvAttributes:EFI_FV_READ_ENABLE\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
+ is cleared to 0 on input, but\r
+ the device does not support\r
+ disabling reads\r
+ (FvAttributes:EFI_FV_READ_DISABL\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
+ is set to 1 on input, but the\r
+ device does not support enabling\r
+ writes\r
+ (FvAttributes:EFI_FV_WRITE_ENABL\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
+ is cleared to 0 on input, but\r
+ the device does not support\r
+ disabling writes\r
+ (FvAttributes:EFI_FV_WRITE_DISAB\r
+ is clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS\r
+ is set on input, but the device\r
+ does not support locking\r
+ (FvAttributes:EFI_FV_LOCK_CAP is\r
+ clear on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+ @retval EFI_ACCESS_DENIED Device is locked and does not\r
+ allow attribute modification\r
+ (FvAttributes:EFI_FV_LOCK_STATUS\r
+ is set on return from\r
+ GetVolumeAttributes()). Actual\r
+ volume attributes are unchanged.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2SetVolumeAttributes (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN OUT EFI_FV_ATTRIBUTES *FvAttributes\r
+ )\r
+{\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+ FRAMEWORK_EFI_FV_ATTRIBUTES FrameworkFvAttributes; \r
+ EFI_STATUS Status;\r
+ UINTN Shift;\r
+\r
+ if (*FvAttributes & (EFI_FV2_READ_LOCK_STATUS | EFI_FV2_WRITE_LOCK_STATUS)) {\r
+ //\r
+ // Framework FV protocol does not support EFI_FV2_READ_LOCK_* | EFI_FV2_WRITE_LOCK_*\r
+ //\r
+ return EFI_INVALID_PARAMETER;\r
+ }\r
+\r
+ *FvAttributes = *FvAttributes & (EFI_FV2_READ_STATUS | EFI_FV2_WRITE_STATUS | EFI_FV2_LOCK_STATUS);\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+\r
+ FrameworkFvAttributes = (*FvAttributes & 0x1ff);\r
+ Shift = (UINTN) RShiftU64(*FvAttributes & EFI_FV2_ALIGNMENT, 16);\r
+ FrameworkFvAttributes = FrameworkFvAttributes | LShiftU64 (EFI_FV_ALIGNMENT_2, Shift);\r
+\r
+ Status = FirmwareVolume->SetVolumeAttributes (\r
+ FirmwareVolume,\r
+ &FrameworkFvAttributes\r
+ );\r
+\r
+ if (!EFI_ERROR (Status)) {\r
+ *FvAttributes = FvAttributesToFv2Attributes (FrameworkFvAttributes);\r
+ }\r
+\r
+ return Status;\r
+}\r
+\r
+/**\r
+ ReadFile() is used to retrieve any file from a firmware volume\r
+ during the DXE phase. The actual binary encoding of the file in\r
+ the firmware volume media may be in any arbitrary format as long\r
+ as it does the following: ?It is accessed using the Firmware\r
+ Volume Protocol. ?The image that is returned follows the image\r
+ format defined in Code Definitions: PI Firmware File Format.\r
+ If the input value of Buffer==NULL, it indicates the caller is\r
+ requesting only that the type, attributes, and size of the\r
+ file be returned and that there is no output buffer. In this\r
+ case, the following occurs:\r
+ - BufferSize is returned with the size that is required to\r
+ successfully complete the read.\r
+ - The output parameters FoundType and *FileAttributes are\r
+ returned with valid values.\r
+ - The returned value of *AuthenticationStatus is undefined.\r
+\r
+ If the input value of Buffer!=NULL, the output buffer is\r
+ specified by a double indirection of the Buffer parameter. The\r
+ input value of *Buffer is used to determine if the output\r
+ buffer is caller allocated or is dynamically allocated by\r
+ ReadFile(). If the input value of *Buffer!=NULL, it indicates\r
+ the output buffer is caller allocated. In this case, the input\r
+ value of *BufferSize indicates the size of the\r
+ caller-allocated output buffer. If the output buffer is not\r
+ large enough to contain the entire requested output, it is\r
+ filled up to the point that the output buffer is exhausted and\r
+ EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is\r
+ returned with the size required to successfully complete the\r
+ read. All other output parameters are returned with valid\r
+ values. If the input value of *Buffer==NULL, it indicates the\r
+ output buffer is to be allocated by ReadFile(). In this case,\r
+ ReadFile() will allocate an appropriately sized buffer from\r
+ boot services pool memory, which will be returned in Buffer.\r
+ The size of the new buffer is returned in BufferSize and all\r
+ other output parameters are returned with valid values.\r
+ ReadFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+ \r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param NameGuid Pointer to an EFI_GUID, which is the file\r
+ name. All firmware file names are EFI_GUIDs.\r
+ A single firmware volume must not have two\r
+ valid files with the same file name\r
+ EFI_GUID.\r
+ \r
+ @param Buffer Pointer to a pointer to a buffer in which the\r
+ file contents are returned, not including the\r
+ file header.\r
+ @param BufferSize Pointer to a caller-allocated UINTN. It\r
+ indicates the size of the memory\r
+ represented by Buffer.\r
+ \r
+ @param FoundType Pointer to a caller-allocated\r
+ EFI_FV_FILETYPE.\r
+ \r
+ @param FileAttributes Pointer to a caller-allocated\r
+ EFI_FV_FILE_ATTRIBUTES.\r
+ \r
+ @param AuthenticationStatus Pointer to a caller-allocated\r
+ UINT32 in which the\r
+ authentication status is\r
+ returned.\r
+ \r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ \r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to\r
+ contain the requested\r
+ output. The buffer is\r
+ filled and the output is\r
+ truncated.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
+\r
+ @retavl EFI_NOT_FOUND Name was not found in the firmware\r
+ volume.\r
+\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ isallow reads.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2ReadFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *NameGuid,\r
+ IN OUT VOID **Buffer,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT EFI_FV_FILETYPE *FoundType,\r
+ OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,\r
+ OUT UINT32 *AuthenticationStatus\r
+ )\r
+{\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+\r
+ return FirmwareVolume->ReadFile (\r
+ FirmwareVolume,\r
+ (EFI_GUID *)NameGuid,\r
+ Buffer,\r
+ BufferSize,\r
+ FoundType,\r
+ FileAttributes,\r
+ AuthenticationStatus\r
+ );\r
+}\r
+\r
+/**\r
+ ReadSection() is used to retrieve a specific section from a file\r
+ within a firmware volume. The section returned is determined\r
+ using a depth-first, left-to-right search algorithm through all\r
+ sections found in the specified file. See\r
+ ????Firmware File Sections???? on page 9 for more details about\r
+ sections. The output buffer is specified by a double indirection\r
+ of the Buffer parameter. The input value of Buffer is used to\r
+ determine if the output buffer is caller allocated or is\r
+ dynamically allocated by ReadSection(). If the input value of\r
+ Buffer!=NULL, it indicates that the output buffer is caller\r
+ allocated. In this case, the input value of *BufferSize\r
+ indicates the size of the caller-allocated output buffer. If\r
+ the output buffer is not large enough to contain the entire\r
+ requested output, it is filled up to the point that the output\r
+ buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned,\r
+ and then BufferSize is returned with the size that is required\r
+ to successfully complete the read. All other\r
+ output parameters are returned with valid values. If the input\r
+ value of *Buffer==NULL, it indicates the output buffer is to\r
+ be allocated by ReadSection(). In this case, ReadSection()\r
+ will allocate an appropriately sized buffer from boot services\r
+ pool memory, which will be returned in *Buffer. The size of\r
+ the new buffer is returned in *BufferSize and all other output\r
+ parameters are returned with valid values. ReadSection() is\r
+ callable only from TPL_NOTIFY and below. Behavior of\r
+ ReadSection() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI\r
+ 2.0 specification.\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance.\r
+ \r
+ @param NameGuid Pointer to an EFI_GUID, which indicates the\r
+ file name from which the requested section\r
+ will be read.\r
+ \r
+ @param SectionType Indicates the section type to return.\r
+ SectionType in conjunction with\r
+ SectionInstance indicates which section to\r
+ return.\r
+ \r
+ @param SectionInstance Indicates which instance of sections\r
+ with a type of SectionType to return.\r
+ SectionType in conjunction with\r
+ SectionInstance indicates which\r
+ section to return. SectionInstance is\r
+ zero based.\r
+ \r
+ @param Buffer Pointer to a pointer to a buffer in which the\r
+ section contents are returned, not including\r
+ the section header.\r
+ \r
+ @param BufferSize Pointer to a caller-allocated UINTN. It\r
+ indicates the size of the memory\r
+ represented by Buffer.\r
+ \r
+ @param AuthenticationStatus Pointer to a caller-allocated\r
+ UINT32 in which the authentication\r
+ status is returned.\r
+ \r
+ \r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ \r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated\r
+ buffer is too small to\r
+ contain the requested\r
+ output. The buffer is\r
+ filled and the output is\r
+ truncated.\r
+ \r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
+ \r
+ @retval EFI_NOT_FOUND The requested file was not found in\r
+ the firmware volume. EFI_NOT_FOUND The\r
+ requested section was not found in the\r
+ specified file.\r
+ \r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+ \r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ disallow reads. EFI_PROTOCOL_ERROR\r
+ The requested section was not found,\r
+ but the file could not be fully\r
+ parsed because a required\r
+ GUIDED_SECTION_EXTRACTION_PROTOCOL\r
+ was not found. It is possible the\r
+ requested section exists within the\r
+ file and could be successfully\r
+ extracted once the required\r
+ GUIDED_SECTION_EXTRACTION_PROTOCOL\r
+ is published.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2ReadSection (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *NameGuid,\r
+ IN EFI_SECTION_TYPE SectionType,\r
+ IN UINTN SectionInstance,\r
+ IN OUT VOID **Buffer,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT UINT32 *AuthenticationStatus\r
+ )\r
+{\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+\r
+ return FirmwareVolume->ReadSection (\r
+ FirmwareVolume,\r
+ (EFI_GUID *)NameGuid,\r
+ SectionType,\r
+ SectionInstance,\r
+ Buffer,\r
+ BufferSize,\r
+ AuthenticationStatus\r
+ );\r
+}\r
+\r
+/**\r
+ WriteFile() is used to write one or more files to a firmware\r
+ volume. Each file to be written is described by an\r
+ EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that\r
+ any required alignment for all files listed in the FileData\r
+ array is compatible with the firmware volume. Firmware volume\r
+ capabilities can be determined using the GetVolumeAttributes()\r
+ call. Similarly, if the WritePolicy is set to\r
+ EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume\r
+ capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the\r
+ firmware volume. EFI_FV_UNRELIABLE_WRITE must always be\r
+ supported. Writing a file with a size of zero\r
+ (FileData[n].BufferSize == 0) deletes the file from the firmware\r
+ volume if it exists. Deleting a file must be done one at a time.\r
+ Deleting a file as part of a multiple file write is not allowed.\r
+ Platform Initialization Specification VOLUME 3 Shared\r
+ Architectural Elements 84 August 21, 2006 Version 1.0\r
+ WriteFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0\r
+ specification.\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance. NumberOfFiles Indicates the number of\r
+ elements in the array pointed to by FileData.\r
+\r
+\r
+ @param WritePolicy Indicates the level of reliability for the\r
+ write in the event of a power failure or\r
+ other system failure during the write\r
+ operation.\r
+\r
+ @param FileData Pointer to an array of\r
+ EFI_FV_WRITE_FILE_DATA. Each element of\r
+ FileData[] represents a file to be written.\r
+\r
+\r
+ @retval EFI_SUCCESS The write completed successfully.\r
+ \r
+ @retval EFI_OUT_OF_RESOURCES The firmware volume does not\r
+ have enough free space to\r
+ storefile(s).\r
+ \r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware volume.\r
+ \r
+ @retval EFI_WRITE_PROTECTED The firmware volume is\r
+ configured to disallow writes.\r
+ \r
+ @retval EFI_NOT_FOUND A delete was requested, but the\r
+ requested file was not found in the\r
+ firmware volume.\r
+ \r
+ @retval EFI_INVALID_PARAMETER A delete was requested with a\r
+ multiple file write.\r
+ \r
+ @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was\r
+ requested.\r
+\r
+ @retval EFI_INVALID_PARAMETER An unknown file type was\r
+ specified.\r
+\r
+ @retval EFI_INVALID_PARAMETER A file system specific error\r
+ has occurred.\r
+ \r
+**/\r
+EFI_STATUS \r
+EFIAPI\r
+Fv2WriteFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN UINT32 NumberOfFiles,\r
+ IN EFI_FV_WRITE_POLICY WritePolicy,\r
+ IN EFI_FV_WRITE_FILE_DATA *FileData\r
+ )\r
+{\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+\r
+ return FirmwareVolume->WriteFile (\r
+ FirmwareVolume,\r
+ NumberOfFiles,\r
+ WritePolicy,\r
+ (FRAMEWORK_EFI_FV_WRITE_FILE_DATA *)FileData\r
+ );\r
+}\r
+\r
+/**\r
+ GetNextFile() is the interface that is used to search a firmware\r
+ volume for a particular file. It is called successively until\r
+ the desired file is located or the function returns\r
+ EFI_NOT_FOUND. To filter uninteresting files from the output,\r
+ the type of file to search for may be specified in FileType. For\r
+ example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of\r
+ this type will be returned in the output. If *FileType is\r
+ EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key\r
+ parameter is used to indicate a starting point of the search. If\r
+ the buffer *Key is completely initialized to zero, the search\r
+ re-initialized and starts at the beginning. Subsequent calls to\r
+ GetNextFile() must maintain the value of *Key returned by the\r
+ immediately previous call. The actual contents of *Key are\r
+ implementation specific and no semantic content is implied.\r
+ GetNextFile() is callable only from TPL_NOTIFY and below.\r
+ Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is\r
+ undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0\r
+ specification. Status Codes Returned\r
+\r
+\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance. Key Pointer to a caller-allocated buffer\r
+ that contains implementation-specific data that is\r
+ used to track where to begin the search for the\r
+ next file. The size of the buffer must be at least\r
+ This->KeySize bytes long. To re-initialize the\r
+ search and begin from the beginning of the\r
+ firmware volume, the entire buffer must be cleared\r
+ to zero. Other than clearing the buffer to\r
+ initiate a new search, the caller must not modify\r
+ the data in the buffer between calls to\r
+ GetNextFile().\r
+\r
+ @param FileType Pointer to a caller-allocated\r
+ EFI_FV_FILETYPE. The GetNextFile() API can\r
+ filter its search for files based on the\r
+ value of the FileType input. A *FileType\r
+ input of EFI_FV_FILETYPE_ALL causes\r
+ GetNextFile() to search for files of all\r
+ types. If a file is found, the file's type\r
+ is returned in FileType. *FileType is not\r
+ modified if no file is found.\r
+\r
+ @param NameGuid Pointer to a caller-allocated EFI_GUID. If a\r
+ matching file is found, the file's name is\r
+ returned in NameGuid. If no matching file is\r
+ found, *NameGuid is not modified.\r
+\r
+ @param Attributes Pointer to a caller-allocated\r
+ EFI_FV_FILE_ATTRIBUTES. If a matching file\r
+ is found, the file's attributes are returned\r
+ in Attributes. If no matching file is found,\r
+ Attributes is not modified. Type\r
+ EFI_FV_FILE_ATTRIBUTES is defined in\r
+ ReadFile().\r
+\r
+ @param Size Pointer to a caller-allocated UINTN. If a\r
+ matching file is found, the file's size is\r
+ returned in *Size. If no matching file is found,\r
+ Size is not modified.\r
+\r
+ @retval EFI_SUCCESS The output parameters are filled with data\r
+ obtained from the first matching file that\r
+ was found.\r
+\r
+ @retval FI_NOT_FOUND No files of type FileType were found.\r
+\r
+\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when\r
+ attempting to access the firmware\r
+ volume.\r
+\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
+ disallow reads.\r
+\r
+ \r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetNextFile (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN OUT VOID *Key,\r
+ IN OUT EFI_FV_FILETYPE *FileType,\r
+ OUT EFI_GUID *NameGuid,\r
+ OUT EFI_FV_FILE_ATTRIBUTES *Attributes,\r
+ OUT UINTN *Size\r
+ )\r
+{\r
+ FIRMWARE_VOLUME2_PRIVATE_DATA *Private;\r
+ EFI_FIRMWARE_VOLUME_PROTOCOL *FirmwareVolume;\r
+\r
+ Private = FIRMWARE_VOLUME2_PRIVATE_DATA_FROM_THIS (This);\r
+ FirmwareVolume = Private->FirmwareVolume;\r
+\r
+ return FirmwareVolume->GetNextFile (\r
+ FirmwareVolume,\r
+ Key,\r
+ FileType,\r
+ NameGuid,\r
+ Attributes,\r
+ Size\r
+ );\r
+}\r
+\r
+/**\r
+ The GetInfo() function returns information of type\r
+ InformationType for the requested firmware volume. If the volume\r
+ does not support the requested information type, then\r
+ EFI_UNSUPPORTED is returned. If the buffer is not large enough\r
+ to hold the requested structure, EFI_BUFFER_TOO_SMALL is\r
+ returned and the BufferSize is set to the size of buffer that is\r
+ required to make the request. The information types defined by\r
+ this specification are required information types that all file\r
+ systems must support.\r
+\r
+ @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance that is the file handle the requested\r
+ information is for.\r
+ \r
+ @param InformationType The type identifier for the\r
+ information being requested.\r
+ \r
+ @param BufferSize On input, the size of Buffer. On output,\r
+ the amount of data returned in Buffer. In\r
+ both cases, the size is measured in bytes.\r
+ \r
+ @param Buffer A pointer to the data buffer to return. The\r
+ buffer's type is indicated by InformationType.\r
+ \r
+ \r
+ @retval EFI_SUCCESS The information was retrieved.\r
+ \r
+ @retval EFI_UNSUPPORTED The InformationType is not known.\r
+ \r
+ @retval EFI_NO_MEDIA The device has no medium.\r
+ \r
+ @retval EFI_DEVICE_ERROR The device reported an error.\r
+ \r
+ @retval EFI_VOLUME_CORRUPTED The file system structures are\r
+ corrupted.\r
+ \r
+ @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to\r
+ read the current directory\r
+ entry. BufferSize has been\r
+ updated with the size needed to\r
+ complete the request.\r
+\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2GetInfo (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *InformationType,\r
+ IN OUT UINTN *BufferSize,\r
+ OUT VOID *Buffer\r
+ )\r
+{\r
+ return EFI_UNSUPPORTED;\r
+}\r
+\r
+/**\r
+\r
+ The SetInfo() function sets information of type InformationType\r
+ on the requested firmware volume.\r
+\r
+\r
+ @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
+ instance that is the file handle the information\r
+ is for.\r
+\r
+ @param InformationType The type identifier for the\r
+ information being set.\r
+\r
+ @param BufferSize The size, in bytes, of Buffer.\r
+\r
+ @param Buffer A pointer to the data buffer to write. The\r
+ buffer's type is indicated by InformationType.\r
+\r
+ @retval EFI_SUCCESS The information was set.\r
+\r
+ @retval EFI_UNSUPPORTED The InformationType is not known.\r
+\r
+ @retval EFI_NO_MEDIA The device has no medium.\r
+\r
+ @retval EFI_DEVICE_ERROR The device reported an error.\r
+\r
+ @retval EFI_VOLUME_CORRUPTED The file system structures are\r
+ corrupted.\r
+\r
+\r
+ @retval EFI_WRITE_PROTECTED The media is read only.\r
+\r
+ @retval EFI_VOLUME_FULL The volume is full.\r
+\r
+ @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the\r
+ size of the type indicated by\r
+ InformationType.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+Fv2SetInfo (\r
+ IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
+ IN CONST EFI_GUID *InformationType,\r
+ IN UINTN BufferSize,\r
+ IN CONST VOID *Buffer\r
+ )\r
+{\r
+ return EFI_UNSUPPORTED;\r
+}\r
projects / mirror_edk2.git / blobdiff