[mirror_edk2.git] / MdeModulePkg / Core / Dxe / FwVolDriver.h

/**@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, Intel Corporation                                                         \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 __FWVOL_H\r
#define __FWVOL_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
EFI_STATUS\r
EFIAPI\r
FvGetVolumeAttributes (\r
  IN    CONST EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,\r
  OUT         EFI_FV_ATTRIBUTES              *Attributes\r
  )\r
/*++\r
\r
Routine Description:\r
    Retrieves attributes, insures positive polarity of attribute bits, returns\r
    resulting attributes in output parameter\r
\r
Arguments:\r
    This        - Calling context\r
    Attributes  - output buffer which contains attributes\r
\r
Returns:\r
    EFI_SUCCESS         - Successfully got volume attributes\r
\r
--*/\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
Routine Description:\r
    Sets current attributes for volume\r
\r
Arguments:\r
    This       - Calling context\r
    Attributes - At input, contains attributes to be set.  At output contains\r
      new value of FV\r
\r
Returns:\r
    EFI_UNSUPPORTED   - Could not be set.\r
--*/\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
Routine Description:\r
    Given the input key, search for the next matching file in the volume.\r
\r
Arguments:\r
    This          -   Indicates the calling context.\r
    FileType      -   FileType is a pointer to a caller allocated\r
                      EFI_FV_FILETYPE. The GetNextFile() API can filter it's\r
                      search for files based on the value of *FileType input.\r
                      A *FileType input of 0 causes GetNextFile() to search for\r
                      files of all types.  If a file is found, the file's type\r
                      is returned in *FileType.  *FileType is not modified if\r
                      no file is found.\r
    Key           -   Key is a pointer to a caller allocated buffer that\r
                      contains implementation specific data that is used to\r
                      track where to begin the search for the next file.\r
                      The size of the buffer must be at least This->KeySize\r
                      bytes long. To reinitialize the search and begin from\r
                      the beginning of the firmware volume, the entire buffer\r
                      must be cleared to zero. Other than clearing the buffer\r
                      to initiate a new search, the caller must not modify the\r
                      data in the buffer between calls to GetNextFile().\r
    NameGuid      -   NameGuid is a pointer to a caller allocated EFI_GUID.\r
                      If a file is found, the file's name is returned in\r
                      *NameGuid.  *NameGuid is not modified if no file is\r
                      found.\r
    Attributes    -   Attributes is a pointer to a caller allocated\r
                      EFI_FV_FILE_ATTRIBUTES.  If a file is found, the file's\r
                      attributes are returned in *Attributes. *Attributes is\r
                      not modified if no file is found.\r
    Size          -   Size is a pointer to a caller allocated UINTN.\r
                      If a file is found, the file's size is returned in *Size.\r
                      *Size is not modified if no file is found.\r
\r
Returns:    \r
    EFI_SUCCESS                 - Successfully find the file.\r
    EFI_DEVICE_ERROR            - Device error.\r
    EFI_ACCESS_DENIED           - Fv could not read.\r
    EFI_NOT_FOUND               - No matching file found.\r
    EFI_INVALID_PARAMETER       - Invalid parameter\r
\r
--*/\r
;\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
Routine Description:\r
    Locates a file in the firmware volume and\r
    copies it to the supplied buffer.\r
\r
Arguments:\r
    This              -   Indicates the calling context.\r
    NameGuid          -   Pointer to an EFI_GUID, which is the filename.\r
    Buffer            -   Buffer is a pointer to pointer to a buffer in\r
                          which the file or section contents or are returned.\r
    BufferSize        -   BufferSize is a pointer to caller allocated\r
                          UINTN. On input *BufferSize indicates the size\r
                          in bytes of the memory region pointed to by\r
                          Buffer. On output, *BufferSize contains the number\r
                          of bytes required to read the file.\r
    FoundType         -   FoundType is a pointer to a caller allocated\r
                          EFI_FV_FILETYPE that on successful return from Read()\r
                          contains the type of file read.  This output reflects\r
                          the file type irrespective of the value of the\r
                          SectionType input.\r
    FileAttributes    -   FileAttributes is a pointer to a caller allocated\r
                          EFI_FV_FILE_ATTRIBUTES.  On successful return from\r
                          Read(), *FileAttributes contains the attributes of\r
                          the file read.\r
    AuthenticationStatus -  AuthenticationStatus is a pointer to a caller\r
                          allocated UINTN in which the authentication status\r
                          is returned.\r
