ts_debugger.dita@ 107390

Last change on this file since 107390 was 107390, checked in by vboxsync, 5 months ago

Docs: bugref:10705. bugref: 10829. The docs build has been modified to split generated refentry dita files and the user manual files and the following commits from doc's team git repo has been applied:

0946136c74dda0483704db891345cb39548b4e28 Started consolidating known issues and troubleshooting information
845b847e6a8e778b38a57867e25ee5e086a73800 Added individual topics for list of known issues, integrated into Troubleshooting section.
bb574836aac775889bd61e4a72f489617fcb7d18 Removed EFI firmware from experimental features for 7.2
6d2e68b244869991e713d170ecd239739d99ba56 Moved known issues into Known Issues section
e2630c896561587718b5c3197c384a38d07014d5 Merge branch 'VBP-1461_experimental-features' into 'main'
0512e2cce51f49ccdc56f3381a2a0c924f2bd278 Feedback on known issues
a77d6c980f6ff5cad9d32b2fb9290990093a03fa Restructured host and guest OS topics
988af5cc9628f5de0806531bc98686f691a911fd Updates with feedbback from Jacob
982a61c9f25b22b745ec483e763e3d88efe59c40 Included feedback from Jacob
93181c8c6cc2d9a26bcccb1145cb0423c0d9f4c9 Updated known issues with feedback from Klaus
8bc369561c383f09b409fe5e44f507440b3735fb Created Legacy Guest OS section
d7932f55accdab7a03666302d58b8c941cd48be2 Moved known issues to more appropriate places for the info
2a4aa094ba8a7ac6894d2a777316eabf41746580 Further moving of known issues
baeabd5308c5519a4dc26b4197be9b00e419a85a Updated links to cli_topics

Property svn:eol-style set to native
Property svn:keywords set to Author Date Id Revision

File size: 8.6 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="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
41	single stepping
42	</p>
43	</li>
44	<li>
45	<p><userinput>g</userinput>: Continue VM execution
46	</p>
47	</li>
48	<li>
49	<p><userinput>t</userinput>: Single step an instruction
50	</p>
51	</li>
52	<li>
53	<p><userinput>rg</userinput>, <userinput>rh</userinput>, and
54	<userinput>r</userinput>: Print the guest, hypervisor, and
55	current registers
56	</p>
57	</li>
58	<li>
59	<p><userinput>kg</userinput>, <userinput>kh</userinput>, and
60	<userinput>k</userinput>: Print the guest, hypervisor, and
61	current call stack
62	</p>
63	</li>
64	<li>
65	<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>
66	</li>
67	<li>
68	<p><userinput>u</userinput>: Unassemble memory
69	</p>
70	</li>
71	<li>
72	<p><userinput>dg</userinput>: Print the guest's GDT</p>
73	</li>
74	<li>
75	<p><userinput>di</userinput>: Print the guest's IDT</p>
76	</li>
77	<li>
78	<p><userinput>dl</userinput>: Print the guest's LDT</p>
79	</li>
80	<li>
81	<p><userinput>dt</userinput>: Print the guest's TSS</p>
82	</li>
83	<li>
84	<p><userinput>dp*</userinput>: Print the guest's page table structures</p>
85	</li>
86	<li>
87	<p><userinput>bp</userinput> and <userinput>br</userinput>: Set a normal and recompiler breakpoint</p>
88	</li>
89	<li>
90	<p><userinput>bl</userinput>: List breakpoints</p>
91	</li>
92	<li>
93	<p><userinput>bc</userinput>: Clear a breakpoint</p>
94	</li>
95	<li>
96	<p><userinput>writecore</userinput>: Write a VM core file to disk.
97	See <xref href="ts_guest-core-format.dita#ts_guest-core-format"/></p>
98	</li>
99	</ul>
100	<p>See the built-in <userinput>help</userinput> for other available commands.</p>
101	<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>
102	<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>
103	<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>
104	<ul>
105	<li>
106	<p><userinput>cfgm</userinput>: Print a branch of the configuration
107	tree
108	</p>
109	</li>
110	<li>
111	<p><userinput>cpuid</userinput>: Display the guest CPUID leaves
112	</p>
113	</li>
114	<li>
115	<p><userinput>ioport</userinput>: Print registered I/O port ranges
116	</p>
117	</li>
118	<li>
119	<p><userinput>mmio</userinput>: Print registered MMIO ranges
120	</p>
121	</li>
122	<li>
123	<p><userinput>mode</userinput>: Print the current paging mode
124	</p>
125	</li>
126	<li>
127	<p><userinput>pit</userinput>: Print the i8254 PIT state
128	</p>
129	</li>
130	<li>
131	<p><userinput>pic</userinput>: Print the i8259A PIC state
132	</p>
133	</li>
134	<li>
135	<p><userinput>ohci</userinput>, <userinput>ehci</userinput>,
136	<userinput>xhci</userinput>: Print a subset of the OHCI, EHCI,
137	and xHCI USB controller state
138	</p>
139	</li>
140	<li>
141	<p><userinput>pcnet0</userinput>: Print the PCnet state
142	</p>
143	</li>
144	<li>
145	<p><userinput>vgatext</userinput>: Print the contents of the VGA
146	framebuffer formatted as standard text mode
147	</p>
148	</li>
149	<li>
150	<p><userinput>timers</userinput>: Print all VM timers
151	</p>
152	</li>
153	</ul>
154	<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>
155	</body>
156
157	</topic>

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

Download in other formats:

Original Format