| 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><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>
|
|---|
| 8 | <note type="caution">
|
|---|
| 9 | <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>
|
|---|
| 10 | </note>
|
|---|
| 11 | <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>
|
|---|
| 12 | <ul>
|
|---|
| 13 | <li>
|
|---|
| 14 | <p>Using a debugger console window displayed alongside the VM</p>
|
|---|
| 15 | </li>
|
|---|
| 16 | <li>
|
|---|
| 17 | <p>Using the <userinput>telnet</userinput> protocol on port 5000</p>
|
|---|
| 18 | </li>
|
|---|
| 19 | </ul>
|
|---|
| 20 | <p>
|
|---|
| 21 | The debugger can be enabled in the following ways:
|
|---|
| 22 | </p>
|
|---|
| 23 | <ul>
|
|---|
| 24 | <li>
|
|---|
| 25 | <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>
|
|---|
| 26 | </li>
|
|---|
| 27 | <li>
|
|---|
| 28 | <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>
|
|---|
| 29 | </li>
|
|---|
| 30 | <li>
|
|---|
| 31 | <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>
|
|---|
| 32 | </li>
|
|---|
| 33 | </ul>
|
|---|
| 34 | <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>
|
|---|
| 35 | <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>
|
|---|
| 36 | <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>
|
|---|
| 37 | <p>A brief summary of frequently used commands is as follows:</p>
|
|---|
| 38 | <ul>
|
|---|
| 39 | <li>
|
|---|
| 40 | <p><userinput>stop</userinput>: Stops the VM execution and enables single stepping</p>
|
|---|
| 41 | </li>
|
|---|
| 42 | <li>
|
|---|
| 43 | <p><userinput>g</userinput>: Continue VM execution</p>
|
|---|
| 44 | </li>
|
|---|
| 45 | <li>
|
|---|
| 46 | <p><userinput>t</userinput>: Single step an instruction</p>
|
|---|
| 47 | </li>
|
|---|
| 48 | <li>
|
|---|
| 49 | <p><userinput>rg</userinput>, <userinput>rh</userinput>, and <userinput>r</userinput>: Print the guest, hypervisor, and current registers</p>
|
|---|
| 50 | </li>
|
|---|
| 51 | <li>
|
|---|
| 52 | <p><userinput>kg</userinput>, <userinput>kh</userinput>, and <userinput>k</userinput>: Print the guest, hypervisor, and current call stack</p>
|
|---|
| 53 | </li>
|
|---|
| 54 | <li>
|
|---|
| 55 | <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>
|
|---|
| 56 | </li>
|
|---|
| 57 | <li>
|
|---|
| 58 | <p><userinput>u</userinput>: Unassemble memory
|
|---|
| 59 | </p>
|
|---|
| 60 | </li>
|
|---|
| 61 | <li>
|
|---|
| 62 | <p><userinput>dg</userinput>: Print the guest's GDT</p>
|
|---|
| 63 | </li>
|
|---|
| 64 | <li>
|
|---|
| 65 | <p><userinput>di</userinput>: Print the guest's IDT</p>
|
|---|
| 66 | </li>
|
|---|
| 67 | <li>
|
|---|
| 68 | <p><userinput>dl</userinput>: Print the guest's LDT</p>
|
|---|
| 69 | </li>
|
|---|
| 70 | <li>
|
|---|
| 71 | <p><userinput>dt</userinput>: Print the guest's TSS</p>
|
|---|
| 72 | </li>
|
|---|
| 73 | <li>
|
|---|
| 74 | <p><userinput>dp*</userinput>: Print the guest's page table structures</p>
|
|---|
| 75 | </li>
|
|---|
| 76 | <li>
|
|---|
| 77 | <p><userinput>bp</userinput> and <userinput>br</userinput>: Set a normal and recompiler breakpoint</p>
|
|---|
| 78 | </li>
|
|---|
| 79 | <li>
|
|---|
| 80 | <p><userinput>bl</userinput>: List breakpoints</p>
|
|---|
| 81 | </li>
|
|---|
| 82 | <li>
|
|---|
| 83 | <p><userinput>bc</userinput>: Clear a breakpoint</p>
|
|---|
| 84 | </li>
|
|---|
| 85 | <li>
|
|---|
| 86 | <p><userinput>writecore</userinput>: Write a VM core file to disk.
|
|---|
| 87 | See <xref href="ts_guest-core-format.dita#ts_guest-core-format"/></p>
|
|---|
| 88 | </li>
|
|---|
| 89 | </ul>
|
|---|
| 90 | <p>See the built-in <userinput>help</userinput> for other available commands.</p>
|
|---|
| 91 | <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>
|
|---|
| 92 | <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>
|
|---|
| 93 | <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>
|
|---|
| 94 | <ul>
|
|---|
| 95 | <li>
|
|---|
| 96 | <p><userinput>cfgm</userinput>: Print a branch of the configuration
|
|---|
| 97 | tree
|
|---|
| 98 | </p>
|
|---|
| 99 | </li>
|
|---|
| 100 | <li>
|
|---|
| 101 | <p><userinput>cpuid</userinput>: Display the guest CPUID leaves
|
|---|
| 102 | </p>
|
|---|
| 103 | </li>
|
|---|
| 104 | <li>
|
|---|
| 105 | <p><userinput>ioport</userinput>: Print registered I/O port ranges
|
|---|
| 106 | </p>
|
|---|
| 107 | </li>
|
|---|
| 108 | <li>
|
|---|
| 109 | <p><userinput>mmio</userinput>: Print registered MMIO ranges
|
|---|
| 110 | </p>
|
|---|
| 111 | </li>
|
|---|
| 112 | <li>
|
|---|
| 113 | <p><userinput>mode</userinput>: Print the current paging mode
|
|---|
| 114 | </p>
|
|---|
| 115 | </li>
|
|---|
| 116 | <li>
|
|---|
| 117 | <p><userinput>pit</userinput>: Print the i8254 PIT state
|
|---|
| 118 | </p>
|
|---|
| 119 | </li>
|
|---|
| 120 | <li>
|
|---|
| 121 | <p><userinput>pic</userinput>: Print the i8259A PIC state
|
|---|
| 122 | </p>
|
|---|
| 123 | </li>
|
|---|
| 124 | <li>
|
|---|
| 125 | <p><userinput>ohci</userinput>, <userinput>ehci</userinput>,
|
|---|
| 126 | <userinput>xhci</userinput>: Print a subset of the OHCI, EHCI,
|
|---|
| 127 | and xHCI USB controller state
|
|---|
| 128 | </p>
|
|---|
| 129 | </li>
|
|---|
| 130 | <li>
|
|---|
| 131 | <p><userinput>pcnet0</userinput>: Print the PCnet state
|
|---|
| 132 | </p>
|
|---|
| 133 | </li>
|
|---|
| 134 | <li>
|
|---|
| 135 | <p><userinput>vgatext</userinput>: Print the contents of the VGA
|
|---|
| 136 | framebuffer formatted as standard text mode
|
|---|
| 137 | </p>
|
|---|
| 138 | </li>
|
|---|
| 139 | <li>
|
|---|
| 140 | <p><userinput>timers</userinput>: Print all VM timers
|
|---|
| 141 | </p>
|
|---|
| 142 | </li>
|
|---|
| 143 | </ul>
|
|---|
| 144 | <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 very valuable.</p>
|
|---|
| 145 | </body>
|
|---|
| 146 |
|
|---|
| 147 | </topic>
|
|---|