Returns:\r
    EFI_SUCCESS                   - Successfully read to memory buffer.\r
    EFI_WARN_BUFFER_TOO_SMALL     - Buffer too small.\r
    EFI_NOT_FOUND                 - Not found.\r
    EFI_DEVICE_ERROR              - Device error.\r
    EFI_ACCESS_DENIED             - Could not read.\r
    EFI_INVALID_PARAMETER         - Invalid parameter.\r
    EFI_OUT_OF_RESOURCES          - Not enough buffer to be allocated.\r
\r
--*/\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
  Routine Description:\r
    Locates a section in a given FFS File and\r
    copies it to the supplied buffer (not including section header).\r
\r
  Arguments:\r
    This              -   Indicates the calling context.\r
    NameGuid          -   Pointer to an EFI_GUID, which is the filename.\r
    SectionType       -   Indicates the section type to return.\r
    SectionInstance   -   Indicates which instance of sections with a type of\r
                          SectionType to return.\r
    Buffer            -   Buffer is a pointer to pointer to a buffer in which\r
                          the file or section contents or are returned.\r
    BufferSize        -   BufferSize is a pointer to caller allocated UINTN.\r
    AuthenticationStatus -AuthenticationStatus is a pointer to a caller\r
                          allocated UINT32 in which the authentication status\r
                          is returned.\r
\r
  Returns:\r
    EFI_SUCCESS                     - Successfully read the file section into buffer.\r
    EFI_WARN_BUFFER_TOO_SMALL       - Buffer too small.\r
    EFI_NOT_FOUND                   - Section not found.\r
    EFI_DEVICE_ERROR                - Device error.\r
    EFI_ACCESS_DENIED               - Could not read.\r
    EFI_INVALID_PARAMETER           - Invalid parameter.\r
\r
--*/\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
    Routine Description:\r
      Writes one or more files to the firmware volume.\r
\r
    Arguments:\r
    This        - Indicates the calling context.\r
    WritePolicy - WritePolicy indicates the level of reliability for\r
                  the write in the event of a power failure or other\r
                  system failure during the write operation.\r
    FileData    - FileData is an pointer to an array of EFI_FV_WRITE_DATA.\r
                  Each element of FileData[] represents a file to be written.\r
\r
    Returns:\r
      EFI_SUCCESS                   - Files successfully written to firmware volume\r
      EFI_OUT_OF_RESOURCES          - Not enough buffer to be allocated.\r
      EFI_DEVICE_ERROR              - Device error.\r
      EFI_WRITE_PROTECTED           - Write protected.\r
      EFI_NOT_FOUND                 - Not found.\r
      EFI_INVALID_PARAMETER         - Invalid parameter.\r
      EFI_UNSUPPORTED               - This function not supported.\r
\r
--*/\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
Routine Description:\r
  Return information of type InformationType for the requested firmware\r
  volume.\r
  \r
Arguments:\r
    This                - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
    InformationType     - InformationType for requested.\r
    BufferSize          - On input, size of Buffer.On output, the amount of\r
                          data returned in Buffer.\r
    Buffer              - A poniter to the data buffer to return.\r
Returns:\r
    EFI_SUCCESS         - Successfully got volume Information.\r
\r
--*/\r
;\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
Routine Description:\r
  Set information of type InformationType for the requested firmware\r
  volume.\r
