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