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_TABLEin memory by its magic - Locate
EFI_DEBUG_IMAGE_INFO_TABLEby its GUID - Map relocated images within GDB
- Provide handy functions and pretty printers
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.
GdbSyms.dll is built as a part of OcSupportPkg, yet prebuilt binaries are also available:
GdbSyms/Bin/X64_XCODE5/GdbSyms.dllis built with UDK2018 and 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 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"
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 the process is as simple as running the following set of commands:
$ ggdb /opt/UDK/Build/OcSupportPkg/NOOPT_XCODE5/X64/OcSupportPkg/Debug/GdbSyms/GdbSyms/DEBUG/GdbSyms.dll.dSYM/Contents/Resources/DWARF/GdbSyms.dll
target remote localhost:8864
source /opt/UDK/OcSupportPkg/Debug/Scripts/gdb_uefi.py
set pagination off
reload-uefi
b DebugBreak