| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="gimdebughyperv-windows-setup">
|
|---|
| 4 | <title>Setting up Windows Guests for Debugging with the Hyper-V
|
|---|
| 5 | Paravirtualization Provider</title>
|
|---|
| 6 |
|
|---|
| 7 | <body>
|
|---|
| 8 | <p>Windows supports debugging over a serial cable, USB, IEEE 1394 Firewire, and Ethernet. USB and IEEE 1394 are not
|
|---|
| 9 | applicable for virtual machines, and Ethernet requires Windows 8 or later. While a serial connection is
|
|---|
| 10 | universally usable, it is slow. </p>
|
|---|
| 11 | <p>Debugging using the Hyper-V debug transport, supported on Windows Vista and later, offers significant benefits.
|
|---|
| 12 | It provides excellent performance due to direct host-to-guest transfers, it is easy to set up and requires minimal
|
|---|
| 13 | support from the hypervisor. It can be used with the debugger running on the same host as the VM or with the
|
|---|
| 14 | debugger and VM on separate machines connected over a network. </p>
|
|---|
| 15 | <p>
|
|---|
| 16 | <b outputclass="bold">Prerequisites</b>
|
|---|
| 17 | </p>
|
|---|
| 18 | <ul>
|
|---|
| 19 | <li>
|
|---|
| 20 | <p>A VM configured for Hyper-V paravirtualization running a Windows Vista or newer Windows guest. You can check
|
|---|
| 21 | the effective paravirtualization provider for your VM with the output of the following
|
|---|
| 22 | <userinput>VBoxManage</userinput> command: </p>
|
|---|
| 23 | <pre xml:space="preserve">$ VBoxManage showvminfo <varname>VM-name</varname>
|
|---|
| 24 | </pre>
|
|---|
| 25 | </li>
|
|---|
| 26 | <li>
|
|---|
| 27 | <p>A sufficiently up-to-date version of the Microsoft WinDbg debugger required to debug the version of Windows
|
|---|
| 28 | in your VM. </p>
|
|---|
| 29 | </li>
|
|---|
| 30 | <li>
|
|---|
| 31 | <p>While Windows 8 and newer Windows guests ship with Hyper-V debug support, Windows 7 and Vista do not. To use
|
|---|
| 32 | Hyper-V debugging with a Windows 7 or Vista guest, copy the file <filepath>kdvm.dll</filepath> from a Windows
|
|---|
| 33 | 8.0 installation. This file is typically located in <filepath>C:\Windows\System32</filepath>. Copy it to the
|
|---|
| 34 | same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or 64-bit version of the DLL which
|
|---|
| 35 | matches your guest OS. </p>
|
|---|
| 36 | <note>
|
|---|
| 37 | <p>Only Windows 8.0 ships <filepath>kdvm.dll</filepath>. Windows 8.1 and newer Windows versions do not. </p>
|
|---|
| 38 | </note>
|
|---|
| 39 | </li>
|
|---|
| 40 | </ul>
|
|---|
| 41 | <p>
|
|---|
| 42 | <b outputclass="bold">VM and Guest Configuration</b>
|
|---|
| 43 | </p>
|
|---|
| 44 | <ol>
|
|---|
| 45 | <li>
|
|---|
| 46 | <p>Power off the VM. </p>
|
|---|
| 47 | </li>
|
|---|
| 48 | <li>
|
|---|
| 49 | <p>Enable the debug options with the following <userinput>VBoxManage</userinput> command: </p>
|
|---|
| 50 | <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --paravirt-debug "enabled=1"</pre>
|
|---|
| 51 | <p>The above command assumes your debugger will connect to your host machine on UDP port 50000. However, if you
|
|---|
| 52 | need to run the debugger on a remote machine you may specify the remote address and port here. For example: </p>
|
|---|
| 53 | <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \
|
|---|
| 54 | --paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</pre>
|
|---|
| 55 | <p>See <xref href="gimdebughyperv.dita#gimdebughyperv"/> for the complete set of options. </p>
|
|---|
| 56 | </li>
|
|---|
| 57 | <li>
|
|---|
| 58 | <p>Start the VM. </p>
|
|---|
| 59 | </li>
|
|---|
| 60 | <li>
|
|---|
| 61 | <p>In the guest, start an elevated command prompt and execute the following commands: </p>
|
|---|
| 62 | <ul>
|
|---|
| 63 | <li>
|
|---|
| 64 | <p>For a Windows 8 or newer Windows guest: </p>
|
|---|
| 65 | <pre xml:space="preserve">bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</pre>
|
|---|
| 66 | </li>
|
|---|
| 67 | <li>
|
|---|
| 68 | <p>For a Windows 7 or Vista guest: </p>
|
|---|
| 69 | <pre xml:space="preserve">bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</pre>
|
|---|
| 70 | <pre xml:space="preserve">bcdedit /set dbgtransport kdvm.dll</pre>
|
|---|
| 71 | <p>The IP address and port in the <userinput>bcdedit</userinput> command are ignored when using the Hyper-V
|
|---|
| 72 | debug transport. Any valid IP and a port number greater than 49151 and lower than 65536 can be entered. </p>
|
|---|
| 73 | <p>The encryption key in the <userinput>bcdedit</userinput> command is relevant and must be valid. The key
|
|---|
| 74 | "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
|
|---|
| 75 | specify any encryption key, <userinput>bcdedit</userinput> will generate one for you and you will need to
|
|---|
| 76 | copy this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used to encrypt
|
|---|
| 77 | the debug data exchanged between Windows and the debugger. </p>
|
|---|
| 78 | </li>
|
|---|
| 79 | <li>
|
|---|
| 80 | <p>Run one or more of the following commands to enable debugging for the appropriate phase or component of
|
|---|
| 81 | your Windows guest: </p>
|
|---|
| 82 | <pre xml:space="preserve">bcdedit /set debug on</pre>
|
|---|
| 83 | <pre xml:space="preserve">bcdedit /set bootdebug on</pre>
|
|---|
| 84 | <pre xml:space="preserve">bcdedit /set {bootmgr} bootdebug on</pre>
|
|---|
| 85 | <p>Please note that the <userinput>bootdebug</userinput> options are only effective on Windows 8 or newer
|
|---|
| 86 | when using the Hyper-V debug transport. Refer to Microsoft Windows documentation for detailed explanation
|
|---|
| 87 | of <userinput>bcdedit</userinput> options. </p>
|
|---|
| 88 | </li>
|
|---|
| 89 | </ul>
|
|---|
| 90 | </li>
|
|---|
| 91 | <li>
|
|---|
| 92 | <p>Start Microsoft WinDbg on your host machine or remote host. </p>
|
|---|
| 93 | <p>From the <b outputclass="bold">File</b> menu, select <b outputclass="bold">Kernel Debug</b>. On the <b
|
|---|
| 94 | outputclass="bold">NET</b> tab, specify the UDP port number you used in the <codeph>paravirtdebug</codeph>
|
|---|
| 95 | options. If you did not specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall
|
|---|
| 96 | or other security software. </p>
|
|---|
| 97 | <p>In the <b outputclass="bold">Key</b> field, enter <codeph>1.2.3.4</codeph> or the encryption key from the
|
|---|
| 98 | <userinput>bcdedit</userinput> command in your Windows guest. </p>
|
|---|
| 99 | <p>Click <b outputclass="bold">OK</b> to start listening for connections. Microsoft WinDbg typically shows a
|
|---|
| 100 | Waiting to Reconnect message during this phase. </p>
|
|---|
| 101 | <p>Alternatively, to directly start a debug session, run WinDbg from the command line as follows : </p>
|
|---|
| 102 | <pre xml:space="preserve">windbg.exe -k net:port=50000,key=1.2.3.4</pre>
|
|---|
| 103 | <p>See the WinDbg documentation for the complete command line syntax. </p>
|
|---|
| 104 | </li>
|
|---|
| 105 | <li>
|
|---|
| 106 | <p>Reboot your Windows guest and it should then connect as a debuggee with Microsoft WinDbg. </p>
|
|---|
| 107 | </li>
|
|---|
| 108 | </ol>
|
|---|
| 109 | </body>
|
|---|
| 110 |
|
|---|
| 111 | </topic>
|
|---|
