Add new API GetSectionFromAnyFvByFileType() into MdePkg DxeServicesLib.

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

diff --git a/MdePkg/Include/Library/DxeServicesLib.h b/MdePkg/Include/Library/DxeServicesLib.h
index e3536687e18bc1a425140b3fddfdd447c9bc09a2..596487da57deba72a495f8a3a5df054b0d2677e0 100644 (file)
--- a/MdePkg/Include/Library/DxeServicesLib.h
+++ b/MdePkg/Include/Library/DxeServicesLib.h
@@ -16,6 +16,56 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #ifndef __DXE_SERVICES_LIB_H__\r
 #define __DXE_SERVICES_LIB_H__\r
 \r
+/**\r
+  Searches all the available firmware volumes and returns the first matching FFS section. \r
+\r
+  This function searches all the firmware volumes for FFS files with FV file type specified by FileType\r
+  The order that the firmware volumes is searched is not deterministic. For each available FV a search \r
+  is made for FFS file of type FileType. If the FV contains more than one FFS file with the same FileType, \r
+  the FileInstance instance will be the matched FFS file. For each FFS file found a search \r
+  is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances \r
+  of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. \r
+  Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. \r
+  It is the caller's responsibility to use FreePool() to free the allocated buffer.  \r
+  See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections \r
+  are retrieved from an FFS file based on SectionType and SectionInstance.\r
+\r
+  If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, \r
+  the search will be retried with a section type of EFI_SECTION_PE32.\r
+  This function must be called with a TPL <= TPL_NOTIFY.\r
+\r
+  If Buffer is NULL, then ASSERT().\r
+  If Size is NULL, then ASSERT().\r
+\r
+  @param  FileType             Indicates the FV file type to search for within all available FVs.\r
+  @param  FileInstance         Indicates which file instance within all available FVs specified by FileType.\r
+                               FileInstance starts from zero.\r
+  @param  SectionType          Indicates the FFS section type to search for within the FFS file \r
+                               specified by FileType with FileInstance.\r
+  @param  SectionInstance      Indicates which section instance within the FFS file \r
+                               specified by FileType with FileInstance to retrieve. SectionInstance starts from zero.\r
+  @param  Buffer               On output, a pointer to a callee allocated buffer containing the FFS file section that was found.\r
+                               Is it the caller's responsibility to free this buffer using FreePool().\r
+  @param  Size                 On output, a pointer to the size, in bytes, of Buffer.\r
+\r
+  @retval  EFI_SUCCESS          The specified FFS section was returned.\r
+  @retval  EFI_NOT_FOUND        The specified FFS section could not be found.\r
+  @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section.\r
+  @retval  EFI_DEVICE_ERROR     The FFS section could not be retrieves due to a device error.\r
+  @retval  EFI_ACCESS_DENIED    The FFS section could not be retrieves because the firmware volume that \r
+                                contains the matching FFS section does not allow reads.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+GetSectionFromAnyFvByFileType  (\r
+  IN  EFI_FV_FILETYPE               FileType,\r
+  IN  UINTN                         FileInstance,\r
+  IN  EFI_SECTION_TYPE              SectionType,\r
+  IN  UINTN                         SectionInstance,\r
+  OUT VOID                          **Buffer,\r
+  OUT UINTN                         *Size\r
+  );\r
+\r
 /**\r
   Searches all the available firmware volumes and returns the first matching FFS section. \r
 \r