Configuring QEMU Kernel Mode Debugging with EXDI - Windows Drivers (2023)

This topic describes how to configure QEMU kernel mode debugging using EXDI. Windows Debugger supports kernel debugging from a QEMU environment with EXDI. This document describes the steps required to establish a GdbServer RSP session between ExdiGdbSrv.dll (GDB Server Client) and QEMU GDB Server.

The described scenario uses a Windows x64 virtual machine and a QEMU GDB server, which also runs on Windows.

It is possible to connect to other operating systems that serve as a host, for example. B.Linux. QEMU, the virtualization and machine emulation software, runs on multiple architectures including x64 and Arm64. The ExdiGdb debug server is also compatible with other processors, for example it is possible to use WinDbg to debug QEMU running on Arm64. This provides multiple options for debugging a Windows VM, allowing the Windows VM to be HW debugged through the available QEMU GDB server connected to the debugger host's EXDI GDB server client.

For general information about installing, configuring, and troubleshooting EXDI connections, seeConfiguring EXDI debugger transport.

EXDI is an interface that allows you to extend WinDbg by adding support for hardware debuggers (eg JTAG based or GdbServer based). The following diagram illustrates the role of EXDI-GdbServer.

Configure a debugger connection to a Windows image in QEMU

In this topic, we describe the process of connecting to a Windows QEMU virtual image running on Windows.

1. Download and install QEMU on Windows.
2. Configure a Windows virtual QEMU target image to boot with the necessary network and BIOS/UEFI settings for debugging.
3. Start the QEMU environment using the configured startup script.
4. Start gdbserver on QEMU.
5. Check network connectivity and find and note the IP address of the target image. (Default HOST IP address from 1.2.3.4).
6. Download and install Windows debugging tools on the host system.
7. Download, build, register and configure EXDI server for QEMU on Github.
8. Configure the debugger host (WinDbg) by editing the EXDI configuration XML files.
9. Start WinDbg from the command line to connect to the EXDI server.
10. Use WinDbg to debug the target Windows QEMU image.

Download and install QEMU on Windows

QEMU is an open source generic machine virtualizer and emulator that performs dynamic translation. When used as a machine emulator, QEMU can run operating systems and programs written for one processor (eg Arm64) on another machine (an x64 PC). You can also run/host virtual machine images for different operating systems (Windows/Linux/Mac).

QEMU can use other hypervisors like KVM to use CPU extensions (HVM) for virtualization. When used as a virtualizer, QEMU achieves near-native performance by running guest code directly on the host's CPU. QEMU can take advantage of the operating system's hypervisor capabilities to offload CPU and MMU emulation onto real hardware.

Download and install QEMU

In this tutorial, QEMU for Windows x64 is installed on an x64 PC that is also running Windows Debugger.

Download QEMU from the QEMU download page:https://www.qemu.org/download/

For information on installing QEMU, refer to the QEMU documentation:https://www.qemu.org/documentacion/

Configuring a target virtual drive

Browse or create a virtual disk image that contains the software you want to debug.

This example uses a disk image of a Windows x64 VHDX virtual machine. For more information about Windows virtual machine images, seeCreate a Hyper-V Virtual Machine on Windows 10.

Include VirtIO Drivers in the Windows Image

To enable network functionality and proper storage device performance, include or install the VirtIO drivers in the Windows virtual machine disk image. VirtIo drivers are available here:https://github.com/virtio-win/kvm-guest-drivers-windows

VirtIO is a standardized interface that allows virtual machines to access abstract hardware such as block devices, network adapters, and consoles. Virtio serves as an abstraction layer for hardware devices in a virtualized environment like QEMU.

Converter VHDX para QEMU

This step is not required but is recommended as better performance is achieved using a native QEMU-QCOW image instead of a VHDX.

Use the following qemu-img.exe command to create the vhdx. For example, this utility is located where you installed QEMUC:\Programa\qemu.

C:\Archivos de programa\qemu> qemu-img convert -c -p -O qcow2 MyVHDXFile.vhdx MyQEMUFile.qcow2

Download UEFI Firmware

For best results, download or compile the UEFI firmware file (OVMF.fd). Firmware required; otherwise, QEMU emulates older BIOS systems by default.

