Setting up Windows Guests for Debugging with the Hyper-V Paravirtualization Provider

Windows supports debugging over a serial cable, USB, IEEE 1394 Firewire, and Ethernet. USB and IEEE 1394 are not applicable for virtual machines, and Ethernet requires Windows 8 or later. While a serial connection is universally usable, it is slow.

Debugging using the Hyper-V debug transport, supported on Windows Vista and later, offers significant benefits. It provides excellent performance due to direct host-to-guest transfers, it is easy to set up and requires minimal support from the hypervisor. It can be used with the debugger running on the same host as the VM or with the debugger and VM on separate machines connected over a network.

Prerequisites

A VM configured for Hyper-V paravirtualization running a Windows Vista or newer Windows guest. You can check the effective paravirtualization provider for your VM with the output of the following VBoxManage command:
```
$ VBoxManage showvminfo VM-name
                           
```
A sufficiently up-to-date version of the Microsoft WinDbg debugger required to debug the version of Windows in your VM.
While Windows 8 and newer Windows guests ship with Hyper-V debug support, Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista guest, copy the file kdvm.dll from a Windows 8.0 installation. This file is typically located in C:\Windows\System32. Copy it to the same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or 64-bit version of the DLL which matches your guest OS.

Only Windows 8.0 ships kdvm.dll. Windows 8.1 and newer Windows versions do not.

VM and Guest Configuration

Power off the VM.
Enable the debug options with the following VBoxManage command:
```
$ VBoxManage modifyvm VM-name --paravirt-debug "enabled=1"
```
The above command assumes your debugger will connect to your host machine on UDP port 50000. However, if you need to run the debugger on a remote machine you may specify the remote address and port here. For example:
```
$ VBoxManage modifyvm VM-name \
--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"
```
See for the complete set of options.
Start the VM.
In the guest, start an elevated command prompt and execute the following commands:
- For a Windows 8 or newer Windows guest:
```
bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4
```
- For a Windows 7 or Vista guest:
```
bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4
```
```
bcdedit /set dbgtransport kdvm.dll
```
  The IP address and port in the bcdedit command are ignored when using the Hyper-V debug transport. Any valid IP and a port number greater than 49151 and lower than 65536 can be entered.
  
  The encryption key in the bcdedit command is relevant and must be valid. The key "1.2.3.4" used in the above example is valid and may be used if security is not a concern. If you do not specify any encryption key, bcdedit will generate one for you and you will need to copy this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used to encrypt the debug data exchanged between Windows and the debugger.
- Run one or more of the following commands to enable debugging for the appropriate phase or component of your Windows guest:
```
bcdedit /set debug on
```
```
bcdedit /set bootdebug on
```
```
bcdedit /set {bootmgr} bootdebug on
```
  Please note that the bootdebug options are only effective on Windows 8 or newer when using the Hyper-V debug transport. Refer to Microsoft Windows documentation for detailed explanation of bcdedit options.
Start Microsoft WinDbg on your host machine or remote host.

From the File menu, select Kernel Debug. On the NET tab, specify the UDP port number you used in the paravirtdebug options. If you did not specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall or other security software.

In the Key field, enter 1.2.3.4 or the encryption key from the bcdedit command in your Windows guest.

Click OK to start listening for connections. Microsoft WinDbg typically shows a Waiting to Reconnect message during this phase.

Alternatively, to directly start a debug session, run WinDbg from the command line as follows :
```
windbg.exe -k net:port=50000,key=1.2.3.4
```
See the WinDbg documentation for the complete command line syntax.
Reboot your Windows guest and it should then connect as a debuggee with Microsoft WinDbg.