[mirror_edk2.git] / MdePkg / Include / Library / PiLib.h

/** @file\r
  MDE PI library functions and macros\r
\r
  Copyright (c) 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
**/\r
\r
#ifndef __PI_LIB_H__\r
#define __PI_LIB_H__\r
\r
#include <Pi/PiFirmwareFile.h>\r
\r
/**\r
  Allocate and fill a buffer with an image identified by a Firmware File GUID name and a Firmware Section type. \r
  The Firmware Volumes to search for the Firmware File can be specified to be either all Firmware Volumes \r
  in the system, or the Firmware Volume which contains the Firmware File specified by an image handle.\r
\r
  If ImageHandle is NULL, all Firmware Volumes in the system will be searched. If ImageHandle is not NULL, \r
  ImageHandle is interpreted as EFI_PEI_FILE_HANDLE for the implementation of this function for PEI phase. \r
  The input parameter ImageHandle is interpreted as EFI_HANDLE, on which an EFI_LOADED_IMAGE_PROTOCOL \r
  is installed, for the implementation of this function for DXE phase. The search always starts from the FV \r
  identified by ImageHandle. If WithinImageFv is TRUE, search will only be performed on the first FV. If WithinImageFv \r
  is FALSE, search will continue on other FVs if it fails on the first FV. The search order of Firmware Volumes is \r
  deterministic but arbitrary if no new firmware volume is added into the system between each search. \r
  \r
  The search order for the section type specified by SectionType in the Firmware File is using a depth-first \r
  and left-to-right algorithm through all sections. The first section found to match SectionType will be returned. \r
  \r
  If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type \r
  to read Firmware Section data from the Firmware File. If no such section exists, the function will try \r
  to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
  \r
  If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
  data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
  read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware \r
  File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
  \r
  The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
  by this function. This function can only be called at TPL_NOTIFY and below.\r
  \r
  If ImageHandle is NULL and WithinImage is TRUE, then ASSERT ();\r
  If NameGuid is NULL, then ASSERT();\r
  If Buffer is NULL, then ASSERT();\r
  If Size is NULL, then ASSERT().\r
\r
  @param  NameGuid             The GUID name of a Firmware File.\r
  @param  SectionType         The Firmware Section type.\r
  @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.\r
  @param  Size                    On output, the size of Buffer.\r
\r
  @retval  EFI_SUCCESS	      The image is found and data and size is returned.\r
  @retval  EFI_NOT_FOUND	    The image specified by NameGuid and SectionType can't be found.\r
  @retval  EFI_OUT_OF_RESOURCES	There were not enough resources to allocate the output data buffer or complete the operations.\r
  @retval  EFI_DEVICE_ERROR	A hardware error occurs during reading from the Firmware Volume.\r
  @retval  EFI_ACCESS_DENIED	The firmware volume containing the searched Firmware File is configured to disallow reads.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
GetSectionFromFvFile (\r
  IN  CONST VOID*        ImageHandle OPTIONAL,\r
  IN  CONST EFI_GUID     *NameGuid,\r
  IN  EFI_SECTION_TYPE   SectionType,\r
  OUT VOID               **Buffer,\r
  OUT UINTN              *Size,\r
  IN  BOOLEAN            WithImageFv\r
  )\r
;\r
\r
/**\r
  Identify the device handle from which the Image is loaded from. As this device handle is passed to\r
  GetSectionFromFv as the identifier for a Firmware Volume, an EFI_FIRMWARE_VOLUME2_PROTOCOL \r
  protocol instance should be located succesfully by calling gBS->HandleProtocol ().\r
\r
  This function locates the EFI_LOADED_IMAGE_PROTOCOL instance installed\r
  on ImageHandle. It then returns EFI_LOADED_IMAGE_PROTOCOL.DeviceHandle.\r
  \r
  If ImageHandle is NULL, then ASSERT ();\r
  If failed to locate a EFI_LOADED_IMAGE_PROTOCOL on ImageHandle, then ASSERT ();\r
  \r
  @param  ImageHandle         The firmware allocated handle for UEFI image.\r
\r
  @retval  EFI_HANDLE	        The device handle from which the Image is loaded from.\r
\r
**/\r
\r
EFI_HANDLE\r
EFIAPI\r
ImageHandleToFvHandle (\r
  EFI_HANDLE ImageHandle\r
  )\r
;\r
\r
/**\r
    Allocate and fill a buffer from the Firmware Section identified by a Firmware File GUID name and a Firmware \r
    Section type and instance number from the any Firmware Volumes in the system.\r
  \r
    The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the \r
    any Firmware Volume in the system. \r
\r
    The search order for Firmware Volumes in the system is determistic but abitrary if no new Firmware Volume is installed\r
    into the system. The search order for the section specified by SectionType within a Firmware File is defined by\r
    EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
    Shared Architectural Elements for detailes.\r
    \r
    If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
    data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
    read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
    EFI_NOT_FOUND is returned.\r
\r
    The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
    by this function. This function can only be called at TPL_NOTIFY and below.\r
    \r
    If NameGuid is NULL, then ASSERT();\r
    If Buffer is NULL, then ASSERT();\r
    If Size is NULL, then ASSERT().\r
  \r
    @param  NameGuid             The GUID name of a Firmware File.\r
    @param  SectionType         The Firmware Section type.\r
    @param  Instance              The instance number of Firmware Section to read from starting from 0.\r
    @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.\r
    @param  Size                    On output, the size of Buffer.\r
  \r
    @retval  EFI_SUCCESS        The image is found and data and size is returned.\r
    @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.\r
    @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
    @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
    @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.\r
  \r
  **/\r
\r
EFI_STATUS\r
EFIAPI\r
GetSectionFromAnyFv (\r
  IN  CONST EFI_GUID                *NameGuid,\r
  IN  EFI_SECTION_TYPE              SectionType,\r
  IN  UINTN                         Instance,\r
  OUT VOID                          **Buffer,\r
  OUT UINTN                         *Size\r
  )\r
;\r
\r
/**\r
    Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
    Section type and instance number from the specified Firmware Volume.\r
  \r
    This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to \r
    carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed \r
    by NameGuid, SectionType and Instance. \r
    \r
    The search order for the section specified by SectionType within a Firmware File is defined by\r
    EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
    Shared Architectural Elements for detailes.\r
    \r
    If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
    data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
    read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
    EFI_NOT_FOUND is returned.\r
    \r
    The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
    by this function. This function can be only called at TPL_NOTIFY and below.\r
    \r
    If FvHandle is NULL, then ASSERT ();\r
    If NameGuid is NULL, then ASSERT();\r
    If Buffer is NULL, then ASSERT();\r
    If Size is NULL, then ASSERT().\r
\r
    @param  FvHandle              The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
    @param  NameGuid             The GUID name of a Firmware File.\r
    @param  SectionType         The Firmware Section type.\r
    @param  Instance              The instance number of Firmware Section to read from starting from 0.\r
    @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.\r
    @param  Size                    On output, the size of Buffer.\r
  \r
    @retval  EFI_SUCCESS        The image is found and data and size is returned.\r
    @retval  EFI_UNSUPPORTED   FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
    @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.\r
    @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
    @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
    @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.\r
  \r
  **/\r
\r
EFI_STATUS\r
EFIAPI\r
GetSectionFromFv (\r
  IN  EFI_HANDLE                    FvHandle,\r
  IN  CONST EFI_GUID                *NameGuid,\r
  IN  EFI_SECTION_TYPE              SectionType,\r
  IN  UINTN                         Instance,\r
  OUT VOID                          **Buffer,\r
  OUT UINTN                         *Size\r
  )\r