One UEFI firmware source is the Open Clear Linux project:https://clearlinux.org/

The UEFI exampleOVMF.fdThe file is here:https://github.com/clearlinux/common/blob/master/OVMF.fd

Extract the contents of the downloaded file inC:\Programa\qemu\Firmware.

For platforms other than Intel AMD64, you must build EDK2 firmware. For more information, seehttps://github.com/tianocore/tianocore.github.io/wiki/How-to-build-OVMF.

Configuring the QEMU startup script

Create your configuration file in QEMU. For example, create aStart QEMUX64Windows.batFile in the QEMU root directory. See the example file below.

Use QEMU startup script to start QEMU

Run the QEMU startup script to start QEMU.

c:\Program Files\qemu\StartQEMUx64Windows.bat

If a firewall defense prompt appears, grant the application full rights for all network types to enable windbg through the Windows firewall to the host debugger machine.

Once the Windows virtual machine is started in the QEMU environment, the QEMU UI will appear.

Use CTRL+ALT+ a numeric key combination to enter the QEMU monitor console. This monitor is also available throughVer->compatmonitor.

untilservidor gdbto start the GDB front-end server on QEMU.

QEMU should appearWaiting for gdb connection on device "tcp::1234"

Return to the main window with the key combination CTRL+ALT+1.

Tip: The GDB console window supports the "system_reset" command to quickly reset the emulation. Type help to see a list of GDB console commands.

Windows QEMU x64 Virtual Machine Startup Script Example

This is an example QEMU configuration script that can be used for AMD64 virtual machines. Replace links pointing to DISK and CD-ROM files with locations on your PC.

REM REM This script is used to run a Windows x64 virtual machine on QEMU hosted on a Windows x64 host system. REM The host system is a PC with an Intel(R) Xeon(R) CPU. REM set EXECUTABLE=qemu-system-x86_64 set MACHINE=-m 6G -smp 4 REM No REM acceleration Generic CPU emulation. REM to find out which CPU types are supported by the version of QEMU on your system, then run: REM qemu-system-x86_64.exe -cpu help REM to see if your host system's CPU is listed. REM set CPU=-machine q35 REM Enable x64 UEFI BIOS used by QEMU: set BIOS=-bios D:\temp\firmware\OVMF.fd REM Use normal GFX simulator set GFX=-device ramfb -device VGA set USB_CTRL=-device usb-ehci,id =usbctrl set KEYB_MOUSE=-device usb-kbd -device usb-tablet REM # The following line enables the full speed HD driver (requires a separate driver) REM # The following line uses the AHCI driver to the virtual disk : set DRIVE0=- device ahci,id=ahci -device ide-hd,drive=disk,bus=ahci.0 REM REM Sets the Windows VM x64 disk image used by QEMU starts REM The disk image is in the qcow2 format accepted by QEMU. REM You will get the .qcow2 image once you get the VHDX Windows VM x64 REM image and apply the script to inject virtio x64 drivers and then REM run the QEMU tool to convert the .VHDX image to .qcow2 REM format, or i.e. REMqemu -img convert -c -p - O qcow2 Windows_VM_VHDX_with_injected_drivers_file.vhdx file.qcow2 REM file : points to the specified qcow2 image path. REM set DISK0=-drive id=disk,file=D:\temp\x64_image_qcow2_for_windows\basex64Client.qcow2,if=none REM REM for kdnet enabled, best option: REM NETWORK0="-netdev user,id=net0,hostfwd=tcp ::53389-:3389,hostfwd=tcp::50001-:50001 -device virtio-net,netdev=net0,disable-legacy=on" REM set NETHOST=-netdev user,id=net0,hostfwd=tcp: : 3589 -:3389 set NETGUEST=-device e1000,netdev=net0 REM # The following line should enable the daemon (instead of Interactive) set DEAMON=-daemonize" %EXECUTABLE% %MACHINE% %CPU% %BIOS% %GFX % % USB_CTRL % %DRIVE0% %DISK0% %NETHOST% %NETGUEST%

Check network connection

Make sure you get the Windows IP address (if the debugger host session is not on the same Windows machine as the QEMU VM).

