gimdebughyperv-windows-setup.dita@ 105293

Last change on this file since 105293 was 98549, checked in by vboxsync, 2 years ago
Docs: bugref:10302. Uploading .dita user manual files we received from the doc team on 25th Jan.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 7.9 KB

Line
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>
9	Windows supports debugging over a serial cable, USB, IEEE 1394
10	Firewire, and Ethernet. USB and IEEE 1394 are not applicable
11	for virtual machines, and Ethernet requires Windows 8 or
12	later. While a serial connection is universally usable, it is
13	slow.
14	</p>
15	<p>
16	Debugging using the Hyper-V debug transport, supported on
17	Windows Vista and later, offers significant benefits. It
18	provides excellent performance due to direct host-to-guest
19	transfers, it is easy to set up and requires minimal support
20	from the hypervisor. It can be used with the debugger running
21	on the same host as the VM or with the debugger and VM on
22	separate machines connected over a network.
23	</p>
24	<p>
25	<b outputclass="bold">Prerequisites</b>
26	</p>
27	<ul>
28	<li>
29	<p>
30	A VM configured for Hyper-V paravirtualization running a
31	Windows Vista or newer Windows guest. You can check the
32	effective paravirtualization provider for your VM with the
33	output of the following <userinput>VBoxManage</userinput>
34	command:
35	</p>
36	<pre xml:space="preserve">$ VBoxManage showvminfo <varname>VM-name</varname>
37	</pre>
38	</li>
39	<li>
40	<p>
41	A sufficiently up-to-date version of the Microsoft WinDbg
42	debugger required to debug the version of Windows in your
43	VM.
44	</p>
45	</li>
46	<li>
47	<p>
48	While Windows 8 and newer Windows guests ship with Hyper-V
49	debug support, Windows 7 and Vista do not. To use Hyper-V
50	debugging with a Windows 7 or Vista guest, copy the file
51	<filepath>kdvm.dll</filepath> from a Windows 8.0
52	installation. This file is typically located in
53	<filepath>C:\Windows\System32</filepath>. Copy it to the
54	same location in your Windows 7/Vista guest. Make sure you
55	copy the 32-bit or 64-bit version of the DLL which matches
56	your guest OS.
57	</p>
58	<note>
59	<p>
60	Only Windows 8.0 ships <filepath>kdvm.dll</filepath>.
61	Windows 8.1 and newer Windows versions do not.
62	</p>
63	</note>
64	</li>
65	</ul>
66	<p>
67	<b outputclass="bold">VM and Guest Configuration</b>
68	</p>
69	<ol>
70	<li>
71	<p>
72	Power off the VM.
73	</p>
74	</li>
75	<li>
76	<p>
77	Enable the debug options with the following
78	<userinput>VBoxManage</userinput> command:
79	</p>
80	<pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --paravirt-debug "enabled=1"</pre>
81	<p>
82	The above command assumes your debugger will connect to
83	your host machine on UDP port 50000. However, if you need
84	to run the debugger on a remote machine you may specify
85	the remote address and port here. For example:
86	</p>
87	<pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \
88	--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</pre>
89	<p>
90	See <xref href="gimdebughyperv.dita#gimdebughyperv"/> for the complete set
91	of options.
92	</p>
93	</li>
94	<li>
95	<p>
96	Start the VM.
97	</p>
98	</li>
99	<li>
100	<p>
101	In the guest, start an elevated command prompt and execute
102	the following commands:
103	</p>
104	<ul>
105	<li>
106	<p>
107	For a Windows 8 or newer Windows guest:
108	</p>
109	<pre xml:space="preserve">bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</pre>
110	</li>
111	<li>
112	<p>
113	For a Windows 7 or Vista guest:
114	</p>
115	<pre xml:space="preserve">bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</pre>
116	<pre xml:space="preserve">bcdedit /set dbgtransport kdvm.dll</pre>
117	<p>
118	The IP address and port in the
119	<userinput>bcdedit</userinput> command are ignored when
120	using the Hyper-V debug transport. Any valid IP and a
121	port number greater than 49151 and lower than 65536
122	can be entered.
123	</p>
124	<p>
125	The encryption key in the <userinput>bcdedit</userinput>
126	command is relevant and must be valid. The key
127	"1.2.3.4" used in the above example is valid and may
128	be used if security is not a concern. If you do not
129	specify any encryption key, <userinput>bcdedit</userinput>
130	will generate one for you and you will need to copy
131	this key to later enter in Microsoft WinDbg on the
132	remote end. This encryption key is used to encrypt the
133	debug data exchanged between Windows and the debugger.
134	</p>
135	</li>
136	<li>
137	<p>
138	Run one or more of the following commands to enable
139	debugging for the appropriate phase or component of
140	your Windows guest:
141	</p>
142	<pre xml:space="preserve">bcdedit /set debug on</pre>
143	<pre xml:space="preserve">bcdedit /set bootdebug on</pre>
144	<pre xml:space="preserve">bcdedit /set {bootmgr} bootdebug on</pre>
145	<p>
146	Please note that the <userinput>bootdebug</userinput>
147	options are only effective on Windows 8 or newer when
148	using the Hyper-V debug transport. Refer to Microsoft
149	Windows documentation for detailed explanation of
150	<userinput>bcdedit</userinput> options.
151	</p>
152	</li>
153	</ul>
154	</li>
155	<li>
156	<p>
157	Start Microsoft WinDbg on your host machine or remote
158	host.
159	</p>
160	<p>
161	From the <b outputclass="bold">File</b> menu,
162	select <b outputclass="bold">Kernel Debug</b>. On
163	the <b outputclass="bold">NET</b> tab, specify the
164	UDP port number you used in the
165	<codeph>paravirtdebug</codeph> options. If you did not
166	specify any, leave it as 50000. Ensure that the UDP port
167	is not blocked by a firewall or other security software.
168	</p>
169	<p>
170	In the <b outputclass="bold">Key</b> field, enter
171	<codeph>1.2.3.4</codeph> or the encryption key from the
172	<userinput>bcdedit</userinput> command in your Windows guest.
173	</p>
174	<p>
175	Click <b outputclass="bold">OK</b> to start
176	listening for connections. Microsoft WinDbg typically
177	shows a Waiting to Reconnect message during this phase.
178	</p>
179	<p>
180	Alternatively, to directly start a debug session, run
181	WinDbg from the command line as follows :
182	</p>
183	<pre xml:space="preserve">windbg.exe -k net:port=50000,key=1.2.3.4</pre>
184	<p>
185	See the WinDbg documentation for the complete command line
186	syntax.
187	</p>
188	</li>
189	<li>
190	<p>
191	Reboot your Windows guest and it should then connect as a
192	debuggee with Microsoft WinDbg.
193	</p>
194	</li>
195	</ol>
196	</body>
197
198	</topic>

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format