/** @file\r
- Mde PI library functions.\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
\r
Copyright (c) 2007 - 2008, Intel Corporation<BR>\r
All rights reserved. This program and the accompanying materials\r
\r
@param ImageHandle The firmware allocated handle for UEFI image.\r
\r
- @retval EFI_HANDLE The device handle from which the Image is loaded from.\r
+ @retval EFI_HANDLE The device handle from which the Image is loaded from.\r
\r
**/\r
EFI_HANDLE\r
}\r
\r
/**\r
- Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
- Section type and instance number from the specified Firmware Volume.\r
+ Allocate and fill a buffer from a Firmware Section identified by a Firmware File GUID name, a Firmware \r
+ Section type and instance number from the specified Firmware Volume.\r
+\r
+ This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to \r
+ carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed \r
+ by NameGuid, SectionType and SectionInstance. \r
+ \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
- This functions first locate the EFI_FIRMWARE_VOLUME2_PROTOCOL protocol instance on FvHandle in order to \r
- carry out the Firmware Volume read operation. The function then reads the Firmware Section found sepcifed \r
- by NameGuid, SectionType and SectionInstance. \r
- \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 FvHandle is NULL, then ASSERT ();\r
- If NameGuid is NULL, then ASSERT();\r
- If Buffer is NULL, then ASSERT();\r
- If Size is NULL, then ASSERT().\r
-\r
- @param FvHandle The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
- @param NameGuid The GUID name of a Firmware File.\r
- @param SectionType The Firmware Section type.\r
- @param SectionInstance The instance number of Firmware Section to read from starting from 0.\r
- @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
- @param Size On output, the size of Buffer.\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
- @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
+ If FvHandle is NULL, then ASSERT ();\r
+ If NameGuid is NULL, then ASSERT();\r
+ If Buffer is NULL, then ASSERT();\r
+ If Size is NULL, then ASSERT().\r
+\r
+ @param FvHandle The device handle that contains a instance of EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
+ @param NameGuid The GUID name of a Firmware File.\r
+ @param SectionType The Firmware Section type.\r
+ @param SectionInstance The instance number of Firmware Section to read from starting from 0.\r
+ @param Buffer On output, Buffer contains the the data read from the section in the Firmware File found.\r
+ @param Size On output, the size of Buffer.\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
**/\r
EFI_STATUS\r
\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
-\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 NameGuid is NULL, then ASSERT();\r
- If Buffer is NULL, then ASSERT();\r
+ Searches all the availables 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 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. 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 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
+ Is it the caller's respobsibility 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 rsources 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
}\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 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
+ Is it the caller's respobsibility to free this buffer 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 rsources 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
\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 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
+ Is it the caller's respobsibility 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 rsources 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
**/\r
EFI_STATUS\r
projects / mirror_edk2.git / blobdiff