\r
Arguments:\r
    This                - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
    InformationType     - InformationType for requested.\r
    BufferSize          - On input, size of Buffer.On output, the amount of\r
                          data returned in Buffer.\r
    Buffer              - A poniter to the data buffer to return.\r
Returns:\r
    EFI_SUCCESS         - Successfully set volume Information.\r
\r
--*/\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
BOOLEAN\r
IsBufferErased (\r
  IN UINT8    ErasePolarity,\r
  IN VOID     *Buffer,\r
  IN UINTN    BufferSize\r
  )\r
/*++\r
\r
Routine Description:\r
  Check if a block of buffer is erased\r
\r
Arguments:\r
  ErasePolarity -  Erase polarity attribute of the firmware volume\r
  Buffer        -  The buffer to be checked\r
  BufferSize    -  Size of the buffer in bytes\r
    \r
Returns:\r
  TRUE  -  The block of buffer is erased\r
  FALSE -  The block of buffer is not erased\r
    \r
--*/\r
;\r
\r
EFI_FFS_FILE_STATE \r
GetFileState (\r
  IN UINT8                ErasePolarity,\r
  IN EFI_FFS_FILE_HEADER  *FfsHeader\r
  )\r
/*++\r
\r
Routine Description:\r
  Get the FFS file state by checking the highest bit set in the header's state field\r
\r
Arguments:\r
  ErasePolarity -  Erase polarity attribute of the firmware volume\r
  FfsHeader     -  Points to the FFS file header\r
    \r
Returns:\r
  FFS File state \r
    \r
--*/\r
;\r
\r
VOID\r
SetFileState (\r
  IN UINT8                State,\r
  IN EFI_FFS_FILE_HEADER  *FfsHeader\r
  )\r
/*++\r
\r
Routine Description:\r
  Set the FFS file state.\r
\r
Arguments:\r
  State         -  The state to be set.\r
  FfsHeader     -  Points to the FFS file header\r
    \r
Returns:\r
  None.\r
    \r
--*/\r
;\r
\r
BOOLEAN\r
VerifyFvHeaderChecksum (\r
  IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader\r
  )\r
/*++\r
\r
Routine Description:\r
  Verify checksum of the firmware volume header \r
\r
Arguments:\r
  FvHeader  -  Points to the firmware volume header to be checked\r
    \r
Returns:\r
  TRUE  -  Checksum verification passed\r
  FALSE -  Checksum verification failed\r
    \r
--*/\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
Routine Description:\r
  Check if it's a valid FFS file header\r
\r
Arguments:\r
  ErasePolarity -  Erase polarity attribute of the firmware volume\r
  FfsHeader     -  Points to the FFS file header to be checked\r
  FileState     -  FFS file state to be returned\r
    \r
Returns:\r
  TRUE  -  Valid FFS file header\r
  FALSE -  Invalid FFS file header\r
    \r
--*/\r
;\r
\r
BOOLEAN\r
IsValidFfsFile (\r
  IN UINT8                ErasePolarity,\r
  IN EFI_FFS_FILE_HEADER  *FfsHeader\r
  )\r
/*++\r
\r
Routine Description:\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
Arguments:\r
  ErasePolarity -  Erase polarity attribute of the firmware volume\r
  FfsHeader     -  Points to the FFS file to be checked\r
    \r
Returns:\r
  TRUE  -  Valid FFS file\r
  FALSE -  Invalid FFS file\r
    \r
--*/\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
Routine Description:\r
  given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and\r
  copy the volume header into it.\r
\r
Arguments:\r
  Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume\r
          header\r
  FwVolHeader - Pointer to pointer to allocated buffer in which the volume\r
                  header is returned.\r
\r
Returns:\r
  Status code.\r
\r
--*/\r
;\r
\r
\r
EFI_STATUS\r
FvCheck (\r
  IN OUT FV_DEVICE  *FvDevice\r
  )\r
