1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic xml:lang="en-us" id="ts_debugger">
<title>The Built-In VM Debugger</title>
<body>
<p>
<ph conkeyref="vbox-conkeyref-phrases/product-name"/> includes a built-in VM debugger, which advanced
users may find useful. This debugger enables you to examine and,
to some extent, control the VM state.
</p>
<note type="caution">
<p>
Use the VM debugger at your own risk. There is no support for
it, and the following documentation is only made available for
advanced users with a very high level of familiarity with the
x86/AMD64 machine instruction set, as well as detailed
knowledge of the PC architecture. A degree of familiarity with
the internals of the guest OS in question may also be very
helpful.
</p>
</note>
<p>
The VM debugger is available in all regular production versions
of <ph conkeyref="vbox-conkeyref-phrases/product-name"/>, but it is disabled by default because the
average user will have little use for it. There are two ways to
access the debugger:
</p>
<ul>
<li>
<p>
Using a debugger console window displayed alongside the VM
</p>
</li>
<li>
<p>
Using the <userinput>telnet</userinput> protocol on port 5000
</p>
</li>
</ul>
<p>
The debugger can be enabled in the following ways:
</p>
<ul>
<li>
<p>
Start the VM directly using <userinput>VirtualBoxVM
--startvm</userinput>, with an additional
<codeph>--dbg</codeph>, <codeph>--debug</codeph>, or
<codeph>--debug-command-line</codeph> argument. See the
<userinput>VirtualBoxVM --help</userinput> command usage help
for details.
</p>
</li>
<li>
<p>
Set the <codeph>VBOX_GUI_DBG_ENABLED</codeph> or
<codeph>VBOX_GUI_DBG_AUTO_SHOW</codeph> environment
variable to <codeph>true</codeph> before launching the
<ph conkeyref="vbox-conkeyref-phrases/product-name"/> process. Setting these variables, only their
presence is checked, is effective even when the first
<ph conkeyref="vbox-conkeyref-phrases/product-name"/> process is the VM selector window. VMs
subsequently launched from the selector will have the
debugger enabled.
</p>
</li>
<li>
<p>
Set the <codeph>GUI/Dbg/Enabled</codeph> extra data item
to <codeph>true</codeph> before launching the VM. This can
be set globally or on a per VM basis.
</p>
</li>
</ul>
<p>
A new <b outputclass="bold">Debug</b> menu entry is added
to the <ph conkeyref="vbox-conkeyref-phrases/product-name"/> application. This menu enables the user to
open the debugger console.
</p>
<p>
The VM debugger command syntax is loosely modeled on Microsoft
and IBM debuggers used on DOS, OS/2, and Windows. Users familiar
with symdeb, CodeView, or the OS/2 kernel debugger will find the
<ph conkeyref="vbox-conkeyref-phrases/product-name"/> VM debugger familiar.
</p>
<p>
The most important command is <userinput>help</userinput>. This will
print brief usage help for all debugger commands. The set of
commands supported by the VM debugger changes frequently and the
<userinput>help</userinput> command is always up-to-date.
</p>
<p>
A brief summary of frequently used commands is as follows:
</p>
<ul>
<li>
<p><userinput>stop</userinput>: Stops the VM execution and enables
single stepping
</p>
</li>
<li>
<p><userinput>g</userinput>: Continue VM execution
</p>
</li>
<li>
<p><userinput>t</userinput>: Single step an instruction
</p>
</li>
<li>
<p><userinput>rg</userinput>, <userinput>rh</userinput>, and
<userinput>r</userinput>: Print the guest, hypervisor, and
current registers
</p>
</li>
<li>
<p><userinput>kg</userinput>, <userinput>kh</userinput>, and
<userinput>k</userinput>: Print the guest, hypervisor, and
current call stack
</p>
</li>
<li>
<p><userinput>da</userinput>, <userinput>db</userinput>,
<userinput>dw</userinput>, <userinput>dd</userinput>,
<userinput>dq</userinput>: Print memory contents as ASCII,
bytes, words, dwords, and qwords
</p>
</li>
<li>
<p><userinput>u</userinput>: Unassemble memory
</p>
</li>
<li>
<p><userinput>dg</userinput>: Print the guest's GDT
</p>
</li>
<li>
<p><userinput>di</userinput>: Print the guest's IDT
</p>
</li>
<li>
<p><userinput>dl</userinput>: Print the guest's LDT
</p>
</li>
<li>
<p><userinput>dt</userinput>: Print the guest's TSS
</p>
</li>
<li>
<p><userinput>dp*</userinput>: Print the guest's page table
structures
</p>
</li>
<li>
<p><userinput>bp</userinput> and <userinput>br</userinput>: Set a
normal and recompiler breakpoint
</p>
</li>
<li>
<p><userinput>bl</userinput>: List breakpoints
</p>
</li>
<li>
<p><userinput>bc</userinput>: Clear a breakpoint
</p>
</li>
<li>
<p><userinput>writecore</userinput>: Write a VM core file to disk.
See <xref href="ts_guest-core-format.dita#ts_guest-core-format"/></p>
</li>
</ul>
<p>
See the built-in <userinput>help</userinput> for other available
commands.
</p>
<p>
The VM debugger supports symbolic debugging, although symbols
for guest code are often not available. For Oracle Solaris
guests, the <userinput>detect</userinput> command automatically
determines the guest OS version and locates kernel symbols in
guest's memory. Symbolic debugging is then available. For Linux
guests, the <userinput>detect</userinput> commands also determines
the guest OS version, but there are no symbols in the guest's
memory. Kernel symbols are available in the file
<filepath>/proc/kallsyms</filepath> on Linux guests. This file
must be copied to the host, for example using
<userinput>scp</userinput>. The <userinput>loadmap</userinput> debugger
command can be used to make the symbol information available to
the VM debugger. Note that the <filepath>kallsyms</filepath>
file contains the symbols for the currently loaded modules. If
the guest's configuration changes, the symbols will change as
well and must be updated.
</p>
<p>
For all guests, a simple way to verify that the correct symbols
are loaded is the <userinput>k</userinput> command. The guest is
normally idling and it should be clear from the symbolic
information that the guest operating system's idle loop is being
executed.
</p>
<p>
Another group of debugger commands is the set of
<userinput>info</userinput> commands. Running <userinput>info
help</userinput> provides complete usage information. The
information commands provide ad-hoc data pertinent to various
emulated devices and aspects of the VMM. There is no general
guideline for using the <userinput>info</userinput> commands, the
right command to use depends entirely on the problem being
investigated. Some of the <userinput>info</userinput> commands are
as follows:
</p>
<ul>
<li>
<p><userinput>cfgm</userinput>: Print a branch of the configuration
tree
</p>
</li>
<li>
<p><userinput>cpuid</userinput>: Display the guest CPUID leaves
</p>
</li>
<li>
<p><userinput>ioport</userinput>: Print registered I/O port ranges
</p>
</li>
<li>
<p><userinput>mmio</userinput>: Print registered MMIO ranges
</p>
</li>
<li>
<p><userinput>mode</userinput>: Print the current paging mode
</p>
</li>
<li>
<p><userinput>pit</userinput>: Print the i8254 PIT state
</p>
</li>
<li>
<p><userinput>pic</userinput>: Print the i8259A PIC state
</p>
</li>
<li>
<p><userinput>ohci</userinput>, <userinput>ehci</userinput>,
<userinput>xhci</userinput>: Print a subset of the OHCI, EHCI,
and xHCI USB controller state
</p>
</li>
<li>
<p><userinput>pcnet0</userinput>: Print the PCnet state
</p>
</li>
<li>
<p><userinput>vgatext</userinput>: Print the contents of the VGA
framebuffer formatted as standard text mode
</p>
</li>
<li>
<p><userinput>timers</userinput>: Print all VM timers
</p>
</li>
</ul>
<p>
The output of the <userinput>info</userinput> commands generally
requires in-depth knowledge of the emulated device or
<ph conkeyref="vbox-conkeyref-phrases/product-name"/> VMM internals. However, when used properly, the
information provided can be invaluable.
</p>
</body>
</topic>
|
