EDK II Debugging

Basic Concepts

EDK II Debug methods enable the following debug techniques:

• Use DEBUG macros instead of inline Print() functions for debug messages
• Use ASSERT macros to halt code execution on critical issues
• Use a software debugger (COM/USB)
• Use a hardware debugger (JTAG/XDB)

The EDK II Debug Library (MdePkg\Include\Library\DebugLib.h) is a portable library supporting DEBUG and ASSERT macros, which can be enabled/disabled during compilation in target.txt. These are designed to work with a second computer attached as a terminal to observe an ASCII debug log.

Debug Macros

• DEBUG (Expression)
• DEBUG_CODE (Expression)
• DEBUG_CODE_BEGIN() & DEBUG_CODE_END()
• DEBUG_CLEAR_MEMORY(...)

Assert Macros

• ASSERT (Expression)
• ASSERT_EFI_ERROR (StatusParameter)
• ASSERT_PROTOCOL_ALREADY_INSTALLED(...)

PCDs to configure DebugLib

The MdePkg Debug Library Class defines two PCDs

• PcdDebugPropertyMask - Bit mask to determine which features are on/off
• PcdDebugPrintErrorLevel - Types of messages produced

Example from Nt32Pkg.dsc:

[PcdsFixedAtBuild.IA32]
 . . .
  gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x1f
  gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x80000040

Definition of PcdDebugPropertyMask bitmask field:

#define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED       0x01
#define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED        0x02
#define DEBUG_PROPERTY_DEBUG_CODE_ENABLED         0x04
#define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED       0x08
#define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED  0x10
#define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED    0x20

Definition of PcdDebugPrintErrorLevel bitmask field:

#define DEBUG_INIT      0x00000001  // Initialization
#define DEBUG_WARN      0x00000002  // Warnings
#define DEBUG_LOAD      0x00000004  // Load events
#define DEBUG_FS        0x00000008  // EFI File system
#define DEBUG_POOL      0x00000010  // Alloc & Free's  Pool
#define DEBUG_PAGE      0x00000020  // Alloc & Free's  Page
#define DEBUG_INFO      0x00000040  // Verbose
#define DEBUG_DISPATCH  0x00000080  // PEI/DXE Dispatchers
#define DEBUG_VARIABLE  0x00000100  //Variable
#define DEBUG_BM        0x00000400  // Boot Manager
#define DEBUG_BLKIO     0x00001000  // BlkIo Driver
#define DEBUG_NET       0x00004000  // SNI Driver
#define DEBUG_UNDI      0x00010000  // UNDI Driver
#define DEBUG_LOADFILE  0x00020000  // Load File 
#define DEBUG_EVENT     0x00080000  // Event messages
#define DEBUG_ERROR     0x80000000  // Error