[mirror_edk2.git] / MdePkg / Include / Ppi / FirmwareVolume.h

/** @file\r
  This file provides functions for accessing a memory-mapped firmware volume of a specific format.\r
\r
  Copyright (c) 2006 - 2007, 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
  @par Revision Reference:\r
  This PPI is defined in PI.\r
  Version 1.00\r
\r
**/\r
\r
#ifndef __FIRMWARE_VOLUME_PPI_H__\r
#define __FIRMWARE_VOLUME_PPI_H__\r
\r
///\r
/// The GUID for this PPI is the same as the firmware volume format GUID.\r
/// The FV format can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined\r
/// format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.\r
/// \r
typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI   EFI_PEI_FIRMWARE_VOLUME_PPI;\r
\r
\r
/**\r
  Process a firmware volume and create a volume handle.\r
\r
  Create a volume handle from the information in the buffer. For\r
  memory-mapped firmware volumes, Buffer and BufferSize refer to\r
  the start of the firmware volume and the firmware volume size.\r
  For non memory-mapped firmware volumes, this points to a\r
  buffer which contains the necessary information for creating\r
  the firmware volume handle. Normally, these values are derived\r
  from the EFI_FIRMWARE_VOLUME_INFO_PPI.\r
  \r
  \r
  @param This                   Points to this instance of the\r
                                EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param Buffer                 Points to the start of the buffer.\r
  @param BufferSize             Size of the buffer.\r
  @param FvHandle               Points to the returned firmware volume\r
                                handle. The firmware volume handle must\r
                                be unique within the system. \r
\r
  @retval EFI_SUCCESS           Firmware volume handle created.\r
  @retval EFI_VOLUME_CORRUPTED  Volume was corrupt.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_PROCESS_FV)(\r
  IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
  IN  VOID                               *Buffer,\r
  IN  UINTN                              BufferSize,\r
  OUT EFI_PEI_FV_HANDLE                  *FvHandle\r
);\r
\r
/**\r
  Finds the next file of the specified type.\r
\r
  This service enables PEI modules to discover additional firmware files. \r
  The FileHandle must be unique within the system.\r
\r
  @param This           Points to this instance of the\r
                        EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param SearchType     A filter to find only files of this type. Type\r
                        EFI_FV_FILETYPE_ALL causes no filtering to be\r
                        done.\r
  @param FvHandle       Handle of firmware volume in which to\r
                        search.\r
  @param FileHandle     Points to the current handle from which to\r
                        begin searching or NULL to start at the\r
                        beginning of the firmware volume. Updated\r
                        upon return to reflect the file found.\r
\r
  @retval EFI_SUCCESS   The file was found.\r
  @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.\r
\r
**/ \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE)( \r
  IN     CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This, \r
  IN     EFI_FV_FILETYPE                     SearchType, \r
  IN     EFI_PEI_FV_HANDLE                   FvHandle,\r
  IN OUT EFI_PEI_FILE_HANDLE                 *FileHandle \r
);\r
\r
\r
/**\r
  Find a file within a volume by its name. \r
  \r
  This service searches for files with a specific name, within\r
  either the specified firmware volume or all firmware volumes.\r
\r
  @param This                   Points to this instance of the\r
                                EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param FileName               A pointer to the name of the file to find\r
                                within the firmware volume.\r
  @param FvHandle               Upon entry, the pointer to the firmware\r
                                volume to search or NULL if all firmware\r
                                volumes should be searched. Upon exit, the\r
                                actual firmware volume in which the file was\r
                                found.\r
  @param FileHandle             Upon exit, points to the found file's\r
                                handle or NULL if it could not be found.\r
\r
  @retval EFI_SUCCESS           File was found.\r
  @retval EFI_NOT_FOUND         File was not found.\r
  @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or\r
                                FileName was NULL.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_FIND_FILE_NAME)(\r
  IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
  IN  CONST  EFI_GUID                    *FileName,\r
  IN  EFI_PEI_FV_HANDLE                  FvHandle,\r
  OUT EFI_PEI_FILE_HANDLE                *FileHandle\r
);\r
\r
\r
/**\r
  Returns information about a specific file.\r
\r
  This function returns information about a specific\r
  file, including its file name, type, attributes, starting\r
  address and size. \r
   \r
  @param This                     Points to this instance of the\r
                                  EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param FileHandle               Handle of the file.\r
  @param FileInfo                 Upon exit, points to the file's\r
                                  information.\r
\r
  @retval EFI_SUCCESS             File information returned.\r
  @retval EFI_INVALID_PARAMETER   If FileHandle does not\r
                                  represent a valid file.\r
  @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.\r
  \r
**/ \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_GET_FILE_INFO)(\r
  IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This, \r
  IN  EFI_PEI_FILE_HANDLE                 FileHandle, \r
  OUT EFI_FV_FILE_INFO                    *FileInfo\r
);\r
\r
/**\r
  This function returns information about the firmware volume.\r
  \r
  @param This                     Points to this instance of the\r
                                  EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param FvHandle                 Handle to the firmware handle.\r
  @param VolumeInfo               Points to the returned firmware volume\r
                                  information.\r
\r
  @retval EFI_SUCCESS             Information returned successfully.\r
  @retval EFI_INVALID_PARAMETER   FvHandle does not indicate a valid\r
                                  firmware volume or VolumeInfo is NULL.\r
\r
**/ \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_GET_INFO)(\r
  IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI   *This, \r
  IN  EFI_PEI_FV_HANDLE                    FvHandle, \r
  OUT EFI_FV_INFO                          *VolumeInfo\r
);\r
\r
/**\r
  Find the next matching section in the firmware file.\r
  \r
  This service enables PEI modules to discover sections\r
  of a given type within a valid file.\r
  \r
  @param This             Points to this instance of the\r
                          EFI_PEI_FIRMWARE_VOLUME_PPI.\r
  @param SearchType       A filter to find only sections of this\r
                          type.\r
  @param FileHandle       Handle of firmware file in which to\r
                          search.\r
  @param SectionData      Updated upon  return to point to the\r
                          section found.\r
  \r
  @retval EFI_SUCCESS     Section was found.\r
  @retval EFI_NOT_FOUND   Section of the specified type was not\r
                          found. SectionData contains NULL.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FV_FIND_SECTION)(\r
  IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI    *This,\r
  IN  EFI_SECTION_TYPE                     SearchType,\r
  IN  EFI_PEI_FILE_HANDLE                  FileHandle,\r
  OUT VOID                                 **SectionData\r
);\r
\r
///\r
/// This PPI provides functions for accessing a memory-mapped firmware volume of a specific format.\r
///\r
struct _EFI_PEI_FIRMWARE_VOLUME_PPI {\r
  ///\r
  /// Process a firmware volume and create a volume handle.\r
  ///\r
  EFI_PEI_FV_PROCESS_FV       ProcessVolume;\r
  ///\r
  /// Find all files of a specific type.\r
  ///\r
  EFI_PEI_FV_FIND_FILE_TYPE   FindFileByType;\r
  ///\r
  /// Find the file with a specific name.\r
  ///\r
  EFI_PEI_FV_FIND_FILE_NAME   FindFileByName;\r
  ///\r
  /// Return the information about a specific file.\r
  ///\r
  EFI_PEI_FV_GET_FILE_INFO    GetFileInfo;\r
  ///\r
  /// Return the firmware volume attributes.\r
  ///\r
  EFI_PEI_FV_GET_INFO         GetVolumeInfo;\r
  ///\r
  /// Find all sections of a specific type.\r
  ///\r
  EFI_PEI_FV_FIND_SECTION     FindSectionByType;\r
};\r
\r
extern EFI_GUID gEfiPeiFirmwareVolumePpiGuid;\r
\r
#endif \r
Commit	Line	Data
	1	/** @file\r
	2	This file provides functions for accessing a memory-mapped firmware volume of a specific format.\r
	3	\r
	4	Copyright (c) 2006 - 2007, Intel Corporation \r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
	13	@par Revision Reference:\r
	14	This PPI is defined in PI.\r
	15	Version 1.00\r
	16	\r
	17	**/\r
	18	\r
	19	#ifndef __FIRMWARE_VOLUME_PPI_H__\r
	20	#define __FIRMWARE_VOLUME_PPI_H__\r
	21	\r
	22	///\r
	23	/// The GUID for this PPI is the same as the firmware volume format GUID.\r
	24	/// The FV format can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined\r
	25	/// format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.\r
	26	/// \r
	27	typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI EFI_PEI_FIRMWARE_VOLUME_PPI;\r
	28	\r
	29	\r
	30	/**\r
	31	Process a firmware volume and create a volume handle.\r
	32	\r
	33	Create a volume handle from the information in the buffer. For\r
	34	memory-mapped firmware volumes, Buffer and BufferSize refer to\r
	35	the start of the firmware volume and the firmware volume size.\r
	36	For non memory-mapped firmware volumes, this points to a\r
	37	buffer which contains the necessary information for creating\r
	38	the firmware volume handle. Normally, these values are derived\r
	39	from the EFI_FIRMWARE_VOLUME_INFO_PPI.\r
	40	\r
	41	\r
	42	@param This Points to this instance of the\r
	43	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	44	@param Buffer Points to the start of the buffer.\r
	45	@param BufferSize Size of the buffer.\r
	46	@param FvHandle Points to the returned firmware volume\r
	47	handle. The firmware volume handle must\r
	48	be unique within the system. \r
	49	\r
	50	@retval EFI_SUCCESS Firmware volume handle created.\r
	51	@retval EFI_VOLUME_CORRUPTED Volume was corrupt.\r
	52	\r
	53	**/\r
	54	typedef\r
	55	EFI_STATUS\r
	56	(EFIAPI *EFI_PEI_FV_PROCESS_FV)(\r
	57	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
	58	IN VOID *Buffer,\r
	59	IN UINTN BufferSize,\r
	60	OUT EFI_PEI_FV_HANDLE *FvHandle\r
	61	);\r
	62	\r
	63	/**\r
	64	Finds the next file of the specified type.\r
	65	\r
	66	This service enables PEI modules to discover additional firmware files. \r
	67	The FileHandle must be unique within the system.\r
	68	\r
	69	@param This Points to this instance of the\r
	70	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	71	@param SearchType A filter to find only files of this type. Type\r
	72	EFI_FV_FILETYPE_ALL causes no filtering to be\r
	73	done.\r
	74	@param FvHandle Handle of firmware volume in which to\r
	75	search.\r
	76	@param FileHandle Points to the current handle from which to\r
	77	begin searching or NULL to start at the\r
	78	beginning of the firmware volume. Updated\r
	79	upon return to reflect the file found.\r
	80	\r
	81	@retval EFI_SUCCESS The file was found.\r
	82	@retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.\r
	83	\r
	84	**/ \r
	85	typedef\r
	86	EFI_STATUS\r
	87	(EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE)( \r
	88	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, \r
	89	IN EFI_FV_FILETYPE SearchType, \r
	90	IN EFI_PEI_FV_HANDLE FvHandle,\r
	91	IN OUT EFI_PEI_FILE_HANDLE *FileHandle \r
	92	);\r
	93	\r
	94	\r
	95	/**\r
	96	Find a file within a volume by its name. \r
	97	\r
	98	This service searches for files with a specific name, within\r
	99	either the specified firmware volume or all firmware volumes.\r
	100	\r
	101	@param This Points to this instance of the\r
	102	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	103	@param FileName A pointer to the name of the file to find\r
	104	within the firmware volume.\r
	105	@param FvHandle Upon entry, the pointer to the firmware\r
	106	volume to search or NULL if all firmware\r
	107	volumes should be searched. Upon exit, the\r
	108	actual firmware volume in which the file was\r
	109	found.\r
	110	@param FileHandle Upon exit, points to the found file's\r
	111	handle or NULL if it could not be found.\r
	112	\r
	113	@retval EFI_SUCCESS File was found.\r
	114	@retval EFI_NOT_FOUND File was not found.\r
	115	@retval EFI_INVALID_PARAMETER FvHandle or FileHandle or\r
	116	FileName was NULL.\r
	117	\r
	118	\r
	119	**/\r
	120	typedef\r
	121	EFI_STATUS\r
	122	(EFIAPI *EFI_PEI_FV_FIND_FILE_NAME)(\r
	123	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
	124	IN CONST EFI_GUID *FileName,\r
	125	IN EFI_PEI_FV_HANDLE FvHandle,\r
	126	OUT EFI_PEI_FILE_HANDLE *FileHandle\r
	127	);\r
	128	\r
	129	\r
	130	/**\r
	131	Returns information about a specific file.\r
	132	\r
	133	This function returns information about a specific\r
	134	file, including its file name, type, attributes, starting\r
	135	address and size. \r
	136	\r
	137	@param This Points to this instance of the\r
	138	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	139	@param FileHandle Handle of the file.\r
	140	@param FileInfo Upon exit, points to the file's\r
	141	information.\r
	142	\r
	143	@retval EFI_SUCCESS File information returned.\r
	144	@retval EFI_INVALID_PARAMETER If FileHandle does not\r
	145	represent a valid file.\r
	146	@retval EFI_INVALID_PARAMETER If FileInfo is NULL.\r
	147	\r
	148	**/ \r
	149	typedef\r
	150	EFI_STATUS\r
	151	(EFIAPI *EFI_PEI_FV_GET_FILE_INFO)(\r
	152	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, \r
	153	IN EFI_PEI_FILE_HANDLE FileHandle, \r
	154	OUT EFI_FV_FILE_INFO *FileInfo\r
	155	);\r
	156	\r
	157	/**\r
	158	This function returns information about the firmware volume.\r
	159	\r
	160	@param This Points to this instance of the\r
	161	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	162	@param FvHandle Handle to the firmware handle.\r
	163	@param VolumeInfo Points to the returned firmware volume\r
	164	information.\r
	165	\r
	166	@retval EFI_SUCCESS Information returned successfully.\r
	167	@retval EFI_INVALID_PARAMETER FvHandle does not indicate a valid\r
	168	firmware volume or VolumeInfo is NULL.\r
	169	\r
	170	**/ \r
	171	typedef\r
	172	EFI_STATUS\r
	173	(EFIAPI *EFI_PEI_FV_GET_INFO)(\r
	174	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, \r
	175	IN EFI_PEI_FV_HANDLE FvHandle, \r
	176	OUT EFI_FV_INFO *VolumeInfo\r
	177	);\r
	178	\r
	179	/**\r
	180	Find the next matching section in the firmware file.\r
	181	\r
	182	This service enables PEI modules to discover sections\r
	183	of a given type within a valid file.\r
	184	\r
	185	@param This Points to this instance of the\r
	186	EFI_PEI_FIRMWARE_VOLUME_PPI.\r
	187	@param SearchType A filter to find only sections of this\r
	188	type.\r
	189	@param FileHandle Handle of firmware file in which to\r
	190	search.\r
	191	@param SectionData Updated upon return to point to the\r
	192	section found.\r
	193	\r
	194	@retval EFI_SUCCESS Section was found.\r
	195	@retval EFI_NOT_FOUND Section of the specified type was not\r
	196	found. SectionData contains NULL.\r
	197	**/\r
	198	typedef\r
	199	EFI_STATUS\r
	200	(EFIAPI *EFI_PEI_FV_FIND_SECTION)(\r
	201	IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
	202	IN EFI_SECTION_TYPE SearchType,\r
	203	IN EFI_PEI_FILE_HANDLE FileHandle,\r
	204	OUT VOID **SectionData\r
	205	);\r
	206	\r
	207	///\r
	208	/// This PPI provides functions for accessing a memory-mapped firmware volume of a specific format.\r
	209	///\r
	210	struct _EFI_PEI_FIRMWARE_VOLUME_PPI {\r
	211	///\r
	212	/// Process a firmware volume and create a volume handle.\r
	213	///\r
	214	EFI_PEI_FV_PROCESS_FV ProcessVolume;\r
	215	///\r
	216	/// Find all files of a specific type.\r
	217	///\r
	218	EFI_PEI_FV_FIND_FILE_TYPE FindFileByType;\r
	219	///\r
	220	/// Find the file with a specific name.\r
	221	///\r
	222	EFI_PEI_FV_FIND_FILE_NAME FindFileByName;\r
	223	///\r
	224	/// Return the information about a specific file.\r
	225	///\r
	226	EFI_PEI_FV_GET_FILE_INFO GetFileInfo;\r
	227	///\r
	228	/// Return the firmware volume attributes.\r
	229	///\r
	230	EFI_PEI_FV_GET_INFO GetVolumeInfo;\r
	231	///\r
	232	/// Find all sections of a specific type.\r
	233	///\r
	234	EFI_PEI_FV_FIND_SECTION FindSectionByType;\r
	235	};\r
	236	\r
	237	extern EFI_GUID gEfiPeiFirmwareVolumePpiGuid;\r
	238	\r
	239	#endif \r