If the GDB server starts successfully, you will see the port number the GDB server is listening on and you need to use that port to configure the host debugger (IP:port pair) in exdiConfigData.xml.

If your host debugger is on the same machine hosting the QEMU guest, the localhost identifier in exdiconfigdata.xml will be used as an IP:port pair (for example, LocalHost:Port:1234). In this example with server and host debugger on the same PC, the default values ​​are used.

Set the CurrentTarget attribute value to "QEMU" in the ExdiConfigData.xml file.

If you are working on remote PC, set QEMU destination IP<Address>: porto<Number>where the GDB server is listening:

• Locate the QEMU component tag element in exdiCondifgData.xml.
• Set the IP:Port Number (LocalHost if the debugger is running on the same host as the QEMU virtual machine) for the QEMU GDB server by typing:
• Save the changes to the exdiConfigdata.xml file located in the path specified by the EXDI_GDBSRV_XML_CONFIG_FILE environment variable.

For more information about QEMU networks, seehttps://wiki.qemu.org/Documentación/Redes

The following commands can be issued from the QEMU console (compatmonitor0) to display network information and connection status.

info redinfo usernet

Install Windows debugging tools on the host system. For information on how to download and install the debugger tools, seeDownload Debugging Tools for Windows.

Download, build and register the EXDI Server DLL

Download the source code of the corresponding ExdiGdbSrv.dll binary (EXDI COM Server Client) from Microsoft/WinDbg-Samples, GitHubhttps://github.com/microsoft/WinDbg-Samples)

git-Clone https://github.com/microsoft/WinDbg-Samples

Create the VS solution (ExdiGdbSrv.sln) as per the architecture of the host debugger installation located at Exdi/exdigdbsrv.

Locate the ExdiGdbSrv.dll created by the build.

Copy the EXDI COM server (ExdiGdbSrv.dll) to the host machine in the directory containing your debugger, .g.C:\Programa (x86)\Windows Kits\10\Debugger\x64oC:\Debugger)

Use regsvr32 to register the DLL from an administrator command prompt.

C:\Program (x86)\Windows Kits\10\Debuggers\x64>regsvr32 ExdiGdbSrv.dll

RegSvr32 should return a message indicating that theDLLRegisterServer in ExdiGdbSrv.dll successfully.

This step only needs to be performed once, but if you change the location of ExdiGdbSrv.dll, you will need to re-register the COM server.

Another option is to use the sample PowerShell script to install the EXDI DLL and launch the debugger for the first time. For more information, seeExample EXDI PowerShell scriptnoConfiguring EXDI debugger transport.

Configure the debugger host (WinDbg) by editing the EXDI configuration XML files

Locate the two necessary configuration files inWinDbg-Samples/Exdi/exdigdbsrv/and copy it to a local debugger machine on your host where the debugger is installed.

• exdiConfigData.xml
• logs do sistema.xml

EXDI_GDBSRV_XML_CONFIG_FILE – Describes the full path to the EXDI XML configuration file.

EXDI_SYSTEM_REGISTERS_MAP_XML_FILE – Describes the full path to the EXDI system registrations map XML file.

For general information about installing, configuring, and troubleshooting EXDI connections, as well as exdiConfigData.xml tags and attributes, seeConfiguring EXDI debugger transport.

Set the environment variables EXDI_GDBSRV_XML_CONFIG_FILE and EXDI_SYSTEM_REGISTERS_MAP_XML_FILE to describe the full path to the Exdi XML configuration file.

system symbol

Open a command prompt and set the following environment variables.

establezca EXDI_GDBSRV_XML_CONFIG_FILE="C:\Arquivos de programas (x86)\Windows Kits\10\Debuggers\x64\exdiConfigData.xml" establezca EXDI_SYSTEM_REGISTERS_MAP_XML_FILE="C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\systemregisters .XML"

untilTO ADJUSTto confirm that the specified path is available in the location of ExdiGdbSrvSample.dll

Power Shell

Open a PowerShell prompt and set the following environment variables:

