-/** @file\r
- Firmware File System protocol. Layers on top of Firmware\r
- Block protocol to produce a file abstraction of FV based files.\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
-\r
-**/\r
-\r
-#ifndef __FW_VOL_DRIVER_H_\r
-#define __FW_VOL_DRIVER_H_\r
-\r
-\r
-#define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')\r
-\r
-//\r
-// Used to track all non-deleted files\r
-//\r
-typedef struct {\r
- LIST_ENTRY Link;\r
- EFI_FFS_FILE_HEADER *FfsHeader;\r
- UINTN StreamHandle;\r
-} FFS_FILE_LIST_ENTRY;\r
-\r
-typedef struct {\r
- UINTN Signature;\r
- EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb;\r
- EFI_HANDLE Handle;\r
- EFI_FIRMWARE_VOLUME2_PROTOCOL Fv;\r
-\r
- EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader;\r
- UINT8 *CachedFv;\r
- UINT8 *EndOfCachedFv;\r
-\r
- FFS_FILE_LIST_ENTRY *LastKey;\r
-\r
- LIST_ENTRY FfsFileListHeader;\r
-\r
- UINT8 ErasePolarity;\r
-} FV_DEVICE;\r
-\r
-#define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)\r
-\r
-/**\r
- Retrieves attributes, insures positive polarity of attribute bits, returns\r
- resulting attributes in output parameter.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param Attributes output buffer which contains attributes.\r
-\r
- @retval EFI_SUCCESS Successfully got volume attributes.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvGetVolumeAttributes (\r
- IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
- OUT EFI_FV_ATTRIBUTES *Attributes\r
- );\r
-\r
-\r
-/**\r
- Sets current attributes for volume\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param Attributes At input, contains attributes to be set. At output\r
- contains new value of FV.\r
-\r
- @retval EFI_UNSUPPORTED Could not be set.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvSetVolumeAttributes (\r
- IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
- IN OUT EFI_FV_ATTRIBUTES *Attributes\r
- );\r
-\r
-\r
-/**\r
- Given the input key, search for the next matching file in the volume.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param Key Key is a pointer to a caller allocated\r
- buffer that contains implementation specific\r
- data that is used to track where to begin\r
- the search for the next file. The size of\r
- the buffer must be at least This->KeySize\r
- bytes long. To reinitialize the search and\r
- begin from the beginning of the firmware\r
- volume, the entire buffer must be cleared to\r
- zero. Other than clearing the buffer to\r
- initiate a new search, the caller must not\r
- modify the data in the buffer between calls\r
- to GetNextFile().\r
- @param FileType FileType is a pointer to a caller allocated\r
- EFI_FV_FILETYPE. The GetNextFile() API can\r
- filter it's search for files based on the\r
- value of *FileType input. A *FileType input\r
- of 0 causes GetNextFile() to search for\r
- files of all types. If a file is found, the\r
- file's type is returned in *FileType.\r
- *FileType is not modified if no file is\r
- found.\r
- @param NameGuid NameGuid is a pointer to a caller allocated\r
- EFI_GUID. If a file is found, the file's\r
- name is returned in *NameGuid. *NameGuid is\r
- not modified if no file is found.\r
- @param Attributes Attributes is a pointer to a caller\r
- allocated EFI_FV_FILE_ATTRIBUTES. If a file\r
- is found, the file's attributes are returned\r
- in *Attributes. *Attributes is not modified\r
- if no file is found.\r
- @param Size Size is a pointer to a caller allocated\r
- UINTN. If a file is found, the file's size\r
- is returned in *Size. *Size is not modified\r
- if no file is found.\r
-\r
- @retval EFI_SUCCESS Successfully find the file.\r
- @retval EFI_DEVICE_ERROR Device error.\r
- @retval EFI_ACCESS_DENIED Fv could not read.\r
- @retval EFI_NOT_FOUND No matching file found.\r
- @retval EFI_INVALID_PARAMETER Invalid parameter\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvGetNextFile (\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
-\r
-/**\r
- Locates a file in the firmware volume and\r
- copies it to the supplied buffer.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param NameGuid Pointer to an EFI_GUID, which is the\r
- filename.\r
- @param Buffer Buffer is a pointer to pointer to a buffer\r
- in which the file or section contents or are\r
- returned.\r
- @param BufferSize BufferSize is a pointer to caller allocated\r
- UINTN. On input *BufferSize indicates the\r
- size in bytes of the memory region pointed\r
- to by Buffer. On output, *BufferSize\r
- contains the number of bytes required to\r
- read the file.\r
- @param FoundType FoundType is a pointer to a caller allocated\r
- EFI_FV_FILETYPE that on successful return\r
- from Read() contains the type of file read.\r
- This output reflects the file type\r
- irrespective of the value of the SectionType\r
- input.\r
- @param FileAttributes FileAttributes is a pointer to a caller\r
- allocated EFI_FV_FILE_ATTRIBUTES. On\r
- successful return from Read(),\r
- *FileAttributes contains the attributes of\r
- the file read.\r
- @param AuthenticationStatus AuthenticationStatus is a pointer to a\r
- caller allocated UINTN in which the\r
- authentication status is returned.\r
-\r
- @retval EFI_SUCCESS Successfully read to memory buffer.\r
- @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.\r
- @retval EFI_NOT_FOUND Not found.\r
- @retval EFI_DEVICE_ERROR Device error.\r
- @retval EFI_ACCESS_DENIED Could not read.\r
- @retval EFI_INVALID_PARAMETER Invalid parameter.\r
- @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvReadFile (\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
-/**\r
- Locates a section in a given FFS File and\r
- copies it to the supplied buffer (not including section header).\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param NameGuid Pointer to an EFI_GUID, which is the\r
- filename.\r
- @param SectionType Indicates the section type to return.\r
- @param SectionInstance Indicates which instance of sections with a\r
- type of SectionType to return.\r
- @param Buffer Buffer is a pointer to pointer to a buffer\r
- in which the file or section contents or are\r
- returned.\r
- @param BufferSize BufferSize is a pointer to caller allocated\r
- UINTN.\r
- @param AuthenticationStatus AuthenticationStatus is a pointer to a\r
- caller allocated UINT32 in which the\r
- authentication status is returned.\r
-\r
- @retval EFI_SUCCESS Successfully read the file section into\r
- buffer.\r
- @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.\r
- @retval EFI_NOT_FOUND Section not found.\r
- @retval EFI_DEVICE_ERROR Device error.\r
- @retval EFI_ACCESS_DENIED Could not read.\r
- @retval EFI_INVALID_PARAMETER Invalid parameter.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvReadFileSection (\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
-/**\r
- Writes one or more files to the firmware volume.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param NumberOfFiles Number of files.\r
- @param WritePolicy WritePolicy indicates the level of reliability\r
- for the write in the event of a power failure or\r
- other system failure during the write operation.\r
- @param FileData FileData is an pointer to an array of\r
- EFI_FV_WRITE_DATA. Each element of array\r
- FileData represents a file to be written.\r
-\r
- @retval EFI_SUCCESS Files successfully written to firmware volume\r
- @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.\r
- @retval EFI_DEVICE_ERROR Device error.\r
- @retval EFI_WRITE_PROTECTED Write protected.\r
- @retval EFI_NOT_FOUND Not found.\r
- @retval EFI_INVALID_PARAMETER Invalid parameter.\r
- @retval EFI_UNSUPPORTED This function not supported.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvWriteFile (\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
-/**\r
- Return information of type InformationType for the requested firmware\r
- volume.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param InformationType InformationType for requested.\r
- @param BufferSize On input, size of Buffer.On output, the amount of data\r
- returned in Buffer.\r
- @param Buffer A poniter to the data buffer to return.\r
-\r
- @retval EFI_SUCCESS Successfully got volume Information.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvGetVolumeInfo (\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
-/**\r
- Set information of type InformationType for the requested firmware\r
- volume.\r
-\r
- @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @param InformationType InformationType for requested.\r
- @param BufferSize On input, size of Buffer.On output, the amount of data\r
- returned in Buffer.\r
- @param Buffer A poniter to the data buffer to return.\r
-\r
- @retval EFI_SUCCESS Successfully set volume Information.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-FvSetVolumeInfo (\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
-//Internal functions\r
-//\r
-typedef enum {\r
- EfiCheckSumUint8 = 0,\r
- EfiCheckSumUint16 = 1,\r
- EfiCheckSumUint32 = 2,\r
- EfiCheckSumUint64 = 3,\r
- EfiCheckSumMaximum = 4\r
-} EFI_CHECKSUM_TYPE;\r
-\r
-\r
-\r
-/**\r
- Check if a block of buffer is erased.\r
-\r
- @param ErasePolarity Erase polarity attribute of the firmware volume\r
- @param InBuffer The buffer to be checked\r
- @param BufferSize Size of the buffer in bytes\r
-\r
- @retval TRUE The block of buffer is erased\r
- @retval FALSE The block of buffer is not erased\r
-\r
-**/\r
-BOOLEAN\r
-IsBufferErased (\r
- IN UINT8 ErasePolarity,\r
- IN VOID *InBuffer,\r
- IN UINTN BufferSize\r
- );\r
-\r
-\r
-/**\r
- Get the FFS file state by checking the highest bit set in the header's state field.\r
-\r
- @param ErasePolarity Erase polarity attribute of the firmware volume\r
- @param FfsHeader Points to the FFS file header\r
-\r
- @return FFS File state\r
-\r
-**/\r
-EFI_FFS_FILE_STATE\r
-GetFileState (\r
- IN UINT8 ErasePolarity,\r
- IN EFI_FFS_FILE_HEADER *FfsHeader\r
- );\r
-\r
-\r
-/**\r
- Set the FFS file state.\r
-\r
- @param State The state to be set.\r
- @param FfsHeader Points to the FFS file header\r
-\r
- @return None.\r
-\r
-**/\r
-VOID\r
-SetFileState (\r
- IN UINT8 State,\r
- IN EFI_FFS_FILE_HEADER *FfsHeader\r
- );\r
-\r
-\r
-/**\r
- Verify checksum of the firmware volume header.\r
-\r
- @param FvHeader Points to the firmware volume header to be checked\r
-\r
- @retval TRUE Checksum verification passed\r
- @retval FALSE Checksum verification failed\r
-\r
-**/\r
-BOOLEAN\r
-VerifyFvHeaderChecksum (\r
- IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader\r
- );\r
-\r
-\r
-/**\r
- Check if it's a valid FFS file header.\r
-\r
- @param ErasePolarity Erase polarity attribute of the firmware volume\r
- @param FfsHeader Points to the FFS file header to be checked\r
- @param FileState FFS file state to be returned\r
-\r
- @retval TRUE Valid FFS file header\r
- @retval FALSE Invalid FFS file header\r
-\r
-**/\r
-BOOLEAN\r
-IsValidFfsHeader (\r
- IN UINT8 ErasePolarity,\r
- IN EFI_FFS_FILE_HEADER *FfsHeader,\r
- OUT EFI_FFS_FILE_STATE *FileState\r
- );\r
-\r
-\r
-/**\r
- Check if it's a valid FFS file.\r
- Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.\r
-\r
- @param ErasePolarity Erase polarity attribute of the firmware volume\r
- @param FfsHeader Points to the FFS file to be checked\r
-\r
- @retval TRUE Valid FFS file\r
- @retval FALSE Invalid FFS file\r
-\r
-**/\r
-BOOLEAN\r
-IsValidFfsFile (\r
- IN UINT8 ErasePolarity,\r
- IN EFI_FFS_FILE_HEADER *FfsHeader\r
- );\r
-\r
-\r
-/**\r
- given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and\r
- copy the volume header into it.\r
-\r
- @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to\r
- read the volume header\r
- @param FwVolHeader Pointer to pointer to allocated buffer in which\r
- the volume header is returned.\r
-\r
- @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.\r
- @retval EFI_SUCCESS Successfully read volume header to the allocated\r
- buffer.\r
-\r
-**/\r
-EFI_STATUS\r
-GetFwVolHeader (\r
- IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb,\r
- OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader\r
- );\r
-\r
-\r
-\r
-/**\r
- Check if an FV is consistent and allocate cache for it.\r
-\r
- @param FvDevice A pointer to the FvDevice to be checked.\r
-\r
- @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.\r
- @retval EFI_SUCCESS FV is consistent and cache is allocated.\r
- @retval EFI_VOLUME_CORRUPTED File system is corrupted.\r
-\r
-**/\r
-EFI_STATUS\r
-FvCheck (\r
- IN OUT FV_DEVICE *FvDevice\r
- );\r
-\r
-#endif\r