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