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

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