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