From bbcdc0b7d9822c1014d563aaf12d8f43aea1a2e1 Mon Sep 17 00:00:00 2001 From: "Doug Cook (WINDOWS)" Date: Sat, 30 Nov 2024 20:21:52 -0800 Subject: MdePkg: Improve comments on DebugLib PCDs DebugLib PCDs are very important, but they're confusing and not well-explained anywhere. Improve the documentation comments for them to explain how they work and how they relate to each other. Signed-off-by: Doug Cook --- MdePkg/MdePkg.dec | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) (limited to 'MdePkg') diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 624f626360..7215a44ad7 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -2222,8 +2222,15 @@ # @ValidList 0x80000003 | 0x3040003 gEfiMdePkgTokenSpaceGuid.PcdStatusCodeValueDxeDriverEnd|0x3040003|UINT32|0x30001014 - ## This flag is used to control build time optimization based on debug print level. - # Its default value is 0xFFFFFFFF to expose all debug print level. + ## This flag is used to control fixed-at-build optimization of DEBUG_PRINT macros.

+ # The default value is 0xFFFFFFFF, meaning that DEBUG_PRINT (...) always evaluates + # the macro arguments and always invokes DebugPrint (...). If you want to optimize + # messages, you might set this to a more restrictive value like 0x80000002 (optimize-out + # everything except errors and warnings).

+ # This flag is consumed by DebugLib's DebugPrintLevelEnabled (Level) function. The + # DEBUG_PRINT (Level, Format, ...) macro in DebugLib.h calls DebugPrintLevelEnabled (Level) + # to filter the output, and most implementations of DebugPrintLevelEnabled (Level) simply + # return (Level & PcdFixedDebugPrintErrorLevel) != 0.

# BIT0 - Initialization message.
# BIT1 - Warning message.
# BIT2 - Load Event message.
@@ -2307,17 +2314,30 @@ gEfiMdePkgTokenSpaceGuid.PcdSpinLockTimeout|10000000|UINT32|0x00000004 ## The mask is used to control DebugLib behavior.

- # BIT0 - Enable Debug Assert.
- # BIT1 - Enable Debug Print.
- # BIT2 - Enable Debug Code.
- # BIT3 - Enable Clear Memory.
- # BIT4 - Enable BreakPoint as ASSERT.
- # BIT5 - Enable DeadLoop as ASSERT.
+ # Note that if the MDEPKG_NDEBUG macro is defined, the ASSERT***, CR, and DEBUG macros will be + # no-ops regardless of this value.
+ # Note that MDEPKG_NDEBUG does not affect DEBUG_PRINT.

+ # BIT0 - ASSERT_ENABLED: Enable the ASSERT*** and CR macros.
+ # BIT1 - PRINT_ENABLED: Enable the DEBUG macro (does not affect the DEBUG_PRINT macro).
+ # BIT2 - CODE_ENABLED: Enable the DEBUG_CODE_BEGIN macro.
+ # BIT3 - CLEAR_MEMORY_ENABLED: Enable the DEBUG_CLEAR_MEMORY macro.
+ # BIT4 - ASSERT_BREAKPOINT_ENABLED: Enable BreakPoint for failed ASSERT.
+ # BIT5 - ASSERT_DEADLOOP_ENABLED: Enable DeadLoop for failed ASSERT.
# @Prompt Debug Property. # @Expression 0x80000002 | (gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask & 0xC0) == 0 gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0|UINT8|0x00000005 - ## This flag is used to control the print out Debug message.

+ ## This flag is used to filter the output of the DEBUG_PRINT macro and DebugPrint functions.

+ # The default value is 0x80000000, meaning that DebugPrint returns immediately for anything + # except errors. You might set this to a value like 0x80000002 to also enable warnings.

+ # This flag is consumed by the BaseDebugPrintErrorLevelLib implementation of + # GetDebugPrintErrorLevel (). DebugLib's DebugPrint (Level, ...) functions return immediately if + # (GetDebugPrintErrorLevel() & Level) == 0. Other implementations of DebugPrintErrorLevelLib + # may provide different definitions of GetDebugPrintErrorLevel ().

+ # Note that the DEBUG_PRINT macro also uses PcdFixedDebugPrintErrorLevel to determine whether + # or not it calls the DebugPrint function, so your message level needs to be enabled in both + # PcdFixedDebugPrintErrorLevel and PcdDebugPrintErrorLevel settings for the DEBUG_PRINT macro + # to work.

# BIT0 - Initialization message.
# BIT1 - Warning message.
# BIT2 - Load Event message.
-- cgit