/*++\r
\r
Routine Description:\r
  Check if a FV is consistent and allocate cache\r
\r
Arguments:\r
  FvDevice - pointer to the FvDevice to be checked.\r
\r
Returns:\r
  EFI_OUT_OF_RESOURCES    - Not enough buffer to be allocated.\r
  EFI_SUCCESS             - FV is consistent and cache is allocated.\r
  EFI_VOLUME_CORRUPTED    - File system is corrupted.\r
\r
--*/\r
;\r
\r
#endif\r
Commit	Line	Data
797a9d67	1	/**@file\r
	2	Firmware File System protocol. Layers on top of Firmware\r
	3	Block protocol to produce a file abstraction of FV based files.\r
	4	\r
28a00297	5	Copyright (c) 2006, Intel Corporation \r
	6	All rights reserved. This program and the accompanying materials \r
	7	are licensed and made available under the terms and conditions of the BSD License \r
	8	which accompanies this distribution. The full text of the license may be found at \r
	9	http://opensource.org/licenses/bsd-license.php \r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	13	\r
797a9d67	14	**/\r
28a00297	15	\r
	16	#ifndef __FWVOL_H\r
	17	#define __FWVOL_H\r
	18	\r
	19	\r
0c2b5da8	20	#define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')\r
0c2b5da8	21	\r
28a00297	22	//\r
	23	// Used to track all non-deleted files\r
	24	//\r
	25	typedef struct {\r
	26	LIST_ENTRY Link;\r
	27	EFI_FFS_FILE_HEADER *FfsHeader;\r
	28	UINTN StreamHandle;\r
28a00297	29	} FFS_FILE_LIST_ENTRY;\r
	30	\r
	31	typedef struct {\r
	32	UINTN Signature;\r
	33	EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb;\r
	34	EFI_HANDLE Handle;\r
0c2b5da8	35	EFI_FIRMWARE_VOLUME2_PROTOCOL Fv;\r
28a00297	36	\r
	37	EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader;\r
	38	UINT8 *CachedFv;\r
	39	UINT8 *EndOfCachedFv;\r
	40	\r
	41	FFS_FILE_LIST_ENTRY *LastKey;\r
	42	\r
	43	LIST_ENTRY FfsFileListHeader;\r
	44	\r
	45	UINT8 ErasePolarity;\r
	46	} FV_DEVICE;\r
	47	\r
