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

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