diff options
author | lgao4 <lgao4@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-11-17 04:39:25 +0000 |
---|---|---|
committer | lgao4 <lgao4@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-11-17 04:39:25 +0000 |
commit | b75a165ded750b3113b90c04af2beef09a9c1329 (patch) | |
tree | ddb6af3794072b5eea2283251b9affba8b631450 /MdePkg/Library/DxeServicesLib | |
parent | d41be01a6f007dc5dfe66217882f640914f648b6 (diff) | |
download | edk2-platforms-b75a165ded750b3113b90c04af2beef09a9c1329.tar.xz |
Update function header align to Mde Lib spec.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6557 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdePkg/Library/DxeServicesLib')
-rw-r--r-- | MdePkg/Library/DxeServicesLib/DxeServicesLib.c | 273 | ||||
-rw-r--r-- | MdePkg/Library/DxeServicesLib/DxeServicesLib.inf | 2 |
2 files changed, 131 insertions, 144 deletions
diff --git a/MdePkg/Library/DxeServicesLib/DxeServicesLib.c b/MdePkg/Library/DxeServicesLib/DxeServicesLib.c index 5dca51a463..b03d019fbb 100644 --- a/MdePkg/Library/DxeServicesLib/DxeServicesLib.c +++ b/MdePkg/Library/DxeServicesLib/DxeServicesLib.c @@ -1,5 +1,6 @@ /** @file
- Mde PI library functions.
+ MDE DXE Services Library provides functions that simplify the development of DXE Drivers.
+ These functions help access data from sections of FFS files.
Copyright (c) 2007 - 2008, Intel Corporation<BR>
All rights reserved. This program and the accompanying materials
@@ -34,7 +35,7 @@ @param ImageHandle The firmware allocated handle for UEFI image.
- @retval EFI_HANDLE The device handle from which the Image is loaded from.
+ @retval EFI_HANDLE The device handle from which the Image is loaded from.
**/
EFI_HANDLE
@@ -60,41 +61,41 @@ InternalImageHandleToFvHandle ( }
/**
- 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 specified Firmware Volume.
+ 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 specified Firmware Volume.
+
+ 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 SectionInstance.
+
+ 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.
- 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 SectionInstance.
-
- 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 FvHandle is NULL, then ASSERT ();
- If NameGuid is NULL, then ASSERT();
- 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 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.
+ 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.
- @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.
+ If FvHandle is NULL, then ASSERT ();
+ If NameGuid is NULL, then ASSERT();
+ 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 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.
**/
EFI_STATUS
@@ -164,48 +165,40 @@ InternalGetSectionFromFv ( /**
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
-
- GetSectionFromAnyFv () 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();
+ Searches all the availables firmware volumes and returns the first matching FFS section.
+
+ This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid.
+ The order that the firmware volumes is searched is not deterministic. For each FFS file found a search
+ is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances
+ of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
+ Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
+ It is the caller's responsibility to use FreePool() to free the allocated buffer.
+ See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections
+ are retrieved from an FFS file based on SectionType and SectionInstance.
+
+ If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
+ the search will be retried with a section type of EFI_SECTION_PE32.
+ This function must be called with a TPL <= TPL_NOTIFY.
+
+ 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.
+ @param NameGuid A pointer to to the FFS filename GUID to search for within
+ any of the firmware volumes in the platform.
+ @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid.
+ @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve.
+ @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
+ Is it the caller's respobsibility to free this buffer using FreePool().
+ @param Size On output, a pointer to the size, in bytes, of Buffer.
+
+ @retval EFI_SUCCESS The specified FFS section was returned.
+ @retval EFI_NOT_FOUND The specified FFS section could not be found.
+ @retval EFI_OUT_OF_RESOURCES There are not enough rsources available to retrieve the matching FFS section.
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error.
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that
+ contains the matching FFS section does not allow reads.
**/
EFI_STATUS
EFIAPI
@@ -289,46 +282,41 @@ Done: }
/**
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
-
- GetSectionFromFv () 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();
+ Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section.
+
+ This function searches the firmware volume that the currently executing module was loaded
+ from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found a search
+ is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance
+ instances of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer.
+ Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size.
+ It is the caller's responsibility to use FreePool() to free the allocated buffer.
+ See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from
+ an FFS file based on SectionType and SectionInstance.
+
+ If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned.
+ If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
+ the search will be retried with a section type of EFI_SECTION_PE32.
+
+ This function must be called with a TPL <= TPL_NOTIFY.
+ 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.
-
+ @param NameGuid A pointer to to the FFS filename GUID to search for within
+ the firmware volumes that the currently executing module was loaded from.
+ @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid.
+ @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve.
+ @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
+ Is it the caller's respobsibility to free this buffer using FreePool().
+ @param Size On output, a pointer to the size, in bytes, of Buffer.
+
+
+ @retval EFI_SUCCESS The specified FFS section was returned.
+ @retval EFI_NOT_FOUND The specified FFS section could not be found.
+ @retval EFI_OUT_OF_RESOURCES There are not enough rsources available to retrieve the matching FFS section.
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error.
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that
+ contains the matching FFS section does not allow reads.
**/
EFI_STATUS
EFIAPI
@@ -352,39 +340,38 @@ GetSectionFromFv ( /**
- Locates a requested firmware section within a file and returns it to a buffer allocated by this function.
-
- GetSectionFromFfs () 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();
+ Searches the FFS file the the currently executing module was loaded from and returns the first matching FFS section.
+
+ This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType.
+ If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType,
+ then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(),
+ and the size of the allocated buffer is returned in Size. It is the caller's responsibility
+ to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for
+ details on how sections are retrieved from an FFS file based on SectionType and SectionInstance.
+
+ If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned.
+ If SectionType is EFI_SECTION_TE, and the search with an FFS file fails,
+ the search will be retried with a section type of EFI_SECTION_PE32.
+ This function must be called with a TPL <= TPL_NOTIFY.
+
+ 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.
+
+ @param SectionType Indicates the FFS section type to search for within the FFS file
+ that the currently executing module was loaded from.
+ @param SectionInstance Indicates which section instance to retrieve within the FFS file
+ that the currently executing module was loaded from.
+ @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found.
+ Is it the caller's respobsibility to free this buffer using FreePool().
+ @param Size On output, a pointer to the size, in bytes, of Buffer.
+
+ @retval EFI_SUCCESS The specified FFS section was returned.
+ @retval EFI_NOT_FOUND The specified FFS section could not be found.
+ @retval EFI_OUT_OF_RESOURCES There are not enough rsources available to retrieve the matching FFS section.
+ @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error.
+ @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that
+ contains the matching FFS section does not allow reads.
**/
EFI_STATUS
diff --git a/MdePkg/Library/DxeServicesLib/DxeServicesLib.inf b/MdePkg/Library/DxeServicesLib/DxeServicesLib.inf index cc4cd6522a..3e04bdb1c8 100644 --- a/MdePkg/Library/DxeServicesLib/DxeServicesLib.inf +++ b/MdePkg/Library/DxeServicesLib/DxeServicesLib.inf @@ -1,5 +1,5 @@ #/** @file
-# Instance of PI Library for DXE phase.
+# DXE Services Library provides access data from sections of FFS files based on FV protocol.
#
# Copyright (c) 2007 - 2008, Intel Corporation.
#
|