cbfae3e8a9
The Visual Studio Windows debugger will only load symbols for PE/COFF images
that Windows is aware of. Therefore, to enable source level debugging, all
PEI/DXE modules must be loaded via LoadLibrary() or LoadLibraryEx() and the
the instance in memory created by LoadLibrary() must be the one that is
actually executed.
The current source level debug implementation in EmulatorPkg for Windows is
inherited from the old Nt32Pkg. This implementation makes the assumption that
all PEI/DXE modules have a DLL export tables with a symbol named
InitializeDriver. Therefore, this source level debug implementation requires
all modules to be linked in a non-PI spec defined manner. Support for adding
the InitializeDriver symbol was removed in EmulatorPkg, which broke source
level debugging.
To fix this, the source level debugging implementation has been modified to
use the PE/COFF entry point directly. This brings the implementation into
compliance with the PI spec and should work with any PEIM/DXE driver.
Implementing this requires parsing the in-memory instance of the PE/COFF image
created by Windows to find the entrypoint and since PEIMs/DXE drivers are not
garunteed to have 4KB aligned sections, it also requires explicit configuration
of the page table using VirtualProtect().
With this fix, the debugging experience is now so good it is unprecedented!
In Visual Studio Code, add the following to launch.json:
{
"version": "0.2.0",
"configurations": [
{
"name": "EmulatorPkg Launch",
"type": "cppvsdbg",
"request": "launch",
"program": "${workspaceFolder}/<path_to_build>/Build/EmulatorX64/DEBUG_<tool_chain>/X64/WinHost",
"args": [],
"stopAtEntry": false,
"cwd": "${workspaceFolder}/<path_to_build>/Build/EmulatorX64/DEBUG_<tool_chain>/X64/",
"environment": [],
"console": false,
}
]
}
Make modifications to the above template as nessesary and build EmulatorPkg.
Now, just add breakpoints directly in Visual Studio Code the way you would with
any other software project. When you start the debugger, it will halt at the
breakpoint automatically without any extra configuration required.
Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Andrew Fish <afish@apple.com>
Cc: Ray Ni <ray.ni@intel.com>
Cc: Chasel Chiu <chasel.chiu@intel.com>
Signed-off-by: Nate DeSimone <nathaniel.l.desimone@intel.com>
|
||
|---|---|---|
| .. | ||
| Application/RedfishPlatformConfig | ||
| AutoScanPei | ||
| BootModePei | ||
| CpuRuntimeDxe | ||
| EmuBlockIoDxe | ||
| EmuBusDriverDxe | ||
| EmuGopDxe | ||
| EmuSimpleFileSystemDxe | ||
| EmuSnpDxe | ||
| EmuThunkDxe | ||
| FirmwareVolumePei | ||
| FlashMapPei | ||
| FvbServicesRuntimeDxe | ||
| Include | ||
| Library | ||
| PlatformCI | ||
| PlatformSmbiosDxe | ||
| RealTimeClockRuntimeDxe | ||
| ResetRuntimeDxe | ||
| Sec | ||
| ThunkPpiToProtocolPei | ||
| TimerDxe | ||
| Unix | ||
| Win | ||
| EmulatorPkg.ci.yaml | ||
| EmulatorPkg.dec | ||
| EmulatorPkg.dsc | ||
| EmulatorPkg.fdf | ||
| Readme.md | ||
| build.sh | ||
Readme.md
Overview
EmulatorPkg provides an environment where a UEFI environment can be emulated under an environment where a full UEFI compatible environment is not possible. (For example, running under an OS where an OS process hosts the UEFI emulation environment.)
https://github.com/tianocore/tianocore.github.io/wiki/EmulatorPkg
Status
- Builds and runs under
- a posix-like environment with X windows
- Linux
- OS X
- Windows environment
- Win10 (verified)
- Win8 (not verified)
- a posix-like environment with X windows
How to Build & Run
You can use the following command to build.
-
32bit emulator in Windows:
build -p EmulatorPkg\EmulatorPkg.dsc -t VS2022 -a IA32 -
64bit emulator in Windows:
build -p EmulatorPkg\EmulatorPkg.dsc -t VS2022 -a X64 -
32bit emulator in Linux:
build -p EmulatorPkg\EmulatorPkg.dsc -t GCC5 -a IA32 -
64bit emulator in Linux:
build -p EmulatorPkg\EmulatorPkg.dsc -t GCC5 -a X64
You can start/run the emulator using the following command:
-
32bit emulator in Windows:
cd Build\EmulatorIA32\DEBUG_VS2022\IA32\ && WinHost.exe -
64bit emulator in Windows:
cd Build\EmulatorX64\DEBUG_VS2022\X64\ && WinHost.exe -
32bit emulator in Linux:
cd Build/EmulatorIA32/DEBUG_GCC5/IA32/ && ./Host -
64bit emulator in Linux:
cd Build/EmulatorX64/DEBUG_GCC5/X64/ && ./Host
On posix-like environment with the bash shell you can use EmulatorPkg/build.sh to simplify building and running emulator.
For example, to build + run:
$ EmulatorPkg/build.sh
$ EmulatorPkg/build.sh run
The build architecture will match your host machine's architecture.
On X64 host machines, you can build + run IA32 mode as well:
$ EmulatorPkg/build.sh -a IA32
$ EmulatorPkg/build.sh -a IA32 run