;\r
\r
/**\r
    Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
    Section type and instance number from the same Firmware Volume with the caller's FFS.\r
  \r
    This functions first locates the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance for same Firmrware Volume\r
    which also contains the FFS of the caller in order to carry out the Firmware Volume read operation. \r
    The function then reads the Firmware Section found sepcifed by NameGuid, SectionType and Instance. \r
    \r
    The search order for the section specified by SectionType within a Firmware File is defined by\r
    EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
    Shared Architectural Elements for detailes.\r
    \r
    If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
    data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
    read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
    EFI_NOT_FOUND is returned.\r
    \r
    The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
    by this function. This function can be only called at TPL_NOTIFY and below.\r
    \r
    If FvHandle is NULL, then ASSERT ();\r
    If NameGuid is NULL, then ASSERT();\r
    If Buffer is NULL, then ASSERT();\r
    If Size is NULL, then ASSERT().\r
\r
    @param  NameGuid             The GUID name of a Firmware File.\r
    @param  SectionType         The Firmware Section type.\r
    @param  Instance              The instance number of Firmware Section to read from starting from 0.\r
    @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.\r
    @param  Size                    On output, the size of Buffer.\r
  \r
    @retval  EFI_SUCCESS        The image is found and data and size is returned.\r
    @retval  EFI_UNSUPPORTED   FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
    @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.\r
    @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
    @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
    @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.\r
  \r
  **/\r
\r
EFI_STATUS\r
EFIAPI\r
GetSectionFromCurrentFv (\r
  IN  CONST EFI_GUID                *NameGuid,\r
  IN  EFI_SECTION_TYPE              SectionType,\r
  IN  UINTN                         Instance,\r
  OUT VOID                          **Buffer,\r
  OUT UINTN                         *Size\r
  )\r
;\r
\r
\r
/**\r
    Allocate and fill a buffer from the first Firmware Section in the same Firmware File as the caller of this function.\r
  \r
    The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the \r
    Firmware Volume specified by FvHandle. On this FvHandle, an EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance \r
    should be located succesfully in order to carry out the Firmware Volume operations.\r
    \r
    The search order for the section type specified by SectionType in the Firmware File is using a depth-first \r
    and left-to-right algorithm through all sections. The first section found to match SectionType will be returned. \r
    \r
    If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type \r
    to read Firmware Section data from the Firmware File. If no such section exists, the function will try \r
    to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
    \r
    If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
    data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
    read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware \r
    File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
    \r
    The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
    by this function. This function can only be called at TPL_NOTIFY and below.\r
    \r
    If FvHandle is NULL and WithinImage is TRUE, then ASSERT ();\r
    If NameGuid is NULL, then ASSERT();\r
    If Buffer is NULL, then ASSERT();\r
    If Size is NULL, then ASSERT().\r
  \r
    @param  NameGuid             The GUID name of a Firmware File.\r
    @param  SectionType         The Firmware Section type.\r
    @param  Buffer                  On output, Buffer contains the the data read from the section in the Firmware File found.\r
    @param  Size                    On output, the size of Buffer.\r
  \r
    @retval  EFI_SUCCESS        The image is found and data and size is returned.\r
    @retval  EFI_NOT_FOUND      The image specified by NameGuid and SectionType can't be found.\r
    @retval  EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
    @retval  EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
    @retval  EFI_ACCESS_DENIED  The firmware volume containing the searched Firmware File is configured to disallow reads.\r
  \r
  **/\r
\r
EFI_STATUS\r
EFIAPI\r
GetSectionFromCurrentFfs (\r
  IN  EFI_SECTION_TYPE              SectionType,\r
  IN  UINTN                         Instance,\r
  OUT VOID                          **Buffer,\r
  OUT UINTN                         *Size\r
  )\r
