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