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.