;\r
\r
#endif\r
\r
Commit	Line	Data
1c280088	1	/** @file\r
	2	MDE PI library functions and macros\r
	3	\r
	4	Copyright (c) 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	**/\r
	14	\r
	15	#ifndef __PI_LIB_H__\r
	16	#define __PI_LIB_H__\r
	17	\r
	18	#include <Pi/PiFirmwareFile.h>\r
	19	\r
	20	/**\r
	21	Allocate and fill a buffer with an image identified by a Firmware File GUID name and a Firmware Section type. \r
	22	The Firmware Volumes to search for the Firmware File can be specified to be either all Firmware Volumes \r
	23	in the system, or the Firmware Volume which contains the Firmware File specified by an image handle.\r
	24	\r
	25	If ImageHandle is NULL, all Firmware Volumes in the system will be searched. If ImageHandle is not NULL, \r
	26	ImageHandle is interpreted as EFI_PEI_FILE_HANDLE for the implementation of this function for PEI phase. \r
	27	The input parameter ImageHandle is interpreted as EFI_HANDLE, on which an EFI_LOADED_IMAGE_PROTOCOL \r
	28	is installed, for the implementation of this function for DXE phase. The search always starts from the FV \r
	29	identified by ImageHandle. If WithinImageFv is TRUE, search will only be performed on the first FV. If WithinImageFv \r
	30	is FALSE, search will continue on other FVs if it fails on the first FV. The search order of Firmware Volumes is \r
	31	deterministic but arbitrary if no new firmware volume is added into the system between each search. \r
	32	\r
	33	The search order for the section type specified by SectionType in the Firmware File is using a depth-first \r
	34	and left-to-right algorithm through all sections. The first section found to match SectionType will be returned. \r
	35	\r
	36	If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type \r
	37	to read Firmware Section data from the Firmware File. If no such section exists, the function will try \r
	38	to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
	39	\r
	40	If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
	41	data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
	42	read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware \r
	43	File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
	44	\r
	45	The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
	46	by this function. This function can only be called at TPL_NOTIFY and below.\r
	47	\r
	48	If ImageHandle is NULL and WithinImage is TRUE, then ASSERT ();\r
	49	If NameGuid is NULL, then ASSERT();\r
	50	If Buffer is NULL, then ASSERT();\r
	51	If Size is NULL, then ASSERT().\r
	52	\r
	53	@param NameGuid The GUID name of a Firmware File.\r
	54	@param SectionType The Firmware Section type.\r
	55	@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
	56	@param Size On output, the size of Buffer.\r
	57	\r
	58	@retval EFI_SUCCESS The image is found and data and size is returned.\r
	59	@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
	60	@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
	61	@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
	62	@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
	63	\r
	64	**/\r
