/** @file\r
- MDE PI library functions and macros\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 or from file path.\r
\r
- Copyright (c) 2007, Intel Corporation \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
-\r
-#include <Pi/PiFirmwareFile.h>\r
-\r
+#ifndef __DXE_SERVICES_LIB_H__\r
+#define __DXE_SERVICES_LIB_H__\r
\r
/**\r
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
-\r
- GetSectionFromAnyFv () is used to read a specific section from a file within a firmware volume. The function\r
- will search the first file with the specified name in all firmware volumes in the system. The search order for firmware \r
- volumes in the system is determistic but abitrary if no new firmware volume is added into the system between \r
- each calls of this function. \r
-\r
- After the specific file is located, the function searches the specifc firmware section with type SectionType in this file. \r
- The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () \r
- found in PI Specification.\r
-\r
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
- is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
- is returned.\r
+ 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
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
- by this function. This function can only be called at TPL_NOTIFY and below.\r
+ @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
- If NameGuid is NULL, then ASSERT();\r
- If Buffer is NULL, then ASSERT();\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 an FFS filename specified by NameGuid. \r
+ The order in which the firmware volumes are searched is not deterministic. 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 NameGuid is NULL, then ASSERT().\r
+ If Buffer is NULL, then ASSERT().\r
If Size is NULL, then ASSERT().\r
\r
- @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested \r
- section will be read. Type EFI_GUID is defined in \r
- InstallProtocolInterface() in the UEFI 2.0 specification. \r
- @param SectionType Indicates the section type to return. SectionType in conjunction with \r
- SectionInstance indicates which section to return. Type \r
- EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
- @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
- SectionType in conjunction with SectionInstance indicates which section to \r
- return. SectionInstance is zero based.\r
- @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
- including the section header. Caller is responsible to free this memory.\r
- @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
- *Buffer.\r
-\r
- @retval EFI_SUCCESS The image is found and data and size is returned.\r
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
\r
+ @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 \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
);\r
\r
/**\r
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
-\r
- GetSectionFromFv () is used to read a specific section from a file within the same firmware volume from which\r
- the running image is loaded. If the specific file is found, the function searches the specifc firmware section with type SectionType. \r
- The details of this search order is defined in description of EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () \r
- found in PI Specification.\r
-\r
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
- is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
- is returned.\r
-\r
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
- by this function. This function can be only called at TPL_NOTIFY and below.\r
-\r
- If NameGuid is NULL, then ASSERT();\r
- If Buffer is NULL, then ASSERT();\r
+ Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section. \r
+\r
+ This function searches the firmware volume that the currently executing module was loaded \r
+ from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found, a search \r
+ is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance \r
+ instances 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 are retrieved from \r
+ an FFS file based on SectionType and SectionInstance.\r
+\r
+ If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned.\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
+ \r
+ This function must be called with a TPL <= TPL_NOTIFY.\r
+ If NameGuid is NULL, then ASSERT().\r
+ If Buffer is NULL, then ASSERT().\r
If Size is NULL, then ASSERT().\r
\r
- @param NameGuid Pointer to an EFI_GUID, which indicates the file name from which the requested \r
- section will be read. Type EFI_GUID is defined in \r
- InstallProtocolInterface() in the UEFI 2.0 specification. \r
- @param SectionType Indicates the section type to return. SectionType in conjunction with \r
- SectionInstance indicates which section to return. Type \r
- EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
- @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
- SectionType in conjunction with SectionInstance indicates which section to \r
- return. SectionInstance is zero based.\r
- @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
- including the section header. Caller is responsible to free this memory.\r
- @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
- *Buffer.\r
-\r
-\r
- @retval EFI_SUCCESS The image is found and data and size is returned.\r
- @retval EFI_UNSUPPORTED FvHandle does not support EFI_FIRMWARE_VOLUME2_PROTOCOL.\r
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
- \r
+ @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 \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
\r
\r
/**\r
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function. \r
-\r
- GetSectionFromFfs () searches the specifc firmware section with type SectionType in the same firmware file from\r
- which the running image is loaded. The details of this search order is defined in description of \r
- EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection () found in PI Specification.\r
-\r
- If SectionType is EFI_SECTION_TE, EFI_SECTION_TE is used as section type to start the search. If EFI_SECTION_TE section \r
- is not found, EFI_SECTION_PE32 will be used to try the search again. If no EFI_SECTION_PE32 section is found, EFI_NOT_FOUND \r
- is returned.\r
-\r
-\r
- The data and size is returned by Buffer and Size. The caller is responsible to free the Buffer allocated \r
- by this function. This function can only be called at TPL_NOTIFY and below.\r
-\r
- If Buffer is NULL, then ASSERT();\r
+ Searches the FFS file the the currently executing module was loaded from and returns the first matching FFS section.\r
+\r
+ This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType.\r
+ If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType, \r
+ then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(), \r
+ and the size of the allocated buffer is returned in Size. It is the caller's responsibility \r
+ to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for \r
+ details on how sections are retrieved from an FFS file based on SectionType and SectionInstance.\r
+\r
+ If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned.\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 SectionType Indicates the section type to return. SectionType in conjunction with \r
- SectionInstance indicates which section to return. Type \r
- EFI_SECTION_TYPE is defined in EFI_COMMON_SECTION_HEADER.\r
- @param SectionInstance Indicates which instance of sections with a type of SectionType to return. \r
- SectionType in conjunction with SectionInstance indicates which section to \r
- return. SectionInstance is zero based.\r
- @param Buffer Pointer to a pointer to a buffer in which the section contents are returned, not \r
- including the section header. Caller is responsible to free this memory.\r
- @param Size Pointer to a caller-allocated UINTN. It indicates the size of the memory represented by \r
- *Buffer.\r
-\r
- @retval EFI_SUCCESS The image is found and data and size is returned.\r
- @retval EFI_NOT_FOUND The image specified by NameGuid and SectionType can't be found.\r
- @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the output data buffer or complete the operations.\r
- @retval EFI_DEVICE_ERROR A hardware error occurs during reading from the Firmware Volume.\r
- @retval EFI_ACCESS_DENIED The firmware volume containing the searched Firmware File is configured to disallow reads.\r
+\r
+ @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 \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