\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 any Firmware Volumes in the system.\r
- \r
- The function will read the first Firmware Section sepcifed by NameGuid, SectionType and Instance by searching\r
- for all Firmware Volumes 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
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
+\r
+ PiLibGetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function\r
+ will search the first file with the specified name in all firmware volumes in the system. The search order for firmware \r
+ volumes in the system is determistic but abitrary if no new firmware volume is added into the system between \r
+ each calls of this function. \r
+\r
+ After the specific file is located, the function searches the specifc firmware section with type SectionType in this file. \r
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () \r
+ found in PI Specification.\r
+\r
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
+ is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
+ 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 Pointer to an EFI_GUID, which indicates the file name from which the requested \r
+ section will be read. Type EFI_GUID is defined in \r
+ InstallProtocolInterface() in the UEFI 2.0 specification. \r
+ @param SectionType Indicates the section type to return. SectionType in conjunction with \r
+ SectionInstance indicates which section to return. Type \r
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
+ SectionType in conjunction with SectionInstance indicates which section to \r
+ return. SectionInstance is zero based.\r
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
+ including the section header. Caller is responsible to free this memory.\r
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
+ *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
EFI_STATUS\r
EFIAPI\r
PiLibGetSectionFromAnyFv (\r
IN CONST EFI_GUID *NameGuid,\r
IN EFI_SECTION_TYPE SectionType,\r
- IN UINTN Instance,\r
+ IN UINTN SectionInstance,\r
OUT VOID **Buffer,\r
OUT UINTN *Size\r
- )\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
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
+\r
+ PiLibGetSectionFromCurrentFv () is used to read a specific section from a file within the same firmware volume from which\r
+ the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType. \r
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () \r
+ found in PI Specification.\r
+\r
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
+ is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
+ 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 NameGuid is NULL, then ASSERT();\r
+ If Buffer is NULL, then ASSERT();\r
+ If Size is NULL, then ASSERT().\r
+\r
+ @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested \r
+ section will be read. Type EFI_GUID is defined in \r
+ InstallProtocolInterface() in the UEFI 2.0 specification. \r
+ @param SectionType Indicates the section type to return. SectionType in conjunction with \r
+ SectionInstance indicates which section to return. Type \r
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
+ SectionType in conjunction with SectionInstance indicates which section to \r
+ return. SectionInstance is zero based.\r
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
+ including the section header. Caller is responsible to free this memory.\r
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
+ *Buffer.\r
+\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
+**/\r
EFI_STATUS\r
EFIAPI\r
PiLibGetSectionFromCurrentFv (\r
IN CONST EFI_GUID *NameGuid,\r
IN EFI_SECTION_TYPE SectionType,\r
- IN UINTN Instance,\r
+ IN UINTN SectionInstance,\r
OUT VOID **Buffer,\r
OUT UINTN *Size\r
- )\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
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
+\r
+ PiLibGetSectionFromCurrentFfs () searches the specifc firmware section with type SectionType in the same firmware file from\r
+ which the running image is loaded. The details of this search order is defined in description of \r
+ EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.\r
+\r
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
+ is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
+ is returned.\r
+\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 Buffer is NULL, then ASSERT();\r
+ If Size is NULL, then ASSERT().\r
+\r
+ @param SectionType Indicates the section type to return. SectionType in conjunction with \r
+ SectionInstance indicates which section to return. Type \r
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
+ SectionType in conjunction with SectionInstance indicates which section to \r
+ return. SectionInstance is zero based.\r
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
+ including the section header. Caller is responsible to free this memory.\r
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
+ *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
- @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
+**/\r
EFI_STATUS\r
EFIAPI\r
PiLibGetSectionFromCurrentFfs (\r
IN EFI_SECTION_TYPE SectionType,\r
- IN UINTN Instance,\r
+ IN UINTN SectionInstance,\r
OUT VOID **Buffer,\r
OUT UINTN *Size\r
- )\r
-;\r
+ );\r
\r
#endif\r
\r
projects / mirror_edk2.git / blobdiff