65	\r
66	EFI_STATUS\r
67	EFIAPI\r
68	GetSectionFromFvFile (\r
69	IN CONST VOID* ImageHandle OPTIONAL,\r
70	IN CONST EFI_GUID *NameGuid,\r
71	IN EFI_SECTION_TYPE SectionType,\r
72	OUT VOID **Buffer,\r
73	OUT UINTN *Size,\r
74	IN BOOLEAN WithImageFv\r
75	)\r
76	;\r
77	\r
b0d803fe	78	/**\r
	79	Identify the device handle from which the Image is loaded from. As this device handle is passed to\r
	80	GetSectionFromFv as the identifier for a Firmware Volume, an EFI_FIRMWARE_VOLUME2_PROTOCOL \r
	81	protocol instance should be located succesfully by calling gBS->HandleProtocol ().\r
	82	\r
	83	This function locates the EFI_LOADED_IMAGE_PROTOCOL instance installed\r
	84	on ImageHandle. It then returns EFI_LOADED_IMAGE_PROTOCOL.DeviceHandle.\r
	85	\r
	86	If ImageHandle is NULL, then ASSERT ();\r
	87	If failed to locate a EFI_LOADED_IMAGE_PROTOCOL on ImageHandle, then ASSERT ();\r
	88	\r
	89	@param ImageHandle The firmware allocated handle for UEFI image.\r
	90	\r
	91	@retval EFI_HANDLE The device handle from which the Image is loaded from.\r
	92	\r
	93	**/\r
	94	\r
	95	EFI_HANDLE\r
	96	EFIAPI\r
	97	ImageHandleToFvHandle (\r
	98	EFI_HANDLE ImageHandle\r
	99	)\r
	100	;\r
	101	\r
	102	/**\r
	103	Allocate and fill a buffer from the Firmware Section identified by a Firmware File GUID name and a Firmware \r
	104	Section type and instance number from the any Firmware Volumes in the system.\r
	105	\r
	106	The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the \r
	107	any Firmware Volume in the system. \r
	108	\r
	109	The search order for Firmware Volumes in the system is determistic but abitrary if no new Firmware Volume is installed\r
	110	into the system. The search order for the section specified by SectionType within a Firmware File is defined by\r
	111	EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
	112	Shared Architectural Elements for detailes.\r
	113	\r
	114	If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
	115	data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
	116	read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
	117	EFI_NOT_FOUND is returned.\r
	118	\r
	119	The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
	120	by this function. This function can only be called at TPL_NOTIFY and below.\r
	121	\r
	122	If NameGuid is NULL, then ASSERT();\r
	123	If Buffer is NULL, then ASSERT();\r
	124	If Size is NULL, then ASSERT().\r
	125	\r
	126	@param NameGuid The GUID name of a Firmware File.\r
	127	@param SectionType The Firmware Section type.\r
	128	@param Instance The instance number of Firmware Section to read from starting from 0.\r
	129	@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
	130	@param Size On output, the size of Buffer.\r
	131	\r
	132	@retval EFI_SUCCESS The image is found and data and size is returned.\r
	133	@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
	134	@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
	135	@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
	136	@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
	137	\r
	138	**/\r
	139	\r
	140	EFI_STATUS\r
	141	EFIAPI\r
