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. + Locates a requested firmware section within a file and returns it to a buffer allocated by this function. - 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. + 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 ) ; /** - 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(). + Locates a requested firmware section within a file and returns it to a buffer allocated by this function. - @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. + 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. + Locates a requested firmware section within a file and returns it to a buffer allocated by this function. - 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. + 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(). + Locates a requested firmware section within a file and returns it to a buffer allocated by this function. - @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. + 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 );