These scripts provide support for easier UEFI code debugging on virtual machines like VMware Fusion or QEMU. The code is based on Andrei Warkentin's DebugPkg with improvements in macOS support, pretty printing, and bug fixing.

The general approach is as follows:

Build GdbSyms binary with EDK II type info in DWARF
Locate EFI_SYSTEM_TABLE in memory by its magic
Locate EFI_DEBUG_IMAGE_INFO_TABLE by its GUID
Map relocated images within GDB
Provide handy functions and pretty printers

Preparing Source Code

By default EDK II optimises produced binaries, so to build a "real" debug binary one should target NOOPT. Do be aware that it strongly affects resulting binary size:

build -a X64 -t XCODE5   -b NOOPT -p OpenCorePkg/OpenCorePkg.dsc # for macOS
build -a X64 -t CLANGPDB -b NOOPT -p OpenCorePkg/OpenCorePkg.dsc # for other systems

GdbSyms.dll is built as a part of OpenCorePkg, yet prebuilt binaries are also available:

GdbSyms/Bin/X64_XCODE5/GdbSyms.dll is built with XCODE5

To wait for debugger connection on startup WaitForKeyPress functions from OcMiscLib.h can be utilised. Do be aware that this function additionally calls DebugBreak function, which may be broken at during GDB init.

VMware Configuration

VMware Fusion contains a dedicated debugStub, which can be enabled by adding the following lines to .vmx file. Afterwards vmware-vmx will listen on TCP ports 8832 and 8864 (on the host) for 32-bit and 64-bit gdb connections respectively, similarly to QEMU:

debugStub.listen.guest32 = "TRUE"
debugStub.listen.guest64 = "TRUE"

In case the debugging session is remote the following lines should be appended:

debugStub.listen.guest32.remote = "TRUE"
debugStub.listen.guest64.remote = "TRUE"

To halt the virtual machine upon executing the first instruction the following line code be added. Note, that it does not seem to work on VMware Fusion 11 and results in freezes:

monitor.debugOnStartGuest32 = "TRUE"

To force hardware breakpoints (instead of software INT 3 breakpoints) add the following line:

debugStub.hideBreakpoints = "TRUE"

To stall during POST for 3 seconds add the following line. Pressing any key will boot into firmware settings:

bios.bootDelay = "3000"

QEMU configuration

In addition to VMware it is also possible to use QEMU. QEMU debugging on macOS host is generally rather limited and slow, but it is enough for generic troubleshooting when no macOS guest booting is required.

Build OVMF firmware in NOOPT mode to be able to debug it:

build -a X64 -t XCODE5   -b NOOPT -p OvmfPkg/OvmfPkgX64.dsc # for macOS
build -a X64 -t CLANGPDB -b NOOPT -p OvmfPkg/OvmfPkgX64.dsc # for other systems

Prepare launch directory with OpenCore as usual. For example, make a directory named QemuRun and cd to it. You should have a similar directory structure:

.
└── ESP
    └── EFI
        ├── BOOT
        │   └── BOOTx64.efi
        └── OC
            ├── OpenCore.efi
            └── config.plist

Run QEMU (OVMF_BUILD should point to OVMF build directory, e.g. $HOME/UefiWorkspace/Build/OvmfX64/NOOPT_XCODE5/FV):

qemu-system-x86_64 -L . -bios "$OVMF_BUILD/OVMF.fd" -hda fat:rw:ESP \
  -machine q35 -m 2048 -cpu Penryn -smp 4,cores=2 -gdb tcp::8864

You may additionally pass -S flag to QEMU to stop at first instruction and wait for GDB connection.

Debugger Configuration

For simplicitly efidebug.tool performs all the necessary GDB or LLDB scripting. Note, that you need to run reload-uefi after any new binary loads.

Check efidebug.tool header for environment variables to configure your setup. For example, you can use EFI_DEBUGGER variable to force LLDB (LLDB) or GDB (GDB).

GDB Configuration

It is a good idea to use GDB Multiarch in case different debugging architectures are planned to be used. This can be done in several ways:

https://www.gnu.org/software/gdb/ — from source
https://macports.org/ — via MacPorts (sudo port install gdb +multiarch)
Your preferred method here

Once GDB is installed you can use efidebug.tool for debugging. In case you do not want to use efidebug.tool, the following set of commands can be used as a reference:

$ ggdb /opt/UDK/Build/OpenCorePkg/NOOPT_XCODE5/X64/OpenCorePkg/Debug/GdbSyms/GdbSyms/DEBUG/GdbSyms.dll.dSYM/Contents/Resources/DWARF/GdbSyms.dll

target remote localhost:8864
source /opt/UDK/OpenCorePkg/Debug/Scripts/gdb_uefi.py
set pagination off
reload-uefi
b DebugBreak

CLANGDWARF

CLANGDWARF toolchain is an LLVM-based toolchain that directly generates PE/COFF images with DWARF debug information via LLD linker. LLVM 9.0 or newer with working dead code stripping in LLD is required for this to work (LLD patches).

Installation: After applying ClangDwarf.patch hack onto EDK II CLANGPDB toolchain will behave as if it was CLANGDWARF.

For debugging support it may be necessary to set EFI_SYMBOL_PATH environment variable to :-separated list of paths with .debug files, for example:

export EFI_SYMBOL_PATH="$WORKSPACE/Build/OvmfX64/NOOPT_CLANGPDB/X64:$WORKSPACE/Build/OpenCorePkg/NOOPT_CLANGPDB/X64"

The reason for this requirement is fragile --add-gnudebug-link option implementation in llvm-objcopy. It strips path from the debug file preserving only filename and also does not update DataDirectory debug entry.

README.md