This folder contains the source for the UEFI debugger extension. This provides functionality within windbg for debugging the UEFI environment. Using the UEFI extension requires that Windbgx has access to the symbol files for the target UEFI code.
The most recent compiled version of this binary can be found as a build artifact in the debug extension workflow.
Windbg debugger extensions need to be compiled with the Microsoft build tools. See the Project MU prerequisites for more details on installing and versions. The easiest way to compile is to use the Developer Command Prompt that comes with the Visual Studio tools installation. In the command prompt, navigate to the folder and run "msbuild".
msbuild -property:Configuration=Release -property:Platform=x64
The project can also be loaded and built in Visual Studio using the solution file. This project requires the Windows SDK and the Windows Driver Kit.
Debugger extensions can be loaded into windbg several ways. First, by manually loading once already in windbg. This can be done with the .load command. Though this will not persist across windbg sessions.
.load <path to uefiext.dll>
The second is to place the DLL in the windbg application folder, or another place in windbg's extpath which can be enumerating using the .extpath command. This will make the extension available to all future windbg sessions.
e.g. C:\Users\<user>\AppData\Local\dbg\EngineExtensions
For more information about loading debugger extensions see the Microsoft documentation page.
Once the extension is loaded into windbg, you can use it by running any of its commands. To see its commands, use the help command to get started.
!uefiext.help
One particularly useful instruction will be the !uefiext.findall instruction
to load the needed modules.
It is advised to configure !uefiext.init as a startup action in
Settings->Debugging Settings->Startup. This will attempt to detect a UEFI environment
and automatically resolve initial symbols when connecting. This will do nothing
when debugging other environments.
Windbg debug extensions allow for programmatic decoding and outputting of data from to debugger. The UEFI debug extension is designed to help with finding, parsing, and changing data in the UEFI environment more accessible from the debugger.
Because UEFI has various environments, SEC, DXE, MM, the extension has a concept
of the current running environment. This can be manually set using !uefiext.setenv.
This environment should be used to change the operation of various routines based
on the current context. For example, enumerating the hobs or loaded modules is
done differently in DXE then it is in MM. At the time of writing this, most functions
are only implemented in DXE, but this environment should always be checked before
accessing environment specific information.
New commands can be exported by added them to the exports in uefiext.def. New commands should also be added to the help command in uefiext.cpp. For reference on how to write debugger extension code, see the Microsoft API Docs.
Copyright (C) Microsoft Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent