Windows HVM Debugging

Debugging Windows HVM guests in OpenXT

For guest HVM debugging, both the host (debugger) and target VM (debuggee) must be configured. The following steps outline setting this up using serial debugging. Note the serial port on the target side is a virtual serial port emulated by qemu.

Note: On OpenXT platforms, be sure to disable stub domains before attempting to connect the VM to the debugger.

On the host computer (the debugger):

Install the Debugging Tools For Windows if you do not have them. You will also need to setup symbol and source code paths. The WinDbg documentation describes how to do this. The package can be found here:
```
http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx
```
It seems recently that the Debugging Tools For Windows have been moved into the WDK/SDK/Visual Studio installs so to get the most recent versions, this is where to look.
Setup the symbol path. This is done in Control Panel -> System ->Advanced -> Environment Variables. Make a New System environment variable like the one shown below. The first part of the following sets up C:\Mydir\symbols for local symbols. The second part after the ; is pulling public symbols from MS down into a local cache in C:\Mydir\symwin.
```
 _NT_SYMBOL_PATH = C:\Mydir\symbols;SRV*C:\Mydir\symwin*http://msdl.microsoft.com/download/symbols
```
Get a copy of File:sockpipe.exe tool. This tool is an OpenXT tool that comes from the this repository. The tool has been attached to this page also.
Run sockpipe.exe from the command line as follows:
```
sockpipe.exe debugpipe 7204
```
Run WinDbg with arguments for connected to the pipe created by sockpipe:
```
windbg -k com:pipe,port=\\.\pipe\debugpipe
```
At this point WinDbg is connected to sockpipe via the pipe above and waiting for the target system to start. The sockpipe application is listening on a socket for an connection from the target HVM (from the qemu to be precise).

On the target XenClient computer (the debuggee):

Boot the HVM you wan't to debug and create a boot entry for debugging. On XP it would involves adding a boot.ini entry. First the file needs to be unhidden and made writable:
```
C:\>attrib -r -h -s boot.ini
```
The copy an existing line from the boot.ini file and paste a new one in - make it look like this:
```
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /debug /debugport=COM1 /baudrate=115200
```
On Vista and Win7 you need to use the bcdedit tool to setup a new boot entry. First lauch a command windows as Administrator and do this:
```
bcdedit /copy {current} /d win7debug
```
Then run msconfig from the same command windows. Select the Boot tab and locate your new win7debug boot entry. Select it and Advanced options. Check the Debug checkbox and in the Global debug settings section set the Debug port to COM1 and the Baud reate to 115200. Note that the Debugging Tools For Windows help has information on setting up both the host and target machines.

Shut the VM down and first disable SELinux - it will interfere with debugging. From a terminal in dom0:

# disable for until reboot
nr
setenabled 0

# or disable forever, first you need to make the fs writeable
rw
# edit /etc/selinux/config and set to permissive
ro

Next edit the xenvm config file for the VM. Add a virtual serial port to it that connect to the host machine as follows. The values can be set in a VM's config file using the folloiwing command in dom0 (note the nodelay option turns of naggling which can disrupt debugger operation):
```
db-write /vm/<uuid>/config/extra-xenvm/0 "serial=tcp:<ip>:<port>,nodelay"
```
This also works:
```
xec-vm -n <vmname> set extra-xenvm "serial=tcp:<ip>:<port>,nodelay"
```
The examples above have qemu connecting out to a listening sockpipe. You can also have qemu listen for incoming sockpipe connections (as a server) with the following (note the nowait will prevent qemu from waiting for a client connection):
```
xec-vm -n <vmname> set extra-xenvm "serial=tcp::<port>,server,nodelay,nowait"
```
Before restarting the VM, make sure that the sockpipe listening app is running - QEMU will try to make a TCP connection to it. Also make sure there are not firewalls or other network issues that could prevent the connection. If QEMU cannot connect, it will spit out a message that looks like this:
```
Unknown internal error. Error code: 199. Message: Dm.Ioemu_failed("Device model 0 on dm-agent 8 died (status = unknown)")
```
Restart the HVM and select the debug boot entry. Early in the VM boot process the debugging session will connect.