0c2b5da8	48	#define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)\r
28a00297	49	\r
	50	\r
	51	EFI_STATUS\r
	52	EFIAPI\r
	53	FvGetVolumeAttributes (\r
0c2b5da8	54	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
0c2b5da8	55	OUT EFI_FV_ATTRIBUTES *Attributes\r
28a00297	56	)\r
	57	/*++\r
	58	\r
	59	Routine Description:\r
	60	Retrieves attributes, insures positive polarity of attribute bits, returns\r
	61	resulting attributes in output parameter\r
	62	\r
	63	Arguments:\r
	64	This - Calling context\r
	65	Attributes - output buffer which contains attributes\r
	66	\r
	67	Returns:\r
	68	EFI_SUCCESS - Successfully got volume attributes\r
	69	\r
	70	--*/\r
	71	;\r
	72	\r
	73	EFI_STATUS\r
	74	EFIAPI\r
	75	FvSetVolumeAttributes (\r
0c2b5da8	76	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
0c2b5da8	77	IN OUT EFI_FV_ATTRIBUTES *Attributes\r
28a00297	78	)\r
	79	/*++\r
	80	\r
	81	Routine Description:\r
	82	Sets current attributes for volume\r
	83	\r
	84	Arguments:\r
	85	This - Calling context\r
	86	Attributes - At input, contains attributes to be set. At output contains\r
	87	new value of FV\r
	88	\r
	89	Returns:\r
	90	EFI_UNSUPPORTED - Could not be set.\r
	91	--*/\r
	92	;\r
	93	\r
	94	EFI_STATUS\r
	95	EFIAPI\r
	96	FvGetNextFile (\r
0c2b5da8	97	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	98	IN OUT VOID *Key,\r
	99	IN OUT EFI_FV_FILETYPE *FileType,\r
	100	OUT EFI_GUID *NameGuid,\r
	101	OUT EFI_FV_FILE_ATTRIBUTES *Attributes,\r
	102	OUT UINTN *Size\r
28a00297	103	)\r
	104	/*++\r
	105	\r
	106	Routine Description:\r
	107	Given the input key, search for the next matching file in the volume.\r
	108	\r
	109	Arguments:\r
	110	This - Indicates the calling context.\r
	111	FileType - FileType is a pointer to a caller allocated\r
	112	EFI_FV_FILETYPE. The GetNextFile() API can filter it's\r
	113	search for files based on the value of *FileType input.\r
	114	A *FileType input of 0 causes GetNextFile() to search for\r
	115	files of all types. If a file is found, the file's type\r
	116	is returned in FileType. FileType is not modified if\r
	117	no file is found.\r
	118	Key - Key is a pointer to a caller allocated buffer that\r
	119	contains implementation specific data that is used to\r
	120	track where to begin the search for the next file.\r
	121	The size of the buffer must be at least This->KeySize\r
	122	bytes long. To reinitialize the search and begin from\r
	123	the beginning of the firmware volume, the entire buffer\r
	124	must be cleared to zero. Other than clearing the buffer\r
	125	to initiate a new search, the caller must not modify the\r
	126	data in the buffer between calls to GetNextFile().\r
	127	NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.\r
	128	If a file is found, the file's name is returned in\r
	129	NameGuid. NameGuid is not modified if no file is\r
	130	found.\r
	131	Attributes - Attributes is a pointer to a caller allocated\r
	132	EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's\r
	133	attributes are returned in Attributes. Attributes is\r
	134	not modified if no file is found.\r
	135	Size - Size is a pointer to a caller allocated UINTN.\r
	136	If a file is found, the file's size is returned in *Size.\r
	137	*Size is not modified if no file is found.\r
	138	\r
	139	Returns: \r
	140	EFI_SUCCESS - Successfully find the file.\r
	141	EFI_DEVICE_ERROR - Device error.\r
	142	EFI_ACCESS_DENIED - Fv could not read.\r
	143	EFI_NOT_FOUND - No matching file found.\r
	144	EFI_INVALID_PARAMETER - Invalid parameter\r
	145	\r
	146	--*/\r
	147	;\r
	148	\r
	149	\r
	150	EFI_STATUS\r
	151	EFIAPI\r
	152	FvReadFile (\r
0c2b5da8	153	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	154	IN CONST EFI_GUID *NameGuid,\r
	155	IN OUT VOID **Buffer,\r
	156	IN OUT UINTN *BufferSize,\r
	157	OUT EFI_FV_FILETYPE *FoundType,\r
	158	OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,\r
	159	OUT UINT32 *AuthenticationStatus\r
28a00297	160	)\r
	161	/*++\r
	162	\r
	163	Routine Description:\r
	164	Locates a file in the firmware volume and\r
	165	copies it to the supplied buffer.\r
	166	\r
	167	Arguments:\r
	168	This - Indicates the calling context.\r
	169	NameGuid - Pointer to an EFI_GUID, which is the filename.\r
	170	Buffer - Buffer is a pointer to pointer to a buffer in\r
	171	which the file or section contents or are returned.\r
	172	BufferSize - BufferSize is a pointer to caller allocated\r
	173	UINTN. On input *BufferSize indicates the size\r
	174	in bytes of the memory region pointed to by\r
	175	Buffer. On output, *BufferSize contains the number\r
	176	of bytes required to read the file.\r
	177	FoundType - FoundType is a pointer to a caller allocated\r
	178	EFI_FV_FILETYPE that on successful return from Read()\r
	179	contains the type of file read. This output reflects\r
	180	the file type irrespective of the value of the\r
	181	SectionType input.\r
	182	FileAttributes - FileAttributes is a pointer to a caller allocated\r
	183	EFI_FV_FILE_ATTRIBUTES. On successful return from\r
	184	Read(), *FileAttributes contains the attributes of\r
	185	the file read.\r
	186	AuthenticationStatus - AuthenticationStatus is a pointer to a caller\r
	187	allocated UINTN in which the authentication status\r
	188	is returned.\r
	189	Returns:\r
	190	EFI_SUCCESS - Successfully read to memory buffer.\r
	191	EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.\r
	192	EFI_NOT_FOUND - Not found.\r
	193	EFI_DEVICE_ERROR - Device error.\r
	194	EFI_ACCESS_DENIED - Could not read.\r
	195	EFI_INVALID_PARAMETER - Invalid parameter.\r
	196	EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.\r
	197	\r
	198	--*/\r
	199	;\r
	200	\r
	201	EFI_STATUS\r
	202	EFIAPI\r
	203	FvReadFileSection (\r
0c2b5da8	204	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	205	IN CONST EFI_GUID *NameGuid,\r
	206	IN EFI_SECTION_TYPE SectionType,\r
	207	IN UINTN SectionInstance,\r
	208	IN OUT VOID **Buffer,\r
	209	IN OUT UINTN *BufferSize,\r
	210	OUT UINT32 *AuthenticationStatus\r
28a00297	211	)\r
	212	/*++\r
	213	\r
	214	Routine Description:\r
	215	Locates a section in a given FFS File and\r
	216	copies it to the supplied buffer (not including section header).\r
	217	\r
	218	Arguments:\r
	219	This - Indicates the calling context.\r
	220	NameGuid - Pointer to an EFI_GUID, which is the filename.\r
	221	SectionType - Indicates the section type to return.\r
	222	SectionInstance - Indicates which instance of sections with a type of\r
	223	SectionType to return.\r
	224	Buffer - Buffer is a pointer to pointer to a buffer in which\r
	225	the file or section contents or are returned.\r
	226	BufferSize - BufferSize is a pointer to caller allocated UINTN.\r
	227	AuthenticationStatus -AuthenticationStatus is a pointer to a caller\r
	228	allocated UINT32 in which the authentication status\r
	229	is returned.\r
	230	\r
	231	Returns:\r
	232	EFI_SUCCESS - Successfully read the file section into buffer.\r
	233	EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.\r
	234	EFI_NOT_FOUND - Section not found.\r
	235	EFI_DEVICE_ERROR - Device error.\r
	236	EFI_ACCESS_DENIED - Could not read.\r
	237	EFI_INVALID_PARAMETER - Invalid parameter.\r
	238	\r
	239	--*/\r
	240	;\r
	241	\r
	242	EFI_STATUS\r
	243	EFIAPI\r
	244	FvWriteFile (\r
0c2b5da8	245	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	246	IN UINT32 NumberOfFiles,\r
	247	IN EFI_FV_WRITE_POLICY WritePolicy,\r
	248	IN EFI_FV_WRITE_FILE_DATA *FileData\r
28a00297	249	)\r
	250	/*++\r
	251	\r
	252	Routine Description:\r
	253	Writes one or more files to the firmware volume.\r
	254	\r
	255	Arguments:\r
	256	This - Indicates the calling context.\r
	257	WritePolicy - WritePolicy indicates the level of reliability for\r
	258	the write in the event of a power failure or other\r
	259	system failure during the write operation.\r
	260	FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.\r
	261	Each element of FileData[] represents a file to be written.\r
	262	\r
	263	Returns:\r
	264	EFI_SUCCESS - Files successfully written to firmware volume\r
	265	EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.\r
	266	EFI_DEVICE_ERROR - Device error.\r
	267	EFI_WRITE_PROTECTED - Write protected.\r
	268	EFI_NOT_FOUND - Not found.\r
	269	EFI_INVALID_PARAMETER - Invalid parameter.\r
	270	EFI_UNSUPPORTED - This function not supported.\r
	271	\r
	272	--*/\r
	273	;\r
	274	\r
