31.4 Debugging code statements

A UEFI Driver may be implemented to support both a debug (check) build and a production build. The debug build includes code that helps debug a UEFI Driver that is not included in normal production builds. UEFI Driver sources are typically implemented with all the debug build statements included. The DSC file used to build the UEFI Driver with the EDK II build tools contains statements to select a debug build or a production build with no source changes to the UEFI Driver.
The EDK II library class called DebugLib provides macros that can be used to insert debug code into a checked build. This debug code can greatly reduce the amount of time it takes to root cause a bug. These macros are typically enabled only for debug builds and disabled in production builds so as to not take up any executable space. The macros available through the DebugLib include:
  • ASSERT (Expression)
  • ASSERT_EFI_ERROR (Status)
  • ASSERT_PROTOCOL_ALREADY_INSTALLED (Handle, Guid)
  • DEBUG ((ErrorLevel, Format,. .))
  • DEBUG_CODE_BEGIN ()
  • DEBUG_CODE_END ()
  • DEBUG_CODE (Expression)
  • DEBUG_CLEAR_MEMORY (Address, Length)
  • CR (Record, TYPE, Field, Signature)
These macros are described in details in the MdePkg documentation available from http://www.tianocore.org. The ErrorLevel parameter passed into the DEBUG() macro allows a UEFI driver to assign a different error level to each debug message, which allows debug messages to be filtered. The DSC files required to build a UEFI Driver can be used to set the ErrorLevel filter mask. The UEFI Shell also supports the Err command that allows the user to set the error level filter mask.
TIP: Use a serial port as a standard error device during debug. This a terminal emulator to be used to log debug messages to a file.
The table below contains the list of error levels that are supported in the UEFI Shell. Other levels are usable, but not defined for a specific area.

Table 46-Error levels

Mnemonic
Value
Description
DEBUG_INIT
0x00000001
Initialization
DEBUG_WARN
0x00000002
Warnings
DEBUG_INFO
0x00000040
Information messages
DEBUG_ERROR
0x80000000
Error messages.
DEBUG_FS
0x00000008
Used by UEFI Drivers that produce the Simple File System Protocol.
DEBUG_BLKIO
0x00001000
Used by UEFI Drivers that produce the Block I/O Protocols.
DEBUG_NET
0x00004000
Used by UEFI Drivers that produce the network protocols other than NII and UNDI.
DEBUG_UNDI
0x00010000
Used by UEFI Drivers that produce the NII Protocol and UNI interface.
DEBUG_LOADFILE
0x00020000
Used by UEFI Drivers that produce the Load File Protocol.
DEBUG_EVENT
0x00080000
Event messages. Used from event notification functions of UEFI Drivers.
DEBUG_LOAD
0x00000004
Load events. DO NOT USE.
DEBUG_POOL
0x00000010
Pool allocations & frees. DO NOT USE.
DEBUG_PAGE
0x00000020
Page allocations & frees. DO NOT USE.
DEBUG_DISPATCH
0x00000080
PEI/DXE/SMM Dispatchers. DO NOT USE.
DEBUG_VARIABLE
0x00000100
Variable. DO NOT USE.
DEBUG_BM
0x00000400
Boot Manager. DO NOT USE.
DEBUG_GCD
0x00100000
Global Coherency Database changes. DO NOT USE.
DEBUG_CACHE
0x00200000
Memory range cache state changes. DO NOT USE.