From b75a165ded750b3113b90c04af2beef09a9c1329 Mon Sep 17 00:00:00 2001 From: lgao4 Date: Mon, 17 Nov 2008 04:39:25 +0000 Subject: 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 --- MdePkg/Library/DxeServicesLib/DxeServicesLib.c | 273 +++++++++++------------ MdePkg/Library/DxeServicesLib/DxeServicesLib.inf | 2 +- 2 files changed, 131 insertions(+), 144 deletions(-) (limited to 'MdePkg/Library/DxeServicesLib') 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
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. # -- cgit v1.2.3