0c2b5da8	275	EFI_STATUS\r
	276	EFIAPI\r
	277	FvGetVolumeInfo (\r
	278	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	279	IN CONST EFI_GUID *InformationType,\r
	280	IN OUT UINTN *BufferSize,\r
	281	OUT VOID *Buffer\r
	282	)\r
	283	/*++\r
	284	\r
	285	Routine Description:\r
	286	Return information of type InformationType for the requested firmware\r
	287	volume.\r
	288	\r
	289	Arguments:\r
	290	This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
	291	InformationType - InformationType for requested.\r
	292	BufferSize - On input, size of Buffer.On output, the amount of\r
	293	data returned in Buffer.\r
	294	Buffer - A poniter to the data buffer to return.\r
	295	Returns:\r
	296	EFI_SUCCESS - Successfully got volume Information.\r
	297	\r
	298	--*/\r
	299	;\r
	300	\r
28a00297	301	\r
0c2b5da8	302	EFI_STATUS\r
	303	EFIAPI\r
	304	FvSetVolumeInfo (\r
	305	IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
	306	IN CONST EFI_GUID *InformationType,\r
	307	IN UINTN BufferSize,\r
	308	IN CONST VOID *Buffer\r
	309	)\r
	310	/*++\r
	311	\r
	312	Routine Description:\r
	313	Set information of type InformationType for the requested firmware\r
	314	volume.\r
	315	\r
	316	Arguments:\r
	317	This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
	318	InformationType - InformationType for requested.\r
	319	BufferSize - On input, size of Buffer.On output, the amount of\r
	320	data returned in Buffer.\r
	321	Buffer - A poniter to the data buffer to return.\r
	322	Returns:\r
	323	EFI_SUCCESS - Successfully set volume Information.\r
	324	\r
	325	--*/\r
	326	;\r
