2.16 UEFI Firmware Tracker

The UEFI Firmware Tracker tracks UEFI, Intel® Slim Bootloader (Intel® SBL) and Intel® Firmware Support Package (Intel® FSP) module loading and unloading to allow source code debugging of UEFI systems. The UEFI Firmware Tracker is implemented as an OS Awareness component. Read more about OS Awareness in chapter 2.

Supported target platforms for the tracker are X86 and ARM64.

While the tracker works on both Windows and Linux and can track UEFI, Intel® Slim Bootloader (Intel® SBL) and Intel® FSP, there are some details to consider when it comes to source code debugging, see section 2.16.3.

2.16.1 Tracking Techniques

Knowing how the UEFI tracker works is optional, but understanding the basics may be useful during configuration. Tracking is handled with several techniques which handles modules loaded in the different UEFI phases.

The below tables lists the tracking techniques available on X86 (figure 7) and ARM64 (figure 8) and for which phases, or modules the tracking techniques work. Note that some tracking techniques may find other module types as well. However, it may not support unload for example.

2.16.2 Commands

The UEFI firmware tracker commands are used to configure the tracker and also to provide information about the UEFI system. The commands are:

For more information about the commands, see:

• section 2.3.1 for an overview of the OS Awareness set of commands, and
• command help information in Simics CLI:

  
  simics> load-module uefi-fw-tracker
  simics> help uefi_fw_tracker
    
  

2.16.3 Source Code Debugging

In order for source code debugging to work, there are some requirements that must be met:

1. The host type in combination with the compiler tool chain used to compile UEFI must be supported (see table in Figure 9).
2. The UEFI system must have been compiled with debug information.
3. The debug information and source files must be available to TCF.

To get the best source code debugging experience when debugging UEFI (or any other binary), please compile with as much debug information as possible and as little optimizationas possible.

If copying an already built UEFI system from another computer, it is important to keep files that are needed for debugging. There is usually a DEBUG folder for each UEFI module that contains the files needed for debugging, and it is important that at least the some of the files are kept. As an example, lets say that the module SecCore has a directory Build/.../SecCore/DEBUG. Then at least the following files must be kept

2.16.4 Configuration

Some platform start scripts come with UEFI Firmware Tracker support. If that is not the case, a tracker configuration must be added.

Here is an example of how to configure the viper system. For more in-depth information on OS Awareness configurations, read section 2.9.

# Specify the file that will contain the tracker parameters.
if not defined tracker_params { $tracker_params = "uefi.params" }

# Load uefi-fw-tracker and insert it into the tracker hierarchy.
load-module uefi-fw-tracker
viper.software.insert-tracker tracker = uefi_fw_tracker_comp

# Detect the parameters which will be written to the $tracker_params.
viper.software.tracker.detect-parameters -overwrite param-file = $tracker_params

# Load the parameters.
viper.software.tracker.load-parameters $tracker_params

# Enable the tracker.
viper.software.enable-tracker
  

If the target configuration scripts configures another OS-Awareness tracker, this should be deleted first with the command <os_awareness>.delete-tracker, for example:

# Delete the current tracker to allow configuration of the UEFI tracker.
viper.software.delete-tracker
  

After incorporating the tracker configuration and starting the simulation, you can debug the system with the debugger commands in Simics CLI. For more information about debugging with Simics in general, see chapter 3.

2.16.5 Troubleshooting

This section describes common problems and how to fix them.

• If debugging of UEFI does not work correctly, please perform the following steps in order:

  • Start by troubleshooting tracking problems in figure 10, 11, and 12 These steps are needed to be sure that the tracker configuration is correct enough to allow finding at least one UEFI module.
  • When the tracker works well enough to at least find an UEFI module, but debugging problems remain, continue to troubleshoot debugging in figure 13, 14 and 15

• If the problem is that the UEFI tracker degrades simulation performance:

  • If the code or situation that demands debugging can be reached by running simulation a specific time or by setting for example an address breakpoint (which does not require debug information and hence not a tracker either):

    1. Start the simulation without the tracker enabled.
    2. Run until the time or address that requires debugging
    3. Enable the tracker to allow source code debugging

    Unless rebuilding UEFI is needed and the same code needs to be debugged several times, saving a checkpoint (write-configuration) after reaching the situation that requires debugging, and for subsequent steps, load the checkpoint (read-configuration), and then enable the tracker may be an option.

  1. Pre-DXE tracking has a lot of performance penalty. If Pre-DXE tracking is used, consider if Execution tracking can be used instead.

2.16.6 Limitations

• Debugging UEFI systems compiled with Visual Studio only works on Windows hosts and require DBGHELP.DLL.

• When debugging UEFI systems compiled with Visual Studio, the paths to the module binaries must be shorter than 256 characters. This is a limitation in DBGHELP.DLL.

• Pre-DXE tracking does not support tracking of Terse Executable (TE) modules.

• When tracking the DXE phase, breakpoints are added on each 4 MB interval in the area specified by dxe-start and dxe-size. Any address within this range that cannot be read when the tracker is enabled is ignored. If the EFI_SYSTEM_TABLE_POINTER is placed in memory that is not readable when the tracker is enabled, DXE will not be detected. As a workaround, either toggle the tracker when in DXE, or set enable_dxe_phase_mem_map_changed_hap to true.

  Setting enable_dxe_phase_mem_map_changed_hap has a severe performance impact on some systems.

• Multi socket system has not been tested and are not officially supported, but may work.

• Only modules that have a PDB pointer containing a PDB file path can be tracked.

• Execution tracking does not track unloading of modules.

• For full SMM tracking both SMM and execution tracking modes must be enabled.

• Only modules that have a module path (IMAGE) in the map-file will be tracked by the map-file tracker. If these modules have a valid PDB pointer, and are executed, it is possible to track them using the execution tracker.

• On ARM64, Pre-DXE tracking is not supported. To track dynamic PEI modules, Execution tracking should be used.

• On ARM64, Reset tracking is not supported. The recommended workaround is to add a breakpoint on reset, and toggle (disable and then enable) the tracker if reset occurs.