diff options
| author | qwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-08-22 09:09:24 +0000 |
|---|---|---|
| committer | qwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-08-22 09:09:24 +0000 |
| commit | ff197efbbcb6e61d8d5305ec564e46fa8e85a4ed (patch) | |
| tree | 04d00bcce8bc6006c9364ecccc961e2e20bc54a6 /MdePkg | |
| parent | 6812ef9feaa052ba669bccd43cd22238240d049d (diff) | |
| download | edk2-platforms-ff197efbbcb6e61d8d5305ec564e46fa8e85a4ed.tar.xz | |
1) Update comments for API in DxePiLib.h
2) Fix a bug that SectionInstance is not referenced in the function GetSectionFromFv
3) Some minor cleanup.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5711 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdePkg')
| -rw-r--r-- | MdePkg/Include/Library/DxePiLib.h | 225 | ||||
| -rw-r--r-- | MdePkg/Library/DxePiLib/DxePiLib.c | 305 |
2 files changed, 269 insertions, 261 deletions
diff --git a/MdePkg/Include/Library/DxePiLib.h b/MdePkg/Include/Library/DxePiLib.h index 16ede8147e..dd80da7a26 100644 --- a/MdePkg/Include/Library/DxePiLib.h +++ b/MdePkg/Include/Library/DxePiLib.h @@ -19,90 +19,100 @@ /**
- Allocate and fill a buffer from the Firmware Section identified by a Firmware File GUID name and a Firmware
- Section type and instance number from any Firmware Volumes in the system.
-
- The function will read the first Firmware Section sepcifed by NameGuid, SectionType and Instance by searching
- for all Firmware Volumes in the system.
-
- The search order for Firmware Volumes in the system is determistic but abitrary if no new Firmware Volume is installed
- into the system. The search order for the section specified by SectionType within a Firmware File is defined by
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization
- Shared Architectural Elements for detailes.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section specified is found to match ,
- EFI_NOT_FOUND is returned.
-
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can only be called at TPL_NOTIFY and below.
-
- If NameGuid is NULL, then ASSERT();
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Instance The instance number of Firmware Section to read from starting from 0.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
-
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function
+ will search the first file with the specified name in all firmware volumes in the system. The search order for firmware
+ volumes in the system is determistic but abitrary if no new firmware volume is added into the system between
+ each calls of this function.
+
+ After the specific file is located, the function searches the specifc firmware section with type SectionType in this file.
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
+ found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can only be called at TPL_NOTIFY and below.
+
+ If NameGuid is NULL, then ASSERT();
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
+ section will be read. Type EFI_GUID is defined in
+ InstallProtocolInterface() in the UEFI 2.0 specification.
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromAnyFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
;
/**
- Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware
- Section type and instance number from the same Firmware Volume with the caller's FFS.
-
- This functions first locates the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance for same Firmrware Volume
- which also contains the FFS of the caller in order to carry out the Firmware Volume read operation.
- The function then reads the Firmware Section found sepcifed by NameGuid, SectionType and Instance.
-
- The search order for the section specified by SectionType within a Firmware File is defined by
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization
- Shared Architectural Elements for detailes.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section specified is found to match ,
- EFI_NOT_FOUND is returned.
-
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can be only called at TPL_NOTIFY and below.
-
- If FvHandle is NULL, then ASSERT ();
- If NameGuid is NULL, then ASSERT();
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Instance The instance number of Firmware Section to read from starting from 0.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromCurrentFv () is used to read a specific section from a file within the same firmware volume from which
+ the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType.
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
+ found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can be only called at TPL_NOTIFY and below.
+
+ If NameGuid is NULL, then ASSERT();
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
+ section will be read. Type EFI_GUID is defined in
+ InstallProtocolInterface() in the UEFI 2.0 specification.
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
@@ -110,7 +120,7 @@ EFIAPI PiLibGetSectionFromCurrentFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
@@ -118,47 +128,46 @@ PiLibGetSectionFromCurrentFv ( /**
- Allocate and fill a buffer from the first Firmware Section in the same Firmware File as the caller of this function.
-
- The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the
- Firmware Volume specified by FvHandle. On this FvHandle, an EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance
- should be located succesfully in order to carry out the Firmware Volume operations.
-
- The search order for the section type specified by SectionType in the Firmware File is using a depth-first
- and left-to-right algorithm through all sections. The first section found to match SectionType will be returned.
-
- If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type
- to read Firmware Section data from the Firmware File. If no such section exists, the function will try
- to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware
- File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.
-
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can only be called at TPL_NOTIFY and below.
-
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param SectionType The Firmware Section type.
- @param Instance Instance number of a section.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromCurrentFfs () searches the specifc firmware section with type SectionType in the same firmware file from
+ which the running image is loaded. The details of this search order is defined in description of
+ EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can only be called at TPL_NOTIFY and below.
+
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromCurrentFfs (
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
diff --git a/MdePkg/Library/DxePiLib/DxePiLib.c b/MdePkg/Library/DxePiLib/DxePiLib.c index 9953095e7d..b192028880 100644 --- a/MdePkg/Library/DxePiLib/DxePiLib.c +++ b/MdePkg/Library/DxePiLib/DxePiLib.c @@ -65,16 +65,14 @@ InternalImageHandleToFvHandle ( This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to
carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed
- by NameGuid, SectionType and Instance.
+ by NameGuid, SectionType and SectionInstance.
- The search order for the section specified by SectionType within a Firmware File is defined by
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization
- Shared Architectural Elements for detailes.
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
+ found in PI Specification.
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section specified is found to match ,
- EFI_NOT_FOUND is returned.
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
by this function. This function can be only called at TPL_NOTIFY and below.
@@ -84,19 +82,19 @@ InternalImageHandleToFvHandle ( If Buffer is NULL, then ASSERT();
If Size is NULL, then ASSERT().
- @param FvHandle The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Instance The instance number of Firmware Section to read from starting from 0.
+ @param FvHandle The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
+ @param NameGuid The GUID name of a Firmware File.
+ @param SectionType The Firmware Section type.
+ @param SectionInstance The instance number of Firmware Section to read from starting from 0.
@param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
@param Size On output, the size of Buffer.
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
@@ -104,7 +102,7 @@ GetSectionFromFv ( IN EFI_HANDLE FvHandle,
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
@@ -133,7 +131,7 @@ GetSectionFromFv ( Fv,
NameGuid,
SectionType,
- 0,
+ SectionInstance,
Buffer,
Size,
&AuthenticationStatus
@@ -149,7 +147,7 @@ GetSectionFromFv ( Fv,
NameGuid,
EFI_SECTION_PE32,
- 0,
+ SectionInstance,
Buffer,
Size,
&AuthenticationStatus
@@ -162,48 +160,55 @@ GetSectionFromFv ( /**
- Allocate and fill a buffer from the Firmware Section identified by a Firmware File GUID name and a Firmware
- Section type and instance number from any Firmware Volumes in the system.
-
- The function will read the first Firmware Section sepcifed by NameGuid, SectionType and Instance by searching
- for all Firmware Volumes in the system.
-
- The search order for Firmware Volumes in the system is determistic but abitrary if no new Firmware Volume is installed
- into the system. The search order for the section specified by SectionType within a Firmware File is defined by
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization
- Shared Architectural Elements for detailes.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section specified is found to match ,
- EFI_NOT_FOUND is returned.
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function
+ will search the first file with the specified name in all firmware volumes in the system. The search order for firmware
+ volumes in the system is determistic but abitrary if no new firmware volume is added into the system between
+ each calls of this function.
+
+ After the specific file is located, the function searches the specifc firmware section with type SectionType in this file.
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
+ found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can only be called at TPL_NOTIFY and below.
+
+ If NameGuid is NULL, then ASSERT();
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
+ section will be read. Type EFI_GUID is defined in
+ InstallProtocolInterface() in the UEFI 2.0 specification.
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can only be called at TPL_NOTIFY and below.
-
- If NameGuid is NULL, then ASSERT();
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Instance The instance number of Firmware Section to read from starting from 0.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
-
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromAnyFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
@@ -213,7 +218,6 @@ PiLibGetSectionFromAnyFv ( UINTN HandleCount;
UINTN Index;
EFI_HANDLE FvHandle;
- EFI_TPL OldTpl;
//
// Search the FV that contain the caller's FFS first.
@@ -226,7 +230,7 @@ PiLibGetSectionFromAnyFv ( FvHandle,
NameGuid,
SectionType,
- Instance,
+ SectionInstance,
Buffer,
Size
);
@@ -234,8 +238,6 @@ PiLibGetSectionFromAnyFv ( return EFI_SUCCESS;
}
- OldTpl = gBS->RaiseTPL (TPL_NOTIFY);
-
HandleBuffer = NULL;
Status = gBS->LocateHandleBuffer (
ByProtocol,
@@ -248,26 +250,25 @@ PiLibGetSectionFromAnyFv ( goto Done;
}
- for (Index = 0; Index < HandleCount; ++Index) {
+ for (Index = 0; Index < HandleCount; Index++) {
//
// Skip the FV that contain the caller's FFS
//
- if (HandleBuffer[Index] == FvHandle) {
- continue;
+ if (HandleBuffer[Index] != FvHandle) {
+ Status = GetSectionFromFv (
+ HandleBuffer[Index],
+ NameGuid,
+ SectionType,
+ SectionInstance,
+ Buffer,
+ Size
+ );
+
+ if (!EFI_ERROR (Status)) {
+ goto Done;
+ }
}
- Status = GetSectionFromFv (
- HandleBuffer[Index],
- NameGuid,
- SectionType,
- Instance,
- Buffer,
- Size
- );
-
- if (!EFI_ERROR (Status)) {
- goto Done;
- }
}
if (Index == HandleCount) {
@@ -276,8 +277,6 @@ PiLibGetSectionFromAnyFv ( Done:
- gBS->RestoreTPL (OldTpl);
-
if (HandleBuffer != NULL) {
FreePool(HandleBuffer);
}
@@ -286,42 +285,45 @@ Done: }
/**
- Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware
- Section type and instance number from the same Firmware Volume with the caller's FFS.
-
- This functions first locates the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance for same Firmrware Volume
- which also contains the FFS of the caller in order to carry out the Firmware Volume read operation.
- The function then reads the Firmware Section found sepcifed by NameGuid, SectionType and Instance.
-
- The search order for the section specified by SectionType within a Firmware File is defined by
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection (). Please check Section 2.4 of Volume 3: Platform Initialization
- Shared Architectural Elements for detailes.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section specified is found to match ,
- EFI_NOT_FOUND is returned.
-
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can be only called at TPL_NOTIFY and below.
-
- If FvHandle is NULL, then ASSERT ();
- If NameGuid is NULL, then ASSERT();
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Instance The instance number of Firmware Section to read from starting from 0.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromCurrentFv () is used to read a specific section from a file within the same firmware volume from which
+ the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType.
+ The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection ()
+ found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can be only called at TPL_NOTIFY and below.
+
+ If NameGuid is NULL, then ASSERT();
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested
+ section will be read. Type EFI_GUID is defined in
+ InstallProtocolInterface() in the UEFI 2.0 specification.
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
@@ -329,7 +331,7 @@ EFIAPI PiLibGetSectionFromCurrentFv (
IN CONST EFI_GUID *NameGuid,
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
@@ -338,7 +340,7 @@ PiLibGetSectionFromCurrentFv ( InternalImageHandleToFvHandle(gImageHandle),
NameGuid,
SectionType,
- Instance,
+ SectionInstance,
Buffer,
Size
);
@@ -346,49 +348,46 @@ PiLibGetSectionFromCurrentFv ( /**
- Allocate and fill a buffer from the first Firmware Section in the same Firmware File as the caller of this function.
-
- The function will read the first Firmware Section found sepcifed by NameGuid and SectionType from the
- Firmware Volume specified by FvHandle. On this FvHandle, an EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance
- should be located succesfully in order to carry out the Firmware Volume operations.
-
- The search order for the section type specified by SectionType in the Firmware File is using a depth-first
- and left-to-right algorithm through all sections. The first section found to match SectionType will be returned.
-
- If SectionType is EFI_SECTION_PE32, EFI_SECTION_PE32 will be used as Firmware Section type
- to read Firmware Section data from the Firmware File. If no such section exists, the function will try
- to read a Firmware File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.
-
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE will be used as Firmware Section type to read Firmware Section
- data from the Firmware File. If no such section exists, EFI_SECTION_PE32 will be used as Firmware Section type to
- read Firmware Section data from the Firmware File. If no such section exists, the function will try to read a Firmware
- File named with NameGuid. If no such file exists, EFI_NOT_FOUND is returned.
-
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
- by this function. This function can only be called at TPL_NOTIFY and below.
-
- If FvHandle is NULL and WithinImage is TRUE, then ASSERT ();
- If NameGuid is NULL, then ASSERT();
- If Buffer is NULL, then ASSERT();
- If Size is NULL, then ASSERT().
-
- @param NameGuid The GUID name of a Firmware File.
- @param SectionType The Firmware Section type.
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.
- @param Size On output, the size of Buffer.
-
- @retval EFI_SUCCESS The image is found and data and size is returned.
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
+ Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
+
+ PiLibGetSectionFromCurrentFfs () searches the specifc firmware section with type SectionType in the same firmware file from
+ which the running image is loaded. The details of this search order is defined in description of
+ EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.
+
+ If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section
+ 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
+ is returned.
+
+
+ The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated
+ by this function. This function can only be called at TPL_NOTIFY and below.
+
+ If Buffer is NULL, then ASSERT();
+ If Size is NULL, then ASSERT().
+
+ @param SectionType Indicates the section type to return. SectionType in conjunction with
+ SectionInstance indicates which section to return. Type
+ EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.
+ @param SectionInstance Indicates which instance of sections with a type of SectionType to return.
+ SectionType in conjunction with SectionInstance indicates which section to
+ return. SectionInstance is zero based.
+ @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not
+ including the section header. Caller is responsible to free this memory.
+ @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by
+ *Buffer.
+
+ @retval EFI_SUCCESS The image is found and data and size is returned.
+ @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.
+ @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.
+ @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.
+ @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.
**/
EFI_STATUS
EFIAPI
PiLibGetSectionFromCurrentFfs (
IN EFI_SECTION_TYPE SectionType,
- IN UINTN Instance,
+ IN UINTN SectionInstance,
OUT VOID **Buffer,
OUT UINTN *Size
)
@@ -397,7 +396,7 @@ PiLibGetSectionFromCurrentFfs ( InternalImageHandleToFvHandle(gImageHandle),
&gEfiCallerIdGuid,
SectionType,
- Instance,
+ SectionInstance,
Buffer,
Size
);
|