UEFI Framework Debugging

Overview

The Intel® Platform Innovation Framework for Unified Extensible Firmware Interface (UEFI), commonly known as the UEFI Framework, is a new firmware architecture standard that defines a set of software interfaces and replaces the legacy BIOS found on traditional PC computers. This framework provides the kind of modularity, flexibility, and extensibility that were formerly unavailable with traditional BIOS. With UEFI, BIOS developers can now write all their code in ’C’, rather than assembly language. See Intel’s web site at http://www.intel.com/technology/framework  or http://www.tianocore.org for more information on UEFI Framework.

Along with this new firmware architecture and the ’C’ code that implements it comes the need for source-level debugging. Arium's debugger, SourcePoint™ (versions 7.0 and later) for Intel and AMD processors offers native debug support for UEFI Framework platforms. Users can set breakpoints, single step, view variables, see the call stack, and access all of the feature-rich functionality SourcePoint normally provides. This includes source-level debugging during the PEI, DXE, and OS Boot phases of UEFI. Below is a set of instructions for setting up SourcePoint to debug the UEFI Framework.  

UEFI Macros

Note: The macros described below are installed in the Macro\UEFI sub-folder of the SourcePoint install path. Several of the UEFI macro files contain directory paths to other macro files. If you move the macro files or change the current working directory in SourcePoint (via the ’cwd’ command), you will need to update the macros files with the new locations.

EFI.mac

After installing SourcePoint, run the EFI.mac macro file located in the Macro\UEFI directory. This creates six custom  toolbar buttons and associates each with a corresponding UEFI proc.

• The StartPEI icon resets the target, then runs to PeiMain and loads the PEI symbols.

• The PEIMs (Pre-UEFI Initialization Modules) icon loads the symbol files for the PEI modules found in target memory.

• The DXEs (Driver Execution Environments) icon loads the symbol files for the DXE modules found in target memory.

• The HOBs (Hand-Off Blocks) icon displays a list of UEFI HOBs found in target memory.

• The SysConfigTable icon displays the contents of the UEFI system configuration table.

• The DumpMemMap icon displays the UEFI Memory Map.

 

 

EFI.mac toolbar buttons

 

PEI Debugging

The PEI environment requires a specialized configuration of SourcePoint. PEI gets control shortly after target reset. PEI modules are dispatched and executed after cache RAM is mapped into system memory and the stack is initialized. Having a stack this early allows ’C’ language code to execute, but a special memory map must be configured to take advantage of it.

 To configure SourcePoint for source-level debugging of PEI code, follow these steps.

1. Optional: Select Options|Target Configuration|Memory Map from the menu, and set it similar to the following (your system may vary depending on your memory map):

The first entry in the table designates the first 1MB of system memory. The middle entry designates the location of the cache RAM mapped into system memory. The third entry designates the firmware ROM.

2. The StartPEI button will reset the target and step one instruction at a time until the processor enters protected mode. It then will load the PEI module symbols and run until PeiMain.

3. Alternatively, you can use the PEIs macro button at any time when the processor is in protected mode.

 

Command window after running PEIMs macro function

 

 

Symbols window after loading PEIM modules

 

 

Code window after loading PEIM modules

DXE Debugging

Once system RAM is initialized and the PEI phase completes, the DXE environment is entered. This is less specialized than PEI; nevertheless, it requires a few SourcePoint parameters to be set.

To configure SourcePoint for source-level debugging of DXE code, follow these steps:

1. Run the target to the UEFI shell, or as far as it will go in DXE.

2. Stop the target.

3. Click the DXEs toolbar icon to load the DXE symbols.

4. Browse the source code files using the Symbols window and set breakpoints in your code.

5. Reset the target and go until you hit a breakpoint.

DXE Code window

HOBs

Open the Command window, and then click the HOBs toolbar icon to display the hand-off blocks on the target.

 

Example of HOB display

System Configuration Table

Open the Command window, and then click the SysConfigTable toolbar icon to display the contents of the UEFI system configuration table on the target.

 

Example of System Configuration Table

Notes

1. DXE Debugging Tip

To stop the target and load symbols just before a DXE module is dispatched, open the Symbols window, choose the Globals tab, and drill down to:

program:   DXEMAIN.efi

module:    image (image.c)

function:   CoreStartImage()

Right click on CoreStartImage and select Open Code Window from the pop-up menu.

Set a processor breakpoint in CoreStartImage( ) where Image->EntryPoint( ) is called. This hits before each DXE module is dispatched, but afterwards its entry is placed in tables. Each time you hit this breakpoint, click the DXEs toolbar icon to load the DXE symbols.

Now you can load symbols just before your DXE module runs instead of running to the UEFI shell, then loading symbols, then resetting the target, then running to your breakpoint.

2. Watchdog Timer on Intel Platforms

Some motherboards with Intel processors have a TCO timer that will assert RESET independent of the emulator. See the Arium application note titled, "Disabling the TCO Timer in an Intel I/O Controller Hub" for details. Resetting the target from SourcePoint can cause a Target state undefined error message to appear because the timer asserts RESET and confuses the emulator. The solution to this problem is to configure the ICH_TCO_Timer_Disable.mac macro to run at every target reset.

3. The UEFI firmware on the target contains strings that hold the paths to the program symbol files on your hard drive. SourcePoint macros read target memory, find these strings, then load the symbol files specified in these paths. The symbol files must be located in the path specified in the UEFI firmware.

For example, one path might look like this:

"Z:\Platform\IntelSsg\D845GRG\Build\IA32\DxeMain.efi"

This architecture, defined by Intel, presents a requirement for UEFI debugging. You must have the UEFI symbol files on the host computer in the same directories as specified in the firmware on the target. This should not be a problem if you build the UEFI firmware on the same host from which you run SourcePoint.

If the drive letter or path doesn’t match exactly, you can use the ’subst’ command from the Windows command prompt to map a drive letter to a desired path (example: 'subst d: c:\working\EFI').