Oracle VM VirtualBox 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.

The VM debugger is available in all regular production versions of Oracle VM VirtualBox, but it is disabled by default because the average user will have little use for it. There are two ways to access the debugger:

• Using a debugger console window displayed alongside the VM

• Using the telnet protocol on port 5000

The debugger can be enabled in the following ways:

• Start the VM directly using VirtualBoxVM --startvm, with an additional --dbg, --debug, or --debug-command-line argument. See the VirtualBoxVM --help command usage help for details.

• Set the VBOX_GUI_DBG_ENABLED or VBOX_GUI_DBG_AUTO_SHOW environment variable to true before launching the Oracle VM VirtualBox process. Setting these variables, only their presence is checked, is effective even when the first Oracle VM VirtualBox process is the VM selector window. VMs subsequently launched from the selector will have the debugger enabled.

• Set the GUI/Dbg/Enabled extra data item to true before launching the VM. This can be set globally or on a per VM basis.

A new Debug menu entry is added to the Oracle VM VirtualBox application. This menu enables the user to open the debugger console.

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 Oracle VM VirtualBox VM debugger familiar.

The most important command is help. This will print brief usage help for all debugger commands. The set of commands supported by the VM debugger changes frequently and the help command is always up-to-date.

A brief summary of frequently used commands is as follows:

• stop: Stops the VM execution and enables single stepping

• g: Continue VM execution

• t: Single step an instruction

• rg, rh, and r: Print the guest, hypervisor, and current registers

• kg, kh, and k: Print the guest, hypervisor, and current call stack

• da, db, dw, dd, dq: Print memory contents as ASCII, bytes, words, dwords, and qwords

• u: Unassemble memory

• dg: Print the guest's GDT

• di: Print the guest's IDT

• dl: Print the guest's LDT

• dt: Print the guest's TSS

• dp*: Print the guest's page table structures

• bp and br: Set a normal and recompiler breakpoint

• bl: List breakpoints

• bc: Clear a breakpoint

• writecore: Write a VM core file to disk. See

See the built-in help for other available commands.

The VM debugger supports symbolic debugging, although symbols for guest code are often not available. For Oracle Solaris guests, the detect command automatically determines the guest OS version and locates kernel symbols in guest's memory. Symbolic debugging is then available. For Linux guests, the detect commands also determines the guest OS version, but there are no symbols in the guest's memory. Kernel symbols are available in the file /proc/kallsyms on Linux guests. This file must be copied to the host, for example using scp. The loadmap debugger command can be used to make the symbol information available to the VM debugger. Note that the kallsyms 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.

For all guests, a simple way to verify that the correct symbols are loaded is the k 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.

Another group of debugger commands is the set of info commands. Running info help 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 info commands, the right command to use depends entirely on the problem being investigated. Some of the info commands are as follows:

• cfgm: Print a branch of the configuration tree

• cpuid: Display the guest CPUID leaves

• ioport: Print registered I/O port ranges

• mmio: Print registered MMIO ranges

• mode: Print the current paging mode

• pit: Print the i8254 PIT state

• pic: Print the i8259A PIC state

• ohci, ehci, xhci: Print a subset of the OHCI, EHCI, and xHCI USB controller state

• pcnet0: Print the PCnet state

• vgatext: Print the contents of the VGA framebuffer formatted as standard text mode

• timers: Print all VM timers

The output of the info commands generally requires in-depth knowledge of the emulated device or Oracle VM VirtualBox VMM internals. However, when used properly, the information provided can be invaluable.