WindowsGuestDrivers/GuestDebugging

Windows guest debugging

Introduction

• Host computer - The computer that runs the debugging session, aka “remote debugger” (!WinDbg)

• Target computer – The computer that is being debugged (the debuggee) runs the kernel-mode module.

To allow kernel debugging on a qemu’s Windows guest we need two Windows VMs which will be “connected” using a __virtual__ null-modem serial cable using qemu’s serial redirection ability. To keep it simple both of these VMs run on the same physical host, but this is not required. The virtual serial cable is connected via TCP, so the host VM and target VM could run on different physical hosts.

Setting up the host VM

qemu host command line

• Add or change the qemu command line to include “-serial tcp::4445,server,nowait”. (4445 can be any valid tcp port)

Host guest OS setting

• Get and install the latest version of the Debugging Tools for Windows

Setting up the target VM

• Apply the [file://10.0.0.1\public\yan\ItaiDocs\WinDbg\qemu-20070110-windbg.patch/ qemu-20070110-windbg.patch] to your qemu sources and build it. (this is something really old, not sure it is needed now).

qemu target command line

• Add or change the qemu command to include “-serial tcp:127.0.0.1:4445”. (here the qemu instance running the serial "server" is local, 127.0.0.1, and listening on port 4445 as specified in the host VM setup)

Target guest OS setting

Windows 2000, XP and 2003

• Edit c:\boot.ini and duplicate the default boot line, at the end of the duplicated boot line add “/debug /debugport=COM1 /baudrate=115200

Windows Vista and Up

• Use BCDedit tool to change boot options [1] [2]
• bcdedit /dbgsettings SERIAL [DEBUGPORT:port] [BAUDRATE:baud]

VMs startup sequence

Since the “virtual serial cable” is based on TCP we employ a client/server startup scheme. The host VM (debugger) acts as the TCP server so it must be started first, before the target VM. Using this scheme (thanks to Yaniv Kamay) allows the host VM to remain up and running even if the target vm has crashed/stopped or needs to be rebooted.

• Start the host VM.
• Start the target VM.
• When the target guest OS starts, choose the [debugger enabled] option from the boot menu.
• On the host VM lanch !WinDbg.
• From the file menu use “Kernel Debug”.
• Click the “COM” tab and make sure that “Baud Rate” and Port are set to the values you used in the target boot.ini entry.
• In the !WinDbg Debug menu choose break to break into the debugger and start the guest kernel debug session.