/** @file\r
MDE DXE Services Library provides functions that simplify the development of DXE Drivers. \r
- These functions help access data from sections of FFS files.\r
+ These functions help access data from sections of FFS files or from file path.\r
\r
- Copyright (c) 2008, Intel Corporation<BR> \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>\r
+(C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR>\r
+This program and the accompanying materials are licensed and made available under \r
+the terms and conditions of the BSD License that accompanies this distribution. \r
+The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php. \r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
\r
**/\r
\r
-#ifndef __PI_LIB_H__\r
-#define __PI_LIB_H__\r
+#ifndef __DXE_SERVICES_LIB_H__\r
+#define __DXE_SERVICES_LIB_H__\r
\r
-#include <Pi/PiFirmwareFile.h>\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
If Size is NULL, then ASSERT().\r
\r
\r
- @param NameGuid A pointer to to the FFS filename GUID to search for within \r
- any of the firmware volumes in the platform. \r
- @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid.\r
- @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve.\r
- @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found. \r
- It is the caller's responsibility to free this buffer using FreePool().\r
+ @param NameGuid A pointer to to the FFS filename GUID to search for \r
+ within any of the firmware volumes in the platform. \r
+ @param SectionType Indicates the FFS section type to search for within \r
+ the FFS file specified by NameGuid.\r
+ @param SectionInstance Indicates which section instance within the FFS file \r
+ specified by NameGuid to retrieve.\r
+ @param Buffer On output, a pointer to a callee-allocated buffer \r
+ containing the FFS file section that was found. \r
+ It is the caller's responsibility to free this \r
+ 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
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve \r
+ the matching FFS section.\r
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a \r
+ device error.\r
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the \r
+ firmware volume that contains the matching FFS \r
+ section does not allow reads.\r
**/\r
EFI_STATUS\r
EFIAPI\r
If Buffer is NULL, then ASSERT().\r
If Size is NULL, then ASSERT().\r
\r
- @param NameGuid A pointer to to the FFS filename GUID to search for within \r
- the firmware volumes that the currently executing module was loaded from.\r
- @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid.\r
- @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve.\r
- @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found. \r
- It is the caller's responsibility to free this buffer using FreePool().\r
+ @param NameGuid A pointer to to the FFS filename GUID to search for \r
+ within the firmware volumes that the currently \r
+ executing module was loaded from.\r
+ @param SectionType Indicates the FFS section type to search for within \r
+ the FFS file specified by NameGuid.\r
+ @param SectionInstance Indicates which section instance within the FFS \r
+ file specified by NameGuid to retrieve.\r
+ @param Buffer On output, a pointer to a callee allocated buffer \r
+ containing the FFS file section that was found. \r
+ It is the caller's responsibility to free this buffer \r
+ using FreePool().\r
@param Size On output, a pointer to the size, in bytes, of Buffer.\r
\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
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve \r
+ the matching FFS section.\r
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a \r
+ device error.\r
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the \r
+ firmware volume that contains the matching FFS \r
+ section does not allow reads. \r
**/\r
EFI_STATUS\r
EFIAPI\r
If Size is NULL, then ASSERT().\r
\r
\r
- @param SectionType Indicates the FFS section type to search for within the FFS file \r
- that the currently executing module was loaded from.\r
- @param SectionInstance Indicates which section instance to retrieve within the FFS file \r
- that the currently executing module was loaded from.\r
- @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found. \r
- It is the caller's responsibility to free this buffer using FreePool().\r
+ @param SectionType Indicates the FFS section type to search for within \r
+ the FFS file that the currently executing module \r
+ was loaded from.\r
+ @param SectionInstance Indicates which section instance to retrieve within \r
+ the FFS file that the currently executing module \r
+ was loaded from.\r
+ @param Buffer On output, a pointer to a callee allocated buffer \r
+ containing the FFS file section that was found. \r
+ It is the caller's responsibility to free this buffer \r
+ 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
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve \r
+ the matching FFS section.\r
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a \r
+ device error.\r
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the \r
+ firmware volume that contains the matching FFS \r
+ section does not allow reads. \r
\r
**/\r
EFI_STATUS\r
OUT UINTN *Size\r
);\r
\r
-#endif\r
\r
+/**\r
+ Get the image file buffer data and buffer size by its device path. \r
+ \r
+ Access the file either from a firmware volume, from a file system interface, \r
+ or from the load file interface.\r
+ \r
+ Allocate memory to store the found image. The caller is responsible to free memory.\r
+\r
+ If FilePath is NULL, then NULL is returned.\r
+ If FileSize is NULL, then NULL is returned.\r
+ If AuthenticationStatus is NULL, then NULL is returned.\r
+\r
+ @param[in] BootPolicy The policy for Open Image File.If TRUE, \r
+ indicates that the request originates from \r
+ the boot manager, and that the boot manager is\r
+ attempting to load FilePath as a boot selection. \r
+ If FALSE, then FilePath must match an exact \r
+ file to be loaded.\r
+ @param[in] FilePath Pointer to the device path of the file that is abstracted to\r
+ the file buffer.\r
+ @param[out] FileSize Pointer to the size of the abstracted file buffer.\r
+ @param[out] AuthenticationStatus Pointer to the authentication status.\r
+\r
+ @retval NULL FilePath is NULL, or FileSize is NULL, or AuthenticationStatus is NULL, or the file can't be found.\r
+ @retval other The abstracted file buffer. The caller is responsible to free memory.\r
+**/\r
+VOID *\r
+EFIAPI\r
+GetFileBufferByFilePath (\r
+ IN BOOLEAN BootPolicy,\r
+ IN CONST EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
+ OUT UINTN *FileSize,\r
+ OUT UINT32 *AuthenticationStatus\r
+ );\r
+\r
+/**\r
+ Searches all the available firmware volumes and returns the file device path of first matching\r
+ FFS section.\r
+\r
+ This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid.\r
+ The order that the firmware volumes is searched is not deterministic. For each FFS file found a search\r
+ is made for FFS sections of type SectionType.\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 NameGuid is NULL, then ASSERT().\r
+\r
+ @param NameGuid A pointer to to the FFS filename GUID to search for\r
+ within any of the firmware volumes in the platform.\r
+ @param SectionType Indicates the FFS section type to search for within\r
+ the FFS file specified by NameGuid.\r
+ @param SectionInstance Indicates which section instance within the FFS file\r
+ specified by NameGuid to retrieve.\r
+ @param FvFileDevicePath Device path for the target FFS\r
+ file.\r
+\r
+ @retval EFI_SUCCESS The specified file device path of FFS section was returned.\r
+ @retval EFI_NOT_FOUND The specified file device path of FFS section could not be found.\r
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a\r
+ device error.\r
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the\r
+ firmware volume that contains the matching FFS section does not\r
+ allow reads.\r
+ @retval EFI_INVALID_PARAMETER FvFileDevicePath is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+GetFileDevicePathFromAnyFv (\r
+ IN CONST EFI_GUID *NameGuid,\r
+ IN EFI_SECTION_TYPE SectionType,\r
+ IN UINTN SectionInstance,\r
+ OUT EFI_DEVICE_PATH_PROTOCOL **FvFileDevicePath\r
+ );\r
+\r
+/**\r
+ Allocates one or more 4KB pages of a given type from a memory region that is\r
+ accessible to PEI.\r
+\r
+ Allocates the number of 4KB pages of type 'MemoryType' and returns a\r
+ pointer to the allocated buffer. The buffer returned is aligned on a 4KB\r
+ boundary. If Pages is 0, then NULL is returned. If there is not enough\r
+ memory remaining to satisfy the request, then NULL is returned.\r
+\r
+ @param[in] MemoryType The memory type to allocate\r
+ @param[in] Pages The number of 4 KB pages to allocate.\r
+\r
+ @return A pointer to the allocated buffer or NULL if allocation fails.\r
+\r
+**/\r
+VOID *\r
+EFIAPI\r
+AllocatePeiAccessiblePages (\r
+ IN EFI_MEMORY_TYPE MemoryType,\r
+ IN UINTN Pages\r
+ );\r
+\r
+#endif\r
projects / mirror_edk2.git / blobdiff