UEFI Debug Mode Configuration

The debugger needs to be correctly configured to be able to load module debug information files. Use the command EFI "SHOWCONFIG" to display the current configuration.

Configuring Build and Target

To create a debug build of UEFI BIOS, specify the "Debug" build target instead of the "Release" build target when calling the helper batch script that triggers the EDK2 build process. Also burn the resulting flash image file onto the target's SPI, since the build tree and the flash image always have to be in perfect sync for symbolic debug to be reliable.

Configuring UEFI Source Tree Path

To use the System Debugger on a machine (host machine) that is different from the machine used to build the UEFI BIOS (build machine). In this case, choose one of the following options:

Option 1: Notify the debugger to translate the path

For example, assumed that the UEFI tree was located in C:\edk2\ on the build machine and D:\uefi\ on the host machine:

  1. In the menu bar, select: Options > Source Directories….
  2. Switch to the Rules tab, click New ....
  3. In the field Replace, enter [BUILD_PATH= "C:\edk2\" ].
  4. In the fieldby, enter [HOST_PATH = "D:\uefi\"].
  5. Click OK twice to close both dialog windows.

See also Source Directories Dialog Box: Rules Tab and Source Directories Dialog Box: Directories Tab.

Option 2: Map a network drive that matches the build path in your host machine.

Configuring the Target Execution Mode

When debugging a 64-bit target processor, the SEC and PEI phases are still executed in 32-bit mode. The debugger detects the current module execution mode automatically. If the automatic detection fails, use the command EFI "SETSWMODE".

Configuring the Debug Information File Format

On a Windows* Host System, the debugger supports debugging UEFI modules built with Microsoft Visual Studio* as well as with the GNU* Compiler. The Microsoft Visual Studio* format (.efi) is the default setting. Use the command EFI "SETSUFFIX" to change the active format to (.debug) for a module compiled with the GNU* Compiler.


On a Linux* host system, the debugger supports only modules built with the GNU* compiler.

For more complete information about compiler optimizations, see our Optimization Notice.