142	GetSectionFromAnyFv (\r
143	IN CONST EFI_GUID *NameGuid,\r
144	IN EFI_SECTION_TYPE SectionType,\r
145	IN UINTN Instance,\r
146	OUT VOID **Buffer,\r
147	OUT UINTN *Size\r
148	)\r
149	;\r
150	\r
151	/**\r
152	Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
153	Section type and instance number from the specified Firmware Volume.\r
154	\r
155	This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to \r
156	carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed \r
157	by NameGuid, SectionType and Instance. \r
158	\r
159	The search order for the section specified by SectionType within a Firmware File is defined by\r
160	EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
161	Shared Architectural Elements for detailes.\r
162	\r
163	If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
164	data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
165	read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
166	EFI_NOT_FOUND is returned.\r
167	\r
168	The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
169	by this function. This function can be only called at TPL_NOTIFY and below.\r
170	\r
171	If FvHandle is NULL, then ASSERT ();\r
172	If NameGuid is NULL, then ASSERT();\r
173	If Buffer is NULL, then ASSERT();\r
174	If Size is NULL, then ASSERT().\r
175	\r
176	@param FvHandle The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
177	@param NameGuid The GUID name of a Firmware File.\r
178	@param SectionType The Firmware Section type.\r
179	@param Instance The instance number of Firmware Section to read from starting from 0.\r
180	@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
181	@param Size On output, the size of Buffer.\r
182	\r
183	@retval EFI_SUCCESS The image is found and data and size is returned.\r
184	@retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
185	@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
186	@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
187	@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
188	@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
189	\r
190	**/\r
191	\r
192	EFI_STATUS\r
193	EFIAPI\r
194	GetSectionFromFv (\r
195	IN EFI_HANDLE FvHandle,\r
196	IN CONST EFI_GUID *NameGuid,\r
197	IN EFI_SECTION_TYPE SectionType,\r
198	IN UINTN Instance,\r
199	OUT VOID **Buffer,\r
200	OUT UINTN *Size\r
201	)\r
202	;\r
203	\r
204	/**\r
205	Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
206	Section type and instance number from the same Firmware Volume with the caller's FFS.\r
207	\r
208	This functions first locates the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance for same Firmrware Volume\r
209	which also contains the FFS of the caller in order to carry out the Firmware Volume read operation. \r
210	The function then reads the Firmware Section found sepcifed by NameGuid, SectionType and Instance. \r
211	\r
212	The search order for the section specified by SectionType within a Firmware File is defined by\r
213	EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization \r
214	Shared Architectural Elements for detailes.\r
215	\r
216	If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
217	data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
218	read Firmware Section data from the Firmware File. If no such section specified is found to match , \r
219	EFI_NOT_FOUND is returned.\r
220	\r
221	The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
222	by this function. This function can be only called at TPL_NOTIFY and below.\r
223	\r
224	If FvHandle is NULL, then ASSERT ();\r
225	If NameGuid is NULL, then ASSERT();\r
226	If Buffer is NULL, then ASSERT();\r
227	If Size is NULL, then ASSERT().\r
228	\r
229	@param NameGuid The GUID name of a Firmware File.\r
230	@param SectionType The Firmware Section type.\r
231	@param Instance The instance number of Firmware Section to read from starting from 0.\r
232	@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
233	@param Size On output, the size of Buffer.\r
234	\r
235	@retval EFI_SUCCESS The image is found and data and size is returned.\r
236	@retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
237	@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
238	@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
239	@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
240	@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
241	\r
242	**/\r
243	\r
244	EFI_STATUS\r
245	EFIAPI\r
246	GetSectionFromCurrentFv (\r
247	IN CONST EFI_GUID *NameGuid,\r
248	IN EFI_SECTION_TYPE SectionType,\r
249	IN UINTN Instance,\r
250	OUT VOID **Buffer,\r
251	OUT UINTN *Size\r
252	)\r
253	;\r
254	\r
255	\r
256	/**\r
257	Allocate and fill a buffer from the first Firmware Section in the same Firmware File as the caller of this function.\r
258	\r
259	The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the \r
260	Firmware Volume specified by FvHandle. On this FvHandle, an EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance \r
261	should be located succesfully in order to carry out the Firmware Volume operations.\r
262	\r
263	The search order for the section type specified by SectionType in the Firmware File is using a depth-first \r
264	and left-to-right algorithm through all sections. The first section found to match SectionType will be returned. \r
265	\r
266	If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type \r
267	to read Firmware Section data from the Firmware File. If no such section exists, the function will try \r
268	to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
269	\r
270	If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section \r
271	data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to \r
272	read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware \r
273	File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.\r
274	\r
275	The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
276	by this function. This function can only be called at TPL_NOTIFY and below.\r
277	\r
278	If FvHandle is NULL and WithinImage is TRUE, then ASSERT ();\r
279	If NameGuid is NULL, then ASSERT();\r
280	If Buffer is NULL, then ASSERT();\r
281	If Size is NULL, then ASSERT().\r
282	\r
283	@param NameGuid The GUID name of a Firmware File.\r
284	@param SectionType The Firmware Section type.\r
285	@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
286	@param Size On output, the size of Buffer.\r
287	\r
288	@retval EFI_SUCCESS The image is found and data and size is returned.\r
289	@retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
290	@retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
291	@retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
292	@retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
293	\r
294	**/\r
295	\r
296	EFI_STATUS\r
297	EFIAPI\r
298	GetSectionFromCurrentFfs (\r
299	IN EFI_SECTION_TYPE SectionType,\r
300	IN UINTN Instance,\r
301	OUT VOID **Buffer,\r
302	OUT UINTN *Size\r
303	)\r
304	;\r
1c280088	305	\r
	306	#endif\r
	307	\r