$env:EXDI_GDBSRV_XML_CONFIG_FILE = 'C:\Programa (x86)\Windows Kits\10\Debuggers\x64\exdiConfigData.xml'$env:EXDI_SYSTEM_REGISTERS_MAP_XML_FILE = 'C:\Programa (x86)\Windows Kits\10\Debuggers\ x64\ registros do sistema.xml'

untildir env:to confirm that the specified path is available in the location of ExdiGdbSrvSample.dll

Start WinDbg on host system

Start the windbg session on the Exdi interface in the same command prompt where you set the environment variables (EXDI_GDBSRV_XML_CONFIG_FILE and EXDI_SYSTEM_REGISTERS_MAP_XML_FILE).

c:\Depuradores> windbg.exe -v -kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Rate,DataBreaks=Exdi

To see additional results, the-v:A detailed session can be used. For general information about WinDbg options, seeWinDbg Command Line Options.

Another option is to use the sample PowerShell script to install the EXDI DLL and launch the debugger for the first time. For more information, seeExample EXDI PowerShell script, noConfiguring EXDI debugger transport.

PS>.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architektur x64 -ExdiDropPath "C:\path\to\built\exdi\files"

The debugger must start and connect to the QEMU GdbServer.

The debugger shows successful initialization of the EXDI transport.

EXDI: DBGCOINITIALIZE RETURNED 0X00000001EXDI: COCREATEINSTANCE () RETURN 0X0000000000EXDI: QUARYINTERFACE (IEXDISERVER3) RETURN 0X0000000000 RESPONSABILIDADE DO DESTINO COMANDO: QEMUEXDICMD: A FUNÇÃO: Interface 0x00000000EXDI: Server::GetNbCodeBpAvail() retornou 0x00000000 EXDI: ExdiNotifyRunChange::Initialize() retornou 0x00000000 EXDI : LiveKernelTargetInfo::Initialize() returned 0x00000000 EXDI: Target initialization successful

The Packets window of the EXDIGdbServer console can also display EXDI connection status information if displayCommPackets="yes" is set in the exdiConfigData.xml file. For more information, see the troubleshooting information atConfiguring EXDI debugger transport.

Use WinDbg to debug the target Windows QEMU image

dbgeng.dll uses a heuristic algorithm to find the NT baseload address position at the time of the interrupt command. If there are no private icons available, this operation will fail.

This means that the interrupt will not work as expected for many connection strings. If you enter the code manually, it's a random location where Windows is running. Since symbols may not be available to target code, it can be difficult to set breakpoints using symbols.

Commands like the following that directly access memory will work.

k, kb, kc, kd, kp, kP, kv (Stack Backtrace anzeigen)

r (Register)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (display memory)

and (Dismount)

And you can step through the code.

p (step)

There are also commands that can be used to try to find the code you want to debug.

s (such speech)

.imgscan (finds image header)

Imgscan can be useful in EDXI debugging because symbol-based breakpoint setting may not be available unlike traditional KDNET-based kernel debugging. Locating a desired target image can make it easier to use its location to set a memory access breakpoint.

.exdicmd (EXDI command)

.exdicmd sends an EXDI command to the target system using the active EXDI debug connection. For more information, see.exdicmd (EXDI command).

EXDI XML configuration files

There are two required XML files used by the EXDI GDB COM server (ExdiGdbSrv.dll).

1. exdiConfigData.xml- This file contains key configuration data that the GDB server client needs to establish a successful GDB session with the HW debugger GDB server target, so the GDB server client does not run when the file location isNotdefined by the EXDI_GDBSRV_XML_CONFIG_FILE environment variable. Each XML tag allows configuration of a specific set of GDB server functions. Below is a list of attributes that you can change in the XML and sample XML.

2. Log do sistema.xml- This file contains a mapping between system logs and your passcode. This is necessary because the GDB server does not provide the shortcode in the xml file and the debugger accesses each system record through the shortcode.

For more information and a description of the GDBServer tags and attributes defined in the XML configuration files, seeConfiguring EXDI debugger transport.

Problems solution

See troubleshooting information atConfiguring EXDI debugger transport.

Configuring EXDI debugger transport

.exdicmd (EXDI command)

KDNET network kernel debug auto setup

Configure KDNET network kernel debugging manually