From 3e5c323866e6f424f15ab7f59595d8929846354e Mon Sep 17 00:00:00 2001 From: gikidy Date: Wed, 26 Nov 2008 03:26:37 +0000 Subject: [PATCH] Synchronize function comment in MdePkg\Library\CpuLib.h, DebugLib.h,DevicePathLib.h, DxeServicesLib.h, DxeServicesTableLib.h, ExtractGuidedSectionLib.h, HobLib.h with the c file instance of this functions in MdePkg. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6727 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Library/CpuLib.h | 2 +- MdePkg/Include/Library/DebugLib.h | 51 ++++------- MdePkg/Include/Library/DevicePathLib.h | 2 +- MdePkg/Include/Library/DxeServicesLib.h | 14 +-- MdePkg/Include/Library/DxeServicesTableLib.h | 2 +- .../Include/Library/ExtractGuidedSectionLib.h | 26 ++++-- MdePkg/Include/Library/HobLib.h | 2 +- .../Library/BaseCpuLib/Ebc/CpuSleepFlushTlb.c | 5 +- MdePkg/Library/BaseCpuLib/Ia32/CpuFlushTlb.c | 6 +- MdePkg/Library/BaseDebugLibNull/DebugLib.c | 35 +++----- .../Library/BaseDebugLibSerialPort/DebugLib.c | 24 +++-- MdePkg/Library/DxeCoreHobLib/HobLib.c | 90 +++++++++++++------ MdePkg/Library/DxeHobLib/HobLib.c | 69 ++++++++++---- .../Library/DxeServicesLib/DxeServicesLib.c | 12 +-- .../PeiExtractGuidedSectionLib.c | 18 ++-- MdePkg/Library/PeiHobLib/HobLib.c | 70 +++++++++++---- MdePkg/Library/UefiDebugLibConOut/DebugLib.c | 31 ++----- MdePkg/Library/UefiDebugLibStdErr/DebugLib.c | 30 +++---- .../UefiDevicePathLib/UefiDevicePathLib.c | 35 +++++--- .../UefiDevicePathLib.c | 35 +++++--- 20 files changed, 324 insertions(+), 235 deletions(-) diff --git a/MdePkg/Include/Library/CpuLib.h b/MdePkg/Include/Library/CpuLib.h index b54dd26991..b9a1869425 100644 --- a/MdePkg/Include/Library/CpuLib.h +++ b/MdePkg/Include/Library/CpuLib.h @@ -7,7 +7,7 @@ PAL Calls require PEI and DXE specific mechanisms to look up PAL Entry Point. As a result, these services could not be defined in the Base Library. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at diff --git a/MdePkg/Include/Library/DebugLib.h b/MdePkg/Include/Library/DebugLib.h index 51da314ea2..0c07aab5fb 100644 --- a/MdePkg/Include/Library/DebugLib.h +++ b/MdePkg/Include/Library/DebugLib.h @@ -4,7 +4,7 @@ The Debug library supports debug print and asserts based on a combination of macros and code. The debug library can be turned on and off so that the debug code does not increase the size of an image. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -69,7 +69,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define EFI_D_ERROR DEBUG_ERROR /** - Prints a debug message to the debug output device if the specified error level is enabled. If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print @@ -94,7 +93,6 @@ DebugPrint ( /** - Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. @@ -108,7 +106,6 @@ DebugPrint ( processing another DebugAssert(), then DebugAssert() must return immediately. If FileName is NULL, then a string of "(NULL) Filename" is printed. - If Description is NULL, then a string of "(NULL) Description" is printed. @param FileName Pointer to the name of the source file that generated the assert condition. @@ -126,14 +123,12 @@ DebugAssert ( /** - Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer. This function fills Length bytes of Buffer with the value specified by PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). - If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). @param Buffer Pointer to the target buffer to be filled with PcdDebugClearMemoryValue. @@ -151,7 +146,6 @@ DebugClearMemory ( /** - Returns TRUE if ASSERT() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of @@ -168,9 +162,8 @@ DebugAssertEnabled ( ); -/** - - Returns TRUE if DEBUG()macros are enabled. +/** + Returns TRUE if DEBUG() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -186,9 +179,8 @@ DebugPrintEnabled ( ); -/** - - Returns TRUE if DEBUG_CODE()macros are enabled. +/** + Returns TRUE if DEBUG_CODE() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -204,9 +196,8 @@ DebugCodeEnabled ( ); -/** - - Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled. +/** + Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -222,8 +213,7 @@ DebugClearMemoryEnabled ( ); -/** - +/** Internal worker macro that calls DebugAssert(). This macro calls DebugAssert() passing in the filename, line number, and @@ -235,8 +225,7 @@ DebugClearMemoryEnabled ( #define _ASSERT(Expression) DebugAssert (__FILE__, __LINE__, #Expression) -/** - +/** Internal worker macro that calls DebugPrint(). This macro calls DebugPrint() passing in the debug error level, a format @@ -249,8 +238,7 @@ DebugClearMemoryEnabled ( #define _DEBUG(Expression) DebugPrint Expression -/** - +/** Macro that calls DebugAssert() if a expression evaluates to FALSE. If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set, @@ -271,8 +259,7 @@ DebugClearMemoryEnabled ( } while (FALSE) -/** - +/** Macro that calls DebugPrint(). If the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set, @@ -291,8 +278,7 @@ DebugClearMemoryEnabled ( } while (FALSE) -/** - +/** Macro that calls DebugAssert() if an EFI_STATUS evaluates to an error code. If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set, @@ -314,8 +300,7 @@ DebugClearMemoryEnabled ( } while (FALSE) -/** - +/** Macro that calls DebugAssert() if a protocol is already installed in the handle database. @@ -367,8 +352,7 @@ DebugClearMemoryEnabled ( #define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal -/** - +/** Macro that marks the end of debug source code. If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, @@ -380,8 +364,7 @@ DebugClearMemoryEnabled ( #define DEBUG_CODE_END() __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE) -/** - +/** Macro that declares a section of debug source code. If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, @@ -395,8 +378,7 @@ DebugClearMemoryEnabled ( DEBUG_CODE_END () -/** - +/** Macro that calls DebugClearMemory() to clear a buffer to a default value. If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set, @@ -415,7 +397,6 @@ DebugClearMemoryEnabled ( /** - Macro that calls DebugAssert() if the containing record does not have a matching signature. If the signatures matches, then a pointer to the data structure that contains a specified field of that data structure is returned. diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h index 891b5d657a..caa7f9dead 100644 --- a/MdePkg/Include/Library/DevicePathLib.h +++ b/MdePkg/Include/Library/DevicePathLib.h @@ -6,7 +6,7 @@ path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from the Base Library, so this library class has an implied dependency on the Base Library. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at diff --git a/MdePkg/Include/Library/DxeServicesLib.h b/MdePkg/Include/Library/DxeServicesLib.h index ef925c9c60..67ddc7f681 100644 --- a/MdePkg/Include/Library/DxeServicesLib.h +++ b/MdePkg/Include/Library/DxeServicesLib.h @@ -2,7 +2,7 @@ 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) 2008, Intel Corporation + Copyright (c) 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -45,12 +45,12 @@ @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. @@ -91,13 +91,13 @@ GetSectionFromAnyFv ( @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. @@ -137,12 +137,12 @@ GetSectionFromFv ( @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. diff --git a/MdePkg/Include/Library/DxeServicesTableLib.h b/MdePkg/Include/Library/DxeServicesTableLib.h index 928730682b..2be06e4209 100644 --- a/MdePkg/Include/Library/DxeServicesTableLib.h +++ b/MdePkg/Include/Library/DxeServicesTableLib.h @@ -11,7 +11,7 @@ Table should use this library. This will typically be DXE Drivers that require GCD or Dispatcher services. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at diff --git a/MdePkg/Include/Library/ExtractGuidedSectionLib.h b/MdePkg/Include/Library/ExtractGuidedSectionLib.h index be963cb5a7..003fc898ba 100644 --- a/MdePkg/Include/Library/ExtractGuidedSectionLib.h +++ b/MdePkg/Include/Library/ExtractGuidedSectionLib.h @@ -1,7 +1,16 @@ /** @file This library provides common functions to process the different guided section data. + + This library provides functions to process GUIDed sections of FFS files. Handlers may + be registered to decode GUIDed sections of FFS files. Services are provided to determine + the set of supported section GUIDs, collection information about a specific GUIDed section, + and decode a specific GUIDed section. + + A library instance that produces this library class may be used to produce a + EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI or a EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL + providing a simple method to extend the number of GUIDed sections types a platform supports. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -27,6 +36,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. then the size required to hold the decoded buffer is returned in OututBufferSize, the size of an optional scratch buffer is returned in ScratchSize, and the Attributes field from EFI_GUID_DEFINED_SECTION header of InputSection is returned in SectionAttribute. + If InputSection is NULL, then ASSERT(). If OutputBufferSize is NULL, then ASSERT(). If ScratchBufferSize is NULL, then ASSERT(). @@ -66,6 +76,7 @@ RETURN_STATUS decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller allocated buffer specified by OutputBuffer. + If InputSection is NULL, then ASSERT(). If OutputBuffer is NULL, then ASSERT(). If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT(). @@ -100,9 +111,10 @@ RETURN_STATUS Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER for a specific GUID section type. - Registers the handlers specified by GetInfoHandler and DecodeHandler witg the GUID specified by SectionGuid. + Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid. If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED. If there are not enough resources available to register the handlers then RETURN_OUT_OF_RESOURCES is returned. + If SectionGuid is NULL, then ASSERT(). If GetInfoHandler is NULL, then ASSERT(). If DecodeHandler is NULL, then ASSERT(). @@ -136,7 +148,7 @@ ExtractGuidedSectionRegisterHandlers ( and caller must treat this array of GUIDs as read-only data. If ExtractHandlerGuidTable is NULL, then ASSERT(). - @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs tht have been registerd through + @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers(). @return the number of the supported extract guided Handler. @@ -149,7 +161,7 @@ ExtractGuidedSectionGetGuidList ( ); /** - Retrives a GUID from a GUIDed section and uses that GUID to select an associated handler of type + Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers(). The selected handler is used to retrieve and return the size of the decoded buffer and the size of an optional scratch buffer required to actually decode the data in a GUIDed section. @@ -161,6 +173,7 @@ ExtractGuidedSectionGetGuidList ( of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers() is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned. + If InputSection is NULL, then ASSERT(). If OutputBufferSize is NULL, then ASSERT(). If ScratchBufferSize is NULL, then ASSERT(). @@ -191,7 +204,7 @@ ExtractGuidedSectionGetInfo ( ); /** - Retrives the GUID from a GUIDed section and uses that GUID to select an associated handler of type + Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers(). The selected handler is used to decode the data in a GUIDed section and return the result in a caller allocated output buffer. @@ -205,7 +218,8 @@ ExtractGuidedSectionGetInfo ( decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller allocated buffer specified by OutputBuffer. This function is responsible for computing the EFI_AUTH_STATUS_PLATFORM_OVERRIDE - bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. + bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. + If InputSection is NULL, then ASSERT(). If OutputBuffer is NULL, then ASSERT(). If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT(). diff --git a/MdePkg/Include/Library/HobLib.h b/MdePkg/Include/Library/HobLib.h index 2e81704421..7f999e1ab8 100644 --- a/MdePkg/Include/Library/HobLib.h +++ b/MdePkg/Include/Library/HobLib.h @@ -8,7 +8,7 @@ allows the PEI phase to pass information to the DXE phase. HOBs are position independent and can be relocated easily to different memory memory locations. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at diff --git a/MdePkg/Library/BaseCpuLib/Ebc/CpuSleepFlushTlb.c b/MdePkg/Library/BaseCpuLib/Ebc/CpuSleepFlushTlb.c index d6346131db..bf1b10374d 100644 --- a/MdePkg/Library/BaseCpuLib/Ebc/CpuSleepFlushTlb.c +++ b/MdePkg/Library/BaseCpuLib/Ebc/CpuSleepFlushTlb.c @@ -1,7 +1,7 @@ /** @file Base Library CPU Functions for EBC - Copyright (c) 2006, Intel Corporation
+ Copyright (c) 2006-2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -16,6 +16,9 @@ /** Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + + Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + **/ VOID EFIAPI diff --git a/MdePkg/Library/BaseCpuLib/Ia32/CpuFlushTlb.c b/MdePkg/Library/BaseCpuLib/Ia32/CpuFlushTlb.c index ff3cf82172..711a1abb6a 100644 --- a/MdePkg/Library/BaseCpuLib/Ia32/CpuFlushTlb.c +++ b/MdePkg/Library/BaseCpuLib/Ia32/CpuFlushTlb.c @@ -1,7 +1,7 @@ /** @file CpuFlushTlb function. - Copyright (c) 2006 - 2007, Intel Corporation
+ Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -15,7 +15,9 @@ /** - Flush TLB of current processor. + Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + + Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. **/ VOID diff --git a/MdePkg/Library/BaseDebugLibNull/DebugLib.c b/MdePkg/Library/BaseDebugLibNull/DebugLib.c index 6fdf6f97a5..7719346682 100644 --- a/MdePkg/Library/BaseDebugLibNull/DebugLib.c +++ b/MdePkg/Library/BaseDebugLibNull/DebugLib.c @@ -12,7 +12,6 @@ **/ - #include #include @@ -23,6 +22,8 @@ the message specified by Format and the associated variable argument list to the debug output device. + If Format is NULL, then ASSERT(). + @param ErrorLevel The error level of the debug message. @param Format Format string for the debug message to print. @param ... Variable argument list whose contents are accessed @@ -44,17 +45,16 @@ DebugPrint ( Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. - Print a message of the form "ASSERT (): \n" + Print a message of the form "ASSERT (): \n" to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then CpuDeadLoop() is called. If neither of these bits are set, then this function returns immediately after the message is printed to the debug output device. - DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while + DebugAssert() must actively prevent recursion. If DebugAssert() is called while processing another DebugAssert(), then DebugAssert() must return immediately. If FileName is NULL, then a string of "(NULL) Filename" is printed. - If Description is NULL, then a string of "(NULL) Description" is printed. @param FileName Pointer to the name of the source file that generated the assert condition. @@ -80,13 +80,12 @@ DebugAssert ( PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - - @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue. + @param Buffer Pointer to the target buffer to be filled with PcdDebugClearMemoryValue. @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. - @return Buffer filled with PcdDebugClearMemoryValue. + @return Buffer Pointer to the target buffer filled with PcdDebugClearMemoryValue. **/ VOID * @@ -108,8 +107,6 @@ DebugClearMemory ( @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set. @retval FALSE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear. - - @return Always return FALSE. **/ BOOLEAN @@ -122,16 +119,14 @@ DebugAssertEnabled ( } -/** - Returns TRUE if the DEBUG() macro is enabled. +/** + Returns TRUE if DEBUG() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. @retval FALSE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear. - - @return Always return FALSE. **/ BOOLEAN @@ -144,16 +139,14 @@ DebugPrintEnabled ( } -/** - Returns TRUE if the DEBUG_CODE() macros are enabled. +/** + Returns TRUE if DEBUG_CODE() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. @retval FALSE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear. - - @return Always return FALSE. **/ BOOLEAN @@ -166,16 +159,14 @@ DebugCodeEnabled ( } -/** - Returns TRUE if the DEBUG_CLEAR_MEMORY() macro is enabled. +/** + Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @retval TRUE The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. @retval FALSE The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear. - - @return Always return FALSE. **/ BOOLEAN diff --git a/MdePkg/Library/BaseDebugLibSerialPort/DebugLib.c b/MdePkg/Library/BaseDebugLibSerialPort/DebugLib.c index 4abdf9cd69..a086e6e992 100644 --- a/MdePkg/Library/BaseDebugLibSerialPort/DebugLib.c +++ b/MdePkg/Library/BaseDebugLibSerialPort/DebugLib.c @@ -21,13 +21,11 @@ #include #include - // // Define the maximum debug and assert message length that this library supports // #define MAX_DEBUG_MESSAGE_LENGTH 0x100 - /** Prints a debug message to the debug output device if the specified error level is enabled. @@ -84,17 +82,16 @@ DebugPrint ( Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. - Print a message of the form "ASSERT (): \n" + Print a message of the form "ASSERT (): \n" to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then CpuDeadLoop() is called. If neither of these bits are set, then this function returns immediately after the message is printed to the debug output device. - DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while + DebugAssert() must actively prevent recursion. If DebugAssert() is called while processing another DebugAssert(), then DebugAssert() must return immediately. If FileName is NULL, then a string of "(NULL) Filename" is printed. - If Description is NULL, then a string of "(NULL) Description" is printed. @param FileName Pointer to the name of the source file that generated the assert condition. @@ -140,13 +137,12 @@ DebugAssert ( PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). - - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). @param Buffer Pointer to the target buffer to be filled with PcdDebugClearMemoryValue. @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. - @return Buffer filled with PcdDebugClearMemoryValue. + @return Buffer Pointer to the target buffer filled with PcdDebugClearMemoryValue. **/ VOID * @@ -188,8 +184,8 @@ DebugAssertEnabled ( } -/** - Returns TRUE if the DEBUG() macro is enabled. +/** + Returns TRUE if DEBUG() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -208,8 +204,8 @@ DebugPrintEnabled ( } -/** - Returns TRUE if the DEBUG_CODE() macros are enabled. +/** + Returns TRUE if DEBUG_CODE() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -228,8 +224,8 @@ DebugCodeEnabled ( } -/** - Returns TRUE if the DEBUG_CLEAR_MEMORY() macro is enabled. +/** + Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. diff --git a/MdePkg/Library/DxeCoreHobLib/HobLib.c b/MdePkg/Library/DxeCoreHobLib/HobLib.c index 302d1bbd8c..e238aa35db 100644 --- a/MdePkg/Library/DxeCoreHobLib/HobLib.c +++ b/MdePkg/Library/DxeCoreHobLib/HobLib.c @@ -1,19 +1,17 @@ /** @file HOB Library implementation for DxeCore driver. - Copyright (c) 2006 - 2008, Intel Corporation
- All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2006 - 2008, Intel Corporation
+All rights reserved. This program and the accompanying materials +are licensed and made available under the terms and conditions of the BSD License +which accompanies this distribution. The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ - - #include #include @@ -23,10 +21,17 @@ /** Returns the pointer to the HOB list. - ASSERT() if the HOB list returned by GetHobList() is NULL. This function returns the pointer to first HOB in the list. - + For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer + to the HOB list. For the DXE phase, the HOB list pointer can be retrieved through + the EFI System Table by looking up theHOB list GUID in the System Configuration Table. + Since the System Configuration Table does not exist that the time the DXE Core is + launched, the DXE Core uses a global variable from the DXE Core Entry Point Library + to manage the pointer to the HOB list. + + If the pointer to the HOB list is NULL, then ASSERT(). + @return The pointer to the HOB list. **/ @@ -43,11 +48,12 @@ GetHobList ( /** Returns the next instance of a HOB type from the starting HOB. - This function searches the first instance of a HOB type from the starting HOB pointer. + This function searches the first instance of a HOB type from the starting HOB pointer. If there does not exist such HOB type from the starting HOB pointer, it will return NULL. In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). @param Type The HOB type to return. @@ -83,8 +89,10 @@ GetNextHob ( /** Returns the first instance of a HOB type among the whole HOB list. - This function searches the first instance of a HOB type among the whole HOB list. - If there does not exist such HOB type in the HOB list, it will return NULL. + This function searches the first instance of a HOB type among the whole HOB list. + If there does not exist such HOB type in the HOB list, it will return NULL. + + If the pointer to the HOB list is NULL, then ASSERT(). @param Type The HOB type to return. @@ -104,15 +112,18 @@ GetFirstHob ( } /** - This function searches the first instance of a HOB from the starting HOB pointer. - Such HOB should satisfy two conditions: - its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. - If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Returns the next instance of the matched GUID HOB from the starting HOB. + + This function searches the first instance of a HOB from the starting HOB pointer. + Such HOB should satisfy two conditions: + its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. + If there does not exist such HOB from the starting HOB pointer, it will return NULL. Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its size info respectively. In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). If HobStart is NULL, then ASSERT(). @@ -142,12 +153,16 @@ GetNextGuidHob ( } /** - This function searches the first instance of a HOB among the whole HOB list. + Returns the first instance of the matched GUID HOB among the whole HOB list. + + This function searches the first instance of a HOB among the whole HOB list. Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its size info respectively. + + If the pointer to the HOB list is NULL, then ASSERT(). If Guid is NULL, then ASSERT(). @param Guid The GUID to match with in the HOB list. @@ -168,11 +183,13 @@ GetFirstGuidHob ( } /** - Get the Boot Mode from the HOB list. + Get the system boot mode from the HOB list. - This function returns the system boot mode information from the + This function returns the system boot mode information from the PHIT HOB in HOB list. + If the pointer to the HOB list is NULL, then ASSERT(). + @param VOID @return The Boot Mode. @@ -190,19 +207,21 @@ GetBootModeHob ( return HandOffHob->BootMode; } + /** Builds a HOB for a loaded PE32 module. This function builds a HOB for a loaded PE32 module. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @param ModuleName The GUID File Name of the module. @param MemoryAllocationModule The 64 bit physical address of the module. @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module's entry point. + @param EntryPoint The 64 bit physical address of the module entry point. **/ VOID @@ -226,6 +245,7 @@ BuildModuleHob ( This function builds a HOB that describes a chunk of system memory. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param ResourceType The type of resource described by this HOB. @@ -250,13 +270,15 @@ BuildResourceDescriptorHob ( } /** - Builds a GUID HOB with a certain data length. + Builds a customized HOB tagged with a GUID for identification and returns + the start address of GUID HOB data. - This function builds a customized HOB tagged with a GUID for identification - and returns the start address of GUID HOB data so that caller can fill the customized data. + This function builds a customized HOB tagged with a GUID for identification + and returns the start address of GUID HOB data so that caller can fill the customized data. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT(). @@ -282,13 +304,16 @@ BuildGuidHob ( } /** - Copies a data buffer to a newly-built HOB. + Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB + data field, and returns the start address of the GUID HOB data. - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field and returns the start address of the GUID HOB data. + This function builds a customized HOB tagged with a GUID for identification and copies the input + data to the HOB data field and returns the start address of the GUID HOB data. It can only be + invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If Data is NULL and DataLength > 0, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @@ -322,6 +347,7 @@ BuildGuidDataHob ( This function builds a Firmware Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @@ -347,11 +373,12 @@ BuildFvHob ( This function builds a EFI_HOB_TYPE_FV2 HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @param Length The size of the Firmware Volume in bytes. - @param FvName The name of the Firmware Volume. + @param FvName The name of the Firmware Volume. @param FileName The name of the file. **/ @@ -373,6 +400,7 @@ BuildFv2Hob ( This function builds a Capsule Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Capsule Volume. @@ -398,6 +426,7 @@ BuildCvHob ( This function builds a HOB for the CPU. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param SizeOfMemorySpace The maximum physical memory addressability of the processor. @@ -423,6 +452,7 @@ BuildCpuHob ( This function builds a HOB for the stack. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the Stack. @@ -448,6 +478,7 @@ BuildStackHob ( This function builds a HOB for BSP store. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the BSP. @@ -475,6 +506,7 @@ BuildBspStoreHob ( This function builds a HOB for the memory allocation. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the memory. diff --git a/MdePkg/Library/DxeHobLib/HobLib.c b/MdePkg/Library/DxeHobLib/HobLib.c index 2e41453a16..9d226fa5ee 100644 --- a/MdePkg/Library/DxeHobLib/HobLib.c +++ b/MdePkg/Library/DxeHobLib/HobLib.c @@ -1,19 +1,17 @@ /** @file HOB Library implemenation for Dxe Phase. - Copyright (c) 2006 - 2008, Intel Corporation
- All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2006 - 2008, Intel Corporation
+All rights reserved. This program and the accompanying materials +are licensed and made available under the terms and conditions of the BSD License +which accompanies this distribution. The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ - - #include #include @@ -56,10 +54,17 @@ HobLibConstructor ( /** Returns the pointer to the HOB list. - ASSERT() if the HOB list returned by GetHobList() is NULL. This function returns the pointer to first HOB in the list. - + For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer + to the HOB list. For the DXE phase, the HOB list pointer can be retrieved through + the EFI System Table by looking up theHOB list GUID in the System Configuration Table. + Since the System Configuration Table does not exist that the time the DXE Core is + launched, the DXE Core uses a global variable from the DXE Core Entry Point Library + to manage the pointer to the HOB list. + + If the pointer to the HOB list is NULL, then ASSERT(). + @return The pointer to the HOB list. **/ @@ -81,6 +86,7 @@ GetHobList ( In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). @param Type The HOB type to return. @@ -118,6 +124,8 @@ GetNextHob ( This function searches the first instance of a HOB type among the whole HOB list. If there does not exist such HOB type in the HOB list, it will return NULL. + + If the pointer to the HOB list is NULL, then ASSERT(). @param Type The HOB type to return. @@ -137,6 +145,8 @@ GetFirstHob ( } /** + Returns the next instance of the matched GUID HOB from the starting HOB. + This function searches the first instance of a HOB from the starting HOB pointer. Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. @@ -146,6 +156,7 @@ GetFirstHob ( In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). If HobStart is NULL, then ASSERT(). @@ -175,12 +186,16 @@ GetNextGuidHob ( } /** + Returns the first instance of the matched GUID HOB among the whole HOB list. + This function searches the first instance of a HOB among the whole HOB list. Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its size info respectively. + + If the pointer to the HOB list is NULL, then ASSERT(). If Guid is NULL, then ASSERT(). @param Guid The GUID to match with in the HOB list. @@ -201,11 +216,13 @@ GetFirstGuidHob ( } /** - Get the Boot Mode from the HOB list. + Get the system boot mode from the HOB list. This function returns the system boot mode information from the - PHIT HOB in HOB list. If PHIT HOB is NULL, then ASSERT(). + PHIT HOB in HOB list. + If the pointer to the HOB list is NULL, then ASSERT(). + @param VOID @return The Boot Mode. @@ -230,13 +247,14 @@ GetBootModeHob ( This function builds a HOB for a loaded PE32 module. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @param ModuleName The GUID File Name of the module. @param MemoryAllocationModule The 64 bit physical address of the module. @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module's entry point. + @param EntryPoint The 64 bit physical address of the module entry point. **/ VOID @@ -260,6 +278,7 @@ BuildModuleHob ( This function builds a HOB that describes a chunk of system memory. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param ResourceType The type of resource described by this HOB. @@ -284,13 +303,15 @@ BuildResourceDescriptorHob ( } /** - Builds a GUID HOB with a certain data length. + Builds a customized HOB tagged with a GUID for identification and returns + the start address of GUID HOB data. This function builds a customized HOB tagged with a GUID for identification and returns the start address of GUID HOB data so that caller can fill the customized data. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT(). @@ -316,13 +337,16 @@ BuildGuidHob ( } /** - Copies a data buffer to a newly-built HOB. + Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB + data field, and returns the start address of the GUID HOB data. - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field and returns the start address of the GUID HOB data. + This function builds a customized HOB tagged with a GUID for identification and copies the input + data to the HOB data field and returns the start address of the GUID HOB data. It can only be + invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If Data is NULL and DataLength > 0, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @@ -356,6 +380,7 @@ BuildGuidDataHob ( This function builds a Firmware Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @@ -381,11 +406,12 @@ BuildFvHob ( This function builds a EFI_HOB_TYPE_FV2 HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @param Length The size of the Firmware Volume in bytes. - @param FvName The name of the Firmware Volume. + @param FvName The name of the Firmware Volume. @param FileName The name of the file. **/ @@ -408,6 +434,7 @@ BuildFv2Hob ( This function builds a Capsule Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Capsule Volume. @@ -433,6 +460,7 @@ BuildCvHob ( This function builds a HOB for the CPU. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param SizeOfMemorySpace The maximum physical memory addressability of the processor. @@ -458,6 +486,7 @@ BuildCpuHob ( This function builds a HOB for the stack. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the Stack. @@ -483,6 +512,7 @@ BuildStackHob ( This function builds a HOB for BSP store. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the BSP. @@ -510,6 +540,7 @@ BuildBspStoreHob ( This function builds a HOB for the memory allocation. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the memory. diff --git a/MdePkg/Library/DxeServicesLib/DxeServicesLib.c b/MdePkg/Library/DxeServicesLib/DxeServicesLib.c index b03d019fbb..cb3450904c 100644 --- a/MdePkg/Library/DxeServicesLib/DxeServicesLib.c +++ b/MdePkg/Library/DxeServicesLib/DxeServicesLib.c @@ -190,12 +190,12 @@ InternalGetSectionFromFv ( @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. @@ -307,13 +307,13 @@ Done: @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. @@ -363,12 +363,12 @@ GetSectionFromFv ( @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(). + Is it the caller's responsibility 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_OUT_OF_RESOURCES There are not enough resources 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. diff --git a/MdePkg/Library/PeiExtractGuidedSectionLib/PeiExtractGuidedSectionLib.c b/MdePkg/Library/PeiExtractGuidedSectionLib/PeiExtractGuidedSectionLib.c index 1633f1b8f4..90cd8e8998 100644 --- a/MdePkg/Library/PeiExtractGuidedSectionLib/PeiExtractGuidedSectionLib.c +++ b/MdePkg/Library/PeiExtractGuidedSectionLib/PeiExtractGuidedSectionLib.c @@ -36,7 +36,7 @@ typedef struct { @param[in, out] InfoPointer Pointer to pei handler info structure. - @retval RETURN_SUCCESS Build Guid hob for the global memory space to store guid and funciton tables. + @retval RETURN_SUCCESS Build Guid hob for the global memory space to store guid and function tables. @retval RETURN_OUT_OF_RESOURCES No enough memory to allocated. **/ RETURN_STATUS @@ -125,9 +125,10 @@ PeiGetExtractGuidedSectionHandlerInfo ( Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs. The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated and caller must treat this array of GUIDs as read-only data. + If ExtractHandlerGuidTable is NULL, then ASSERT(). - @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs tht have been registerd through + @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs that have been registered through ExtractGuidedSectionRegisterHandlers(). @return the number of the supported extract guided Handler. @@ -163,9 +164,10 @@ ExtractGuidedSectionGetGuidList ( Registers handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER for a specific GUID section type. - Registers the handlers specified by GetInfoHandler and DecodeHandler witg the GUID specified by SectionGuid. + Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid. If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED. If there are not enough resources available to register the handlers then RETURN_OUT_OF_RESOURCES is returned. + If SectionGuid is NULL, then ASSERT(). If GetInfoHandler is NULL, then ASSERT(). If DecodeHandler is NULL, then ASSERT(). @@ -244,7 +246,7 @@ ExtractGuidedSectionRegisterHandlers ( } /** - Retrives a GUID from a GUIDed section and uses that GUID to select an associated handler of type + Retrieves a GUID from a GUIDed section and uses that GUID to select an associated handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers(). The selected handler is used to retrieve and return the size of the decoded buffer and the size of an optional scratch buffer required to actually decode the data in a GUIDed section. @@ -256,6 +258,7 @@ ExtractGuidedSectionRegisterHandlers ( of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers() is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned. + If InputSection is NULL, then ASSERT(). If OutputBufferSize is NULL, then ASSERT(). If ScratchBufferSize is NULL, then ASSERT(). @@ -311,7 +314,7 @@ ExtractGuidedSectionGetInfo ( for (Index = 0; Index < HandlerInfo->NumberOfExtractHandler; Index ++) { if (CompareGuid (HandlerInfo->ExtractHandlerGuidTable + Index, &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) { // - // Call the match handler to getinfo for the input section data. + // Call the match handler to get info for the input section data. // return HandlerInfo->ExtractGetInfoHandlerTable [Index] ( InputSection, @@ -329,7 +332,7 @@ ExtractGuidedSectionGetInfo ( } /** - Retrives the GUID from a GUIDed section and uses that GUID to select an associated handler of type + Retrieves the GUID from a GUIDed section and uses that GUID to select an associated handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers(). The selected handler is used to decode the data in a GUIDed section and return the result in a caller allocated output buffer. @@ -343,7 +346,8 @@ ExtractGuidedSectionGetInfo ( decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller allocated buffer specified by OutputBuffer. This function is responsible for computing the EFI_AUTH_STATUS_PLATFORM_OVERRIDE - bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. + bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. + If InputSection is NULL, then ASSERT(). If OutputBuffer is NULL, then ASSERT(). If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT(). diff --git a/MdePkg/Library/PeiHobLib/HobLib.c b/MdePkg/Library/PeiHobLib/HobLib.c index 1d58479296..476ea06dbc 100644 --- a/MdePkg/Library/PeiHobLib/HobLib.c +++ b/MdePkg/Library/PeiHobLib/HobLib.c @@ -1,18 +1,17 @@ /** @file Provide Hob Library functions for Pei phase. - Copyright (c) 2007 - 2008, Intel Corporation
- All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2007 - 2008, Intel Corporation
+All rights reserved. This program and the accompanying materials +are licensed and made available under the terms and conditions of the BSD License +which accompanies this distribution. The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ - #include #include @@ -24,10 +23,17 @@ /** Returns the pointer to the HOB list. - ASSERT() if the HOB list returned by GetHobList() is NULL. This function returns the pointer to first HOB in the list. - + For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer + to the HOB list. For the DXE phase, the HOB list pointer can be retrieved through + the EFI System Table by looking up theHOB list GUID in the System Configuration Table. + Since the System Configuration Table does not exist that the time the DXE Core is + launched, the DXE Core uses a global variable from the DXE Core Entry Point Library + to manage the pointer to the HOB list. + + If the pointer to the HOB list is NULL, then ASSERT(). + @return The pointer to the HOB list. **/ @@ -55,6 +61,7 @@ GetHobList ( In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). @param Type The HOB type to return. @@ -92,6 +99,8 @@ GetNextHob ( This function searches the first instance of a HOB type among the whole HOB list. If there does not exist such HOB type in the HOB list, it will return NULL. + + If the pointer to the HOB list is NULL, then ASSERT(). @param Type The HOB type to return. @@ -111,6 +120,8 @@ GetFirstHob ( } /** + Returns the next instance of the matched GUID HOB from the starting HOB. + This function searches the first instance of a HOB from the starting HOB pointer. Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. @@ -120,6 +131,7 @@ GetFirstHob ( In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer unconditionally: it returns HobStart back if HobStart itself meets the requirement; caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). If HobStart is NULL, then ASSERT(). @@ -149,12 +161,16 @@ GetNextGuidHob ( } /** + Returns the first instance of the matched GUID HOB among the whole HOB list. + This function searches the first instance of a HOB among the whole HOB list. Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its size info respectively. + + If the pointer to the HOB list is NULL, then ASSERT(). If Guid is NULL, then ASSERT(). @param Guid The GUID to match with in the HOB list. @@ -175,11 +191,13 @@ GetFirstGuidHob ( } /** - Get the Boot Mode from the HOB list. + Get the system boot mode from the HOB list. - This function returns the system boot mode information - by PeiCore GetBootMode Service. + This function returns the system boot mode information from the + PHIT HOB in HOB list. + If the pointer to the HOB list is NULL, then ASSERT(). + @param VOID @return The Boot Mode. @@ -235,13 +253,14 @@ InternalPeiCreateHob ( This function builds a HOB for a loaded PE32 module. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @param ModuleName The GUID File Name of the module. @param MemoryAllocationModule The 64 bit physical address of the module. @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module's entry point. + @param EntryPoint The 64 bit physical address of the module entry point. **/ VOID @@ -280,6 +299,7 @@ BuildModuleHob ( This function builds a HOB that describes a chunk of system memory. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param ResourceType The type of resource described by this HOB. @@ -308,13 +328,15 @@ BuildResourceDescriptorHob ( } /** - Builds a GUID HOB with a certain data length. + Builds a customized HOB tagged with a GUID for identification and returns + the start address of GUID HOB data. This function builds a customized HOB tagged with a GUID for identification and returns the start address of GUID HOB data so that caller can fill the customized data. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT(). @@ -345,13 +367,16 @@ BuildGuidHob ( } /** - Copies a data buffer to a newly-built HOB. + Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB + data field, and returns the start address of the GUID HOB data. - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field and returns the start address of the GUID HOB data. + This function builds a customized HOB tagged with a GUID for identification and copies the input + data to the HOB data field and returns the start address of the GUID HOB data. It can only be + invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. The HOB Header and Name field is already stripped. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). If Data is NULL and DataLength > 0, then ASSERT(). If there is no additional space for HOB creation, then ASSERT(). @@ -387,6 +412,7 @@ BuildGuidDataHob ( This function builds a Firmware Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @@ -414,11 +440,12 @@ BuildFvHob ( This function builds a EFI_HOB_TYPE_FV2 HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Firmware Volume. @param Length The size of the Firmware Volume in bytes. - @param FvName The name of the Firmware Volume. + @param FvName The name of the Firmware Volume. @param FileName The name of the file. **/ @@ -447,6 +474,7 @@ BuildFv2Hob ( This function builds a Capsule Volume HOB. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The base address of the Capsule Volume. @@ -469,6 +497,7 @@ BuildCvHob ( This function builds a HOB for the CPU. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param SizeOfMemorySpace The maximum physical memory addressability of the processor. @@ -501,6 +530,7 @@ BuildCpuHob ( This function builds a HOB for the stack. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the Stack. @@ -538,6 +568,7 @@ BuildStackHob ( This function builds a HOB for BSP store. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the BSP. @@ -577,6 +608,7 @@ BuildBspStoreHob ( This function builds a HOB for the memory allocation. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). @param BaseAddress The 64 bit physical address of the memory. diff --git a/MdePkg/Library/UefiDebugLibConOut/DebugLib.c b/MdePkg/Library/UefiDebugLibConOut/DebugLib.c index 7f93509b2d..f416bcb3c0 100644 --- a/MdePkg/Library/UefiDebugLibConOut/DebugLib.c +++ b/MdePkg/Library/UefiDebugLibConOut/DebugLib.c @@ -12,10 +12,8 @@ **/ - #include - #include #include #include @@ -23,15 +21,12 @@ #include #include - // // Define the maximum debug and assert message length that this library supports // #define MAX_DEBUG_MESSAGE_LENGTH 0x100 - /** - Prints a debug message to the debug output device if the specified error level is enabled. If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print @@ -87,21 +82,19 @@ DebugPrint ( /** - Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. - Print a message of the form "ASSERT (): \n" + Print a message of the form "ASSERT (): \n" to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then CpuDeadLoop() is called. If neither of these bits are set, then this function returns immediately after the message is printed to the debug output device. - DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while + DebugAssert() must actively prevent recursion. If DebugAssert() is called while processing another DebugAssert(), then DebugAssert() must return immediately. If FileName is NULL, then a string of "(NULL) Filename" is printed. - If Description is NULL, then a string of "(NULL) Description" is printed. @param FileName Pointer to the name of the source file that generated the assert condition. @@ -150,15 +143,13 @@ DebugAssert ( /** - Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer. This function fills Length bytes of Buffer with the value specified by PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). - - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). @param Buffer Pointer to the target buffer to be filled with PcdDebugClearMemoryValue. @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. @@ -186,7 +177,6 @@ DebugClearMemory ( /** - Returns TRUE if ASSERT() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of @@ -206,9 +196,8 @@ DebugAssertEnabled ( } -/** - - Returns TRUE if DEBUG()macros are enabled. +/** + Returns TRUE if DEBUG() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -227,9 +216,8 @@ DebugPrintEnabled ( } -/** - - Returns TRUE if DEBUG_CODE()macros are enabled. +/** + Returns TRUE if DEBUG_CODE() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -248,9 +236,8 @@ DebugCodeEnabled ( } -/** - - Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled. +/** + Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. diff --git a/MdePkg/Library/UefiDebugLibStdErr/DebugLib.c b/MdePkg/Library/UefiDebugLibStdErr/DebugLib.c index 608ed26929..6d5ae16e73 100644 --- a/MdePkg/Library/UefiDebugLibStdErr/DebugLib.c +++ b/MdePkg/Library/UefiDebugLibStdErr/DebugLib.c @@ -15,7 +15,6 @@ #include - #include #include #include @@ -30,7 +29,6 @@ /** - Prints a debug message to the debug output device if the specified error level is enabled. If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print @@ -85,21 +83,19 @@ DebugPrint ( /** - Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. - Print a message of the form "ASSERT (): \n" + Print a message of the form "ASSERT (): \n" to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then CpuDeadLoop() is called. If neither of these bits are set, then this function returns immediately after the message is printed to the debug output device. - DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while + DebugAssert() must actively prevent recursion. If DebugAssert() is called while processing another DebugAssert(), then DebugAssert() must return immediately. If FileName is NULL, then a string of "(NULL) Filename" is printed. - If Description is NULL, then a string of "(NULL) Description" is printed. @param FileName Pointer to the name of the source file that generated the assert condition. @@ -148,17 +144,15 @@ DebugAssert ( /** - Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer. This function fills Length bytes of Buffer with the value specified by PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - - @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue. + @param Buffer Pointer to the target buffer to be filled with PcdDebugClearMemoryValue. @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. @return Buffer Pointer to the target buffer filled with PcdDebugClearMemoryValue. @@ -184,7 +178,6 @@ DebugClearMemory ( /** - Returns TRUE if ASSERT() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of @@ -204,9 +197,8 @@ DebugAssertEnabled ( } -/** - - Returns TRUE if DEBUG()macros are enabled. +/** + Returns TRUE if DEBUG() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -225,9 +217,8 @@ DebugPrintEnabled ( } -/** - - Returns TRUE if DEBUG_CODE()macros are enabled. +/** + Returns TRUE if DEBUG_CODE() macros are enabled. This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. @@ -246,9 +237,8 @@ DebugCodeEnabled ( } -/** - - Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled. +/** + Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise FALSE is returned. diff --git a/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c b/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c index 708b48a088..8bdb598f88 100644 --- a/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c +++ b/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c @@ -50,8 +50,9 @@ GLOBAL_REMOVE_IF_UNREFERENCED CONST EFI_DEVICE_PATH_PROTOCOL mUefiDevicePathLib DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned. @param DevicePath A pointer to a device path data structure. - - @return The size of a device path in bytes. + + @retval 0 If DevicePath is NULL. + @retval Others The size of a device path in bytes. **/ UINTN @@ -87,11 +88,14 @@ GetDevicePathSize ( DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer is returned. Otherwise, NULL is returned. + The memory for the new device path is allocated from EFI boot services memory. + It is the responsibility of the caller to free the memory allocated. @param DevicePath A pointer to a device path data structure. - @return A pointer to the duplicated device path. - + @retval NULL If DevicePath is NULL. + @retval Others A pointer to the duplicated device path. + **/ EFI_DEVICE_PATH_PROTOCOL * EFIAPI @@ -132,8 +136,10 @@ DuplicateDevicePath ( @param FirstDevicePath A pointer to a device path data structure. @param SecondDevicePath A pointer to a device path data structure. - - @return A pointer to the new device path. + + @retval NULL If there is not enough memory for the newly allocated buffer. + @retval Others A pointer to the new device path if success. + Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -201,7 +207,11 @@ AppendDevicePath ( @param DevicePath A pointer to a device path data structure. @param DevicePathNode A pointer to a single device path node. - @return A pointer to the new device path. + @retval NULL If there is not enough memory for the new device path. + @retval Others A pointer to the new device path if success. + A copy of DevicePathNode followed by an end-of-device-path node + if both FirstDevicePath and SecondDevicePath are NULL. + A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -381,8 +391,7 @@ GetNextDevicePathInstance ( } /** - Creates a copy of the current device path instance and returns a pointer to the next device path - instance. + Creates a device node. This function creates a new device node in a newly allocated buffer of size NodeLength and initializes the device path node header with NodeType and NodeSubType. The new device path node @@ -396,7 +405,7 @@ GetNextDevicePathInstance ( @param NodeSubType The device node sub-type for the new device node. @param NodeLength The length of the new device node. - @return A pointer to the new create device path. + @return The new device path. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -502,13 +511,17 @@ DevicePathFromHandle ( handle Device. The allocated device path is returned. If Device is NULL or Device is a handle that does not support the device path protocol, then a device path containing a single device path node for the file specified by FileName is allocated and returned. + The memory for the new device path is allocated from EFI boot services memory. It is the responsibility + of the caller to free the memory allocated. + If FileName is NULL, then ASSERT(). + If FileName is not aligned on a 16-bit boundary, then ASSERT(). @param Device A pointer to a device handle. This parameter is optional and may be NULL. @param FileName A pointer to a Null-terminated Unicode string. - @return A pointer to the new created file device path. + @return The allocated device path. **/ EFI_DEVICE_PATH_PROTOCOL * diff --git a/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c b/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c index 37a0ae792b..1380a03d16 100644 --- a/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c +++ b/MdePkg/Library/UefiDevicePathLibDevicePathProtocol/UefiDevicePathLib.c @@ -67,8 +67,9 @@ DevicePathLibConstructor ( DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned. @param DevicePath A pointer to a device path data structure. - - @return The size of a device path in bytes. + + @retval 0 If DevicePath is NULL. + @retval Others The size of a device path in bytes. **/ UINTN @@ -87,11 +88,14 @@ GetDevicePathSize ( DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer is returned. Otherwise, NULL is returned. + The memory for the new device path is allocated from EFI boot services memory. + It is the responsibility of the caller to free the memory allocated. @param DevicePath A pointer to a device path data structure. - @return A pointer to the duplicated device path. - + @retval NULL If DevicePath is NULL. + @retval Others A pointer to the duplicated device path. + **/ EFI_DEVICE_PATH_PROTOCOL * EFIAPI @@ -118,8 +122,10 @@ DuplicateDevicePath ( @param FirstDevicePath A pointer to a device path data structure. @param SecondDevicePath A pointer to a device path data structure. - - @return A pointer to the new device path. + + @retval NULL If there is not enough memory for the newly allocated buffer. + @retval Others A pointer to the new device path if success. + Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -150,7 +156,11 @@ AppendDevicePath ( @param DevicePath A pointer to a device path data structure. @param DevicePathNode A pointer to a single device path node. - @return A pointer to the new device path. + @retval NULL If there is not enough memory for the new device path. + @retval Others A pointer to the new device path if success. + A copy of DevicePathNode followed by an end-of-device-path node + if both FirstDevicePath and SecondDevicePath are NULL. + A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -229,8 +239,7 @@ GetNextDevicePathInstance ( } /** - Creates a copy of the current device path instance and returns a pointer to the next device path - instance. + Creates a device node. This function creates a new device node in a newly allocated buffer of size NodeLength and initializes the device path node header with NodeType and NodeSubType. The new device path node @@ -244,7 +253,7 @@ GetNextDevicePathInstance ( @param NodeSubType The device node sub-type for the new device node. @param NodeLength The length of the new device node. - @return A pointer to the new created file device path + @return The new device path. **/ EFI_DEVICE_PATH_PROTOCOL * @@ -318,13 +327,17 @@ DevicePathFromHandle ( handle Device. The allocated device path is returned. If Device is NULL or Device is a handle that does not support the device path protocol, then a device path containing a single device path node for the file specified by FileName is allocated and returned. + The memory for the new device path is allocated from EFI boot services memory. It is the responsibility + of the caller to free the memory allocated. + If FileName is NULL, then ASSERT(). + If FileName is not aligned on a 16-bit boundary, then ASSERT(). @param Device A pointer to a device handle. This parameter is optional and may be NULL. @param FileName A pointer to a Null-terminated Unicode string. - @return A pointer to the new created file device path + @return The allocated device path. **/ EFI_DEVICE_PATH_PROTOCOL * -- 2.39.2