28a00297	327	\r
	328	//\r
	329	//Internal functions\r
	330	//\r
	331	typedef enum {\r
	332	EfiCheckSumUint8 = 0,\r
	333	EfiCheckSumUint16 = 1,\r
	334	EfiCheckSumUint32 = 2,\r
	335	EfiCheckSumUint64 = 3,\r
	336	EfiCheckSumMaximum = 4\r
	337	} EFI_CHECKSUM_TYPE;\r
	338	\r
	339	\r
	340	BOOLEAN\r
	341	IsBufferErased (\r
	342	IN UINT8 ErasePolarity,\r
	343	IN VOID *Buffer,\r
	344	IN UINTN BufferSize\r
	345	)\r
	346	/*++\r
	347	\r
	348	Routine Description:\r
	349	Check if a block of buffer is erased\r
	350	\r
	351	Arguments:\r
	352	ErasePolarity - Erase polarity attribute of the firmware volume\r
	353	Buffer - The buffer to be checked\r
	354	BufferSize - Size of the buffer in bytes\r
	355	\r
	356	Returns:\r
	357	TRUE - The block of buffer is erased\r
	358	FALSE - The block of buffer is not erased\r
	359	\r
	360	--*/\r
	361	;\r
	362	\r
	363	EFI_FFS_FILE_STATE \r
	364	GetFileState (\r
	365	IN UINT8 ErasePolarity,\r
	366	IN EFI_FFS_FILE_HEADER *FfsHeader\r
	367	)\r
	368	/*++\r
	369	\r
	370	Routine Description:\r
	371	Get the FFS file state by checking the highest bit set in the header's state field\r
	372	\r
	373	Arguments:\r
	374	ErasePolarity - Erase polarity attribute of the firmware volume\r
	375	FfsHeader - Points to the FFS file header\r
	376	\r
	377	Returns:\r
	378	FFS File state \r
	379	\r
	380	--*/\r
	381	;\r
	382	\r
	383	VOID\r
	384	SetFileState (\r
	385	IN UINT8 State,\r
	386	IN EFI_FFS_FILE_HEADER *FfsHeader\r
	387	)\r
	388	/*++\r
	389	\r
	390	Routine Description:\r
391	Set the FFS file state.\r
392	\r
393	Arguments:\r
394	State - The state to be set.\r
395	FfsHeader - Points to the FFS file header\r
396	\r
397	Returns:\r
398	None.\r
399	\r
400	--*/\r
401	;\r
402	\r
403	BOOLEAN\r
404	VerifyFvHeaderChecksum (\r
405	IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader\r
406	)\r
407	/*++\r
408	\r
409	Routine Description:\r
410	Verify checksum of the firmware volume header \r
411	\r
412	Arguments:\r
413	FvHeader - Points to the firmware volume header to be checked\r
414	\r
415	Returns:\r
416	TRUE - Checksum verification passed\r
417	FALSE - Checksum verification failed\r
418	\r
419	--*/\r
420	;\r
421	\r
422	BOOLEAN\r
423	IsValidFfsHeader (\r
424	IN UINT8 ErasePolarity,\r
425	IN EFI_FFS_FILE_HEADER *FfsHeader,\r
426	OUT EFI_FFS_FILE_STATE *FileState\r
427	)\r
428	/*++\r
429	\r
430	Routine Description:\r
431	Check if it's a valid FFS file header\r
432	\r
433	Arguments:\r
434	ErasePolarity - Erase polarity attribute of the firmware volume\r
435	FfsHeader - Points to the FFS file header to be checked\r
436	FileState - FFS file state to be returned\r
437	\r
438	Returns:\r
439	TRUE - Valid FFS file header\r
440	FALSE - Invalid FFS file header\r
441	\r
442	--*/\r
443	;\r
444	\r
445	BOOLEAN\r
446	IsValidFfsFile (\r
447	IN UINT8 ErasePolarity,\r
448	IN EFI_FFS_FILE_HEADER *FfsHeader\r
449	)\r
450	/*++\r
451	\r
452	Routine Description:\r
453	Check if it's a valid FFS file. \r
454	Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.\r
455	\r
456	Arguments:\r
457	ErasePolarity - Erase polarity attribute of the firmware volume\r
458	FfsHeader - Points to the FFS file to be checked\r
459	\r
460	Returns:\r
461	TRUE - Valid FFS file\r
462	FALSE - Invalid FFS file\r
463	\r
464	--*/\r
465	;\r
466	\r
467	EFI_STATUS\r
468	GetFwVolHeader (\r
469	IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb,\r
470	OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader\r
471	)\r
472	/*++\r
473	\r
474	Routine Description:\r
475	given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and\r
476	copy the volume header into it.\r
477	\r
478	Arguments:\r
479	Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume\r
480	header\r
481	FwVolHeader - Pointer to pointer to allocated buffer in which the volume\r
482	header is returned.\r
483	\r
484	Returns:\r
485	Status code.\r
486	\r
487	--*/\r
488	;\r
489	\r
490	\r
491	EFI_STATUS\r
492	FvCheck (\r
493	IN OUT FV_DEVICE *FvDevice\r
494	)\r
495	/*++\r
496	\r
497	Routine Description:\r
498	Check if a FV is consistent and allocate cache\r
499	\r
500	Arguments:\r
501	FvDevice - pointer to the FvDevice to be checked.\r
502	\r
503	Returns:\r
504	EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.\r
505	EFI_SUCCESS - FV is consistent and cache is allocated.\r
506	EFI_VOLUME_CORRUPTED - File system is corrupted.\r
507	\r
508	--*/\r
509	;\r
510	\r
511	#endif\r